node-serum2-preset-packager/dist/index.d.mts

Xfer Serum 2 Preset Packager for NodeJS

/**
 * @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 };