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

Sauf mention contraire, le contenu de cette page est protégé par la licence Creative Commons Attribution-ShareAlike 3.0 License