Package com.dixshtix.niff

This package is for the manipulation of (Musical) Notation Interchange File Format (NIFF) Files.


Interface Summary
NiffParserListener Implements a simple SAX-like interface to the NIFF file parser.

Class Summary
ChunkLengthTable Defines fixed-length of NIFF file chunks to allow backward compatibility.
CustomGraphicsList The Custom Graphics list is an optional table in the Setup Section that is used to store fonts and custom graphics.
DataSection The part of a NIFF file that contains the music symbols and layout information.
DumpOne Display the contents of a niff file.
DumpTwo Based on code in the Public Domain 1995,1996 by Timothy Butler.
FontDescriptionsList The Font Descriptions list is an optional table in the Setup Section that is composed of a series of Font Description chunks.
Form Top-level RIFX Form for NIFF files.
InfoList One or more of a series of structured comment chunks, as described in the RIFF documentation in the Microsoft Multimedia Programmer's Reference Manual.
NIFF001 Write a simple niff file.
PageList This RIFF LIST is composed of Systems, and page information.
Parser Parse chunk information from a niff file.
Parser.DefaultContext A simple modal class for keeping track of parser state.
PartsList This RIFF LIST is composed of a series of Part Description chunks.
RiffTagRepresentation Title:
SetupSection Contains general information that applies to the whole score.
StaffGroupingsList The Staff Groupings RIFF LIST is a series of Staff Grouping chunks.
StaffList This RIFF LIST is composed of Time-Slices, musical symbols, and additional information.
SystemList This RIFF LIST is composed of Staffs, and page information.
Tag A mechanism for adding variable-length tags binary data to a RIFF file.
ToMidi Dump chunk information about a niff file.
ToXML Dump chunk information about a niff file.

Package com.dixshtix.niff Description

This package is for the manipulation of (Musical) Notation Interchange File Format (NIFF) Files.

Historical Background

The NIFF project began in February 1994, with a meeting between technical people representing three major music notation programs (Encore, Score, Finale) and three music scanning programs (MidiScan, SightReader, NoteScan). The group's goal was to define a new standard format for exchange of music notation data, which everyone agreed was long overdue in the industry.

In January of 1995, Coda, publisher of Encore, pulled out to be replaced by Mark of the Unicorn, Twelve Tone Systems, Opcode Systems and TAP Music Systems/MusicWare as financial sponsors. This package is based on NIFF version 6a, revision 3, drafted on October 15, 1988 and described as on the verge of achieving this goal. This library was begun in October, 2000.


NIFF is a file format designed to allow the interchange of music notation data between and among music notation editing and publishing programs and music scanning programs. Music notation is a complex language, always changing, sometimes ambiguous, sometimes redundant, and used by many people for many purposes. It was realized that it was impossible to create a perfect single model for music notation, but NIFF was designed to provide a solid, practical, usable format, which may exclude some unusual situations but be preferable to no solution.

The NIFF format follows the design rules of the RIFF structure from Microsoft. In NIFF, an additional type of data item known as a "tag" has been defined as an integral part of the format. Tags are used for adding optional elements to the required part of a chunk. Although not part of the standard RIFF design, tags can be described within RIFF's logical definition language.

The same NIFF format definition can be used on all architectures, with the first four bytes of a NIFF file indicating a RIFF file in Motorola (big-endian) format (ASCII bytes 'RIFX'). All 16- or 32-bit quantities in this file are in big-endian format, which is also Java's native format.

Logical, Graphical and Performance (MIDI) Data

Researchers Severo Ornstein and John Maxwell found that the computer representation of music notation has three distinct components only partially related to each other: logical, graphical, and performance (MIDI) information. NIFF designers have found it useful to further subdivide the graphical information into page layout and non-page layout information.

The only information that NIFF absolutely requires is the logical kind. NIFF is structured as a page-ordered format, but can accomodate writing programs without access to page layout information and systems like DARMS, which allows even non-page-layout graphical information such as stem direction to be absent.

When complete graphical information is present in a NIFF file, the reading program can decide between

  1. observing the page layout and other positioning information,
  2. ignoring graphical information in favor of its own defaults, or
  3. some intelligent combination.
When any graphical information is absent from a NIFF file, the reading program is expected to provide its own intelligent defaults.

It is recommended that the user of the NIFF writing and reading programs be given as much control as possible. The user should decide the level of detail stored in the file by the writing program, and the degree of freedom used in interpretation by the reading program.

Additionally, NIFF allows thorough linking of MIDI data and notation.

Logical Structure

There are some terms commonly found in discussions of music notation which most musicians intuitively understand. These terms have a specific usage in the context of NIFF files.

Each NIFF file contains one score. A score could hold anything from a one-bar music example, to a song, a piano sonata movement, or a movement of a symphony in full score. A work in more than one movement would normally be stored with each movement in its own NIFF file.
A stream of musical events and associated symbols, text and graphics which can be extracted and printed on a part score for and individual performer. A part may contain music to be played sequentially on different related instruments by the same performer (e.g. oboe/English horn). The maximum number of staves used for display is defined for each part.
A rhythmically independent stream of musical events within a part, and its associated symbols, text and graphics. Voices can appear and disappear at any time within a part.
The visual framework on a page, where symbols representing simultaneous events in the various parts are more or less vertically aligned. All parts of the score are logically present in every system, although some may be "hidden."
An arrangement of parallel horizontal lines serving as the locale for displaying musical symbols. It is a sort of vessel within a system into which musical symbols can be "poured." Displayed on it are musical symbols, text and graphics belonging to one or more parts.
The mechanism by which a specific point in time is identified in the score. Musical symbols representing simultaneous events are logically grouped within the same time-slice. The music symbols in a NIFF file are physically grouped by page and staff, so symbols belonging to a common logical time-slice may be physically separated in the file. Horizontal placement can be optionally supplied for a time=slice.

There are two types of time-slice: measure-start and event. The measure-start time-slice identifies the start time of a measure with respect to the start of the score. The event time-slice identifies the start time of an event such as a note or rest with respect to the start of the measure.

Example 1:
In a Mahler symphony score there are three trumpet parts. In one system, the trumpets appear on three separate staffs, because they are playing a complex cannon. In another system, they appear all together on one staff, called "Tpts. 1, 2, 3" because they are playing homophonic music. They are written as chords, with 3 notes on one stem.

In the logical view, the notes played by the trumpets belong to three separate parts.

In the physical view of the canonic system, each trumpet part is assigned its own staff. Each staff is labelled with its own name, "Tpt. 1", "Tpt. 2", "Tpt 3".

In the physical view of the homophonic system, the three parts are combined together into a single staff, labelled "Tpts. 1,2,3." The simultaneous notes of each chord played by the three trumpet parts appear together with a single stem within a time-slice. Each note indicates the part to which it belongs.

Example 2:
Consider a score with divisi writing where the first violin part is temporarily divided into groups. The first violin is split onto two separate staves in one system and three separate staves in another system. There are a variety of ways this could be represented in NIFF. The choice depends on the desired result when the parts are to be extracted and printed for individual players.
  1. If the first violin part score is to show all the divisi parts, the first violin should be defined as a single part with three voices and a maximum number of staves of three. The notes of this part would be distributed among the one, two, or three active voices, each voice presented on its own staff.
  2. If separate part scores are to be printed for different first violin players, more than one first violin part should be defined in the NIFF file. All the musical symbols that are to be printed on a particular part score would have that part number indicated. If the same passage is to be printed on two different part scores, both part numbers should be indicated for each symbol within the passage.

Physical Structure

A NIFF file is divided into two sections - the SetupSection, containing general information that applies to the whole score, and the DataSection, containing the music symbols and layout information.

Data Types

The same data types are used in both chunk and tag definitions. Currently defined data types are described below.
NIFF data types
TypeJava TypeDescription
BYTEbye (promoted to short & 0xff)a 1 byte unsigned integer
SIGNEDBYTEbytea 1 byte signed integer
CHARbytea 1 byte character value
SHORTshorta 2 byte signed integer
LONGinta 4 byte signed integer
FOURCCFourByteConstanta 4 byte ASCII character value
RATIONAL2 ints (numerator and denominator)2 2 byte signed integers (numerator and denominator)
STROFFSETinta 2 byte signed integer pointing to a RIFF ZSTR in the String Table chunk in the Setup Section. A RIFF ZSTR is a series of ASCII characters followed by a terminating null. -1 means a null pointer. Embedded zero bytes are not allowed within a ZSTR.
FONTPTRinta 2 byte pointer to a Font Description chunk in the Font Descriptions list.
EMPTYvoid0 bytes. This is used for chunk types for which there are no required elements, and tags whose full meaning is conveyed by the tag ID.

N.B. Time did not permit full development of an International String Table in time for NIFF 6a. This would be a Setup Section chunk that would allow character strings to be stored for fonts that require two bytes for each character code, such as Chinese, Japanese, or Korean. An associated data type would be required to reference strings in this table, as well as an International Text chunk containing a field with this data type. Other enhancements to the format to make use of this feature have not been fully investigated. It is possible that this feature could be developed in the future.