Workflow Reference Operations updated 2026-07-09 Routing updated 2026-07-09

Maolan Workflow

A practical map of how Maolan sessions move from track setup and plugin routing to autosave recovery, diagnostics, templates, and final export.

Explore Signal Flow See Recovery Path
At a glance
15s

Autosave cadence

3

Plugin host formats on Linux / FreeBSD

5

Core session subdirectories

3

Diagnostics bundle files

Signal Flow Storage Templates Recovery Diagnostics Platform Notes

Routing and Signal Flow

Maolan uses a per-track plugin graph rather than a fixed insert chain. Audio and MIDI paths are explicit, so the graph itself is the workflow.

Track Graph Model

Sidechains in orange

Default track state

New tracks start with passthrough audio routing from input to output, plus MIDI passthrough on the first input/output path.

Plugin loading

Loading a plugin does not rewrite existing connections. The graph decides what actually receives or emits signal.

Per-clip FX

Audio clips on supported Unix builds can open their own plugin graph. If a clip has no saved graph yet, Maolan seeds a default passthrough clip graph first.

Folder track graphs

Folder tracks have their own plugin graph. Child tracks route into the folder graph, and child outputs can connect directly to folder plugins or to the folder output.

Audio nodes

Main ports and extra auxiliary or sidechain ports are shown separately so unusual bus layouts remain visible.

MIDI nodes

MIDI input and output are explicit too. If a plugin emits MIDI, it must be routed onward to keep events moving.

Typical Graph Paths

Serial insert
Track Input -> Plugin A -> Plugin B -> Track Output
Sidechain

Keep the main audio input connected to the plugin’s main input, then route the source track or upstream output into the orange sidechain input separately.

MIDI instrument / effect

Connect MIDI source to the plugin, then wire the plugin’s audio output to the next stage or track output. Route MIDI output explicitly if the plugin generates events.

Grouped audio render order

Child clips render first, then group-level fades are applied, and finally the group clip plugin graph is processed.

Session Storage

Sessions are directory-based, with the main project state in <branch>.json (default main.json) and supporting assets stored alongside it.

Session Layout

<branch>.json

Tracks, clips, connections, plugin graph topology, plugin state, transport state, metadata, export settings, MIDI learn bindings, clip-group membership in grouped_clips, per-audio-clip plugin graph state in plugin_graph_json, pitch-correction segment settings, and UI sizing values.

session.json

Live Session View scene list and slot references.

audio/, midi/, peaks/, pitch/, plugins/

Imported media, waveform peak cache, cached pitch analysis data, and plugin session assets live inside the session directory.

data/

Consolidated external audio, MIDI, and plugin file references.

.maolan_autosave/snapshots/

Timestamped recovery snapshots written beside the live session.

App-Level State

Config file
~/.config/maolan/config.toml

If the file does not exist, Maolan creates it on startup with defaults. It stores UI sizing, export defaults, preferred I/O devices, snap mode, bit depth, and recent session paths.

  • font_size
  • mixer_height
  • track_width
  • default_export_sample_rate_hz
  • default_snap_mode
  • default_audio_bit_depth
  • default_output_device_id
  • default_input_device_id
  • recent_session_paths

Recent sessions

Stored in recent_session_paths, normalized before display, deduplicated, pruned when invalid, and capped to the configured limit.

Session save/load

Saved sessions restore plugin graph topology, connections, plugin state, clip groups, and per-audio-clip plugin graphs rather than just track ordering.

Templates and Restore Paths

Maolan separates full-session reuse from single-track reuse, while keeping graph state part of both save and restore workflows.

Session templates

~/.config/maolan/session_templates/<name>/

Each template includes session.json and the same supporting subdirectories as a normal session.

  • Includes track structure, routing, plugin graphs, plugin state, metadata, and export settings.
  • Excludes audio clips, MIDI clips, frozen render state, and frozen backups.

Track templates

~/.config/maolan/track_templates/<name>/

A track template stores track.json and a plugins/ directory for one reusable channel strip.

  • Includes track settings, plugin graph, plugin state, and connections involving that track.
  • Excludes audio clips and MIDI clips.

Folder templates

~/.config/maolan/track_templates/<name>/

Folder track templates are stored in the same track-templates directory. A folder template's track.json contains a children array with the saved subtree.

  • Includes the folder track's settings, plugin graph, plugin state, child-to-folder-plugin connections, disabled child-to-folder-output feeds, and internal connections.
  • Includes the full child track subtree recursively.
  • Excludes audio clips, MIDI clips, and connections to tracks outside the saved subtree.

Cross-format restore behavior

Mixed Unix graphs containing LV2 and CLAP plugins are restored in saved order. VST3 state is preserved through the current host restore path as well, so sessions and templates retain routing intent instead of reconstructing a simplified chain.

Autosave and Recovery

Recovery is built around timestamped snapshots saved inside the session folder, with the newest valid snapshot preferred first.

1

Snapshot generation

Every 15 seconds, Maolan writes a snapshot to <session>/.maolan_autosave/snapshots/<timestamp>/.

2

Validity check

A snapshot is considered valid when it contains session.json.

3

Startup / open comparison

On startup or open, Maolan can detect when the latest autosave is newer than the live session file.

4

Preview and restore

Recovery preview summarizes track, audio-clip, and MIDI-clip count deltas. If newer snapshots fail to restore, older snapshots are offered as fallback candidates. Restoring a snapshot loads it as current state and marks the session as unsaved.

Recovery boundaries

Newest-first sorting

Snapshot selection prefers the most recent valid entry rather than trying to merge newer pieces from multiple points in time.

Unsaved state after restore

Restore is a recovery load, not a silent replacement of the live project file, so the session remains dirty until saved.

Undo / redo note

Graph connection edits and plugin load or unload actions are covered by undo and redo. Low-level state-restore mechanics are internal replay behavior, not user-facing history items.

  • Loop, punch-range, and record-enable toggles are history-recorded.
  • Tempo and time-signature edits, modulator changes, track hierarchy changes, clip plugin graph changes, automation lane edits, and pitch-correction edits are history-recorded.
  • Track automation level, balance, and mute updates are runtime playback/write-mode side effects and are excluded from history.
  • Transport/query/report actions are intentionally kept out of history.
  • High-frequency automation playback adjustments are also excluded to avoid history noise.
  • MIDI learn arm actions are excluded; actual binding changes remain history-recorded.
  • Plugin discovery and query actions are not recorded in history.

Diagnostics and Export

The workflow closes with session inspection and multi-format export behavior that persists relevant settings back into the project.

Diagnostics bundle

UI reports

Session Diagnostics, MIDI Mappings Report, and Export Diagnostics Bundle are exposed in the interface.

Bundle location

Written to <session>/maolan_diagnostics_<unix-seconds>/ when a session is open, otherwise to /tmp/maolan_diagnostics_<unix-seconds>/.

Bundle contents

session_diagnostics.txt, midi_mappings.txt, and ui_summary.json.

Modulators

Modulators pane

Open the Modulators pane with View → Modulators or M. Press + to create a modulator with a name, enable toggle, shape, rate mode, rate value, and phase. Rates are set in Hz or as musical divisions.

Assign a target

The selected modulator shows target overlays on mixer faders and pans and on automation-lane headers. The Assign dialog asks for the min and max range. Targets include track Volume/Balance, visible automation lanes (plugin parameters, MIDI CC), and the master output. Assignments are saved in the session.

Step recording

Step toggle

Toggle Step in the piano-roll toolbar. Played MIDI notes are inserted at the step cursor with a length equal to the current MIDI snap interval, and the cursor advances automatically.

Snap fallback

NoSnap and Clips snap modes fall back to a sixteenth-note step length.

Fold mixer strips

Collapsible folder strips

Folder tracks render in the mixer as collapsible strips. Click the ▼ / ▶ header toggle to expand or collapse nested child tracks; a collapsed strip shows only the folder.

Folder strip behavior

Folder strips omit the record-arm button because folders cannot be armed. Double-click a folder strip to open the folder connections graph.

maolan-generate operations

GUI launch path

The desktop app launches the local maolan-generate binary and exchanges progress and result data over a socketpair IPC path.

Runtime split

Prompt generation runs in a dedicated HeartMuLa token-generation subprocess, then decode continues in-process with HeartCodec.

Model resolution

Without --model-dir <path>, model assets are resolved through the Hugging Face cache using hf-hub.

Expected repos and files

HeartMuLa uses maolandaw/HeartMuLa-happy-new-year-burn or maolandaw/HeartMuLa-RL-oss-3B-20260123 with heartmula.bpk, tokenizer.json, and gen_config.json. HeartCodec uses maolandaw/HeartCodec-oss-20260123-burn with heartcodec.bpk.

CLI boundaries

The current CLI supports --model <happy-new-year|RL>, --length in milliseconds, --decode-only with --frames-json, and decode-only worker control through --decode-threads.

Media consolidation

Consolidate

File → Consolidate copies external audio, MIDI, and CLAP/LV2 plugin file references into the session's data/ directory and updates the references.

Delete unused files

File → Delete unused files scans audio/, midi/, peaks/, and pitch/ and removes files not referenced by the session or any non-hidden branch JSON. Unused clips in the Clips pane are removed first when unreferenced.

Pitch-correction cache and render flow

Session requirement

Opening pitch correction for an audio clip requires a saved/opened session.

Cached source analysis

Analysis results are cached under pitch/ and reused for matching source file+offset+length combinations.

Apply and playback

Apply saves correction points/settings to the clip and keeps source audio untouched while enabling real-time playback.

Freeze pipeline

Frozen audio previews render through the pitch-corrected signal path so exported/flattened results match.

Export behavior

Mixdown and stems

Mixdown renders selected hardware output ports. Stem export writes one file per eligible selected track into <base>_stems/.

Formats and limits

Multiple output formats can be written in a single export run. MP3 export is limited to mono or stereo output.

Persisted settings

Normalization and master-limiter settings are stored in the session file along with export dialog settings.

Platform Notes

Runtime behavior differs by OS and plugin host path, which affects how the workflow starts before any session is even opened.

Linux / FreeBSD

Startup runs on Wayland when available and falls back to X11 (Xorg) when Wayland is unavailable. Plugin UI embedding still requires an X11 display (XWayland is sufficient under Wayland). Plugin discovery runs for LV2, VST3, and CLAP.

Audio device filtering

The hardware preference dialog filters devices by direction: output lists show only devices with output support, and input lists show only devices with input support.

Plugin blocklist

~/.config/maolan/plugin-blocklist.json hides blocklisted plugins from the plugin browser and skips them during system scans. Entries are added manually or automatically when a single-plugin scan fails. CLAP and VST3 entries match the full plugin file path; LV2 entries match the bundle_uri or plugin uri. Restart Maolan after editing the file.

Debugging

Passing --log-level <level> enables tracing output to stderr. Valid levels: none, info, warning, error, debug.

macOS host discovery

macOS builds support CLAP and VST3 discovery on startup, but they do not use the Unix LV2 host path.