Typescript FLP Library

A minimalist TypeScript library for reading and modifying FL Studio project files (.flp).

Designed for non-destructive modifications ("conservative patch").

Features

• Project metadata: Read and modify name, description, artist, genre, and BPM
• Time information: Read and modify creation date and work time
• Samples: List sample paths and batch rewrite paths
• VST Plugins: List plugins with name and vendor (when available)
• Stable round-trip: Untargeted data remains byte-for-byte identical

Installation

npm install ts-flp
# or
pnpm add ts-flp
# or
yarn add ts-flp

Usage

Reading a project

import { readFileSync, writeFileSync } from 'fs';
import { parseFlp, serializeFlp, readProjectMeta, listSamples, listPlugins } from 'ts-flp';

// Load and parse the .flp file
const buffer = readFileSync('my-project.flp');
const parsed = parseFlp(buffer);

// Read metadata
const meta = readProjectMeta(parsed);
console.log(`Project: ${meta.name}`);
console.log(`Artist: ${meta.artist}`);
console.log(`Genre: ${meta.genre}`);
console.log(`BPM: ${meta.bpm}`);

// List samples
const samples = listSamples(parsed);
for (const sample of samples) {
  console.log(`Sample: ${sample.path}`);
}

// List plugins
const plugins = listPlugins(parsed);
for (const plugin of plugins) {
  console.log(`Plugin: ${plugin.name} (${plugin.vendor ?? 'N/A'})`);
}

Modifying metadata

import { readFileSync, writeFileSync } from 'fs';
import { parseFlp, serializeFlp, writeProjectMeta } from 'ts-flp';

const buffer = readFileSync('my-project.flp');
let parsed = parseFlp(buffer);

// Modify metadata
parsed = writeProjectMeta(parsed, {
  name: 'New Title',
  artist: 'My Name',
  genre: 'Electronic',
  bpm: 140,
});

// Save
writeFileSync('my-project-modified.flp', serializeFlp(parsed));

Rewriting sample paths

import { readFileSync, writeFileSync } from 'fs';
import { parseFlp, serializeFlp, rewriteSamplePaths } from 'ts-flp';

const buffer = readFileSync('my-project.flp');
let parsed = parseFlp(buffer);

// Remap paths (e.g., disk migration)
parsed = rewriteSamplePaths(parsed, (oldPath) => {
  return oldPath.replace('D:\\Samples\\', 'E:\\NewSamples\\');
});

writeFileSync('my-project-migrated.flp', serializeFlp(parsed));

Modifying time information

import { readFileSync, writeFileSync } from 'fs';
import { parseFlp, serializeFlp, readProjectTimeInfo, writeProjectTimeInfo } from 'ts-flp';

const buffer = readFileSync('my-project.flp');
let parsed = parseFlp(buffer);

// Read time info
const timeInfo = readProjectTimeInfo(parsed);
console.log(`Created on: ${timeInfo.creationDate}`);
console.log(`Work time: ${timeInfo.workTimeSeconds} seconds`);

// Modify creation date
parsed = writeProjectTimeInfo(parsed, {
  creationDate: new Date('2024-01-01'),
  workTimeSeconds: 3600, // 1 hour
});

writeFileSync('my-project-modified.flp', serializeFlp(parsed));

API

Main types

interface ProjectMeta {
  name: string | null;
  description: string | null;
  artist: string | null;
  genre: string | null;
  bpm: number | null;
}

interface ProjectTimeInfo {
  creationDate: Date | null;
  workTimeSeconds: number | null;
}

interface SampleRef {
  eventIndex: number;
  path: string;
}

interface PluginRef {
  name: string | null;
  vendor: string | null;
}

Functions

| Function | Description | | ------------------------------------ | -------------------------------------------------- | | parseFlp(buffer) | Parse a .flp buffer into a ParsedFlp structure | | serializeFlp(parsed) | Serialize a ParsedFlp structure to buffer | | readProjectMeta(parsed) | Read project metadata | | writeProjectMeta(parsed, meta) | Modify project metadata | | readProjectTimeInfo(parsed) | Read time information | | writeProjectTimeInfo(parsed, info) | Modify time information | | listSamples(parsed) | List all samples in the project | | rewriteSamplePaths(parsed, mapper) | Batch rewrite sample paths | | listPlugins(parsed) | List all plugins (VST and native) | | getFlVersion(parsed) | Get the FL Studio version string | | getPPQ(parsed) | Get the PPQ (Pulses Per Quarter note) |

Constraints and limitations

What this library does

• Non-destructive read and write of .flp files
• Byte-for-byte preservation of unmodified data
• Compatibility with FL Studio 11.5+ (UTF-16LE strings)

What this library does NOT do

• Full editor for patterns, mixer, playlist, automation
• Create .flp files from scratch
• Guarantee VST vendor availability (returns null if not serialized)
• Support compressed (zipped) .flp files

Architecture

src/
  generated/
    events.generated.ts    # Event constants
  io/
    BinaryReader.ts        # Binary reading
    BinaryWriter.ts        # Binary writing
  parser/
    FlpParser.ts           # .flp Parser/Serializer
  api/
    ProjectApi.ts          # High-level API
  index.ts                 # Entry point

Development

# Install dependencies
pnpm install

# Type checking
pnpm run typecheck

# Tests
pnpm run test

# Build
pnpm run build

Credits

• PyFLP - Reference implementation for FL Studio file format
• smart-buffer - Binary read/write
• protobufjs - VarInt encoding

License

GPL-3.0

Acknowledgements

A huge thank you to @demberto (PyFLP), @monadgroup (FLParser), and FLPEdit for their incredible reverse-engineering work on the FL Studio .flp format.

This project would never have been possible without them.