Maolan OSC

Maolan supports an OSC control surface for transport, track management, routing, plugins, automation, clip editing, MIDI editing, MIDI learn, audio/MIDI devices, offline bounce, and state queries.

OSC is disabled by default.

Enabling OSC

Enable OSC from Preferences in the GUI:

Open Preferences.
Turn on Enable OSC.
Save preferences.

Once enabled, Maolan starts an OSC listener thread in the engine.

The preference is stored in:

~/.config/maolan/config.toml

OSC Listener

The engine listens on:

0.0.0.0:9000

There is no /maolan prefix on any OSC address.

Command Addresses

Arguments use OSC type tags:

i — integer
f — float
s — string
T / F — true / false (also accepted as i 0/1)

Transport

/transport/play
/transport/stop
/transport/pause
/transport/start
/transport/end
/transport/position i — set transport position in samples
/transport/position_at i i — set position after N frames
/transport/session_play
/transport/record i — enable (1) or disable (0) recording
/transport/loop_enable i
/transport/loop_range ii — start, end in samples
/transport/loop_range/clear — clear the loop range
/transport/punch_enable i
/transport/punch_range ii — start, end in samples
/transport/punch_range/clear — clear the punch range
/transport/metronome i
/transport/clip_playback i
/transport/session_clip_playback i
/transport/panic
/transport/tempo f — set tempo in BPM
/transport/time_signature ii — numerator, denominator
/transport/tempo_map s — JSON tempo/time-signature map
/step_recording i — enable (1) or disable (0) step recording

Compatibility aliases are still accepted:

/transport/jump_to_start → /transport/start
/transport/jump_to_end → /transport/end
/transport/start_of_session → /transport/start
/transport/end_of_session → /transport/end

Tempo map JSON format:

{
  "tempo_points": [
    {"sample": 0, "bpm": 120.0}
  ],
  "time_signature_points": [
    {"sample": 0, "numerator": 4, "denominator": 4}
  ]
}

Session

/session/launch s i — launch clip on track/scene
/session/stop s i — stop clip on track/scene
/session/scene i — launch every clip in the given scene
/session/stop_scene i — stop every clip in the given scene
/session/stopall — stop all currently playing session clips
/session/path s — set session path

History is intentionally not exposed over OSC.

Track Management

/track/add s i i i i i — name, audio_ins, midi_ins, audio_outs, midi_outs, folder
/track/remove s
/track/rename s s
/track/set_folder s i
/track/toggle_folder s
/track/set_parent s s — empty parent string removes the parent
/track/add_audio_input s
/track/remove_audio_input s
/track/add_audio_output s
/track/remove_audio_output s

Track Mixing / State

/track/level s f
/track/balance s f
/track/automation_level s f
/track/automation_balance s f
/track/midi_cc s i i i — track_name, channel, cc, value
/track/mute s i
/track/solo s i
/track/arm s i
/track/phase s i
/track/master s i
/track/color s f f f [f] — RGBA (alpha defaults to 1.0)
/track/color/clear s — clear the track color
/track/frozen s i
/track/midi_lane_channel s i i — channel -1 clears the assignment
/track/session_slot s i s
/track/session_slot_play_enabled s i i
/track/toggle_input_monitor s i
/track/toggle_disk_monitor s i
/track/toggle_midi_input_monitor s i
/track/toggle_midi_disk_monitor s i
/track/clear_default_passthrough s
/track/clear_plugins s
/track/connect_audio s s i s i
/track/disconnect_audio s s i s i
/track/connect_midi s s i s i
/track/disconnect_midi s s i s i

Connectable node strings: "track_input", "track_output", "child:<name>", "clap_<id>", "vst3_<id>", "lv2_<id>".

Routing

/connect s i s i s — from_track, from_port, to_track, to_port, kind
/disconnect s i s i s

kind is "audio" or "midi".

Clips

/clip/add s s i i i i i i i i s [s] [s] — track, name, start, length, offset, input_channel, muted, fade_enabled, fade_in, fade_out, kind, optional source_name, optional preview_name
/clip/remove s s s — track, kind, comma-separated indices
/clip/move s s i s i i i — kind, from_track, from_index, to_track, to_offset, to_channel, copy
/clip/fade s i s i i i — track, clip_index, kind, fade_enabled, fade_in_samples, fade_out_samples
/clip/bounds s i s i i i — track, clip_index, kind, start, length, offset
/clip/mute s i s i
/clip/rename s i s s
/clip/source_name s i s s
/clip/plugin_graph_json s i s — empty JSON string clears the graph
/clip/pitch_correction s i s — JSON pitch-correction data or empty string
/clip_group/add s s s s — track, kind, audio_clip JSON, midi_clip JSON

Pitch-correction JSON format:

{
  "preview_name": "preview.wav",
  "source_name": "source.wav",
  "source_offset": 0,
  "source_length": 44100,
  "frame_likeness": 0.5,
  "inertia_ms": 50,
  "formant_compensation": false,
  "points": [
    {
      "start_sample": 0,
      "length_samples": 1000,
      "detected_midi_pitch": 60.0,
      "target_midi_pitch": 61.0,
      "clarity": 0.9
    }
  ]
}

MIDI Editing

All MIDI editing commands take a JSON string as the last argument.

/midi/insert_notes s i s
/midi/delete_notes s i s
/midi/modify_notes s i s
/midi/insert_controllers s i s
/midi/delete_controllers s i s
/midi/modify_controllers s i s
/midi/sysex s i s
/midi/step_record s i i i — device, channel, pitch, velocity

Insert-notes JSON format:

[
  {"index": 0, "start_sample": 0, "length_samples": 1000,
   "pitch": 60, "velocity": 100, "channel": 0}
]

Delete-notes JSON format:

{
  "indices": [0, 1],
  "deleted": [
    {"index": 0, "start_sample": 0, "length_samples": 1000,
     "pitch": 60, "velocity": 100, "channel": 0}
  ]
}

Modify-notes JSON format:

{
  "indices": [0, 1],
  "new": [{"start_sample": 0, "length_samples": 1000, "pitch": 60, ...}],
  "old": [{"start_sample": 0, "length_samples": 1000, "pitch": 59, ...}]
}

Controller JSON objects use sample, controller, value, and channel. SysEx JSON format:

[{"sample": 0, "data": [240, 1, 2, 247]}]

Plugins

/plugin/load s s s — track_name, format ("clap", "vst3", "lv2"), plugin ID
/plugin/unload s s s
/plugin/unload_instance s s i
/plugin/bypass s s i i — track_name, format, instance_id, bypassed
/plugin/show_gui s s i
/plugin/snapshot_state s s i
/plugin/restore_state s s i s — JSON state ({"bytes":[...]} for CLAP, {"plugin_id":"...","component_state":[...],"controller_state":[...]} for VST3)
/plugin/set_resource_dir s s i s
/plugin/update_file_reference s s i i s — track_name, format, instance_id, file_index, path
/plugin/connect_audio s s i s i
/plugin/disconnect_audio s s i s i
/plugin/connect_midi s s i s i
/plugin/disconnect_midi s s i s i
/plugin/set_param s s i i f
/clip_plugin/set_param s s i i i f
/clip_plugin/snapshot_state s s i i
/clip_plugin/restore_state s s i i s
/clip_plugin/set_resource_dir s s i i s
/clip_plugin/update_file_reference s s i i i s

Plugin graph node strings:

"track_input"
"track_output"
"clap_<instance_id>"
"vst3_<instance_id>"
"lv2_<instance_id>"

Automation

Automation targets supported in OSC:

"volume"
"balance"
"midi_cc_<channel>_<cc>" — channel is 1–16

Addresses:

/automation/mode s s — track_name, mode ("read", "touch", "latch", "write")
/automation/toggle_lane s s
/automation/insert_point s s i f — track_name, target, sample, value
/automation/delete_point s s i — track_name, target, sample

MIDI Learn

Track targets: volume, balance, mute, solo, arm, input_monitor, disk_monitor.

Global targets: play_pause, stop, record_toggle.

Session target strings:

slot:<track>:<scene>
scene:<scene>
stop_track:<track>
stop_all

Binding JSON (empty string clears):

{"device": "X-Touch", "channel": 1, "cc": 7}

Addresses:

/midi_learn/arm_track s s
/midi_learn/arm_global s
/midi_learn/arm_session s
/midi_learn/bind_track s s s
/midi_learn/bind_global s s
/midi_learn/bind_session s s
/midi_learn/clear

Modulators / Devices

/modulators s — JSON array of modulators
/device/audio_open s — JSON audio-device configuration
/device/midi_in_open s
/device/midi_out_open s
/device/jack/add_audio_in
/device/jack/remove_audio_in i
/device/jack/add_audio_out
/device/jack/remove_audio_out i

Audio-device JSON format:

{
  "device": "hw:0",
  "input_device": "hw:0",
  "sample_rate_hz": 48000,
  "bits": 32,
  "exclusive": false,
  "period_frames": 256,
  "nperiods": 2,
  "sync_mode": false,
  "actual_period_frames": 256,
  "input_channels": 2,
  "output_channels": 2,
  "bytes_per_frame": 8
}

Offline Bounce

/bounce/start s s i i s i — track, output_path, start_sample, length_samples, automation_lanes JSON, apply_fader
/bounce/cancel s
/bounce/cancel_all

Piano Key

/piano_key s i i i — track_name, note, velocity, on

Query Addresses

Queries return replies to the sender.

/query/tracks → /response/tracks s...
/query/transport → /response/transport i i f i i (sample, playing, tempo, time_sig_num, time_sig_denom)
/query/meters → /response/meters ...
/query/plugins s → /response/plugins s i (i s s s i)* (track_name, plugin_count, instance_id, format, uri, name, bypassed)
/query/plugin_parameters s s i i → /response/plugin_parameters s i s s (track_name, instance_id, format, parameters_json)
/query/clip_plugin_parameters s s i i i → clip plugin parameters reply
/query/clap_plugins → /response/clap_plugins s...
/query/clap_plugins_with_capabilities → list with I/O capabilities
/query/vst3_plugins → /response/vst3_plugins s...
/query/lv2_plugins → /response/lv2_plugins s...
/query/clap_note_names s → /response/clap_note_names s...
/query/lv2_midnam s → /response/lv2_midnam s ... (LV2 midnam MIDI note names; Unix only)
/query/vst3_graph s → /response/vst3_graph s...
/query/diagnostics → /response/diagnostics s...
/query/midi_learn_report → /response/midi_learn_report s...

Plugin-list replies contain strings in the form id|name for CLAP and VST3, uri|name for LV2.

Errors are reported as:

/error s

`maolan-osc` Helper

The repository includes a command-line helper:

maolan-osc

Global Options

maolan-osc --target 127.0.0.1:9000 play
maolan-osc --host 192.168.1.10 --port 9000 stop
maolan-osc --file commands.txt

--file <path> reads commands from a file, one per line, using the same syntax as the command line. Blank lines and lines starting with # are ignored, and single or double quotes group arguments that contain whitespace (track names, JSON payloads). The whole file is parsed first and every error is reported with its line number; packets are sent only when the file parses without errors.

Example command file:

# set up a mix
track level "Drums" -6.0
track mute "Drums" 1
tempo 128.5

A ready-made example file with five commands is available at maolan/docs/commands.txt in the repository.

Examples

cargo run --bin maolan-osc -- play
cargo run --bin maolan-osc -- stop
cargo run --bin maolan-osc -- pause
cargo run --bin maolan-osc -- start
cargo run --bin maolan-osc -- end

cargo run --bin maolan-osc -- position 44100
cargo run --bin maolan-osc -- tempo 128.5
cargo run --bin maolan-osc -- record 1

cargo run --bin maolan-osc -- track add "Vocals" 2 0 2 0
cargo run --bin maolan-osc -- track remove "Vocals"
cargo run --bin maolan-osc -- track rename "Vocals" "Lead Vocals"
cargo run --bin maolan-osc -- track folder "Buses" 1
cargo run --bin maolan-osc -- track parent "Kick" "Drums"

cargo run --bin maolan-osc -- track level "Drums" -6.0
cargo run --bin maolan-osc -- track mute "Drums" 1
cargo run --bin maolan-osc -- track solo "Drums" 1
cargo run --bin maolan-osc -- track arm "Vocals" 1

cargo run --bin maolan-osc -- connect "Kick" 0 "Drums" 0 audio
cargo run --bin maolan-osc -- disconnect "Kick" 0 "Drums" 0 audio

cargo run --bin maolan-osc -- plugin load "Drums" clap "rs.maolan.widener"
cargo run --bin maolan-osc -- plugin bypass "Drums" clap 0 1
cargo run --bin maolan-osc -- plugin connect_audio "Drums" track_input 0 clap_0 0
cargo run --bin maolan-osc -- plugin set_param "Drums" clap 0 0 0.75

cargo run --bin maolan-osc -- track connect_audio "Drums" child:"Sub" 0 track_output 0

cargo run --bin maolan-osc -- clip add "Vocals" "Take 1" 0 44100 0 0 0 1 100 100 audio

cargo run --bin maolan-osc -- midi insert_notes "Piano" 0 '[{"index":0,"start_sample":0,"length_samples":1000,"pitch":60,"velocity":100,"channel":0}]'

cargo run --bin maolan-osc -- automation mode "Drums" touch
cargo run --bin maolan-osc -- automation point "Drums" midi_cc_1_7 44100 64.0

cargo run --bin maolan-osc -- midi_learn bind_track "Drums" volume '{"device":"X-Touch","channel":1,"cc":7}'

cargo run --bin maolan-osc -- query tracks
cargo run --bin maolan-osc -- query transport
cargo run --bin maolan-osc -- query meters
cargo run --bin maolan-osc -- query plugins "Drums"
cargo run --bin maolan-osc -- query plugin_parameters "Drums" clap 0
cargo run --bin maolan-osc -- query clap_plugins
cargo run --bin maolan-osc -- query clap_plugins_with_capabilities
cargo run --bin maolan-osc -- query diagnostics

cargo run --bin maolan-osc -- session stop_scene 2
cargo run --bin maolan-osc -- track automation_level "Drums" -6.0
cargo run --bin maolan-osc -- track midi_cc "Drums" 1 7 64
cargo run --bin maolan-osc -- step_recording 1

cargo run --bin maolan-osc -- plugin show_gui "Drums" clap 0
cargo run --bin maolan-osc -- plugin snapshot_state "Drums" clap 0
cargo run --bin maolan-osc -- plugin restore_state "Drums" clap 0 '{"bytes":[1,2,3]}'
cargo run --bin maolan-osc -- plugin update_file_reference "Drums" clap 0 0 "/tmp/sample.wav"

cargo run --bin maolan-osc -- clip_plugin snapshot_state "Drums" clap 0 0

Run maolan-osc --help for the full command list.

Notes

OSC only starts after it is enabled in preferences and the setting has been saved.
If OSC is disabled, maolan-osc can still send packets, but the engine will not be listening for them.
Query replies are sent to the source address of the request.
Complex structured data (clip data, MIDI notes, controllers, tempo maps, modulators, audio-device settings, automation lanes) is sent as JSON strings because the OSC implementation uses flat typed arguments rather than bundles.

Keyboard shortcuts

Maolan DAW