node-serum2-preset-packager
Version:
Xfer Serum 2 Preset Packager for NodeJS
63 lines (61 loc) • 2.99 kB
text/typescript
/**
* @fileoverview Utilities for **packing** and **unpacking** Xfer Serum preset
* (`*.SerumPreset`) files.
*
* The binary layout, reconstructed from the reference Python implementation, is:
*
* ```
* ┌───────────────┬────────────────────────────────────────────────────────┐
* │ Offset (hex) │ Description │
* ├───────────────┼────────────────────────────────────────────────────────┤
* │ 00 │ MAGIC = "XferJson\0" (9 bytes, ASCII) │
* │ 09 │ JSON length (u32 LE) │
* │ 0D │ Reserved (u32 LE, always 0) │
* │ 11 │ Metadata (UTF-8 JSON, `JSON length` bytes) │
* │ … │ CBOR length (u32 LE) │
* │ … │ Flags (u32 LE, 2 ⇒ Zstandard compressed) │
* │ … │ Data (zstd-compressed CBOR, `CBOR length` bytes) │
* └───────────────┴────────────────────────────────────────────────────────┘
* ```
*
* All multi-byte integers are little-endian. The helpers below abstract the
* repeated 32-bit-LE conversions; the public API is exposed through the
* {@link unpack} and {@link pack} functions.
*
* @author (c) 2025 — Charles Brébant
* @license MIT
*/
/**
* **Unpack** a proprietary Xfer Serum preset file (`*.SerumPreset`) into a
* plain-text JSON document.
*
* The resulting JSON structure:
*
* ```jsonc
* {
* "metadata": { /* original metadata *\/ },
* "data": { /* decoded synth state *\/ }
* }
* ```
*
* @param srcPath Path to the binary `.SerumPreset` file.
* @param dstPath Destination path for the generated JSON file.
*
* @throws {Error} If the magic header is incorrect or if the decompressed CBOR
* length does not match the length declared in the header.
*/
declare function unpack(srcPath: string, dstPath: string): Promise<void>;
/**
* **Pack** a JSON description (produced by {@link unpack}) back into a
* binary `*.SerumPreset`.
*
* @param srcPath Path to the source JSON file.
* @param dstPath Destination path for the compiled preset.
*
* @remarks
* - Compression level is fixed to **3**, mirroring the reference Python
* implementation for deterministic output.
* - Unknown header flags are left untouched for forward compatibility.
*/
declare function pack(srcPath: string, dstPath: string): Promise<void>;
export { pack, unpack };