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
révision de page: 3, édité la dernière fois: 26 May 2020 18:06