API Reference - Général Midi Boop

Transport

All commands are sent via WebSocket as JSON messages:

{ "command": "device_list", "id": "unique-request-id" }

Responses include the matching id for correlation:

{ "type": "response", "id": "unique-request-id", "data": { ... } }

Authentication

When GMBOOP_API_TOKEN is set, connect with:

WebSocket: ws://host:port?token=YOUR_TOKEN
HTTP: Authorization: Bearer YOUR_TOKEN header

REST Endpoints

Method	Path	Auth	Description
GET	`/api/health`	No	Health check (status, version, uptime)
GET	`/api/status`	Yes	Device/route/file counts, memory
GET	`/api/metrics`	Yes	Prometheus-compatible metrics
POST	`/api/transcription`	Yes	Queue an audio → MIDI transcription (raw audio bytes)

Commands (146 total)

Device Management (21 commands)

Command	Description	Parameters
`device_list`	List all connected devices with settings	—
`device_refresh`	Refresh device list from hardware	—
`device_info`	Get device details	`deviceId`
`device_set_properties`	Set device properties	`deviceId`, properties
`device_enable`	Enable/disable device	`deviceId`, `enabled`
`device_identity_request`	Request SysEx identity	`deviceName`, `deviceId?`
`device_save_sysex_identity`	Save SysEx identity	`deviceId`, `channel?`, `identity`
`instrument_update_settings`	Update instrument settings	`deviceId`, `channel`, settings
`instrument_get_settings`	Get instrument settings	`deviceId`, `channel?`
`instrument_update_capabilities`	Update instrument capabilities	`deviceId`, `channel`, capabilities
`instrument_get_capabilities`	Get instrument capabilities	`deviceId`, `channel?`
`instrument_list_capabilities`	List all instrument capabilities	—
`instrument_list_registered`	List registered instruments	—
`instrument_list_connected`	List connected instruments	—
`instrument_delete`	Delete instrument	`deviceId`, `channel?`
`instrument_add_to_device`	Add instrument to device channel	`deviceId`, `channel`, config
`instrument_list_by_device`	List instruments on device	`deviceId`
`instrument_create_virtual`	Create virtual instrument	`name`, `preset`, `channel`, config
`virtual_create`	Create virtual device	`name`
`virtual_delete`	Delete virtual device	`deviceId`
`virtual_list`	List virtual devices	—

MIDI Messages (8 commands)

Command	Description	Parameters
`midi_send`	Send raw MIDI message	`deviceId`, `type`, message data
`midi_send_note`	Send note on/off	`deviceId`, `channel`, `note`, `velocity`, `duration?`
`midi_send_cc`	Send Control Change	`deviceId`, `channel`, `controller`, `value`
`midi_send_pitchbend`	Send Pitch Bend	`deviceId`, `channel`, `value`
`midi_panic`	All sound off on all channels	`deviceId`
`midi_all_notes_off`	All notes off on all channels	`deviceId`
`midi_reset`	MIDI System Reset	`deviceId`

File Management (WebSocket commands)

Upload + download moved to HTTP in v6. Uploads use POST /api/files (raw binary body) and downloads stream from GET /api/files/:id/blob. The legacy file_upload WS command is gone; file_export now returns { url, contentHash, size, ... } instead of an inline base64 payload. See "HTTP endpoints" below.

Command	Description	Parameters
`file_list`	List files in folder	`folder?` (default '/')
`file_metadata`	Get file metadata	`fileId`
`file_read`	Read MIDI file for editing	`fileId`
`file_write`	Write MIDI file from editor	`fileId`, `midiData`
`file_delete`	Delete file	`fileId`
`file_save_as`	Save with new name	`fileId`, `newFilename`, `midiData`
`file_rename`	Rename file	`fileId`, `newFilename`
`file_move`	Move file to folder	`fileId`, `folder`
`file_duplicate`	Duplicate file (no-op when content_hash exists)	`fileId`
`file_export`	Return signed download metadata `{url}`	`fileId`
`file_search`	Search files	`query`
`file_filter`	Advanced filtering	Multiple filter criteria
`file_channels`	Get MIDI channels	`fileId`
`file_reanalyze_all`	Reanalyze all files	—
`file_routing_status`	Get routing status	`fileId`
`midi_instruments_list`	List distinct instruments	—
`midi_categories_list`	List instrument categories	—

HTTP endpoints

Method	Path	Body / Query	Response
`POST`	`/api/files?filename=&folder=`	Raw MIDI bytes (`Content-Type: application/octet-stream`), capped at `MAX_MIDI_FILE_SIZE`	`201 {fileId, contentHash, status:'created', ...}` or `200 {status:'duplicate'}` if content already known
`GET`	`/api/files/:id/blob[?dl=1]`	—	`200` streaming `audio/midi`; `ETag` is the SHA-256 content hash

Same-origin browser requests skip the bearer-token check; external clients must send Authorization: Bearer <GMBOOP_API_TOKEN>.

WS events (server → client)

Event	Payload	When
`file_upload_progress`	`{uploadId, stage}`	Emitted during `POST /api/files` for stages: `received`, `hashed`, `parsed`, `analyzed`, `stored`
`file_uploaded`	`{fileId, filename, contentHash}`	Once a file row is committed
`file_list_updated`	`{files: [...]}`	After any CRUD on the library
`file_delete`	`{fileId}`	After a file row + blob is deleted
`file_write`	`{fileId, contentHash}`	After the editor saves new bytes
`playback_status`, `playback_position`	scheduler state	High-frequency push during playback
`playlist_item_changed`, `playlist_waiting`	queue state	Multi-file playback transitions
`monitor_event`	live MIDI message	Routing monitor stream
`device_connected`, `device_disconnected`	`{deviceId, ...}`	Hot-plug detection
`latency_calibration_complete`	`{deviceId, latency, min, max}`	After `latency_measure` finishes

API surface not consumed by the bundled SPA

These WS commands are exposed for external clients or future UI work but the current SPA does not call them. They are NOT dead — removing them would break programmatic clients. Listed here so contributors know the gap on the UI side:

route_* (CRUD on static device-to-device routes) — the SPA uses per-file routing (file_routing_sync) instead.
preset_save / _load / _list / _delete / _rename / _export — no preset UI yet.
midi_panic — no emergency-stop button wired in the SPA.
file_export — the SPA downloads via GET /api/files/:id/blob?dl=1 directly; this command duplicates the URL returned by file_metadata.
file_channels, playlist_status — diagnostic queries, no UI surface.
latency_measure / _set / _get / _list / _delete / _auto_calibrate / _recommendations / _export — the SPA uses the calibrate_* family. Profiles are persisted on the device's channel-0 row of instruments_latency (sync_delay, avg_latency, min_latency, max_latency, last_calibration) and reloaded at every boot via LatencyCompensator.loadProfilesFromDB.

Playback (21 commands)

Command	Description	Parameters
`playback_start`	Start MIDI playback	`fileId`, `outputDevice?`
`playback_stop`	Stop playback	—
`playback_pause`	Pause playback	—
`playback_resume`	Resume playback	—
`playback_seek`	Seek to position	`position`
`playback_status`	Get playback status	—
`playback_set_loop`	Enable/disable loop	`enabled`
`playback_get_channels`	Get channel routing	—
`playback_set_channel_routing`	Route channel to device	`channel`, `deviceId`, `targetChannel?`
`playback_clear_channel_routing`	Clear all routings	—
`playback_mute_channel`	Mute/unmute channel	`channel`, `muted`
`analyze_channel`	Analyze MIDI channel	`fileId`, `channel`
`generate_assignment_suggestions`	Auto-assignment suggestions	`fileId`, `topN?`, `minScore?`
`apply_assignments`	Apply auto-assignments	`originalFileId`, `assignments`, `createAdaptedFile?`
`validate_instrument_capabilities`	Validate capabilities	—
`get_instrument_defaults`	Get default capabilities	`instrumentId`, `type?`
`update_instrument_capabilities`	Update capabilities	`updates`
`get_file_routings`	Get saved routings	`fileId`
`playback_set_tempo`	Set tempo	(planned)
`playback_transpose`	Transpose	(planned)
`playback_set_volume`	Set volume	(planned)

Routing (17 commands)

Command	Description	Parameters
`route_create`	Create MIDI route	Route config
`route_delete`	Delete route	`routeId`
`route_list`	List all routes	—
`route_enable`	Enable/disable route	`routeId`, `enabled`
`route_info`	Get route info	`routeId`
`filter_set`	Set route filter	`routeId`, `filter`
`filter_clear`	Clear route filter	`routeId`
`channel_map`	Set channel mapping	`routeId`, `mapping`
`monitor_start`	Start MIDI monitoring	`deviceId`
`monitor_stop`	Stop MIDI monitoring	`deviceId`
`route_test`	Test route	`routeId`
`route_duplicate`	Duplicate route	`routeId`
`route_export`	Export route	`routeId`
`route_import`	Import route	`route`
`route_clear_all`	Delete all routes	—
`file_routing_sync`	Sync file routing to DB	`fileId`, `channels`
`file_routing_bulk_sync`	Bulk sync routings	`routings`

Bluetooth (9 commands)

Command	Description	Parameters
`ble_scan_start`	Start BLE scan	`duration?` (default 5s), `filter?`
`ble_scan_stop`	Stop BLE scan	—
`ble_connect`	Connect to device	`address`
`ble_disconnect`	Disconnect device	`address`
`ble_forget`	Forget/unpair device	`address`
`ble_paired`	List paired devices	—
`ble_status`	Get adapter status	—
`ble_power_on`	Enable Bluetooth	—
`ble_power_off`	Disable Bluetooth	—

Serial (6 commands)

Command	Description	Parameters
`serial_scan`	Scan serial ports	—
`serial_list`	List open ports	—
`serial_open`	Open serial port	`path`, `name?`, `direction?`
`serial_close`	Close serial port	`path`
`serial_status`	Get serial status	—
`serial_set_enabled`	Enable/disable serial	`enabled`

Network (4 commands)

Command	Description	Parameters
`network_scan`	Scan network devices	`timeout?`, `fullScan?`
`network_connected_list`	List connected devices	—
`network_connect`	Connect to device	`ip`/`address`, `port?`
`network_disconnect`	Disconnect device	`ip`/`address`

Latency (10 commands)

Command	Description	Parameters
`latency_measure`	Measure device latency	`deviceId`, `iterations?`
`latency_set`	Set latency value	`deviceId`, `latency`
`latency_get`	Get latency profile	`deviceId`
`latency_list`	List all profiles	—
`latency_delete`	Delete profile	`deviceId`
`latency_auto_calibrate`	Auto-calibrate	`deviceIds`
`latency_recommendations`	Get recommendations	—
`latency_export`	Export all profiles	—
`calibrate_delay`	Calibrate delay	`deviceId`, `channel`, options
`calibrate_list_alsa_devices`	List ALSA devices	—

Lighting (35 commands)

Command	Description	Parameters
`lighting_device_list`	List lighting devices	—
`lighting_device_add`	Add device	`name`, `type?`, `connection_config`, `led_count`, `enabled`
`lighting_device_update`	Update device	`id`, fields
`lighting_device_delete`	Delete device	`id`
`lighting_device_test`	Test device	`id`
`lighting_device_scan`	Scan for devices	`type?`, `subnet?`
`lighting_rule_list`	List rules	`device_id?`
`lighting_rule_add`	Add rule	`device_id`, `name`, config
`lighting_rule_update`	Update rule	`id`, fields
`lighting_rule_delete`	Delete rule	`id`
`lighting_rule_test`	Test rule	`id`
`lighting_rules_export`	Export rules	`device_id?`
`lighting_rules_import`	Import rules	`import_data`
`lighting_preset_list`	List presets	—
`lighting_preset_save`	Save preset	`name`
`lighting_preset_load`	Load preset	`id`
`lighting_preset_delete`	Delete preset	`id`
`lighting_all_off`	All lights off	—
`lighting_blackout`	Blackout	—
`lighting_effect_start`	Start effect	`device_id`, `effect_type`, options
`lighting_effect_stop`	Stop effect	`effect_key`
`lighting_effect_list`	List active effects	—
`lighting_master_dimmer`	Get/set brightness	`value?`
`lighting_group_create`	Create group	`name`, `device_ids`
`lighting_group_delete`	Delete group	`name`
`lighting_group_list`	List groups	—
`lighting_group_color`	Set group color	`name`, color params
`lighting_group_off`	Turn group off	`name`
`lighting_scene_save`	Save scene	`name`, `device_colors`
`lighting_scene_apply`	Apply scene	`scene`
`lighting_midi_learn`	MIDI learn mode	—
`lighting_bpm_set`	Set effect BPM	`bpm`
`lighting_bpm_get`	Get current BPM	—
`lighting_bpm_tap`	Tap tempo	—
`lighting_led_broadcast`	Toggle LED broadcast	`enabled?`
`lighting_dmx_profiles`	List DMX profiles	—

String Instruments & Tablature (14 commands)

Command	Description	Parameters
`string_instrument_create`	Create config	`device_id`, `channel`, `instrument_name`, tuning config
`string_instrument_update`	Update config	`id`, fields
`string_instrument_delete`	Delete config	`id` or `device_id`+`channel`
`string_instrument_get`	Get config	`id` or `device_id`+`channel`
`string_instrument_list`	List configs	`device_id?`
`string_instrument_get_presets`	List tuning presets	—
`string_instrument_apply_preset`	Get preset data	`preset_key`
`string_instrument_create_from_preset`	Create from preset	`device_id`, `channel`, `preset`
`tablature_save`	Save tablature	`midi_file_id`, `string_instrument_id`, `tablature_data`
`tablature_get`	Get tablature	`midi_file_id`, `channel?`
`tablature_get_by_file`	Get all for file	`midi_file_id`
`tablature_delete`	Delete tablature	`midi_file_id`, `channel?`
`tablature_convert_from_midi`	MIDI → tablature	`notes`, instrument config
`tablature_convert_to_midi`	Tablature → MIDI	`tab_events`, instrument config

Audio → MIDI transcription (10 commands)

Optional feature — see AUDIO_TRANSCRIPTION.md. On a server with no engine installed every command still answers: capabilities report disabled/degraded and the others fail with a typed ERR_TRANSCRIPTION_* code rather than an internal error.

Command	Description	Parameters
`transcription_capabilities`	Is the feature usable? FFmpeg + engine status	`refresh?`
`transcription_backends`	Engines with capabilities, status and licensing	`refresh?`
`transcription_create`	Queue a job from an inline payload (≤ 8 MB)	`filename`, `audio` (base64), `backendId?`, `quality?`, `preset?`, `folder?`, `options?`
`transcription_status`	One job, or every job when `jobId` is omitted	`jobId?`
`transcription_cancel`	Stop a queued or running job	`jobId`
`transcription_result`	Rich result: notes, confidence, expression curves	`jobId`
`transcription_delete`	Forget a finished job	`jobId`
`transcription_install_backend`	Install an engine — refused without consent when its licence requires it	`backendId`, `acceptLicense?`, `acceptedModelLicense?`
`transcription_uninstall_backend`	Remove an engine and its environment	`backendId`
`transcription_backend_status`	One engine, plus any install currently running	`backendId`, `refresh?`

HTTP upload

Audio does not fit in a 16 MB WebSocket frame, so real uploads go over HTTP — the same split the MIDI library uses.

Method	Path	Body / Query	Response
`POST`	`/api/transcription?filename=&folder=&backendId=&quality=&preset=&detectDrums=&detectInstruments=&detectTempo=&preserveDynamics=&preservePitchBends=`	Raw audio bytes (`Content-Type: application/octet-stream`), capped at `transcription.maxAudioFileBytes`	`202 {job}` — the work has not started; follow it through the events below

WS events (server → client)

Event	Payload	When
`transcription_created`	`{jobId, sourceName, backendId, status, queuePosition}`	A job was queued
`transcription_progress`	`{jobId, stage, progress}`	Stage change, or a throttled progress update. `progress` is `null` when the engine reports none — show an indeterminate bar
`transcription_complete`	`{jobId, fileId, summary, warnings}`	The MIDI is in the library
`transcription_failed`	`{jobId, reason, message, retryable}`	`reason` is one of the `TRANSCRIPTION_REASONS` values
`transcription_cancelled`	`{jobId}`	The user stopped it
`transcription_backend_changed`	`{backendId, status, previousStatus, detail}`	An engine became available, broke, or was installed
`transcription_install_progress`	`{backendId, stage, progress}`	Stages: `checking`, `creating_environment`, `downloading`, `verifying`. `progress` is `null` — pip gives no usable fraction
`transcription_install_complete`	`{backendId, outcome, message}`	`outcome`: `installed` \| `removed` \| `failed` \| `cancelled`

Job stages, in order: queued → preprocessing → transcribing → postprocessing → generating_midi → importing → complete, or failed / cancelled.

Sessions & Presets (10 commands)

Command	Description	Parameters
`session_save`	Save session	`name`, `description`
`session_load`	Load session	`sessionId`
`session_list`	List sessions	—
`session_delete`	Delete session	`sessionId`
`session_export`	Export session	`sessionId`
`session_import`	Import session	`name`, `description`, `data`
`preset_save`	Save preset	`name`, `description`, `type`, `data`
`preset_load`	Load preset	`presetId`
`preset_list`	List presets	`type?`
`preset_delete`	Delete preset	`presetId`

Playlists (4 commands)

Command	Description	Parameters
`playlist_create`	Create playlist	`name`, `description`
`playlist_delete`	Delete playlist	`playlistId`
`playlist_list`	List playlists	—
`playlist_add_file`	Add file to playlist	`playlistId`, file data

System (10 commands)

Command	Description	Parameters
`system_status`	System status	—
`system_info`	System info (OS, CPU, memory)	—
`system_restart`	Restart application	—
`system_shutdown`	Shutdown application	—
`system_check_update`	Check for updates	—
`system_update`	Perform update	—
`system_backup`	Create DB backup	`path?`
`system_restore`	Restore from backup	(planned)
`system_logs`	Get recent logs	`data?`
`system_clear_logs`	Clear logs	—

Events (WebSocket Broadcasts)

Events are pushed to all connected clients:

{ "type": "event", "event": "device_connected", "data": { ... }, "timestamp": 1234567890 }

Event	Description
`connected`	Welcome message on connection
`device_connected`	MIDI device connected
`device_disconnected`	MIDI device disconnected
`midi_message`	MIDI message received
`midi_routed`	MIDI message routed
`playback_started`	Playback started
`playback_stopped`	Playback stopped
`playback_position`	Playback position update
`file_uploaded`	File uploaded
`transcription_created`	Audio → MIDI job queued
`transcription_progress`	Audio → MIDI stage or progress update
`transcription_complete`	Audio → MIDI job finished, file in the library
`transcription_failed`	Audio → MIDI job failed (typed reason)
`transcription_cancelled`	Audio → MIDI job cancelled
`transcription_backend_changed`	A transcription engine's status changed
`error`	Application error

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

API Reference - Général Midi Boop

Transport

Authentication

REST Endpoints

Commands (146 total)

Device Management (21 commands)

MIDI Messages (8 commands)

File Management (WebSocket commands)

HTTP endpoints

WS events (server → client)

API surface not consumed by the bundled SPA

Playback (21 commands)

Routing (17 commands)

Bluetooth (9 commands)

Serial (6 commands)

Network (4 commands)

Latency (10 commands)

Lighting (35 commands)

String Instruments & Tablature (14 commands)

Audio → MIDI transcription (10 commands)

HTTP upload

WS events (server → client)

Sessions & Presets (10 commands)

Playlists (4 commands)

System (10 commands)

Events (WebSocket Broadcasts)