tserato 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# pyserato-ts
+
+TypeScript port of pyserato (https://github.com/laker-93/pyserato/).
+
+## Write Crates
+
+```
+// example/testEncoder.ts
+import { Builder, Crate, Track, V2Mp3Encoder, HotCue, HotCueType } from "tserato"
+
+async function main() {
+  // create encoder + builder
+  const mp3Encoder = new V2Mp3Encoder();
+  const builder = new Builder(mp3Encoder);
+
+  // create crate
+  const crate = new Crate("foojs");
+
+  // add track
+  const track = Track.fromPath("/Users/lukepurnell/test music/Russian Circles - Gnosis/Russian Circles - Gnosis - 06 Betrayal.mp3");
+  crate.addTrack(track);
+
+  // add cues
+  track.addHotCue(
+    new HotCue({
+      name: "mycue1",
+      type: HotCueType.CUE,
+      start: 500,
+      index: 1,
+    })
+  );
+  track.addHotCue(
+    new HotCue({
+      name: "mycue2",
+      type: HotCueType.CUE,
+      start: 1000,
+      index: 2,
+    })
+  );
+
+  track.addHotCue(
+    new HotCue({
+      name: "myloop1",
+      type: HotCueType.LOOP,
+      start: 2000,
+      end: 3000,
+      index: 3,
+    })
+  );
+
+  // save crate (writes .crate file + tags)
+  await builder.save(crate, undefined, true);
+
+  console.log("Crate saved successfully!");
+}
+
+main().catch(console.error);
+
+```
+
+## Write Cues
+
+```
+import { Builder, Crate, Track, V2Mp3Encoder, HotCue, HotCueType } from "tserato"
+
+async function main() {
+  // create encoder + builder
+  const mp3Encoder = new V2Mp3Encoder();
+  const builder = new Builder(mp3Encoder);
+
+  // create crate
+  const crate = new Crate("foojs");
+
+  // add track
+  const track = Track.fromPath("/Users/lukepurnell/test music/Russian Circles - Gnosis/Russian Circles - Gnosis - 06 Betrayal.mp3");
+  crate.addTrack(track);
+
+  // add cues
+  track.addHotCue(
+    new HotCue({
+      name: "mycue1",
+      type: HotCueType.CUE,
+      start: 500,
+      index: 1,
+    })
+  );
+  track.addHotCue(
+    new HotCue({
+      name: "mycue2",
+      type: HotCueType.CUE,
+      start: 1000,
+      index: 2,
+    })
+  );
+
+  track.addHotCue(
+    new HotCue({
+      name: "myloop1",
+      type: HotCueType.LOOP,
+      start: 2000,
+      end: 3000,
+      index: 3,
+    })
+  );
+
+  // save crate (writes .crate file + tags)
+  await builder.save(crate, undefined, true);
+
+  console.log("Crate saved successfully!");
+}
+
+main().catch(console.error);
+```

package/dist/builder.d.ts

@@ -0,0 +1,15 @@
+import { BaseEncoder } from './encoders/baseEncoder';
+import { Crate } from './model/crate';
+export declare class Builder {
+    private _encoder?;
+    constructor(encoder?: BaseEncoder);
+    private static _resolvePath;
+    private static _parseCrateNames;
+    private _buildCrateFilepath;
+    parseCratesFromRootPath(subcratePath: string): Record<string, Crate>;
+    private _buildCratesFromFilepath;
+    private _parseCrateTracks;
+    private _construct;
+    save(root: Crate, savePath?: string, overwrite?: boolean): void;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAMtC,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,CAAc;gBACnB,OAAO,CAAC,EAAE,WAAW;IAEjC,OAAO,CAAC,MAAM,CAAE,YAAY;IAc5B,OAAO,CAAC,MAAM,CAAE,gBAAgB;IAKhC,OAAO,CAAE,mBAAmB;IAQ5B,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAiBpE,OAAO,CAAC,wBAAwB;IAqBhC,OAAO,CAAE,iBAAiB;IAkB1B,OAAO,CAAC,UAAU;IA2DlB,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,GAAE,MAA8B,EAAE,SAAS,UAAQ;CAO9E"}

package/dist/builder.js

@@ -0,0 +1,187 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Builder = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crate_1 = require("./model/crate");
+const track_1 = require("./model/track");
+const util_1 = require("./util");
+const DEFAULT_SERATO_FOLDER = path.join(process.env.HOME || process.cwd(), 'Music', '_Serato_');
+class Builder {
+    constructor(encoder) { this._encoder = encoder; }
+    static *_resolvePath(root) {
+        let pathStr = '';
+        const stack = [[root, pathStr]];
+        while (stack.length) {
+            const [crate, p] = stack.pop();
+            let newPath = p + `${crate.name}%%`;
+            const children = crate.children;
+            if (children && children.length) {
+                for (const child of children)
+                    stack.push([child, newPath]);
+            }
+            yield [crate, newPath.replace(/%%$/, '') + '.crate'];
+        }
+    }
+    static *_parseCrateNames(filepath) {
+        const parts = path.basename(filepath).split('%%');
+        for (const p of parts)
+            yield p.replace('.crate', '');
+    }
+    *_buildCrateFilepath(crate, seratoFolder) {
+        const subcrateFolder = path.join(seratoFolder, 'SubCrates');
+        if (!fs.existsSync(subcrateFolder))
+            fs.mkdirSync(subcrateFolder, { recursive: true });
+        for (const [c, p] of Builder._resolvePath(crate)) {
+            yield [c, path.join(subcrateFolder, p)];
+        }
+    }
+    parseCratesFromRootPath(subcratePath) {
+        const result = {};
+        const entries = fs.readdirSync(subcratePath);
+        for (const name of entries) {
+            if (!name.endsWith('crate'))
+                continue;
+            const full = path.join(subcratePath, name);
+            const crate = this._buildCratesFromFilepath(full);
+            if (result[crate.name]) {
+                const merged_crate = crate.plus(result[crate.name]);
+                result[crate.name] = merged_crate;
+            }
+            else {
+                result[crate.name] = crate;
+            }
+        }
+        return result;
+    }
+    _buildCratesFromFilepath(filepath) {
+        const crateNames = Array.from(Builder._parseCrateNames(filepath));
+        let childCrate = null;
+        let crate = null;
+        for (const crateName of crateNames.reverse()) {
+            if (childCrate == null) {
+                crate = new crate_1.Crate(crateName);
+                for (const filePath of this._parseCrateTracks(filepath)) {
+                    const t = track_1.Track.fromPath(filePath);
+                    crate.addTrack(t);
+                }
+                childCrate = crate;
+            }
+            else {
+                crate = new crate_1.Crate(crateName, [childCrate]);
+                childCrate = crate;
+            }
+        }
+        if (!crate)
+            throw new Error(`no crates parsed from ${filepath}`);
+        return crate;
+    }
+    *_parseCrateTracks(filepath) {
+        let buffer = fs.readFileSync(filepath);
+        buffer = Buffer.from(buffer);
+        while (buffer.length > 0) {
+            const otrkIdx = buffer.indexOf(Buffer.from('otrk'));
+            if (otrkIdx < 0)
+                break;
+            const ptrkIdx = buffer.indexOf(Buffer.from('ptrk'), otrkIdx);
+            if (ptrkIdx < 0)
+                break;
+            const ptrkSection = buffer.slice(ptrkIdx);
+            const trackNameLength = ptrkSection.readUInt32BE(4);
+            const trackNameEncoded = ptrkSection.slice(8, 8 + trackNameLength);
+            let filePath = (0, util_1.seratoDecode)(trackNameEncoded);
+            if (!filePath.startsWith('/'))
+                filePath = '/' + filePath;
+            yield filePath;
+            buffer = ptrkSection.slice(8 + trackNameLength);
+        }
+    }
+    _construct(crate) {
+        // ----- HEADER -----
+        let header = (0, util_1.concatBytes)([
+            (0, util_1.latin1Encode)("vrsn"),
+            (0, util_1.intToBytes)(0, 1),
+            (0, util_1.intToBytes)(0, 1),
+            (0, util_1.seratoEncode)("81.0"),
+            (0, util_1.seratoEncode)("/Serato ScratchLive Crate"),
+        ]);
+        // ----- DEFAULT COLUMNS -----
+        const DEFAULT_COLUMNS = ["track", "artist", "album", "length"];
+        const parts = [];
+        for (const column of DEFAULT_COLUMNS) {
+            parts.push((0, util_1.latin1Encode)("ovct"));
+            parts.push((0, util_1.intToBytes)(column.length * 2 + 18, 4));
+            parts.push((0, util_1.latin1Encode)("tvcn"));
+            parts.push((0, util_1.intToBytes)(column.length * 2, 4));
+            parts.push((0, util_1.seratoEncode)(column));
+            parts.push((0, util_1.latin1Encode)("tvcw"));
+            parts.push((0, util_1.intToBytes)(2, 4));
+            parts.push((0, util_1.latin1Encode)("0"));
+            parts.push((0, util_1.latin1Encode)("0"));
+        }
+        const columnSection = (0, util_1.concatBytes)(parts);
+        // ----- PLAYLIST SECTION -----
+        const playlistParts = [];
+        if (crate.tracks) {
+            for (const track of crate.tracks) {
+                if (this._encoder) {
+                    this._encoder.write(track);
+                }
+                const absoluteTrackPath = path.resolve(track.path);
+                const otrkSize = (0, util_1.intToBytes)(absoluteTrackPath.length * 2 + 8, 4);
+                const ptrkSize = (0, util_1.intToBytes)(absoluteTrackPath.length * 2, 4);
+                playlistParts.push((0, util_1.latin1Encode)("otrk"));
+                playlistParts.push(otrkSize);
+                playlistParts.push((0, util_1.latin1Encode)("ptrk"));
+                playlistParts.push(ptrkSize);
+                playlistParts.push((0, util_1.seratoEncode)(absoluteTrackPath));
+            }
+        }
+        const playlistSection = (0, util_1.concatBytes)(playlistParts);
+        // ----- FINAL CONTENTS -----
+        const contents = (0, util_1.concatBytes)([header, columnSection, playlistSection]);
+        return contents;
+    }
+    save(root, savePath = DEFAULT_SERATO_FOLDER, overwrite = false) {
+        for (const [crate, filepath] of this._buildCrateFilepath(root, savePath)) {
+            if (fs.existsSync(filepath) && !overwrite)
+                continue;
+            const buffer = this._construct(crate);
+            fs.writeFileSync(filepath, buffer);
+        }
+    }
+}
+exports.Builder = Builder;

package/dist/encoders/baseEncoder.d.ts

@@ -0,0 +1,8 @@
+import { Track } from '../model/track';
+export declare abstract class BaseEncoder {
+    abstract get tagName(): string;
+    abstract get tagVersion(): Buffer;
+    abstract get markersName(): string;
+    abstract write(track: Track): void;
+}
+//# sourceMappingURL=baseEncoder.d.ts.map

package/dist/encoders/baseEncoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseEncoder.d.ts","sourceRoot":"","sources":["../../src/encoders/baseEncoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,8BAAsB,WAAW;IAC/B,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC;IAC/B,QAAQ,KAAK,UAAU,IAAI,MAAM,CAAC;IAClC,QAAQ,KAAK,WAAW,IAAI,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CACnC"}

package/dist/encoders/baseEncoder.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseEncoder = void 0;
+class BaseEncoder {
+}
+exports.BaseEncoder = BaseEncoder;

package/dist/encoders/serato_tags.d.ts

@@ -0,0 +1,5 @@
+export declare const SERATO_MARKERS_V2 = "Serato Markers2";
+export declare const SERATO_OVERVIEW = "Serato Overview";
+export declare const SERATO_MARKERS_V1 = "Serato Markers_";
+export declare const SERATO_ANALYSIS = "Serato Analysis";
+//# sourceMappingURL=serato_tags.d.ts.map

package/dist/encoders/serato_tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serato_tags.d.ts","sourceRoot":"","sources":["../../src/encoders/serato_tags.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AACnD,eAAO,MAAM,eAAe,oBAAoB,CAAC;AACjD,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AACnD,eAAO,MAAM,eAAe,oBAAoB,CAAC"}

package/dist/encoders/serato_tags.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERATO_ANALYSIS = exports.SERATO_MARKERS_V1 = exports.SERATO_OVERVIEW = exports.SERATO_MARKERS_V2 = void 0;
+exports.SERATO_MARKERS_V2 = 'Serato Markers2';
+exports.SERATO_OVERVIEW = 'Serato Overview';
+exports.SERATO_MARKERS_V1 = 'Serato Markers_';
+exports.SERATO_ANALYSIS = 'Serato Analysis';

package/dist/encoders/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function encode(data: Buffer): Buffer;
+export declare function decode(data: Buffer): Buffer;
+//# sourceMappingURL=utils.d.ts.map

package/dist/encoders/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/encoders/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS3C;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS3C"}

package/dist/encoders/utils.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encode = encode;
+exports.decode = decode;
+function encode(data) {
+    const a = data.readUInt8(0);
+    const b = data.readUInt8(1);
+    const c = data.readUInt8(2);
+    const z = c & 0x7F;
+    const y = ((c >> 7) | (b << 1)) & 0x7F;
+    const x = ((b >> 6) | (a << 2)) & 0x7F;
+    const w = a >> 5;
+    return Buffer.from([w, x, y, z]);
+}
+function decode(data) {
+    const w = data.readUInt8(0);
+    const x = data.readUInt8(1);
+    const y = data.readUInt8(2);
+    const z = data.readUInt8(3);
+    const c = (z & 0x7F) | ((y & 0x01) << 7);
+    const b = ((y & 0x7F) >> 1) | ((x & 0x03) << 6);
+    const a = ((x & 0x7F) >> 2) | ((w & 0x07) << 5);
+    return Buffer.from([a, b, c]);
+}

package/dist/encoders/v2/v2Mp3Encoder.d.ts

@@ -0,0 +1,21 @@
+import { HotCue } from '../../../src/model/hotCue';
+import { Track } from '../../model/track';
+import { BaseEncoder } from '../baseEncoder';
+export declare class V2Mp3Encoder extends BaseEncoder {
+    get tagName(): string;
+    get tagVersion(): Buffer;
+    get markersName(): string;
+    write(track: Track): void;
+    readCues(track: Track): HotCue[];
+    private _decode;
+    private _removeNullPadding;
+    private _getEntryName;
+    private _padEncodedData;
+    private _write;
+    private _encode;
+    private _pad;
+    private _removeEncodedDataPad;
+    private _padPayload;
+    private _enrichPayload;
+}
+//# sourceMappingURL=v2Mp3Encoder.d.ts.map

package/dist/encoders/v2/v2Mp3Encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2Mp3Encoder.d.ts","sourceRoot":"","sources":["../../../src/encoders/v2/v2Mp3Encoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAEnD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAiC7C,qBAAa,YAAa,SAAQ,WAAW;IAE3C,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAKzB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE;IAoBhC,OAAO,CAAE,OAAO;IAmDhB,OAAO,CAAC,kBAAkB;IAK1B,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,MAAM;IAkCd,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,cAAc;CASvB"}

package/dist/encoders/v2/v2Mp3Encoder.js

@@ -0,0 +1,197 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.V2Mp3Encoder = void 0;
+const hotCue_1 = require("../../../src/model/hotCue");
+const hotCueType_1 = require("../../model/hotCueType");
+const baseEncoder_1 = require("../baseEncoder");
+const serato_tags_1 = require("../serato_tags");
+const mp3tag_js_1 = __importDefault(require("mp3tag.js"));
+const util_1 = require("../../util");
+const fs = require('fs');
+/**
+ * Replacement for Python's BytesIO
+ */
+class BufferReader {
+    constructor(buffer) {
+        this.buffer = buffer;
+        this.offset = 0;
+    }
+    read(n) {
+        const chunk = this.buffer.slice(this.offset, this.offset + n);
+        this.offset += n;
+        return chunk;
+    }
+    readUInt8() {
+        const value = this.buffer.readUInt8(this.offset);
+        this.offset += 1;
+        return value;
+    }
+    readUInt32BE() {
+        const value = this.buffer.readUInt32BE(this.offset);
+        this.offset += 4;
+        return value;
+    }
+}
+class V2Mp3Encoder extends baseEncoder_1.BaseEncoder {
+    get tagName() {
+        return serato_tags_1.SERATO_MARKERS_V2;
+    }
+    get tagVersion() {
+        return Buffer.from([0x01, 0x01]);
+    }
+    get markersName() {
+        return "Serato Markers2";
+    }
+    write(track) {
+        const payload = this._encode(track);
+        this._write(track, payload);
+    }
+    readCues(track) {
+        // Read the buffer of an audio file
+        const buffer = fs.readFileSync(track.path.toString());
+        // Now, pass it to MP3Tag
+        const mp3tag = new mp3tag_js_1.default(buffer, true);
+        mp3tag.read();
+        const geob = mp3tag.tags.v2?.GEOB;
+        if (!geob || !geob) {
+            return [];
+        }
+        const data = Buffer.from(geob[0].object);
+        return Array.from(this._decode(data));
+    }
+    *_decode(data) {
+        const fp = new BufferReader(data);
+        // Expect version 0x01, 0x01
+        const a = fp.readUInt8();
+        const b = fp.readUInt8();
+        if (a !== 0x01 || b !== 0x01) {
+            throw new Error("Invalid Serato markers header");
+        }
+        const payload = fp.read(data.length - 2);
+        let processed = this._removeNullPadding(payload);
+        processed = this._padEncodedData(processed);
+        const decoded = Buffer.from(processed.toString(), "base64");
+        const fp2 = new BufferReader(decoded);
+        const a2 = fp2.readUInt8();
+        const b2 = fp2.readUInt8();
+        if (a2 !== 0x01 || b2 !== 0x01) {
+            throw new Error("Invalid decoded header");
+        }
+        while (true) {
+            const entryName = this._getEntryName(fp2);
+            if (entryName.length === 0) {
+                break;
+            }
+            const structLength = fp2.readUInt32BE();
+            if (structLength <= 0)
+                throw new Error("Invalid struct length");
+            const entryData = fp2.read(structLength);
+            switch (entryName) {
+                case "COLOR":
+                    // not yet implemented
+                    continue;
+                case "CUE":
+                    yield hotCue_1.HotCue.fromBytes(entryData, hotCueType_1.HotCueType.CUE);
+                    continue;
+                case "LOOP":
+                    yield hotCue_1.HotCue.fromBytes(entryData, hotCueType_1.HotCueType.LOOP);
+                    continue;
+                case "BPMLOCK":
+                    // not yet implemented
+                    continue;
+            }
+        }
+    }
+    _removeNullPadding(payload) {
+        const nullIndex = payload.indexOf(0x00);
+        return nullIndex >= 0 ? payload.slice(0, nullIndex) : payload;
+    }
+    _getEntryName(fp) {
+        const bytes = [];
+        while (true) {
+            const byte = fp.read(1)[0];
+            if (byte === 0x00)
+                break;
+            bytes.push(byte);
+        }
+        return Buffer.from(bytes).toString("utf-8");
+    }
+    _padEncodedData(data) {
+        const len = data.length;
+        let padding;
+        if (len % 4 === 1) {
+            padding = Buffer.from("A==");
+        }
+        else {
+            padding = Buffer.from("=".repeat((-len % 4 + 4) % 4));
+        }
+        return Buffer.concat([data, padding]);
+    }
+    _write(track, payload) {
+        // Read the buffer of an audio file
+        const buffer = fs.readFileSync(track.path.toString());
+        const mp3tag = new mp3tag_js_1.default(buffer, true);
+        mp3tag.read();
+        // Write the ID3v2 tags.
+        // See https://mp3tag.js.org/docs/frames.html for the list of supported ID3v2 frames
+        const object = Array.from(payload);
+        mp3tag.tags.v2.GEOB = [
+            {
+                format: 'application/octet-stream',
+                filename: "",
+                object: object,
+                description: this.markersName,
+            }
+        ];
+        // Save the tags
+        mp3tag.save({ id3v2: { encoding: "latin1" } });
+        // Handle error if there's any
+        if (mp3tag.error !== '')
+            throw new Error(mp3tag.error);
+        // Read the new buffer again
+        mp3tag.read();
+        // Write the new buffer to file
+        fs.writeFileSync(track.path.toString(), mp3tag.buffer);
+    }
+    _encode(track) {
+        let payload = Buffer.alloc(0);
+        for (const cue of track.hotCues) {
+            payload = Buffer.concat([payload, cue.toV2Bytes()]);
+        }
+        for (const cue of track.cueLoops) {
+            payload = Buffer.concat([payload, cue.toV2Bytes()]);
+        }
+        return this._pad(payload);
+    }
+    _pad(payload, entriesCount) {
+        // prepend tag version
+        payload = Buffer.concat([this.tagVersion, payload]);
+        payload = this._removeEncodedDataPad(Buffer.from(payload.toString("base64")));
+        payload = this._padPayload((0, util_1.splitString)(payload));
+        payload = this._enrichPayload(payload, entriesCount);
+        return payload;
+    }
+    _removeEncodedDataPad(data) {
+        return Buffer.from(data.toString().replace(/=/g, "A"));
+    }
+    _padPayload(payload) {
+        const length = payload.length;
+        if (length < 468) {
+            return Buffer.concat([payload, Buffer.alloc(468 - length)]);
+        }
+        return Buffer.concat([payload, Buffer.alloc(982 - length), Buffer.from([0x00])]);
+    }
+    _enrichPayload(payload, entriesCount) {
+        let header = this.tagVersion;
+        if (entriesCount !== undefined) {
+            const buf = Buffer.alloc(4);
+            buf.writeUInt32BE(entriesCount, 0);
+            header = Buffer.concat([header, buf]);
+        }
+        return Buffer.concat([header, payload]);
+    }
+}
+exports.V2Mp3Encoder = V2Mp3Encoder;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Builder } from './builder';
+export { V2Mp3Encoder } from './encoders/v2/v2Mp3Encoder';
+export { Crate } from './model/crate';
+export { Track } from './model/track';
+export { HotCue } from './model/hotCue';
+export { HotCueType } from './model/hotCueType';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HotCueType = exports.HotCue = exports.Track = exports.Crate = exports.V2Mp3Encoder = exports.Builder = void 0;
+var builder_1 = require("./builder");
+Object.defineProperty(exports, "Builder", { enumerable: true, get: function () { return builder_1.Builder; } });
+var v2Mp3Encoder_1 = require("./encoders/v2/v2Mp3Encoder");
+Object.defineProperty(exports, "V2Mp3Encoder", { enumerable: true, get: function () { return v2Mp3Encoder_1.V2Mp3Encoder; } });
+var crate_1 = require("./model/crate");
+Object.defineProperty(exports, "Crate", { enumerable: true, get: function () { return crate_1.Crate; } });
+var track_1 = require("./model/track");
+Object.defineProperty(exports, "Track", { enumerable: true, get: function () { return track_1.Track; } });
+var hotCue_1 = require("./model/hotCue");
+Object.defineProperty(exports, "HotCue", { enumerable: true, get: function () { return hotCue_1.HotCue; } });
+var hotCueType_1 = require("./model/hotCueType");
+Object.defineProperty(exports, "HotCueType", { enumerable: true, get: function () { return hotCueType_1.HotCueType; } });

package/dist/model/crate.d.ts

@@ -0,0 +1,15 @@
+import { Track } from './track';
+export declare class Crate {
+    private _children;
+    readonly name: string;
+    private _tracks;
+    constructor(name: string, children?: Crate[]);
+    get children(): Crate[];
+    get tracks(): Set<Track>;
+    addTrack(track: Track): void;
+    toString(): string;
+    plus(other: Crate): Crate;
+    deepCopy(memodict?: Map<any, any>): Crate;
+    equals(other: Crate): boolean;
+}
+//# sourceMappingURL=crate.d.ts.map

package/dist/model/crate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crate.d.ts","sourceRoot":"","sources":["../../src/model/crate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,qBAAa,KAAK;IAChB,OAAO,CAAC,SAAS,CAAU;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,OAAO,CAAa;gBAEhB,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,KAAK,EAAO;IAMhD,IAAI,QAAQ,IAAI,KAAK,EAAE,CAEtB;IAED,IAAI,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAEvB;IAED,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAO5B,QAAQ,IAAI,MAAM;IAQlB,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;IAazB,QAAQ,CAAC,QAAQ,gBAAsB,GAAG,KAAK;IAa/C,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;CAqB9B"}

package/dist/model/crate.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Crate = void 0;
+const util_1 = require("../util");
+class Crate {
+    constructor(name, children = []) {
+        this._children = [...children];
+        this.name = (0, util_1.sanitizeFilename)(name);
+        this._tracks = new Set();
+    }
+    get children() {
+        return this._children;
+    }
+    get tracks() {
+        return this._tracks;
+    }
+    addTrack(track) {
+        if (this._tracks.has(track)) {
+            throw new util_1.DuplicateTrackError(`track ${track} is already in the crate ${this.name}`);
+        }
+        this._tracks.add(track);
+    }
+    toString() {
+        return `Crate<${this.name}>`;
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return this.toString();
+    }
+    plus(other) {
+        if (this.name !== other.name) {
+            throw new Error("Cannot merge crates with different names");
+        }
+        const childrenCopy = [...this._children, ...other._children].map((c) => c.deepCopy());
+        const merged = new Crate(this.name, childrenCopy);
+        const allTracks = new Set([...this._tracks, ...other._tracks]);
+        for (const track of allTracks) {
+            merged.addTrack(track);
+        }
+        return merged;
+    }
+    deepCopy(memodict = new Map()) {
+        if (memodict.has(this)) {
+            return memodict.get(this);
+        }
+        const childrenCopy = this._children.map((c) => c.deepCopy(memodict));
+        const copy = new Crate(this.name, childrenCopy);
+        memodict.set(this, copy);
+        for (const track of this._tracks) {
+            copy.addTrack(track);
+        }
+        return copy;
+    }
+    equals(other) {
+        if (this.name !== other.name)
+            return false;
+        if (this._tracks.size !== other._tracks.size)
+            return false;
+        // compare tracks by reference equality (like Python set)
+        for (const track of this._tracks) {
+            if (!other._tracks.has(track))
+                return false;
+        }
+        if (this._children.length || other._children.length) {
+            const sortedChildren = [...this._children].sort((a, b) => a._tracks.size - b._tracks.size);
+            const sortedOtherChildren = [...other._children].sort((a, b) => a._tracks.size - b._tracks.size);
+            if (sortedChildren.length !== sortedOtherChildren.length)
+                return false;
+            for (let i = 0; i < sortedChildren.length; i++) {
+                if (!sortedChildren[i].equals(sortedOtherChildren[i]))
+                    return false;
+            }
+        }
+        return true;
+    }
+}
+exports.Crate = Crate;

package/dist/model/hotCue.d.ts

@@ -0,0 +1,28 @@
+import { HotCueType } from './hotCueType';
+import { SeratoColor } from './seratoColor';
+import { Buffer } from 'buffer';
+export interface HotCueData {
+    name: string;
+    type: HotCueType;
+    start: number;
+    index: number;
+    end?: number | null;
+    isLocked?: boolean;
+    color?: SeratoColor;
+}
+export declare class HotCue implements HotCueData {
+    name: string;
+    type: HotCueType;
+    start: number;
+    index: number;
+    end?: number | null;
+    isLocked?: boolean;
+    color: SeratoColor;
+    constructor(data: HotCueData);
+    toString(): string;
+    toV2Bytes(): Buffer;
+    private loopToV2Bytes;
+    private cueToV2Bytes;
+    static fromBytes(data: Buffer, hotcueType: HotCueType): HotCue;
+}
+//# sourceMappingURL=hotCue.d.ts.map

package/dist/model/hotCue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotCue.d.ts","sourceRoot":"","sources":["../../src/model/hotCue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AA6BhC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,qBAAa,MAAO,YAAW,UAAU;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;gBAEP,IAAI,EAAE,UAAU;IAU5B,QAAQ,IAAI,MAAM;IAMlB,SAAS,IAAI,MAAM;IAMnB,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,YAAY;IAiDpB,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM;CAiE/D"}

package/dist/model/hotCue.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HotCue = void 0;
+const hotCueType_1 = require("./hotCueType");
+const seratoColor_1 = require("./seratoColor");
+const buffer_1 = require("buffer");
+function writeNullTerminatedString(str) {
+    const encoder = new TextEncoder();
+    const strBytes = encoder.encode(str);
+    const result = new Uint8Array(strBytes.length + 1); // +1 for null terminator
+    result.set(strBytes, 0);
+    result[strBytes.length] = 0;
+    return result;
+}
+function concatUint8Arrays(arrays) {
+    let totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+    let result = new Uint8Array(totalLength);
+    let offset = 0;
+    arrays.forEach(arr => {
+        result.set(arr, offset);
+        offset += arr.length;
+    });
+    return result;
+}
+function encodeElement(name, data) {
+    const nameBytes = writeNullTerminatedString(name);
+    const lengthBytes = new Uint8Array(4);
+    new DataView(lengthBytes.buffer).setUint32(0, data.length, false); // big endian
+    return concatUint8Arrays([nameBytes, lengthBytes, data]);
+}
+class HotCue {
+    constructor(data) {
+        this.name = data.name;
+        this.type = data.type;
+        this.start = data.start;
+        this.index = data.index;
+        this.end = data.end ?? null;
+        this.isLocked = data.isLocked ?? false;
+        this.color = data.color ?? seratoColor_1.SeratoColor.RED;
+    }
+    toString() {
+        const startStr = `${this.start}ms`;
+        const endStr = this.end != null ? ` | End: ${this.end}ms` : '';
+        return `Start: ${startStr}${endStr} | Index: ${String(this.index).padStart(2)} | Name: ${this.name} | Color: ${this.color}`;
+    }
+    toV2Bytes() {
+        if (this.type === hotCueType_1.HotCueType.CUE)
+            return this.cueToV2Bytes();
+        if (this.type === hotCueType_1.HotCueType.LOOP)
+            return this.loopToV2Bytes();
+        throw new Error(`unsupported hotcue type ${this.type}`);
+    }
+    loopToV2Bytes() {
+        let nameBytes = writeNullTerminatedString(this.name);
+        let buf = new Uint8Array(0x14 + nameBytes.length);
+        let dv = new DataView(buf.buffer);
+        buf[0x0] = 0x00; // flags? (unused in parse)
+        buf[0x1] = this.index;
+        dv.setUint32(0x02, this.start, false);
+        dv.setUint32(0x06, this.end, false);
+        buf[0x0e] = 0;
+        buf[0x0f] = 0;
+        buf[0x10] = 255;
+        buf[0x11] = 255;
+        buf[0x13] = 1;
+        buf.set(nameBytes, 0x14);
+        return buffer_1.Buffer.from(encodeElement("LOOP", buf));
+    }
+    cueToV2Bytes() {
+        const parts = [];
+        // >B (unsigned char, big-endian)
+        parts.push(buffer_1.Buffer.from([0]));
+        // >B self.index
+        parts.push(buffer_1.Buffer.from([this.index]));
+        // >I self.start (4-byte big-endian unsigned int)
+        const startBuf = buffer_1.Buffer.alloc(4);
+        startBuf.writeUInt32BE(this.start, 0);
+        parts.push(startBuf);
+        // >B 0
+        parts.push(buffer_1.Buffer.from([0]));
+        // >3s color (3 raw bytes from hex string)
+        const colorBuf = buffer_1.Buffer.from(this.color, "hex");
+        if (colorBuf.length !== 3) {
+            throw new Error(`Color must be 3 bytes (e.g. "ff0000"), got ${this.color}`);
+        }
+        parts.push(colorBuf);
+        // >B 0
+        parts.push(buffer_1.Buffer.from([0]));
+        parts.push(buffer_1.Buffer.from([1]));
+        parts.push(buffer_1.Buffer.from(this.name, "utf8"));
+        // >B 0 (null terminator after name)
+        parts.push(buffer_1.Buffer.from([0]));
+        const data = buffer_1.Buffer.concat(parts);
+        const lenBuf = buffer_1.Buffer.alloc(4);
+        lenBuf.writeUInt32BE(data.length, 0);
+        const payload = buffer_1.Buffer.concat([
+            buffer_1.Buffer.from("CUE", "ascii"),
+            buffer_1.Buffer.from([0]),
+            lenBuf,
+            data,
+        ]);
+        return payload;
+    }
+    static fromBytes(data, hotcueType) {
+        let offset = 1; // skip first null
+        if (hotcueType === hotCueType_1.HotCueType.CUE) {
+            const index = data.readUInt8(offset);
+            offset += 1;
+            const start = data.readUInt32BE(offset);
+            offset += 4;
+            offset += 1; // skip null / position end
+            offset += 0; // skip placeholder
+            const colorBytes = data.slice(offset, offset + 3);
+            offset += 3;
+            offset += 1; // skip null
+            const locked = data.readUInt8(offset) !== 0;
+            offset += 1;
+            const nameBuf = data.slice(offset).subarray(0, data.slice(offset).indexOf(0));
+            const name = nameBuf.toString("utf-8");
+            const colorHex = colorBytes.toString("hex").toUpperCase();
+            const color = (Object.values(seratoColor_1.SeratoColor).includes(colorHex)
+                ? colorHex
+                : seratoColor_1.SeratoColor.RED);
+            return new HotCue({
+                name,
+                type: hotCueType_1.HotCueType.CUE,
+                index,
+                start,
+                color,
+                isLocked: locked,
+            });
+        }
+        else if (hotcueType === hotCueType_1.HotCueType.LOOP) {
+            const index = data.readUInt8(offset);
+            offset += 1;
+            const start = data.readUInt32BE(offset);
+            offset += 4;
+            const end = data.readUInt32BE(offset);
+            offset += 4;
+            // Skip to offset 0x0E
+            offset = 0x0E;
+            // skip color placeholder bytes (0x0E–0x11)
+            offset += 2; // 0x0E, 0x0F
+            offset += 2; // 0x10, 0x11
+            offset += 1; // 0x12 (padding)
+            const isLocked = Boolean(data.readUInt8(offset));
+            offset += 1;
+            // read null-terminated name
+            const nameEnd = data.indexOf(0x00, offset);
+            const name = data.toString("utf8", offset, nameEnd === -1 ? data.length : nameEnd);
+            return new HotCue({
+                name,
+                type: hotCueType_1.HotCueType.CUE,
+                index,
+                start,
+                end: end,
+                color: seratoColor_1.SeratoColor.RED,
+                isLocked: isLocked,
+            });
+        }
+        else {
+            throw new Error(`Unknown hotcue type: ${hotcueType}`);
+        }
+    }
+}
+exports.HotCue = HotCue;

package/dist/model/hotCueType.d.ts

@@ -0,0 +1,7 @@
+export declare enum HotCueType {
+    CUE = 0,
+    LOOP = 1,
+    INVALID = 99,
+    PASSTHROUGH = 100
+}
+//# sourceMappingURL=hotCueType.d.ts.map

package/dist/model/hotCueType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotCueType.d.ts","sourceRoot":"","sources":["../../src/model/hotCueType.ts"],"names":[],"mappings":"AAAA,oBAAY,UAAU;IACpB,GAAG,IAAI;IACP,IAAI,IAAI;IACR,OAAO,KAAK;IACZ,WAAW,MAAM;CAClB"}

package/dist/model/hotCueType.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HotCueType = void 0;
+var HotCueType;
+(function (HotCueType) {
+    HotCueType[HotCueType["CUE"] = 0] = "CUE";
+    HotCueType[HotCueType["LOOP"] = 1] = "LOOP";
+    HotCueType[HotCueType["INVALID"] = 99] = "INVALID";
+    HotCueType[HotCueType["PASSTHROUGH"] = 100] = "PASSTHROUGH";
+})(HotCueType || (exports.HotCueType = HotCueType = {}));

package/dist/model/seratoColor.d.ts

@@ -0,0 +1,21 @@
+export declare enum SeratoColor {
+    RED = "CC0000",
+    ORANGE = "CC4400",
+    AMBER = "CC8800",
+    YELLOW = "CCCC00",
+    LIME_GREEN = "88CC00",
+    GREEN_YELLOW = "44CC00",
+    GREEN = "00CC00",
+    MINT_GREEN = "00CC44",
+    TEAL_GREEN = "00CC88",
+    TEAL = "00CCCC",
+    SKY_BLUE = "0088CC",
+    BLUE = "0044CC",
+    DARK_BLUE = "0000CC",
+    PURPLE = "4400CC",
+    VIOLET = "8800CC",
+    MAGENTA = "CC00CC",
+    PINK = "CC0088",
+    RED_PINK = "CC0044"
+}
+//# sourceMappingURL=seratoColor.d.ts.map

package/dist/model/seratoColor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seratoColor.d.ts","sourceRoot":"","sources":["../../src/model/seratoColor.ts"],"names":[],"mappings":"AAAA,oBAAY,WAAW;IACrB,GAAG,WAAW;IACd,MAAM,WAAW;IACjB,KAAK,WAAW;IAChB,MAAM,WAAW;IACjB,UAAU,WAAW;IACrB,YAAY,WAAW;IACvB,KAAK,WAAW;IAChB,UAAU,WAAW;IACrB,UAAU,WAAW;IACrB,IAAI,WAAW;IACf,QAAQ,WAAW;IACnB,IAAI,WAAW;IACf,SAAS,WAAW;IACpB,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,OAAO,WAAW;IAClB,IAAI,WAAW;IACf,QAAQ,WAAW;CACpB"}

package/dist/model/seratoColor.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SeratoColor = void 0;
+var SeratoColor;
+(function (SeratoColor) {
+    SeratoColor["RED"] = "CC0000";
+    SeratoColor["ORANGE"] = "CC4400";
+    SeratoColor["AMBER"] = "CC8800";
+    SeratoColor["YELLOW"] = "CCCC00";
+    SeratoColor["LIME_GREEN"] = "88CC00";
+    SeratoColor["GREEN_YELLOW"] = "44CC00";
+    SeratoColor["GREEN"] = "00CC00";
+    SeratoColor["MINT_GREEN"] = "00CC44";
+    SeratoColor["TEAL_GREEN"] = "00CC88";
+    SeratoColor["TEAL"] = "00CCCC";
+    SeratoColor["SKY_BLUE"] = "0088CC";
+    SeratoColor["BLUE"] = "0044CC";
+    SeratoColor["DARK_BLUE"] = "0000CC";
+    SeratoColor["PURPLE"] = "4400CC";
+    SeratoColor["VIOLET"] = "8800CC";
+    SeratoColor["MAGENTA"] = "CC00CC";
+    SeratoColor["PINK"] = "CC0088";
+    SeratoColor["RED_PINK"] = "CC0044";
+})(SeratoColor || (exports.SeratoColor = SeratoColor = {}));

package/dist/model/tempo.d.ts

@@ -0,0 +1,5 @@
+export interface Tempo {
+    position?: number | null;
+    bpm?: number | null;
+}
+//# sourceMappingURL=tempo.d.ts.map

package/dist/model/tempo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tempo.d.ts","sourceRoot":"","sources":["../../src/model/tempo.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB"}

package/dist/model/tempo.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/model/track.d.ts

@@ -0,0 +1,29 @@
+import { HotCue } from './hotCue';
+import { Tempo } from './tempo';
+export declare class Track {
+    path: string;
+    trackId: string;
+    averageBpm: number;
+    dateAdded: string;
+    playCount: string;
+    tonality: string;
+    totalTime: number;
+    beatgrid: Tempo[];
+    hotCues: HotCue[];
+    cueLoops: HotCue[];
+    constructor(trackPath: string, params?: {
+        trackId?: string;
+        averageBpm?: number;
+        dateAdded?: string;
+        playCount?: string;
+        tonality?: string;
+        totalTime?: number;
+        beatgrid?: Tempo[];
+        hotCues?: HotCue[];
+        cueLoops?: HotCue[];
+    });
+    static fromPath(trackPath: string, userRoot?: string): Track;
+    addBeatgridMarker(tempo: Tempo): void;
+    addHotCue(hotCue: HotCue): void;
+}
+//# sourceMappingURL=track.d.ts.map

package/dist/model/track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../../src/model/track.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,qBAAa,KAAK;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAElB,QAAQ,EAAE,KAAK,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;gBAGjB,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KAChB;IAeR,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK;IAK5D,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIrC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAehC"}

package/dist/model/track.js

@@ -0,0 +1,75 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Track = void 0;
+const path = __importStar(require("path"));
+const hotCueType_1 = require("./hotCueType");
+class Track {
+    constructor(trackPath, params = {}) {
+        this.path = trackPath;
+        this.trackId = params.trackId ?? "";
+        this.averageBpm = params.averageBpm ?? 0.0;
+        this.dateAdded = params.dateAdded ?? "";
+        this.playCount = params.playCount ?? "";
+        this.tonality = params.tonality ?? "";
+        this.totalTime = params.totalTime ?? 0.0;
+        this.beatgrid = params.beatgrid ?? [];
+        this.hotCues = params.hotCues ?? [];
+        this.cueLoops = params.cueLoops ?? [];
+    }
+    static fromPath(trackPath, userRoot) {
+        const resolved = userRoot ? path.resolve(userRoot, trackPath) : path.resolve(trackPath);
+        return new Track(resolved);
+    }
+    addBeatgridMarker(tempo) {
+        this.beatgrid.push(tempo);
+    }
+    addHotCue(hotCue) {
+        if (this.hotCues.length >= 8) {
+            throw new Error("cannot have more than 8 hot cues on a track");
+        }
+        if (this.cueLoops.length >= 4) {
+            throw new Error("cannot have more than 4 loops on a track");
+        }
+        const atIndex = hotCue.index;
+        if (hotCue.type === hotCueType_1.HotCueType.LOOP) {
+            this.cueLoops.splice(atIndex, 0, hotCue);
+        }
+        else {
+            this.hotCues.splice(atIndex, 0, hotCue);
+        }
+    }
+}
+exports.Track = Track;

package/dist/util.d.ts

@@ -0,0 +1,11 @@
+import { Buffer } from 'buffer';
+export declare function splitString(input: Buffer, after?: number, delimiter?: Buffer): Buffer;
+export declare function seratoDecode(s: Buffer): string;
+export declare function concatBytes(arrays: Uint8Array[]): Uint8Array;
+export declare function latin1Encode(str: string): Uint8Array;
+export declare function intToBytes(value: number, length: number): Uint8Array;
+export declare function seratoEncode(s: string): Uint8Array;
+export declare function sanitizeFilename(filename: string): string;
+export declare class DuplicateTrackError extends Error {
+}
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,EAAE,SAAS,GAAE,MAA0B,GAAG,MAAM,CAY5G;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CA2B9C;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,CAS5D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAEpD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAOpE;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAWlD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,qBAAa,mBAAoB,SAAQ,KAAK;CAAG"}

package/dist/util.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuplicateTrackError = void 0;
+exports.splitString = splitString;
+exports.seratoDecode = seratoDecode;
+exports.concatBytes = concatBytes;
+exports.latin1Encode = latin1Encode;
+exports.intToBytes = intToBytes;
+exports.seratoEncode = seratoEncode;
+exports.sanitizeFilename = sanitizeFilename;
+const buffer_1 = require("buffer");
+const INVALID_CHARACTERS_REGEX = /[^A-Za-z0-9_ ]/i;
+function splitString(input, after = 72, delimiter = buffer_1.Buffer.from('\n')) {
+    const pieces = [];
+    let buf = buffer_1.Buffer.from(input);
+    while (buf.length > 0) {
+        pieces.push(buf.slice(0, after));
+        buf = buf.slice(after);
+    }
+    return buffer_1.Buffer.concat(pieces.reduce((acc, p, i) => {
+        if (i)
+            acc.push(delimiter);
+        acc.push(p);
+        return acc;
+    }, []));
+}
+function seratoDecode(s) {
+    // Decodes Serato 4-byte blocks into UTF-16-encoded string
+    const out = [];
+    for (let i = 0; i < s.length; i += 4) {
+        const block = s.slice(i, i + 4);
+        if (block.length < 4)
+            break;
+        const w = block.readUInt8(0);
+        const x = block.readUInt8(1);
+        const y = block.readUInt8(2);
+        const z = block.readUInt8(3);
+        const c = (z & 0x7F) | ((y & 0x01) << 7);
+        const b = ((y & 0x7F) >> 1) | ((x & 0x03) << 6);
+        const a = ((x & 0x7F) >> 2) | ((w & 0x07) << 5);
+        out.push(a, b, c);
+    }
+    // Interpret as UTF-16-BE pairs
+    // Convert bytes to string by grouping into 2-byte code units
+    const bytes = buffer_1.Buffer.from(out);
+    let str = '';
+    for (let i = 0; i < bytes.length; i += 2) {
+        const hi = bytes[i];
+        const lo = (i + 1) < bytes.length ? bytes[i + 1] : 0;
+        const code = (hi << 8) | lo;
+        if (code === 0)
+            break;
+        str += String.fromCharCode(code);
+    }
+    return str;
+}
+function concatBytes(arrays) {
+    const totalLength = arrays.reduce((sum, a) => sum + a.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const a of arrays) {
+        result.set(a, offset);
+        offset += a.length;
+    }
+    return result;
+}
+function latin1Encode(str) {
+    return Uint8Array.from(buffer_1.Buffer.from(str, "latin1"));
+}
+function intToBytes(value, length) {
+    const bytes = new Uint8Array(length);
+    for (let i = 0; i < length; i++) {
+        // big-endian
+        bytes[length - 1 - i] = (value >> (8 * i)) & 0xff;
+    }
+    return bytes;
+}
+function seratoEncode(s) {
+    const result = [];
+    for (const c of s) {
+        const codePoint = c.charCodeAt(0); // UTF-16 code unit
+        // Big-endian: high byte first, then low byte
+        result.push((codePoint >> 8) & 0xff);
+        result.push(codePoint & 0xff);
+    }
+    return Uint8Array.from(result);
+}
+function sanitizeFilename(filename) {
+    return filename.replace(INVALID_CHARACTERS_REGEX, '-');
+}
+class DuplicateTrackError extends Error {
+}
+exports.DuplicateTrackError = DuplicateTrackError;

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "tserato",
+  "version": "0.1.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "scripts": {
+    "build": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laker-93/tserato.git"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.1",
+    "typescript": "^5.3.3",
+    "vitest": "^0.34.6"
+  },
+  "dependencies": {
+    "base-64": "^1.0.0",
+    "mp3tag.js": "^3.14.1",
+    "node-id3": "^0.2.6"
+  }
+}