AyaneFormatSpec

On disk Ayane format specification.

Goals

• Compact
• Easy to serialize
• Easy to parse
• Retro & Futoro-compatible (old version of software can skip optional)
• Generic enough so that some operations could be performed by external tools.
  • • View/edit text fields.
    • Some merges.
• Optionally typed, and not redundant typing.
  • • • Don't repeat type for homogeneous data structures (list, maps, …).
      • Indicate type (self-describing chunk, i.e. schema-less).
      • May omit type when schema is known beforehand.
• Close to existing standards when applicable.

Non-Goals

• Extreme compactness.
• IFF compatibility. Rationale: unlikely to be used on another platform or even another software.
• Complete genericness (self-descriptive). Rationale: idem + critical chunks must be known anyway.

Some common patterns (hu!):

• Short integer ids are used for instruments (0 to 99 for now), tables (0 to 127 for now), clips (0 to 255 for now).
• There can be a lot of gaps (i.e. , so user can use id space as seen fit: e.g. Instrument id >= 64 for samples.
• Each structure can have alternative definitions, numbered from 0.

Implications:

• Each kind (table, instr, clip) would be a map of sequence: {id: [def]}.

Design choices

• VLI: Variable length encoding for integers (e.g. length of data). Rationale:
  • • More efficient size-wise.
    • Close the debate Little/BigEndian, 16 vs 32 bits.
• Critical chunks starts with Uppercase.
• Optional chunks starts with lowercase.

Type

We reserved one byte to indicate the type of the subsequent value.
They are refered below with `t_` prefix (t_unspecified, t_string, …)

• Base
  • 00: unspecified (that is, not explicit on disc, specified externally in the schema)
  • 01: reserved
• integers (nb: type/2 gives size in bytes) —-
  • 02: unsigned byte
  • 03: signed byte
  • 04: unsigned word (16 bits)
  • 05: signed word (16 bits)
  • 06: unsigned 24bits (unused here)
  • 07: signed 24bits (unused here)
  • 08: unsigned 32bits (unused here)
  • 09: signed 32bits (unused here)
• Misc
  • 22, n: string of length n (NB: Strings don't end with \0 since size is specified).
  • 40, id: reference to table.

Format schema

---------+----------------------------------+---------------+
bytes    | Content                          | Notes         |
---------+----------------------------------+---------------+
 4       |  "Aya!"                          | Magic string. |
 5+VLI+n | "info", t_string, n, "text here" | Name of the work and additional info |
 5+VLI+n | "auth", t_string, n, "text here" | Author        |

 5+VLI   | "pots", t_unspecified [a], n     | Settings of the tool itself, that affects edition/display but not the saved module |
========== Pots ================================================
n ** byte | TODO
========== End of pots =========================================

 5+VLI   | "nibs", t_unspecified [a], n     | Global settings of the module (e.g. starting replay speed etc...) |
========== Settings ============================================
n ** byte | settings. TODO
========== End of settings =====================================

 6       | "tabl", t_unspecified [a], 0 [b]      | Tables.
 VLI     | x                                     | x = # of tables. For each table:
========== Table ==================================================
 VLI     | id | Id of the table (0 to 127 for now). 
 VLI     | y  | y= # of alternative. For each alternative:
------ Alternative ------------------------------------------------
 1       | 0              | Reserved for alternative flags.
 VLI+n   | n, "text here" | Annotations/info
 1       | <type>         | Type of elements.
 VLI     | m              | Numbers of elements.
 VLI     | l              | Loop length (0 for no loop). Restart l units from end of table.
 m * ?   | elements       |
 1       | 00             | Reserved for extension.
------- End of Alternative ----------------------------------------
======= End of table ==============================================

 6       | "inst", t_unspecified [a], 0 [b]      | Instruments.
 VLI     | x                                     | x = # of instruments. For each instrument:
========== Instrument =============================================
 VLI     | id | Id of the instrument (0 to 99 for now). 
 VLI     | y  | y= # of alternative. For each alternative:
------ Alternative ------------------------------------------------
 1       | 0              | Reserved for alternative flags.
 VLI+n   | n, "text here" | Annotations/info
 VLI     | m              | Numbers of elements. For each element:
...... Element ...................................
 1       | Id             | Id king / command / fx
 1       | p              | # params. For each param:
______ Param ________
 1       | Type           | 
 ?       | Value          | Size is infered from type.
------- End of Alternative ----------------------------------------
======= End of instrument ==============================================

 6       | "clip", t_unspecified [a], 0 [b]      | Clips.
 VLI     | x                                     | x = # of clips. For each clip:
========== Clip ============================================
 VLI     | id | Id of the clip (0 to 255 for now). 
 VLI     | y  | y= # of alternative. For each alternative:
------ Alternative -----------------------------------------
 1       | 0              | Reserved for alternative flags.
 VLI+n   | n, "text here" | Annotations/info
 VLI     | r              | Numbers of rows. For each row:
...... Row ...................................
 VLI     | d              | d = duration
 1       | flags          | Presence of note/instr/vol/fxs. 
 1       | note           | Only if corresponding flag set.
 1       | instr          | Only if corresponding flag set.
 1       | vol          | Only if corresponding flag set.
 4*?     | fxs            | Encoded as instrument's elements. Only if corresponding flag sets.
------- End of Alternative ----------------------------------
======= End of clip =========================================

 6       | "maps", t_unspecified [a], 0 [b]      | Sequences (aka song maps).
 VLI     | x                                     | x = # of maps. For each map:
========== Map =============================================
 VLI     | id | Id of the map (0 to 99 for now). 
 VLI     | y  | y= # of alternative. For each alternative:
------ Alternative -----------------------------------------
 1       | 0              | Reserved for alternative flags.
 VLI+n   | n, "text here" | Annotations/info
 VLI     | r              | Numbers of rows. For each row:
...... Row ...................................
Like clip row.
------- End of Alternative ----------------------------------
======= End of Map ==========================================

[a] Type is implicit from tag (schema). 00 (unspecified) is put here for uniformity and for future proofing.
[b] Size can be infered from structure. 00 (unspecified) is put here for uniformity and for future proofing.

References

• IFF quick introduction and motivation
• IFF format summary: most common chunks.
• lesson learned
• An IFF proposal for tracker module