Maolan OSC

Bind Address

The engine listens on:

0.0.0.0:9000

Scope

• There is no /maolan prefix on any OSC address.
• Arguments use OSC type tags: i integer, f float, s string, T/F true/false (also accepted as i 0/1).
• 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.

Session

History is intentionally not exposed over OSC.

Track Management

Routing

kind is "audio" or "midi".

Clips

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.

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 graph node strings

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

Automation

Targets: "volume", "balance", "midi_cc_<channel>_<cc>" (channel is 1–16).

MIDI Learn

Track targets: volume, balance, mute, solo, arm, input_monitor, disk_monitor. Global targets: play_pause, stop, record_toggle. Session targets: slot:<track>:<scene>, scene:<scene>, stop_track:<track>, stop_all.

Binding JSON (empty string clears)

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

Modulators / Devices

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

Piano Key

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

Subcommands

Subcommands cover transport, tracks, routing, plugins, clip plugins, clips, MIDI editing, automation, MIDI learn, session, step recording, and queries.

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

Command Files

--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 containing 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.

# 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 /commands.txt.

Examples

cargo run --bin maolan-osc -- play
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 level "Drums" -6.0
cargo run --bin maolan-osc -- connect "Kick" 0 "Drums" 0 audio
cargo run --bin maolan-osc -- plugin load "Drums" clap "rs.maolan.widener"
cargo run --bin maolan-osc -- plugin set_param "Drums" clap 0 0 0.75
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 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 -- session stop_scene 2