docs: LLM-ready documentation suite — LLM_CONTEXT.md, module deep-dives, JSON schemas, CLI reference
Complete documentation system for LLM consumption: primary LLM_CONTEXT.md (27KB system overview), 4 module deep-dives (composer, reaper-builder, reaper-scripting, calibrator), 2 JSON Schema draft-07 contracts, CLI reference, and README correction (FL Studio -> REAPER identity).
This commit is contained in:
renato97
158
docs/schemas/reascript-protocol.json
Normal file
158
docs/schemas/reascript-protocol.json
Normal file
@@ -0,0 +1,158 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://fl-control/schemas/reascript-protocol.json",
|
||||
"title": "ReaScript Protocol",
|
||||
"description": "Command/result protocol for ReaScript two-way JSON communication",
|
||||
"definitions": {
|
||||
"ReaScriptCommand": {
|
||||
"title": "ReaScriptCommand",
|
||||
"description": "Command sent to the ReaScript via fl_control_command.json",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"version": {
|
||||
"type": "integer",
|
||||
"description": "Protocol version",
|
||||
"default": 1
|
||||
},
|
||||
"action": {
|
||||
"description": "Single action name or pipeline list. Known values: add_plugins, configure_fx_params, verify_fx, calibrate, render",
|
||||
"default": "calibrate",
|
||||
"oneOf": [
|
||||
{ "type": "string" },
|
||||
{
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
}
|
||||
]
|
||||
},
|
||||
"rpp_path": {
|
||||
"type": "string",
|
||||
"description": "Path to .rpp file to open",
|
||||
"default": ""
|
||||
},
|
||||
"render_path": {
|
||||
"type": "string",
|
||||
"description": "Path for rendered WAV output",
|
||||
"default": ""
|
||||
},
|
||||
"timeout": {
|
||||
"type": "integer",
|
||||
"description": "Polling timeout in seconds",
|
||||
"default": 120
|
||||
},
|
||||
"track_calibration": {
|
||||
"type": "array",
|
||||
"description": "Per-track volume/pan/send calibration",
|
||||
"default": [],
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"track_index": { "type": "integer" },
|
||||
"volume": { "type": "number" },
|
||||
"pan": { "type": "number" },
|
||||
"sends": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"dest_track_index": { "type": "integer" },
|
||||
"level": { "type": "number" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"plugins_to_add": {
|
||||
"type": "array",
|
||||
"description": "Each dict: {\"track_name\": str, \"fx_name\": str, \"params\": {\"0\": float, ...}}",
|
||||
"default": [],
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"track_name": { "type": "string" },
|
||||
"fx_name": { "type": "string" },
|
||||
"params": {
|
||||
"type": "object",
|
||||
"additionalProperties": { "type": "number" }
|
||||
}
|
||||
},
|
||||
"required": ["track_name", "fx_name"]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"ReaScriptResult": {
|
||||
"title": "ReaScriptResult",
|
||||
"description": "Result written by the ReaScript to fl_control_result.json",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"version": {
|
||||
"type": "integer",
|
||||
"description": "Protocol version",
|
||||
"default": 1
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"description": "ok | error | timeout",
|
||||
"default": "ok",
|
||||
"enum": ["ok", "error", "timeout"]
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"description": "Error or status message",
|
||||
"default": ""
|
||||
},
|
||||
"lufs": {
|
||||
"type": ["number", "null"],
|
||||
"description": "Integrated LUFS",
|
||||
"default": null
|
||||
},
|
||||
"integrated_lufs": {
|
||||
"type": ["number", "null"],
|
||||
"description": "Integrated LUFS reading",
|
||||
"default": null
|
||||
},
|
||||
"short_term_lufs": {
|
||||
"type": ["number", "null"],
|
||||
"description": "Short-term LUFS",
|
||||
"default": null
|
||||
},
|
||||
"fx_errors": {
|
||||
"type": "array",
|
||||
"description": "FX verification errors. Each dict: {\"track_index\": int, \"fx_index\": int, \"name\": str, \"expected\": str}",
|
||||
"default": [],
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"track_index": { "type": "integer" },
|
||||
"fx_index": { "type": "integer" },
|
||||
"name": { "type": "string" },
|
||||
"expected": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"tracks_verified": {
|
||||
"type": "integer",
|
||||
"description": "Number of tracks verified",
|
||||
"default": 0
|
||||
},
|
||||
"added_plugins": {
|
||||
"type": "array",
|
||||
"description": "Each dict: {\"fx_name\": str, \"instance_id\": int, \"track_name\": str, \"status\": str}",
|
||||
"default": [],
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"fx_name": { "type": "string" },
|
||||
"instance_id": { "type": "integer" },
|
||||
"track_name": { "type": "string" },
|
||||
"status": { "type": "string" }
|
||||
},
|
||||
"required": ["fx_name", "track_name", "status"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
423
docs/schemas/song-definition.json
Normal file
423
docs/schemas/song-definition.json
Normal file
@@ -0,0 +1,423 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://fl-control/schemas/song-definition.json",
|
||||
"title": "SongDefinition",
|
||||
"description": "Complete song definition — the source of truth for one .rpp file",
|
||||
"type": "object",
|
||||
"required": ["meta"],
|
||||
"properties": {
|
||||
"meta": { "$ref": "#/definitions/SongMeta" },
|
||||
"tracks": {
|
||||
"type": "array",
|
||||
"description": "List of REAPER tracks with clips and plugins",
|
||||
"default": [],
|
||||
"items": { "$ref": "#/definitions/TrackDef" }
|
||||
},
|
||||
"patterns": {
|
||||
"type": "array",
|
||||
"description": "Pattern definitions for arrangement",
|
||||
"default": [],
|
||||
"items": { "$ref": "#/definitions/PatternDef" }
|
||||
},
|
||||
"items": {
|
||||
"type": "array",
|
||||
"description": "Arrangement items referencing patterns",
|
||||
"default": [],
|
||||
"items": { "$ref": "#/definitions/ArrangementItemDef" }
|
||||
},
|
||||
"progression_name": {
|
||||
"type": "string",
|
||||
"description": "Chord progression name (e.g. i-VII-VI-VII)",
|
||||
"default": "i-VII-VI-VII"
|
||||
},
|
||||
"section_template": {
|
||||
"type": "string",
|
||||
"description": "Section template name",
|
||||
"default": "standard"
|
||||
},
|
||||
"samples": {
|
||||
"type": "object",
|
||||
"description": "Sample file map (name → filename)",
|
||||
"default": {},
|
||||
"additionalProperties": { "type": "string" }
|
||||
},
|
||||
"sections": {
|
||||
"type": "array",
|
||||
"description": "Section definitions in playback order",
|
||||
"default": [],
|
||||
"items": { "$ref": "#/definitions/SectionDef" }
|
||||
},
|
||||
"master_plugins": {
|
||||
"type": "array",
|
||||
"description": "List of plugin registry keys for master FX chain",
|
||||
"default": [],
|
||||
"items": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"SongMeta": {
|
||||
"title": "SongMeta",
|
||||
"description": "Song metadata — tempo, key, time signature",
|
||||
"type": "object",
|
||||
"required": ["bpm", "key"],
|
||||
"properties": {
|
||||
"bpm": {
|
||||
"type": "number",
|
||||
"description": "Tempo 20–999",
|
||||
"minimum": 20,
|
||||
"maximum": 999
|
||||
},
|
||||
"key": {
|
||||
"type": "string",
|
||||
"description": "Key string e.g. Am, Dm, Gm",
|
||||
"pattern": "^[A-G][b#]?m?$"
|
||||
},
|
||||
"title": {
|
||||
"type": "string",
|
||||
"description": "Song title",
|
||||
"default": ""
|
||||
},
|
||||
"ppq": {
|
||||
"type": "integer",
|
||||
"description": "Ticks per quarter note (REAPER default)",
|
||||
"default": 960
|
||||
},
|
||||
"time_sig_num": {
|
||||
"type": "integer",
|
||||
"description": "Time signature numerator",
|
||||
"default": 4
|
||||
},
|
||||
"time_sig_den": {
|
||||
"type": "integer",
|
||||
"description": "Time signature denominator",
|
||||
"default": 4
|
||||
},
|
||||
"calibrate": {
|
||||
"type": "boolean",
|
||||
"description": "Enable post-processing mix calibration",
|
||||
"default": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"MidiNote": {
|
||||
"title": "MidiNote",
|
||||
"description": "A single MIDI note event",
|
||||
"type": "object",
|
||||
"required": ["pitch", "start", "duration"],
|
||||
"properties": {
|
||||
"pitch": {
|
||||
"type": "integer",
|
||||
"description": "MIDI note number 0–127 (60 = middle C)",
|
||||
"minimum": 0,
|
||||
"maximum": 127
|
||||
},
|
||||
"start": {
|
||||
"type": "number",
|
||||
"description": "Start time in beats from item start"
|
||||
},
|
||||
"duration": {
|
||||
"type": "number",
|
||||
"description": "Duration in beats"
|
||||
},
|
||||
"velocity": {
|
||||
"type": "integer",
|
||||
"description": "Velocity 0–127",
|
||||
"minimum": 0,
|
||||
"maximum": 127,
|
||||
"default": 64
|
||||
}
|
||||
}
|
||||
},
|
||||
"CCEvent": {
|
||||
"title": "CCEvent",
|
||||
"description": "A MIDI CC event within a clip",
|
||||
"type": "object",
|
||||
"required": ["controller", "time", "value"],
|
||||
"properties": {
|
||||
"controller": {
|
||||
"type": "integer",
|
||||
"description": "CC number (e.g. 11 = Expression)"
|
||||
},
|
||||
"time": {
|
||||
"type": "number",
|
||||
"description": "Position in beats from clip start"
|
||||
},
|
||||
"value": {
|
||||
"type": "integer",
|
||||
"description": "CC value 0–127",
|
||||
"minimum": 0,
|
||||
"maximum": 127
|
||||
}
|
||||
}
|
||||
},
|
||||
"ClipDef": {
|
||||
"title": "ClipDef",
|
||||
"description": "A clip placed on a track — either audio or MIDI",
|
||||
"type": "object",
|
||||
"required": ["position", "length"],
|
||||
"properties": {
|
||||
"position": {
|
||||
"type": "number",
|
||||
"description": "Start position in beats"
|
||||
},
|
||||
"length": {
|
||||
"type": "number",
|
||||
"description": "Duration in beats"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Display name",
|
||||
"default": ""
|
||||
},
|
||||
"audio_path": {
|
||||
"type": ["string", "null"],
|
||||
"description": "Absolute path to audio file (for audio clips)",
|
||||
"default": null
|
||||
},
|
||||
"midi_notes": {
|
||||
"type": "array",
|
||||
"description": "List of MIDI notes (for MIDI clips)",
|
||||
"default": [],
|
||||
"items": { "$ref": "#/definitions/MidiNote" }
|
||||
},
|
||||
"midi_cc": {
|
||||
"type": "array",
|
||||
"description": "MIDI CC events",
|
||||
"default": [],
|
||||
"items": { "$ref": "#/definitions/CCEvent" }
|
||||
},
|
||||
"loop": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the audio clip loops",
|
||||
"default": false
|
||||
},
|
||||
"fade_in": {
|
||||
"type": "number",
|
||||
"description": "Fade-in duration in seconds",
|
||||
"default": 0.0
|
||||
},
|
||||
"fade_out": {
|
||||
"type": "number",
|
||||
"description": "Fade-out duration in seconds",
|
||||
"default": 0.0
|
||||
},
|
||||
"vol_mult": {
|
||||
"type": "number",
|
||||
"description": "Volume multiplier applied at clip level",
|
||||
"default": 1.0
|
||||
}
|
||||
}
|
||||
},
|
||||
"PluginDef": {
|
||||
"title": "PluginDef",
|
||||
"description": "A VST plugin instance on a track",
|
||||
"type": "object",
|
||||
"required": ["name", "path"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Display name (e.g. Serum 2)"
|
||||
},
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Plugin path/identifier (e.g. VST3: Serum 2 (Xfer Records))"
|
||||
},
|
||||
"index": {
|
||||
"type": "integer",
|
||||
"description": "Chain position (0 = first)",
|
||||
"default": 0
|
||||
},
|
||||
"params": {
|
||||
"type": "object",
|
||||
"description": "Optional dict of parameter index → value",
|
||||
"default": {},
|
||||
"additionalProperties": { "type": "number" }
|
||||
},
|
||||
"preset_data": {
|
||||
"type": ["array", "null"],
|
||||
"description": "Base64 preset chunks",
|
||||
"default": null,
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"role": {
|
||||
"type": "string",
|
||||
"description": "Track role for role-aware preset lookup (e.g. bass, lead, pad)",
|
||||
"default": ""
|
||||
},
|
||||
"builtin": {
|
||||
"type": "boolean",
|
||||
"description": "True → deferred to ReaScript, not written to .rpp",
|
||||
"default": false
|
||||
}
|
||||
}
|
||||
},
|
||||
"TrackDef": {
|
||||
"title": "TrackDef",
|
||||
"description": "A track in the REAPER project",
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Track display name"
|
||||
},
|
||||
"volume": {
|
||||
"type": "number",
|
||||
"description": "0.0–1.0 (maps to REAPER volume fader)",
|
||||
"default": 0.85
|
||||
},
|
||||
"pan": {
|
||||
"type": "number",
|
||||
"description": "-1.0 to 1.0",
|
||||
"default": 0.0
|
||||
},
|
||||
"color": {
|
||||
"type": "integer",
|
||||
"description": "REAPER color index (0–67), 0 = default",
|
||||
"default": 0
|
||||
},
|
||||
"clips": {
|
||||
"type": "array",
|
||||
"description": "Audio/MIDI clips placed on this track",
|
||||
"default": [],
|
||||
"items": { "$ref": "#/definitions/ClipDef" }
|
||||
},
|
||||
"plugins": {
|
||||
"type": "array",
|
||||
"description": "VST plugins on this track",
|
||||
"default": [],
|
||||
"items": { "$ref": "#/definitions/PluginDef" }
|
||||
},
|
||||
"send_reverb": {
|
||||
"type": "number",
|
||||
"description": "Reverb send level 0.0–1.0",
|
||||
"default": 0.0
|
||||
},
|
||||
"send_delay": {
|
||||
"type": "number",
|
||||
"description": "Delay send level 0.0–1.0",
|
||||
"default": 0.0
|
||||
},
|
||||
"send_level": {
|
||||
"type": "object",
|
||||
"description": "Dict mapping return track index → send level 0.0–1.0",
|
||||
"default": {},
|
||||
"additionalProperties": { "type": "number" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"SectionDef": {
|
||||
"title": "SectionDef",
|
||||
"description": "A section in the song arrangement with energy and dynamics",
|
||||
"type": "object",
|
||||
"required": ["name", "bars"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Display name (e.g. intro, chorus, verse)"
|
||||
},
|
||||
"bars": {
|
||||
"type": "integer",
|
||||
"description": "Length in bars"
|
||||
},
|
||||
"energy": {
|
||||
"type": "number",
|
||||
"description": "Energy level 0.0–1.0 (controls velocity multiplier)",
|
||||
"default": 0.5
|
||||
},
|
||||
"velocity_mult": {
|
||||
"type": "number",
|
||||
"description": "Velocity multiplier applied to all notes in section",
|
||||
"default": 1.0
|
||||
},
|
||||
"vol_mult": {
|
||||
"type": "number",
|
||||
"description": "Volume multiplier applied to track in section",
|
||||
"default": 1.0
|
||||
}
|
||||
}
|
||||
},
|
||||
"PatternDef": {
|
||||
"title": "PatternDef",
|
||||
"description": "A pattern definition with generator and variation axes",
|
||||
"type": "object",
|
||||
"required": ["id", "name", "instrument", "channel", "bars", "generator"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "integer",
|
||||
"description": "Unique pattern ID"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Display name (e.g. Kick Main)"
|
||||
},
|
||||
"instrument": {
|
||||
"type": "string",
|
||||
"description": "Sample/instrument key (e.g. kick, snare)"
|
||||
},
|
||||
"channel": {
|
||||
"type": "integer",
|
||||
"description": "MIDI channel (11 = kick, 12 = snare, etc.)"
|
||||
},
|
||||
"bars": {
|
||||
"type": "integer",
|
||||
"description": "Length in bars"
|
||||
},
|
||||
"generator": {
|
||||
"type": "string",
|
||||
"description": "Generator function name"
|
||||
},
|
||||
"velocity_mult": {
|
||||
"type": "number",
|
||||
"description": "Velocity multiplier (0.85–1.1)",
|
||||
"default": 1.0
|
||||
},
|
||||
"density": {
|
||||
"type": "number",
|
||||
"description": "Note density 0.0–1.0",
|
||||
"default": 1.0
|
||||
}
|
||||
}
|
||||
},
|
||||
"ArrangementItemDef": {
|
||||
"title": "ArrangementItemDef",
|
||||
"description": "An item placed in the arrangement referencing a pattern on a track",
|
||||
"type": "object",
|
||||
"required": ["pattern", "bar", "bars", "track"],
|
||||
"properties": {
|
||||
"pattern": {
|
||||
"type": "integer",
|
||||
"description": "Pattern ID"
|
||||
},
|
||||
"bar": {
|
||||
"type": "number",
|
||||
"description": "Start position in bars"
|
||||
},
|
||||
"bars": {
|
||||
"type": "number",
|
||||
"description": "Length in bars"
|
||||
},
|
||||
"track": {
|
||||
"type": "integer",
|
||||
"description": "Track index"
|
||||
}
|
||||
}
|
||||
},
|
||||
"ArrangementTrack": {
|
||||
"title": "ArrangementTrack",
|
||||
"description": "A track in the REAPER arrangement with index and display name",
|
||||
"type": "object",
|
||||
"required": ["index", "name"],
|
||||
"properties": {
|
||||
"index": {
|
||||
"type": "integer",
|
||||
"description": "Track index"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Display name"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user