Skip to content

neumaRk — Datapack

1. Datapack concept

A datapack is the fundamental structural unit of musical content in neumaRk.

It represents a vertical block of musical information synchronized in time, typically corresponding to one or more aligned lines:

  • markers
  • chords
  • notes
  • articulations
  • dynamics
  • lyrics
  • formatting

Each datapack describes a coherent temporal sequence (one or more consecutive measures). Musical datapacks are separated from one another by one or more blank lines, which have structural delimiting value. The presence of a blank line implies the conclusion of the preceding datapack.

2. Line types

Each line in a datapack has a semantic type.

The type may be:

  • explicit, through a marker;
  • implicit, deduced from content and position.

2.1 Explicit line markers

Explicit markers consist of:

  • one, two, or three uppercase letters;
  • followed by );
  • followed by a space.
Marker Type
M) Markers
C) Chords
A) Articulations
N) Notes
D) Dynamics
L) Lyrics
F) Format

Markers are optional.

3. Logical line order (implicit deduction)

In the absence of explicit markers, line types are deduced according to the following logical order:

  1. Markers (at most one line, optional)
  2. Chords
  3. zero or more lines;
  4. the last one is considered the primary chord line
  5. Note groups, each consisting of:
  6. an Articulations line (optional, preceding)
  7. a Notes line (mandatory in the absence of chords)
  8. a Dynamics line (optional, following)
  9. a Lyrics line (optional, last)
  10. Format (at most one line, optional, always last)

4. Datapack validity rules

A datapack is valid if:

  • it contains at least one Notes line or one Chords line;
  • it respects the logical line order;
  • all musical lines are temporally alignable.

A datapack is not valid if:

  • it contains only text lines;
  • it contains a non-final Format line.

5. Barlines and measures

All lines except Format lines:

  • may contain barlines (in their absence, all content belongs to the first measure of the line);
  • implicitly define the subdivision into measures.

5.1 Supported barlines

The supported barline symbols are:

  • | single barline
  • || double barline
  • |. or .| final barline
  • |: repeat start
  • :| repeat end

The final barline symbol must be preceded by a space.

6. Measure decorators

Measure decorators are elements adjacent to a barline and are divided into:

  • BEGIN decorators (to the right of the barline)
  • END decorators (to the left of the barline)

6.1 BEGIN decorators

Placed immediately to the right of the barline.

Supported decorators:

  • Time signature and/or key change

  • enclosed in parentheses;

  • separated by commas;
  • arbitrary order.

Examples:

|(3/4,Dm)
|([3+3+2]/8)

  • Volta endings

  • text enclosed in square brackets;

  • optional +n to indicate duration in measures.

Example:

|[1.]+4
  • $ segno
  • @ coda

If present, time signature and key must precede any other BEGIN decorator.

6.2 END decorators

Placed immediately to the left of the barline.

Supported decorators:

  • $ segno
  • @ coda
  • DC
  • DCal@
  • DCalFINE
  • D$
  • D$al@
  • D$alFINE
  • FINE
  • al@
  • free text enclosed in square brackets (graphical annotation)

7. Markers line

The Markers line:

  • contains markers enclosed in square brackets;
  • markers refer to the beginning of the measure.

If a marker is preceded by a barline:

  • there must be a space between the barline and the marker;
  • to avoid ambiguity with volta decorators.

It is best practice to place flow-related decorators (DC, DS, coda, etc.) in this line.

8. Format line

The Format line may be declared:

  • explicitly, using the F) marker;
  • implicitly, if the line content is unambiguously recognizable as a format line.

If present, the Format line must be:

  • unique per datapack;
  • always the last line of the datapack.

In case of ambiguity with a musical line, the musical interpretation always prevails, and the line is not considered a Format line.

The Format line contains alignment indications:

Symbol Alignment
_ LEFT
\_ RIGHT
* CENTER
** JUSTIFIED (default)

9. Margins between datapacks

A line that:

  • follows a blank line;
  • begins with -;
  • contains only -, spaces, tabs, or %;

indicates a vertical margin between datapacks.

The margin depth is determined by the maximum number of consecutive - characters:

  • - - - → margin 1
  • - -- - → margin 2
  • --- - → margin 3

The % symbol indicates a possible page break.

10. Comments

C-like comments are allowed, both inside and outside datapacks, in single-line (// comment) or multi-line (/* comment ... */) form.