ts-flp 1.0.5 → 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,489 @@
+/**
+ * FL Studio .flp file parser and serializer
+ * Conservative patch approach: preserves all unknown data byte-for-byte
+ *
+ * Event payload sizes follow the deterministic FL Studio event ranges,
+ * including explicit overrides for known format exceptions.
+ */
+/**
+ * Represents a single event in an FLP file
+ * Stores raw bytes to enable conservative patching
+ */
+interface FlpEvent {
+    /** Event ID (0-255) */
+    id: number;
+    /** Data type classification */
+    kind: 'u8' | 'i8' | 'u16' | 'i16' | 'u32' | 'i32' | 'f32' | 'text' | 'data' | 'unknown';
+    /** Original header bytes (ID + size for variable-length events) */
+    header: Buffer;
+    /** Event payload data */
+    payload: Buffer;
+}
+/**
+ * Represents a parsed FLP file
+ * Contains all data needed for conservative round-trip
+ */
+interface ParsedFlp {
+    /** FLhd chunk (header) - 14 bytes total */
+    headerChunkBytes: Buffer;
+    /** FLdt chunk header (magic + size placeholder) - 8 bytes */
+    fldtHeaderBytes: Buffer;
+    /** All events from the FLdt chunk */
+    events: FlpEvent[];
+    /** Any trailing bytes after events (should be empty) */
+    trailingBytes: Buffer | undefined;
+    /** Detected FL version for string encoding */
+    flVersion: string;
+    /** Whether to use UTF-16LE for strings (FL >= 11.5) */
+    useUnicode: boolean;
+}
+/**
+ * Parses an FL Studio project file
+ *
+ * @param buffer - Raw file data
+ * @returns Parsed FLP structure
+ * @throws Error if file is corrupted or invalid
+ */
+declare function parseFlp(buffer: Buffer): ParsedFlp;
+/**
+ * Serializes a parsed FLP back to a buffer
+ * Recalculates FLdt chunk size if events have changed
+ *
+ * @param parsed - Parsed FLP structure
+ * @returns Serialized buffer
+ */
+declare function serializeFlp(parsed: ParsedFlp): Buffer;
+/**
+ * Creates a new event with the given ID and payload.
+ *
+ * For TEXT/DATA events (id >= 192) the header includes a VarInt size prefix.
+ * For BYTE/WORD/DWORD events the header is a single byte (the event ID).
+ */
+declare function createEvent(id: number, payload: Buffer): FlpEvent;
+/**
+ * Applies a patcher function to all events
+ * Returns a new ParsedFlp with patched events
+ *
+ * @param parsed - Original parsed FLP
+ * @param patcher - Function that transforms each event
+ * @returns New ParsedFlp with patched events
+ */
+declare function patchEvents(parsed: ParsedFlp, patcher: (event: FlpEvent, index: number) => FlpEvent): ParsedFlp;
+/**
+ * Finds all events with a specific ID
+ */
+declare function findEvents(parsed: ParsedFlp, eventId: number): FlpEvent[];
+/**
+ * Finds the first event with a specific ID
+ */
+declare function findFirstEvent(parsed: ParsedFlp, eventId: number): FlpEvent | undefined;
+/**
+ * Gets event payload as a string (handles encoding)
+ */
+declare function getEventString(event: FlpEvent, useUnicode: boolean): string;
+/**
+ * Creates a text payload with proper encoding
+ */
+declare function createTextPayload(text: string, useUnicode: boolean): Buffer;
+/**
+ * Gets event payload as a number
+ */
+declare function getEventNumber(event: FlpEvent): number;
+/**
+ * Creates a numeric payload
+ */
+declare function createNumberPayload(value: number, kind: 'u8' | 'i8' | 'u16' | 'i16' | 'u32' | 'i32' | 'f32'): Buffer;
+
+/**
+ * High-level API for reading and modifying FL Studio project files
+ * Provides typed access to project metadata, samples, plugins, and time info
+ */
+
+/**
+ * Project metadata (name, description, artist, genre, BPM)
+ */
+interface ProjectMeta {
+    name: string | null;
+    description: string | null;
+    artist: string | null;
+    genre: string | null;
+    bpm: number | null;
+}
+/**
+ * Reads project metadata from a parsed FLP
+ */
+declare function readProjectMeta(parsed: ParsedFlp): ProjectMeta;
+/**
+ * Writes project metadata to a parsed FLP
+ * Only modifies fields that are provided (non-undefined)
+ */
+declare function writeProjectMeta(parsed: ParsedFlp, meta: Partial<ProjectMeta>): ParsedFlp;
+/**
+ * Project creation date and work time
+ */
+interface ProjectTimeInfo {
+    creationDate: Date | null;
+    workTimeSeconds: number | null;
+}
+/**
+ * Reads project time info from a parsed FLP
+ * Timestamp event contains: Float64 created_on (days), Float64 time_spent (days)
+ */
+declare function readProjectTimeInfo(parsed: ParsedFlp): ProjectTimeInfo;
+/**
+ * Writes project time info to a parsed FLP
+ * Only modifies fields that are provided (non-undefined)
+ *
+ * If `creationDate` or `workTimeSeconds` is set to `null`, the final value will be set on `0` (Delphi epoch)
+ */
+declare function writeProjectTimeInfo(parsed: ParsedFlp, info: Partial<ProjectTimeInfo>): ParsedFlp;
+/**
+ * Reference to a sample in the project
+ */
+interface SampleRef {
+    /** Index of the event in the events array */
+    eventIndex: number;
+    /** File path of the sample */
+    path: string;
+}
+/**
+ * Lists all samples in the project
+ */
+declare function listSamples(parsed: ParsedFlp): SampleRef[];
+/**
+ * Rewrites sample paths using a mapper function
+ */
+declare function rewriteSamplePaths(parsed: ParsedFlp, mapper: (oldPath: string) => string): ParsedFlp;
+/**
+ * Reference to a plugin in the project
+ */
+interface PluginRef {
+    /** Plugin name (may be null if not available) */
+    name: string | null;
+    /** Plugin vendor/provider (may be null if not stored in file) */
+    vendor: string | null;
+}
+/**
+ * Lists all plugins (VST and native) in the project
+ * Returns plugin name and vendor where available
+ */
+declare function listPlugins(parsed: ParsedFlp): PluginRef[];
+/**
+ * Gets the FL Studio version string from the project
+ */
+declare function getFlVersion(parsed: ParsedFlp): string;
+/**
+ * Gets the PPQ (Pulses Per Quarter note) from the header
+ */
+declare function getPPQ(parsed: ParsedFlp): number;
+
+/**
+ * Event IDs used by FL Studio project files
+ * Based on PyFLP's event definitions
+ */
+declare const EVENT_ID: {
+    readonly PROJECT_LOOP_ACTIVE: 9;
+    readonly PROJECT_SHOW_INFO: 10;
+    readonly PROJECT__VOLUME: 12;
+    readonly PROJECT_PAN_LAW: 23;
+    readonly PROJECT_LICENSED: 28;
+    readonly PROJECT__TEMPO_COARSE: number;
+    readonly PROJECT_PITCH: number;
+    readonly PROJECT__TEMPO_FINE: number;
+    readonly PROJECT_CUR_GROUP_ID: number;
+    readonly PROJECT_TEMPO: number;
+    readonly PROJECT_FL_BUILD: number;
+    readonly PROJECT_TITLE: number;
+    readonly PROJECT_COMMENTS: number;
+    readonly PROJECT_URL: number;
+    readonly PROJECT__RTF_COMMENTS: number;
+    readonly PROJECT_FL_VERSION: number;
+    readonly PROJECT_LICENSEE: number;
+    readonly PROJECT_DATA_PATH: number;
+    readonly PROJECT_GENRE: number;
+    readonly PROJECT_ARTISTS: number;
+    readonly PROJECT_TIMESTAMP: number;
+    readonly CHANNEL_IS_ENABLED: 0;
+    readonly CHANNEL__VOL_BYTE: 2;
+    readonly CHANNEL__PAN_BYTE: 3;
+    readonly CHANNEL_ZIPPED: 15;
+    readonly CHANNEL_PING_PONG_LOOP: 20;
+    readonly CHANNEL_TYPE: 21;
+    readonly CHANNEL_ROUTED_TO: 22;
+    readonly CHANNEL_IS_LOCKED: 32;
+    readonly CHANNEL_NEW: 64;
+    readonly CHANNEL_FREQ_TILT: number;
+    readonly CHANNEL_FX_FLAGS: number;
+    readonly CHANNEL_CUTOFF: number;
+    readonly CHANNEL__VOL_WORD: number;
+    readonly CHANNEL__PAN_WORD: number;
+    readonly CHANNEL_PREAMP: number;
+    readonly CHANNEL_FADE_OUT: number;
+    readonly CHANNEL_FADE_IN: number;
+    readonly CHANNEL_RESONANCE: number;
+    readonly CHANNEL_STEREO_DELAY: number;
+    readonly CHANNEL_POGO: number;
+    readonly CHANNEL_TIME_SHIFT: number;
+    readonly CHANNEL_CHILDREN: number;
+    readonly CHANNEL_SWING: number;
+    readonly CHANNEL_RING_MOD: number;
+    readonly CHANNEL_CUT_GROUP: number;
+    readonly CHANNEL_ROOT_NOTE: number;
+    readonly CHANNEL_DELAY_MOD_XY: number;
+    readonly CHANNEL_REVERB: number;
+    readonly CHANNEL__STRETCH_TIME: number;
+    readonly CHANNEL_FINE_TUNE: number;
+    readonly CHANNEL_SAMPLER_FLAGS: number;
+    readonly CHANNEL_LAYER_FLAGS: number;
+    readonly CHANNEL_GROUP_NUM: number;
+    readonly CHANNEL_AU_SAMPLE_RATE: number;
+    readonly CHANNEL__NAME: 192;
+    readonly CHANNEL_SAMPLE_PATH: number;
+    readonly CHANNEL_DELAY: number;
+    readonly CHANNEL_PARAMETERS: number;
+    readonly CHANNEL_ENVELOPE_LFO: number;
+    readonly CHANNEL_LEVELS: number;
+    readonly CHANNEL_POLYPHONY: number;
+    readonly CHANNEL_TRACKING: number;
+    readonly CHANNEL_LEVEL_ADJUSTS: number;
+    readonly CHANNEL_AUTOMATION: number;
+    readonly PLUGIN_COLOR: 128;
+    readonly PLUGIN_ICON: number;
+    readonly PLUGIN_INTERNAL_NAME: number;
+    readonly PLUGIN_NAME: number;
+    readonly PLUGIN_WRAPPER: number;
+    readonly PLUGIN_DATA: number;
+    readonly DISPLAY_GROUP_NAME: number;
+    readonly RACK_SWING: 11;
+    readonly RACK__FIT_TO_STEPS: 13;
+    readonly RACK_WINDOW_HEIGHT: number;
+    readonly MIXER_SLOT_INDEX: number;
+    readonly MIXER_INSERT_ICON: number;
+    readonly MIXER_INSERT_OUTPUT: number;
+    readonly MIXER_INSERT_COLOR: number;
+    readonly MIXER_INSERT_INPUT: number;
+    readonly MIXER_INSERT_NAME: number;
+    readonly MIXER_INSERT_ROUTING: number;
+    readonly MIXER_INSERT_FLAGS: number;
+};
+/**
+ * Event data type classification
+ */
+type EventKind = 'u8' | 'i8' | 'u16' | 'i16' | 'u32' | 'i32' | 'f32' | 'text' | 'data' | 'unknown';
+/**
+ * Maps event IDs to their data type
+ * Used for proper serialization/deserialization
+ */
+declare const EVENT_KIND: Record<number, EventKind>;
+/**
+ * Determines the event kind based on ID
+ * Falls back to range-based detection if not explicitly mapped
+ */
+declare function getEventKind(eventId: number): EventKind;
+/**
+ * Returns the fixed size for BYTE/WORD/DWORD events
+ * Returns -1 for variable-length events (TEXT/DATA)
+ */
+declare function getEventFixedSize(eventId: number): number;
+
+/**
+ * Binary reader for FL Studio .flp files
+ * Uses smart-buffer for binary reading and protobufjs for VarInt decoding
+ */
+declare class BinaryReader {
+    private sb;
+    private source;
+    constructor(buffer: Buffer);
+    /**
+     * Returns current read position
+     */
+    tell(): number;
+    /**
+     * Seeks to an absolute position
+     */
+    seek(pos: number): void;
+    /**
+     * Seeks relative to current position
+     */
+    skip(offset: number): void;
+    /**
+     * Returns total buffer length
+     */
+    length(): number;
+    /**
+     * Returns remaining bytes to read
+     */
+    remaining(): number;
+    /**
+     * Returns true if there are more bytes to read
+     */
+    hasMore(): boolean;
+    /**
+     * Reads an unsigned 8-bit integer
+     */
+    readU8(): number;
+    /**
+     * Reads a signed 8-bit integer
+     */
+    readI8(): number;
+    /**
+     * Reads an unsigned 16-bit integer (little-endian)
+     */
+    readU16LE(): number;
+    /**
+     * Reads a signed 16-bit integer (little-endian)
+     */
+    readI16LE(): number;
+    /**
+     * Reads an unsigned 32-bit integer (little-endian)
+     */
+    readU32LE(): number;
+    /**
+     * Reads a signed 32-bit integer (little-endian)
+     */
+    readI32LE(): number;
+    /**
+     * Reads a 32-bit float (little-endian)
+     */
+    readF32LE(): number;
+    /**
+     * Reads a 64-bit float (little-endian)
+     */
+    readF64LE(): number;
+    /**
+     * Reads raw bytes
+     */
+    readBytes(length: number): Buffer;
+    /**
+     * Reads a VarInt (variable-length integer) using protobufjs
+     * FL Studio uses this encoding for TEXT and DATA event sizes
+     */
+    readVarInt(): number;
+    /**
+     * Reads an ASCII string (null-terminated)
+     */
+    readAsciiString(length: number): string;
+    /**
+     * Reads a UTF-16LE string (null-terminated)
+     */
+    readUtf16LEString(length: number): string;
+    /**
+     * Peeks at bytes without advancing position
+     */
+    peek(length: number): Buffer;
+    /**
+     * Peeks at a single byte without advancing position
+     */
+    peekU8(): number;
+    /**
+     * Returns the internal buffer
+     */
+    toBuffer(): Buffer;
+}
+
+/**
+ * Binary writer for FL Studio .flp files
+ * Uses smart-buffer for binary writing and protobufjs for VarInt encoding
+ */
+declare class BinaryWriter {
+    private sb;
+    constructor();
+    /**
+     * Returns current write position (total bytes written)
+     */
+    tell(): number;
+    /**
+     * Writes an unsigned 8-bit integer
+     */
+    writeU8(value: number): void;
+    /**
+     * Writes a signed 8-bit integer
+     */
+    writeI8(value: number): void;
+    /**
+     * Writes an unsigned 16-bit integer (little-endian)
+     */
+    writeU16LE(value: number): void;
+    /**
+     * Writes a signed 16-bit integer (little-endian)
+     */
+    writeI16LE(value: number): void;
+    /**
+     * Writes an unsigned 32-bit integer (little-endian)
+     */
+    writeU32LE(value: number): void;
+    /**
+     * Writes a signed 32-bit integer (little-endian)
+     */
+    writeI32LE(value: number): void;
+    /**
+     * Writes a 32-bit float (little-endian)
+     */
+    writeF32LE(value: number): void;
+    /**
+     * Writes a 64-bit float (little-endian)
+     */
+    writeF64LE(value: number): void;
+    /**
+     * Writes raw bytes
+     */
+    writeBytes(data: Buffer): void;
+    /**
+     * Writes a VarInt (variable-length integer) using protobufjs
+     * FL Studio uses this encoding for TEXT and DATA event sizes
+     */
+    writeVarInt(value: number): void;
+    /**
+     * Writes an ASCII string (null-terminated)
+     */
+    writeAsciiString(str: string): void;
+    /**
+     * Writes a UTF-16LE string (null-terminated)
+     */
+    writeUtf16LEString(str: string): void;
+    /**
+     * Gets the final buffer
+     */
+    toBuffer(): Buffer;
+}
+/**
+ * Encodes a VarInt to a Buffer using protobufjs (standalone utility)
+ */
+declare function encodeVarInt(value: number): Buffer;
+/**
+ * Calculates the byte size needed for a VarInt
+ */
+declare function varIntSize(value: number): number;
+
+interface SampleInspectionOptions {
+    mode?: 'resolve' | 'check';
+    projectPath?: string;
+    projectRoot?: string;
+    /** Explicit roots for DAW-specific relative reference types. */
+    relativeRoots?: Readonly<Record<string, string>>;
+    /** Recursive discovery only; basename matches never establish media identity. */
+    searchRoots?: readonly string[];
+    signal?: AbortSignal;
+    concurrency?: number;
+    maxSearchEntries?: number;
+}
+type SampleStatus = 'unchecked' | 'found' | 'missing' | 'unresolved' | 'ambiguous' | 'inaccessible';
+interface SampleCandidate {
+    path: string;
+    source: 'declared' | 'relative' | 'search';
+    confidence: 'exact' | 'name-only';
+}
+interface SampleInspection {
+    referenceIndex: number;
+    recordedPath: string;
+    pathType: 'posix' | 'windows' | 'relative' | 'daw' | 'unknown';
+    relativePath: string | null;
+    candidates: SampleCandidate[];
+    resolvedPath: string | null;
+    status: SampleStatus;
+    reason: string | null;
+}
+
+declare function inspectSamples(parsed: ParsedFlp, options?: SampleInspectionOptions): Promise<SampleInspection[]>;
+
+export { BinaryReader, BinaryWriter, EVENT_ID, EVENT_KIND, type FlpEvent, type ParsedFlp, type PluginRef, type ProjectMeta, type ProjectTimeInfo, type SampleCandidate, type SampleInspection, type SampleInspectionOptions, type SampleRef, type SampleStatus, createEvent, createNumberPayload, createTextPayload, encodeVarInt, findEvents, findFirstEvent, getEventFixedSize, getEventKind, getEventNumber, getEventString, getFlVersion, getPPQ, inspectSamples, listPlugins, listSamples, parseFlp, patchEvents, readProjectMeta, readProjectTimeInfo, rewriteSamplePaths, serializeFlp, varIntSize, writeProjectMeta, writeProjectTimeInfo };

package/dist/index.d.ts

@@ -34,4 +34,6 @@ export { getFlVersion, getPPQ, listPlugins, listSamples, readProjectMeta, readPr
 export { EVENT_ID, EVENT_KIND, getEventFixedSize, getEventKind } from "./src/generated/events.generated.js";
 export { BinaryReader } from "./src/io/BinaryReader.js";
 export { BinaryWriter, encodeVarInt, varIntSize } from "./src/io/BinaryWriter.js";
+export { inspectSamples } from './src/api/inspectSamples.js';
+export type { SampleInspectionOptions, SampleInspection, SampleCandidate, SampleStatus } from './src/samples/inspectReferences.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EACL,WAAW,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,UAAU,EAC/D,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EACnH,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,YAAY,EACZ,MAAM,EACN,WAAW,EACX,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,SAAS,EACf,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAG5G,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EACL,WAAW,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,UAAU,EAC/D,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EACnH,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,YAAY,EACZ,MAAM,EACN,WAAW,EACX,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,SAAS,EACf,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAG5G,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGlF,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,YAAY,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC"}