com.dixshtix.niff
Class Tag

java.lang.Object
  |
  +--com.dixshtix.niff.Tag

All Implemented Interfaces:

java.lang.Comparable

public class Tag

extends java.lang.Object

implements java.lang.Comparable

A mechanism for adding variable-length tags binary data to a RIFF file.

Each NIFF file chunk has a fixed-length part and a variable length part. The fixed-length part is composed of a set of required elements described by each chunk definition. The variable length part is composed of a series of optional tags which may be used occasionally or only by certain programs.

A tag is a self-contained set of variable-length information composed of a one byte code indicating what type of tag it is, followed by a one byte length field, followed by the tag's data.

Defined in the Java programming language, a tag looks like this:

public class tag {
byte tagID; // Unsigned
byte tagSize; // the (unsigned) size of field <tagData>
byte tagData[tagSize]; // the actual data of the tag
} tag;

The presence of the tags' size allows programs to ignore the rest of a tag which is not recognized. The tagData field always has an even number of bytes. A pad byte with value zero is added to the end, if necessary for the data to end on a word boundary. The value of tagSize does not include the pad byte.

Any number of tags may be appended to the required part of a chunk. NIFF-defined options, user-defined options, and future extensions can all be represented in the form of tags.

Any defined tag may be added to any chunk type; however, some combinations might be meaningless. When used on an anchor symbol chunk, a tag applies to all symbol chunks dependent on the anchor, where meaningful. When used on a Stem chunk, a tag applies to all associated Notehead chunks.

The "Tags" item listed under each chunk description contains a few suggestions for tags to be used in that context. It is not intended to restrict the the creative use of tags. Any tag is allowed to be placed on any chunk.

When the meaning of a particular tag is not specified for a particular chunk, it is the responsibility of the the writing program to use the tag in a meaningful way, and the reading program must do its best to interpret it.

Timing Representation

Durations in music notation are inherently rational numbers (fractions) which describe the relationship between a specific unit of time (the note value) and a standard unit of time (traditionally the whole note). A half note is 1/2 of a whole note; a quarter note is 1/4 of a whole note. Infinitely smaller note types can be invented by increasing the denominator to any power of 2.

More interestingly, the duration of each note in a tuplet sometimes can be precisely represented only by a fraction, such as half note triplets, where each note's duration can be accurately represented as 1/3. When three half notes occur in the time normally allotted for 2, each note takes up 2/3 the time of a normal half note (1/3 = 2/3 * 1/2). Similarly, when 3 quarter notes are stretched out to the time of 4 (notated as 3:4 over a bracket, in tuplet notation), this duration can also be represented as 1/3: each note takes up 4/3 of the time of a normal quarter note (1/3 = 4/3 * 1/4).

A fraction consisting of two integers (a numerator and a denominator) is therefore a natural way to describe durations.

Corrected from NIFF 6a, FONTIDX has replaced FONTPTR.

Field Summary

static Tag	absPlacement Non-default horizontal and vertical placement, in absolute units, of the dependent symbol's reference point relative to the anchor's reference point.
static Tag	altEnding The sequence number of the ending.
static Tag	anchorOverride Contains the chunk type of the non-default anchor symbol.
static Tag	articDirection Used on the Articulation chunk to specifically indicate a particular version of the articulation symbol, such as fermata or strong accent.
static Tag	bezierIncoming Used on a slur node to specify an incoming Bezier control point.
static Tag	bezierOutgoing Used on a slur node to specify an outgoing Bezier control point.
static Tag	chordSymbolsOffset Used on the Part Description chunk, to specify the default vertical placement of chord symbols with respect to the top staff of the part, in absolute units.
static Tag	customFontChar Used on a music symbol chunk to indicate that a nonstandard character and font is to be used.
static Tag	customGraphicTag Used when a custom graphic is to be used in place of the standard appearance of the music symbol.
static Tag	endOfSystem Used to indicate that the chunk is located at the rightmost end of a system.
static Tag	fannedBeam Used on the first node of a Beam to indicate an accelerando or ritard.
static Tag	figBassOffset Used on the Part Description chunk, to specify the default vertical placement of the top numeral of figured bass symbols with respect to the bottom staff of the part, in absolute units.
static Tag	fontID Used to indicate that a nondefault font is to be used for the chunk on which this tag occurs.
static Tag	graceNote Used on a Stem, Notehead, or Rest.
static Tag	guitarGridOffset Used on the Part Description chunk, to specify the default vertical placement of guitar grid symbols with respect to the top staff of the part, in absolute units.
static Tag	guitarTabTag Used on a Staff Header chunk to indicate that the staff is guitar tablature, and its symbols should be interpreted accordingly (not used for playback).
static Tag	height Vertical height, in absolute units.
static Tag	id Identification number.
static Tag	invisible When this tag is used on a symbol, the symbol's function and/or sound is unchanged, but the symbol does not appear visibly in the score.
static Tag	largeSize Indicates that the symbol is larger than default size.
static Tag	lineQuality Used on symbol chunks such as Barline, Line, or Slur to indicate that the line is not solid.
static Tag	logicalPlacement Non-default horizontal and vertical logical placement of the dependent symbol's reference point relative to the anchor's reference point.
static Tag	lyricVerseOffset This tag is appended to the Part Description chunk in the Setup Section, to define the vertical offset and Lyric Verse ID of one line of lyrics.
static Tag	midiPerformance Used on note chunks.
static Tag	multiNodeEndOfSyst Used on a node of a multi-node symbol to indicate that the symbol continues on the following system.
static Tag	multiNodeStartOfSyst Used on a node of a multi-node symbol to indicate that this is the continuation of a symbol which started on the previous system.
private static java.util.Map	nameToNumber
static Tag	numberOfFlags Number of flags on stemmed note.
static Tag	numberOfNodes Total number of nodes in file for this multi-node symbol.
static Tag	numberStyle No data.
private static java.util.Map	numberToName
static Tag	numStaffLines Non-default number of lines in a staff, used on the Staff Header.
static Tag	ossia Used on one or more Staff Header chunks in a system to indicate an alternate performance of another staff or staves.
static Tag	partDescOverride Used with Part ID on any chunk where Part ID can be specified, such as a Tag Activate/Inactivate, Staff Header or a music symbol chunk.
static Tag	partID Used to associate chunks in the Data Section with a particular Part Description chunk in the Setup Section When used on a Staff Header chunk, it indicates that all symbols within the Staff list belong to the part.
static Tag	refPtOverride Description of non-default reference points on the anchor and dependent symbols.
static Tag	rehearsalOffset Used on the Part Description chunk, to specify the default vertical placement of the rehearsal mark with respect to the top staff of the part, in absolute units.
static Tag	restNumeral Number that is to appear centered over multiple-measure rest symbol.
static Tag	silent When this tag is used, the sound is suppressed for the symbol.
static Tag	slashedStem Indicates the presence of a slash on a stem, as in a grace note.
static Tag	smallSize Indicates that the symbol is smaller than default size.
static Tag	spacingByPart This tag is added to the NIFF Information chunk to indicate that a special horizontal spacing scheme is used.
static Tag	splitStem Used on each Notehead chunk of an altered unison, when a single stem connects two or more notes, usually at the same staff step but different horizontal placements that are more than one notewidth apart.
static Tag	staffName Used on a Text chunk to indicate its function as a name for a staff or staff grouping.
static Tag	staffStep Used to indicate vertical placement using the "staff step" units of measurement.
static Tag	thickness Used on symbol chunks such as Barline, Line, Hairpin, or Slur, to indicate the thickness of the line, in absolute units.
static Tag	tieDirection Used on Tie chunks and simple Slur chunks, to indicating the bow direction of the curve.
static Tag	tupletDesc Describe a tuplet.
static Tag	userDefined Provide for a user defined tag for vendor-specific expansion.
private byte	value
static Tag	voiceID Used on music symbols in the Data Section to uniquely identify a voice within the part.
static Tag	width Horizontal width, in absolute units.

Constructor Summary

Tag(int n)

Tag(java.lang.String name)

Tag(java.lang.String name, int n)

Method Summary

int	compareTo(java.lang.Object obj)
boolean	equals(byte b)
boolean	equals(java.lang.Object obj)
int	hashCode()
static Tag	read(java.io.InputStream s)
java.lang.String	toString()
static java.lang.String	toString(byte b)
void	write(java.io.OutputStream s)

Methods inherited from class java.lang.Object

, clone, finalize, getClass, notify, notifyAll, registerNatives, wait, wait, wait

Field Detail

nameToNumber

private static java.util.Map nameToNumber

numberToName

private static java.util.Map numberToName

absPlacement

public static final Tag absPlacement

Non-default horizontal and vertical placement, in absolute units, of the dependent symbol's reference point relative to the anchor's reference point.

Logical Placement and Absolute Placement are mutually exclusive.

Interpretation of placement values by the reading program.

When encountering only absolute placement values in a NIFF file, a reading program could ignore them completely (strictly using its own defaults), or it could observe them without question. More intelligently, it could use them as a clue to determine logical placement of the symbols, avoiding collisions or incorrect alignment when necessary.

See ChunkLengthTable.NiffInfo for a discussion of Absolute Units.

Absolute Placement	STRUCTURE	0x01
		horizontal SHORT vertical SHORT

altEnding

public static final Tag altEnding

The sequence number of the ending. Used on the first measure-start Time-Slice chunk of each alternate ending to validate the duplicate start time values. See also Alternate Ending Graphic chunk and Repeat Sign chunk, and the General Discussion section of Repeats and Alternate Endings, which includes an example.

Alternate Ending	BYTE	0x02

See Also:

ChunkLengthTable.RepeatSign, ChunkLengthTable.AltEndingGraphic

anchorOverride

public static final Tag anchorOverride

Contains the chunk type of the non-default anchor symbol.

Anchor Override	FOURCC	0x03

articDirection

public static final Tag articDirection

Used on the Articulation chunk to specifically indicate a particular version of the articulation symbol, such as fermata or strong accent.

Articulation Direction	BYTE	0x04
		1 = pointed up 2 = pointed down

bezierIncoming

public static final Tag bezierIncoming

Used on a slur node to specify an incoming Bezier control point. Gives the horizontal and vertical placement of the incoming Bezier control point relative to the slur endpoint. Can also be used on a tie node. See also Bezier Outgoing tag.

Bezier Incoming	STRUCT	0x05
		horizontal SHORT vertical SHORT

Example 1 - slur anchored to two notes:

Stem

Notehead
Slur, ID=1, Number of Nodes=2, Absolute Placement= (H1, V1), Bezier Outgoing = (H2, V2)

Stem

Notehead
Slur, ID=1, Absolute Placement= (H3, V3), Bezier Incoming = (H4, V4)

Example 2 - slur anchored to three notes (such as when it starts below an upstem note, swings up over the top of a down stem note, and then back down below another upstem note):

Stem

Notehead
Slur, ID=2, Number of Nodes=3, Absolute Placement = (H1, V1), Bezier Outgoing = (H2, V2)

Stem

Notehead
Slur, ID=2, Absolute Placement = (H3, V3), Bezier Incoming = (H4, V4), Bezier Outgoing = (H5, V5)

Stem

Notehead
Slur, ID=2, Absolute Placement = (H6, V6), Bezier Incoming = (H7, V7)

bezierOutgoing

public static final Tag bezierOutgoing

Used on a slur node to specify an outgoing Bezier control point. Gives the horizontal and vertical placement of the outgoing Bezier control point relative to the slur endpoint. Can also be used on a tie node See bezierIncoming tag for examples.

Bezier Outgoing	STRUCT	0x06
		horizontal SHORT vertical SHORT Horizontal and vertical placement of the outgoing Bezier control point relative to the slur endpoint.

chordSymbolsOffset

public static final Tag chordSymbolsOffset

Used on the Part Description chunk, to specify the default vertical placement of chord symbols with respect to the top staff of the part, in absolute units. In the Data Section, Chord Symbol chunks are interspersed with the music symbols of the first (top) staff of the part.

See ChunkLengthTable.NiffInfo for a discussion of Absolute Units.

Chord Symbols Offset	SHORT	0x07

customFontChar

public static final Tag customFontChar

Used on a music symbol chunk to indicate that a nonstandard character and font is to be used. The function of the music symbol chunk is otherwise unchanged.

Is this meant to be a 1-char ZSTR ?

Custom Font Character	STRUCT	0x08
		font ID FONTIDX character code CHAR[2]

See Also:

ChunkLengthTable.FontDescription

customGraphicTag

public static final Tag customGraphicTag

Used when a custom graphic is to be used in place of the standard appearance of the music symbol.

The index into the Custom Graphic list of an EPS Graphic chunk containing a description of the graphic symbol.

Custom Graphic	SHORT	0x09
		value SHORT

See Also:

ChunkLengthTable.CustomGraphicChk, CustomGraphicsList

endOfSystem

public static final Tag endOfSystem

Used to indicate that the chunk is located at the rightmost end of a system. This could be used at the end of a system on a Barline symbol in place of a horizontal offset, to avoid the undesirable results of rounding errors or font-width errors. It could be used at the end of a system where no barline is present, on an event Time-Slice chunk used as an anchor for a dependent symbol. To indicate the continuation of a multi-node chunk onto another system, use the Multi-node End Of System and Multi-node Start Of System tags instead.

End Of System	EMPTY	0x0A

fannedBeam

public static final Tag fannedBeam

Used on the first node of a Beam to indicate an accelerando or ritard.

Fanned Beam	SHORT	0x0B
		On first beam node only. 1 = fanned beam expanding toward right 2 = fanned beam shrinking toward right

figBassOffset

public static final Tag figBassOffset

Used on the Part Description chunk, to specify the default vertical placement of the top numeral of figured bass symbols with respect to the bottom staff of the part, in absolute units. In the Data Section, Figured Bass chunks are interspersed with the music symbols of the last (bottom) staff of the part.

See ChunkLengthTable.NiffInfo for a discussion of Absolute Units.

Figured Bass Offset	SHORT	0x0C

fontID

public static final Tag fontID

Used to indicate that a nondefault font is to be used for the chunk on which this tag occurs. Can be used on any music symbol or text-type chunk. Gives the index into the Font list, of the font to be used.

Font ID	FONTIDX	0x0D

See Also:

ChunkLengthTable.FontDescription

graceNote

public static final Tag graceNote

Used on a Stem, Notehead, or Rest. Indicates the logical start time as an offset from the time-slice start time. Negative values indicate that the grace note starts before the time slice, so during playback it should sound before the note. Zero and positive values indicate that the grace note's time value is stolen from the following note in the same voice.

A grace note is a note whose time value is not counted in the general rhythm; its time value must be subtracted from that of the preceding or following normal note during performance. A grace note is always associated with the event time-slice of the normal note following it. It is indicated by the addition of a Grace Note tag to a Notehead or Stem chunk. The Grace Note tag gives the note's logical start time as an offset from thestart time of its time-slice (negative, zero or positive, depending on the chosen interpretation of grace notes and the note's position within a series of grace notes).

For small notes that break the meter but whose time is not subtracted from that of the preceding or following normal note, do not use the Grace Note tag.

The performance start time (in the note's MIDI Performance tag) is given as an offset in MIDI ticks from the grace note's logical start time. Other tags that might be found on a grace note's Notehead or Stem chunk include the Slash tag, Small Size tag, and the Absolute Placement tag (with a negative value) indicating a negative horizontal offset from the time-slice.

In the following example, the grace note's time value is subtracted from the preceding note during performance, as in Chopin or Liszt. However, the duration field on the preceding Notehead chunk is not modified to compensate for the grace note. The start time on the Grace Note tag gives a negative offset of 1/32 from its time slice, which can be used by the reading program during playback.

Time-slice, type=event,start-time=0/4
Stem
Notehead, shape=filled, staff step=0, duration=1/4
Time-slice, type=event, start-time=1/4
Stem, Number of Flags=1, Slashed Stem, Small Size, Grace Note=-1/32
Notehead, shape=filled, staff step=2, duration=1/32
Stem
Notehead, shape=filled, staff step=1, duration=1/4

Grace Note	RATIONAL	0x0E

guitarGridOffset

public static final Tag guitarGridOffset

Used on the Part Description chunk, to specify the default vertical placement of guitar grid symbols with respect to the top staff of the part, in absolute units. In the Data Section, Guitar Grid chunks are interspersed with the music symbols of the first (top) staff of the part.

See ChunkLengthTable.NiffInfo for a discussion of Absolute Units.

Guitar Grid Offset	SHORT	0x0F

guitarTabTag

public static final Tag guitarTabTag

Used on a Staff Header chunk to indicate that the staff is guitar tablature, and its symbols should be interpreted accordingly (not used for playback).

Guitar Tablature	EMPTY	0x10

height

public static final Tag height

Vertical height, in absolute units. See ChunkLengthTable.NiffInfo for a discussion of Absolute Units.

Height	SHORT	0x11

id

public static final Tag id

Identification number. Used to uniquely identify multi-node symbols. Should be assigned sequentially within a chunk type, starting with zero.

ID	SHORT	0x12

invisible

public static final Tag invisible

When this tag is used on a symbol, the symbol's function and/or sound is unchanged, but the symbol does not appear visibly in the score.

Invisible	EMPTY	0x13

largeSize

public static final Tag largeSize

Indicates that the symbol is larger than default size. For more precise control of size, use the Font ID tag instead.

Large Size	EMPTY	0x14

lineQuality

public static final Tag lineQuality

Used on symbol chunks such as Barline, Line, or Slur to indicate that the line is not solid.

Line Quality	BYTE	0x15
		0 = no line 1 = dotted line 2 = dashed line 3 = wavy line

logicalPlacement

public static final Tag logicalPlacement

Non-default horizontal and vertical logical placement of the dependent symbol's reference point relative to the anchor's reference point.

Symbol Placement.

NIFF allows a variety of choices in describing the placement of symbols. The placement of a symbol is always described in terms of its relationship to its anchor. The choices include default placement, logical placement and absolute placement. A reference point for each symbol, defined by default, or explicitly by use of the Reference Point Override tag, is used in the interpretation of both absolute and logical placement values.

It is suggested that the writing program allow the user as much control as possible in the choice of the symbol placement technique or combination of techniques used in a particular NIFF file.

When non-default placement information is present for a symbol, it should not contradict the placement relationship implied by the file syntax, but should complement it.

Default, logical and absolute placement.

Default placement: This is the case when no indication of symbol placement is present for a symbol other than that implied by the file syntax. The reading program must use its own defaults for intelligent placement of the symbol.

Logical placement: This supplies the logical relationship between a dependent symbol and its anchor. It is implemented by the use of the Logical Placement tag, which indicates direction such as left, right, above, below or centered, and proximity such as touching or offset; and the Staff Step tag, which gives the position of the symbol's hot spot as a particular staff line or space.

Absolute placement: This gives the exact location of the symbol, as an offset in absolute measurement units relative to its anchor. This is useful when an exact reproduction of the original image is desirable. It is implemented by the use of the absPlacement tag, which supplies the exact horizontal and vertical offsets of symbols from one another.

Choice of placement technique by the writing program.

Absolute placement allows for the most precise rendering of the original notation. However, there are many situations where logical or default placement is more appropriate:

1. When the reading program does not have access to the music font specified by the writing program, use of absolute measurements could result in overlapping or incorrect alignment of symbols.
2. When the reading program has no concept of page layout, absolute positioning would either be discarded or used only for its logical placement implications.
3. In some cases, the user may simply not care to retain the details of the writing program's symbol placement, preferring a default layout by the reading program instead.

Combinations of the various techniques can be included in a NIFF file. One possibility might be for a writing program to record page layout information such as the vertical location of each system and staff, and the horizontal position of each measure. Finer detail might be stored only when the user has specified non-default placement of some object, such as when a slur has been reshaped to avoid another symbol. In this case the writing program might store the absolute placement of a particular slur's endpoints in relation to its stem anchors.

The use of the three placement options will likely evolve during the trial implementation of NIFF.

Logical Placement and Absolute Placement are mutually exclusive.

Logical Placement	STRUCTURE	0x16
		horizontal BYTE 0=default 1=left 2=right 3 = stem side 4= note side 5 = centered Values 3 and 4 are only to be used on a symbol dependent on a note or stem. "Stem side" and "note side" have the same meaning as "left" and "right" respectively for down stems, and the opposite for up stems. vertical BYTE 0=default 1=above 2=below 3 = stem side 4= note side 5 = centered Values 3 and 4 are only to be used on a symbol dependent on a note or stem. "Stem side" and "note side" have the same meaning as "above" and "below" respectively for up stems, and the opposite for down stems. proximity BYTE 0= not applicable, or default 1 = touching, or exactly aligned 2 = offset slightly Used to refine the meaning of Non-default logical placement of the symbol's bounding box relative to the anchor's bounding box. For instance, a note slightly offset from a stem would be given the value 2.

lyricVerseOffset

public static final Tag lyricVerseOffset

This tag is appended to the Part Description chunk in the Setup Section, to define the vertical offset and Lyric Verse ID of one line of lyrics. Any number of them can be present.

See ChunkLengthTable.NiffInfo for a discussion of Absolute Units.

Lyric Verse Offset	STRUCT	0x17
		lyric line offset SHORT Default vertical placement of a line of lyrics with respect to the bottom staff of the part, in absolute units. A null value (-1) is allowed, even when Lyric chunks are present in the Data Section. In the Data Section, Lyric chunks are interspersed with the music symbols of the part in the Staff lists. Lyric Verse ID BYTE Used to associate the Lyric Verse ID field on Lyric chunks in the Data Section with the default vertical offset supplied here.

midiPerformance

public static final Tag midiPerformance

Used on note chunks. See Timing Representation in the Discussion Section, for a description of its use.

For performance playback, both start time and duration are measured in MIDI ticks, which denote some fixed amount of time using an integer. MIDI ticks are well suited to performance information because of their high resolution. The relationship between the performance and logical values is described by the field MIDI ticks per quarter note, stored in the NIFF Information chunk in the Setup Section.

The performance start time and duration are given as offsets (+/-) from the logical start time and duration of the event.

Lengthy or complex MIDI information that cannot be represented with the simple MIDI Performance tag can be supplied with the MIDI Data Stream chunk (see below under MIDI Integration).

MIDI Performance	STRUCT	0x18
		start time LONG Start time, given in MIDI ticks, as an offset from the time-slice duration LONG Duration, given in MIDI ticks pitch BYTE MIDI pitch (0-127) velocity BYTE MIDI velocity (0-127) Corrected from NIFF 6a, where start time and duration had been marked as RATIONAL.

See Also:

ChunkLengthTable.MidiDataStream

multiNodeEndOfSyst

public static final Tag multiNodeEndOfSyst

Used on a node of a multi-node symbol to indicate that the symbol continues on the following system. The node containing this tag will always be paired with a node with the Multi-node Start Of System tag, located at the beginning of the following system. A reading program that does not have a system break at the same measure can ignore both nodes and use just the logical start and end nodes of the multi-node symbol.

Multi-system multi-node symbols.

When a multi-node symbol crosses a system boundary, two special tags are used: the Multi-node End Of System tag, and the Multi-node Start Of System tag. These are required because the reading program might not have a system break in the same location as the writing program, and thus might not require these extra nodes. It can ignore all nodes with these tags if desired.

An example of the use of these tags is when a tie extends from the last note on one system to the first note in the following system. In this case the tie symbol will contain an extra pair of nodes, one at the end of the first system and one at the start of the next. All four nodes are assigned the same ID.

In the following example, the tie's Multi-node End Of System node is anchored to the Barline chunk at the end of the first system. The tie's Multi-node Start Of System node is anchored to the current time-slice, optionally with a negative horizontal placement.

Diagram D
[the end of system barline was accidentally omitted from this diagram]

Example:

(System 1)

Time-slice, type=event, start-time=3/4
Stem
Notehead, staff step=5, duration=1/4
Tie, ID=1, Number of Nodes=4
Time-Slice,type=event, start-time=4/4
Barline
Tie, ID=1, Anchor Override=Barline, Multi-node End Of System

(System 2)

Time-slice, type=measure-start, start-time=16/4
Clef, shape=F clef, staff step=6
Time-slice, type=event, start-time=0/4
Tie, ID=1, Anchor Override=Time-Slice, Multi-node Start Of System
Stem
Notehead, staff step=5, duration=1/4
Tie, ID=1

Multi-node End Of System	EMPTY	0x19

multiNodeStartOfSyst

public static final Tag multiNodeStartOfSyst

Used on a node of a multi-node symbol to indicate that this is the continuation of a symbol which started on the previous system. See multiNodeEndOfSyst tag for more details.

Multi-node Start Of System	EMPTY	0x1A

numStaffLines

public static final Tag numStaffLines

Non-default number of lines in a staff, used on the Staff Header. (The default number is 5.) For example, a value of 6 would be used for guitar tablature, or a value of 1 for some percussion parts.

Number of Staff Lines	BYTE	0x1D

numberOfFlags

public static final Tag numberOfFlags

Number of flags on stemmed note.

Number of Flags	BYTE	0x1B

numberOfNodes

public static final Tag numberOfNodes

Total number of nodes in file for this multi-node symbol. Always present on the first node chunk of any multi-node symbol.

Number Of Nodes	SHORT	0x1C

numberStyle

public static final Tag numberStyle

No data.

Number Style	BYTE	0x2E
		numstyleDefault = 0, numstyleFirstNumOnly = 1, numstyle2NumsWithColon = 2, numstyleNumString = 3, numstyleNoNumber = 4

ossia

public static final Tag ossia

Used on one or more Staff Header chunks in a system to indicate an alternate performance of another staff or staves. The Part ID and/or Voice ID of the symbols in the ossia staff or staves duplicate those in the staff or staves to which the ossia is an alternative.

An ossia is to be stored as one or more additional Staff chunks within a System list, each labelled with an Ossia tag applied to the Staff Header chunk. The presence of the Ossia tag indicates that this is an alternate performance of the symbols in one or more other staves. The part and voice of the ossia staves' symbols must be marked (individually, or by a shorthand method), to indicate which parts and voices it represents an alternative to.

The value of the ossia tag indicates whether the ossia or the non-ossia alternative is to sound during playback. (The choice may be given to the user, or may depend on the capabilities of the notation software.

Additional tags which might be added to the Staff Header for an ossia are the placement tags and the Width tag, indicating a shorted staff that starts partway into the measure.

Ossia	BYTE	0x1E
		0 = do not playback the ossia - for display only 1 = playback the ossia instead of the staff to which it is an alternative

partDescOverride

public static final Tag partDescOverride

Used with Part ID on any chunk where Part ID can be specified, such as a Tag Activate/Inactivate, Staff Header or a music symbol chunk. It overrides the default characteristics of the part given in the Setup Section Part Description chunk. Its scope depends on the chunk type on which it appears.

Part Description Override	STRUCT	0x1F
		MIDI channel SIGNEDBYTE Use -1 to specify none. MIDI cable SIGNEDBYTE Use -1 to specify none. transpose SIGNEDBYTE Number of halfsteps to transpose this part during playback.

partID

public static final Tag partID

Used to associate chunks in the Data Section with a particular Part Description chunk in the Setup Section When used on a Staff Header chunk, it indicates that all symbols within the Staff list belong to the part. It can also be used on a Tag Activate or Tag Inactivate chunk to restrict the scope of those chunks (see general discussion of Tag Activate/Inactivate).

Part ID	SHORT	0x20
		0-32767. When this tag is applied to an anchor, its scope includes all symbols dependent on the anchor.

refPtOverride

public static final Tag refPtOverride

Description of non-default reference points on the anchor and dependent symbols. Always used in combination with either Absolute Placement or Logical Placement tags.

Reference Point Override	STRUCTURE	0x21
		anchor h BYTE dependent h BYTE 0 = the symbol's default horizontal reference 1 = left of symbol's bounding box 2 = right of the symbol's bounding box 3 = horizontal center of the symbol's bounding box anchor v BYTE dependent v BYTE 0 = the symbol's default vertical reference 1 = top of symbol's bounding box 2 = bottom of the symbol's bounding box 3 = vertical center of the symbol's bounding box

rehearsalOffset

public static final Tag rehearsalOffset

Used on the Part Description chunk, to specify the default vertical placement of the rehearsal mark with respect to the top staff of the part, in absolute units. In the Data Section, Rehearsal Mark chunks are interspersed with the music symbols of the first (top) staff of the part.

See ChunkLengthTable.NiffInfo for a discussion of Absolute Units.

Rehearsal Mark Offset	SHORT	0x22

restNumeral

public static final Tag restNumeral

Number that is to appear centered over multiple-measure rest symbol.

Rest Numeral	SHORT	0x23

silent

public static final Tag silent

When this tag is used, the sound is suppressed for the symbol. The function of the symbol is other wise unchanged: it appears visibly in the score, and its duration is set as normal for use by a spacing algorithm. A cue note is one example of its use.

Silent	EMPTY	0x24

slashedStem

public static final Tag slashedStem

Indicates the presence of a slash on a stem, as in a grace note. For Tremolo slashes, use a ChunkLengthTable.Tremolo chunk.

Slashed Stem	EMPTY	0x25

smallSize

public static final Tag smallSize

Indicates that the symbol is smaller than default size. Examples of its use are on a Clef chunk for clef changes, on a Stem, Notehead or Rest chunk with the Grace Note tag for small grace notes, and on a Stem, Notehead or Rest with the Silent tag, to indicate a cue note or rest. For more precise control of size, use the Font ID tag instead.

Small Size	EMPTY	0x26

spacingByPart

public static final Tag spacingByPart

This tag is added to the NIFF Information chunk to indicate that a special horizontal spacing scheme is used. In this scheme, the symbols of each part are assigned horizontal placement values independently of the other parts, as though the file contained a set of part scores instead of or in addition to one ensemble score.

Each part's symbols are stored with the minimum size requirement for displaying those symbols when only that part is present. To produce correct spacing of an ensemble score recorded with this scheme, a reading program would calculate for each time-slice the greatest required width among any of the parts, and use that width for the whole ensemble at that time-slice.

A reading program that does not handle this type of spacing scheme should ignore horizontal placement completely, using its own spacing defaults instead.

Spacing By Part	EMPTY	0x27

See Also:

ChunkLengthTable.NiffInfo

splitStem

public static final Tag splitStem

Used on each Notehead chunk of an altered unison, when a single stem connects two or more notes, usually at the same staff step but different horizontal placements that are more than one notewidth apart. The exact visual appearance depends on the reading program's defaults.

Split Stem	EMPTY	0x28

staffName

public static final Tag staffName

Used on a Text chunk to indicate its function as a name for a staff or staff grouping. This allows the reading program to use intelligent defaults for placement of the text, when no placement tag is supplied. For a staff name, this tag should appear on a Text chunk following a Staff Header chunk. For a grouping name, it should appear on a Text chunk following a Staff Grouping chunk in a Staff Groupings list (in either the Setup Section or the Data Section).

The Part Description chunk has fields for part name and part abbreviation. These can be used by the reading program as the names to be placed to the left of the system identifying the parts. This would be easiest in simple scores, where there is a clear correspondence between parts and staves and each Staff Header chunk has a Part ID tag to identify it. The part name font in the Default Values chunk can be used by the reading program for these simple part names and abbreviations.

In more complex cases, the writing program can use more precision in describing the function and placement of text to appear to the left of the system. An individual label can be specified for either a staff or a staff grouping. For instance, it is possible to give the label "Horns" to a brace connecting a pair of horn staves, one labeled "1-3" and the other "4-6." To create a label for a staff or staff grouping, the writing program should use the Staff Name tag on Text chunks stored in the appropriate context. The placement tag and Font ID tag may also be used.

For a staff name, a Text chunk with the Staff Name tag should be stored following a Staff Header chunk. Its placement, if specified, would be given relative to the staff's origin. For a grouping name, a Text chunk with the Staff Name tag should be stored following a Staff Grouping chunk in a Staff Groupings list (in either the Setup Section or the Data Section). Its placement, if specified, would then be given relative to the staff origin of the top staff of the grouping.

Staff Name	EMPTY	0x29

See Also:

ChunkLengthTable.Part

staffStep

public static final Tag staffStep

Used to indicate vertical placement using the "staff step" units of measurement. Places the symbol's vertical hot spot on the specified staff line or space. If used with Logical Placement or Absolute Placement, it overrides the vertical component of those tags. When used on a chunk that has staff step as a required field, such as Notehead or Clef, it overrides the graphical placement of the symbol but not the musical function of the staff step field.

NIFF uses two different measurement systems - absolute units and staff steps.

Absolute units are the writing program's own choice of units, declared in the Setup Section NIFF Information chunk. ChunkLengthTable.NiffInfo

The placement of a symbol whose meaning depends on its vertical position on a staff line or space is given as a staff step. The origin of the staff step system is the bottom line, which is given the value zero. Step numbers increase by one for each successive line or space in an upward direction from the origin. Negative numbers are used for the spaces and ledger lines below the origin.

Staff Step	SIGNEDBYTE (byte)	0x2A

thickness

public static final Tag thickness

Used on symbol chunks such as Barline, Line, Hairpin, or Slur, to indicate the thickness of the line, in absolute units. When used on a Rehearsal Mark symbol, it refers to the thickness of the enclosure (box or circle).

See ChunkLengthTable.NiffInfo for a discussion of Absolute Units.

Thickness	SHORT	0x2B

tieDirection

public static final Tag tieDirection

Used on Tie chunks and simple Slur chunks, to indicating the bow direction of the curve.

Tie Direction	BYTE	0x2C
		1 = endpoints below, rounded above 2 = endpoints above, rounded below

See Also:

ChunkLengthTable.Tie, ChunkLengthTable.Slur

tupletDesc

public static final Tag tupletDesc

Describe a tuplet.

The duration field in a Notehead chunk is the same whether or not the note is included in a tuplet. Additional information (a series of tuplet chunks) is to be stored in the file for each tuplet. The first tuplet chunk contains a transformation ratio to be applied to each note in the tuplet, and graphical information about the appearance of the tuplet such as the presence of numbers and/or brackets.

The tuplet transformation ratio is in the form of 4 integers: a, b, c, and d, where a b-type notes occur in the time of c d-type notes. In conventional usage of tuplets, b and d will be the same, but many musicians use tuplets in an "unconventional" way, and may choose to represent a tuplet as, for example, three half notes in the time of four quarter notes (a, b, c, d = 3, 2, 4, 4).

For example, in the case of half note triplets the transformation ratio in the tuplet chunk is 3:2. When applied to the half note duration on the note chunk (1/2), this would result in an effective duration of 1/3 (1/3= 2/3 * 1/2). The effective duration need not be stored in the file, since it can be calculated by the reading program from values in the note and tuplet chunks.

Tuplet Description	STRUCT	0x2D
		transformation ratio a b RATIONAL transformation ratio c d RATIONAL The four integers in the transformation are applied to the events at each node of the tuplet, as described above. grouping symbol BYTE 0 = default 1 = number only 2 = number with broken slur 3 = number outside slur 4 = number inside slur 5 = number with broken bracket 6 = number outside bracket 7 = number inside bracket 8 = bracket only 9 = slur only 10 = no symbol

See Also:

ChunkLengthTable.Tuplet

userDefined

public static final Tag userDefined

Provide for a user defined tag for vendor-specific expansion.

NIFF users such as commercial software vendors and academic researchers can define their own NIFF tags, to provide for features of their software that are not present in the NIFF specification. NIFF users who want to define their own tags must formally register a unique two byte NIFF User ID, using a protocol yet to be developed.

User-defined tags are identified by a tag ID of 255 (0xFF). The NIFF User ID is stored in the first two bytes of the tagData field. The user defines the structure and value of the remainder of the data portion of the chunk tag. The presence of the size field allows reading programs to ignore unrecognized user-defined tags.

NIFF users should clearly document the structure and function of each user-defined tag. The details of administering a documentation library have yet to be determined.

voiceID

public static final Tag voiceID

Used on music symbols in the Data Section to uniquely identify a voice within the part. As a convention, should be assigned sequentially starting with zero, although voices can appear and disappear at random within a part. Always used in conjunction with Part ID. It can also be used on a Tag Activate or Tag Inactivate chunk to restrict the scope of those chunks (see ChunkLengthTable.TagActivate).

When this tag is applied to an anchor, its scope includes all symbols dependent on the anchor.

Voice ID	SHORT (short)	0x2F
		0-32767.

width

public static final Tag width

Horizontal width, in absolute units. See ChunkLengthTable.NiffInfo for a discussion of Absolute Units.

Width	SHORT (short)	0x30

value

private byte value

Constructor Detail

Tag

public Tag(java.lang.String name,
           int n)

Tag

public Tag(int n)

Tag

public Tag(java.lang.String name)

Method Detail

toString

public static java.lang.String toString(byte b)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(byte b)

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

compareTo

public int compareTo(java.lang.Object obj)

Specified by:

compareTo in interface java.lang.Comparable

write

public void write(java.io.OutputStream s)
           throws java.io.IOException

read

public static Tag read(java.io.InputStream s)
                throws java.io.IOException