The paths on this machine the server needs (FL, loopMIDI, FL's Hardware folder, preset libraries), stored in kuruitsugizaki.json. Call it first in a new install, and whenever another tool answers that a key is not set. No arguments: every key with its value or the path detected for it, and whether that path exists. key alone: that key. key and value: set it. Never guess a path or search the disk for one: ask the user where it is, then set it.

Set up the live link to FL. Needed once per install, and again after this folder moves. Close FL first. It does two things: 1) writes FL's controller script into FL's Settings\Hardware folder (config key fl_hardware), with this folder's bridge path in it, replacing an older copy; 2) unless a MIDI input in FL already has the script, makes a loopMIDI port named kuruitsugizaki and assigns the script to it in FL's MIDI settings. Both live in the registry, which FL rewrites when it closes; if FL was open, the answer's midi entry says so and what to do by hand. Returns {ok, installed, bridge, changed, midi, next}. Then start FL and call fl_probe to see the script answer.

Check the live link to FL: returns FL's scripting API version, its embedded Python version, FL's pid and the pipe handle it holds, or an error saying what is missing. Call it first when a live tool (fl_exec, fl_call, fl_transport, project_write with open) fails, and after fl_install. When FL is closed it starts it (and loopMIDI) to test the link and closes it again: launched_fl_seconds says how long FL took, closed_fl that it was closed. Reads nothing from the project.

Call one function of FL's scripting API inside the running FL and return what it returns: {ok, value} or {ok: false, error}. For a single read or change, e.g. a parameter name or a mixer level of the open project. Use fl_exec for several calls or logic; use project_read and project_write for anything the .flp file holds, which need no FL. A setter changes the open project as an edit by hand would; nothing is saved. Needs FL open; it is not started for this.

Run Python inside the running FL's embedded interpreter, where FL's modules (channels, mixer, plugins, transport, patterns, general ...) import. For live reads or changes that need several calls or logic; one call is simpler with fl_call. Returns {ok, value} with what the code assigns to result, or {ok: false, error} with the traceback. FL's sandbox refuses files, sockets and pipes. Changes act on the open project and are not saved. Needs FL open; it is not started for this.

Read one FL Studio .flp file into JSON; FL need not run and the file is not changed. Use it to see what a project holds, to take parts from it, or to check what project_write wrote. For the style across many projects use profile; for the project open in FL right now, fl_exec. Views: 'summary' (start here: instruments, per-pattern stats, a per-track arrangement timeline, the parts sounding in each bar, mixer effects); 'compact' (default: every note and clip as rows, the same shape project_write accepts; notes [bar, beat, tick, len_ticks, key, vel, instrument#], clips [track, bar, beat, tick, len_ticks, src, trim?] where src is a pattern id, s a sample, a an automation clip); 'full' (exact, round-trips byte for byte; large, so narrow it with patterns or arrangements); 'score' (a bar range of the first arrangement as text, one row per step and one column per part, so how the parts line up can be read; bars [first, last]). Fails with the parser's error on a file that is not an .flp.

Write a project document to an .flp file, replacing any file at path. This is how a piece gets made.

The document: the compact form project_read returns, or its full form. The field reference is README.md, 'Project JSON, compact form'; examples/README.md has a working document per feature. Read one before a first write.

Sounds:

• an instrument is a plugin by name (see plugins) with an optional preset, or a channel copied from a saved project, state {from: file, channel: n};

• an effect is mixer.effects {track, slot, plugin} or one copied, {track, slot, from: {file, track, slot}}.

Units that are easy to get wrong: 96 ticks per beat, 4/4; keys like 'D#4' with MIDI 60 = C4; mixer volume 0.8 = 0 dB; a tempo automation value is (bpm - 60) / 120. Mixer inserts run 1-125.

Without open, FL need not run. With open or play, FL first saves the project it has open (so no dialog appears), then opens this one.

Returns the file read back (channels, notes per pattern, clips per arrangement) and the writer's warnings; read them.

Render an .flp to audio: a .wav and .mp3 beside it (replacing earlier ones), then a spectrogram and a short report. Call it after project_write to check a piece. FL renders from the command line, so an FL the harness started is saved first and closed; an FL the user started is left alone and the render refused until they close it. Runs detached and returns at once; a 2-minute piece takes under a minute. Returns {ok, rendering, log, saved_open_project}. Then call render_report(path) until it stops saying the render is running, and make no live call (fl_exec, fl_call, fl_transport) before that: FL is closed while it renders.

Read what fl_render produced: the short report (length, peak, key, the number of parts sounding in each bar, and a flag only where something is found) and the spectrogram picture, as [text, image]. Call it after fl_render; it does not wait, and while the render is still going it says so: call again. With no render on record it answers to call fl_render first; a render that failed comes back as its log. Look at the picture before handing a piece over; the full analysis is in the .txt the report names. FL need not run. It writes into tmp/spectro/ only: a resized picture, and the spectrogram and its .txt again from the .wav when the log has no analysis.

List the plugins this machine has: every plugin in FL's plugin database, and every tuned instance in the optional library project. Call it to choose instruments and effects before project_write; then presets for a plugin's presets, params for its automatable parameters. Each row: name, kind (instrument or effect), vendor, format (native, vst3, clap, vst), source (fl or library), how many presets load by name, whether it has a parameter map. Any of them goes into project_write by name: an instrument as {kind: plugin, plugin: , preset?, format?}, an effect as mixer.effects [{track, slot, plugin: , preset?, format?}]; without a preset it arrives as if dragged in fresh from FL's browser, a library instance as saved. A plugin installed in several formats is one name (native, then vst3, clap, vst unless format is given). By default it lists only VST3 and CLAP plugins; native=true adds FL's own. Reads files only; FL need not run.

List the presets that load by name for one plugin; an id goes into project_write as an instrument's or effect's preset. Call it after plugins, when choosing a sound. Returns {plugin, kind, total, presets}; total counts every match, and when there are more than limit the list is an even spread across the preset folders, each folder an equal share, not the first ones. A plugin name that matches nothing or several plugins returns {ok: false, error} naming the candidates. Reads files only and FL need not run, except with harvest, which opens the plugin in FL and adds its built-in presets to the catalog.

A plugin's automatable parameters, for writing automation: each one's index (the param of an automation target {channel: id, param: index} or {mixer: t, slot: s, param: index}), its name, and what its normalised value means where measured (FL's display at 0, .25, .5, .75 and 1, so a value can be picked for a wanted Hz, dB or %). Call it before automating a plugin or effect knob. It answers only for plugins with a parameter map (plugins shows which); for any other, read names live with fl_call('plugins.getParamName', ...). Not for choosing a sound: plugins lists what is installed, presets a plugin's presets. Reads files only; FL need not run.

Play or stop whatever project is open in the running FL, to hear it; it changes nothing in any file. action 'play' plays from the start, also when called while playing. action 'stop' stops playback. mode 'song' plays the arrangement, 'pattern' loops one pattern (pattern: its number, selected first); without mode FL keeps the one it has. Needs FL open with a project; it is not started for this: open one with project_write(open=true), which can also start playback itself (play='song'). Returns {playing, mode}. To get audio out, use fl_render, which saves and closes FL instead.

List a person's projects from a folder of their .flp files: tempo, key and arrangement length in bars, so you know which to open and read in full with project_read. Reads every .flp under the folder, subfolders included, and changes none of them; FL need not run; about 2 s for 80 projects. Also written as profile.md and profile.json to tmp/profile//. Projects that fail to read are listed, not fatal; a folder with no .flp returns {ok: false, error}. Without folder it reads config projects_folder; when that is not set, ask the user where their own projects are and pass that folder, which is then saved there, so later sessions do not ask again. When they have none, set projects_folder to 'none' with config, and profile then answers that.

List samples for drums, one-shots, loops and breaks; a sample's path (its folder plus its name) goes into project_write as a sampler's or audio clip's path. Call it before choosing any sample, and take samples only from folders the user gave.

No arguments: the user's sample folders, each with its subfolders and how many audio files each holds. With query, the samples whose path matches; with folder, that folder's subfolders and files, and a query stays inside it. Returns {total, results: {folder: [[name, seconds]]}}; past limit the list is an even spread across folders.

When config sample_folders is not set it returns {ok: false, error}: ask the user where their samples are and set it with config (a folder or a JSON list), or 'none' when they have none, which makes FL's factory packs the source; the answer is kept.

Changes no sample file; FL need not run. It caches folder listings in tmp/samples/index/; measure also writes tmp/samples/.tsv.