Maolan Workflow
A practical map of how Maolan sessions move from track setup and plugin routing to autosave recovery, diagnostics, templates, and final export.
Autosave cadence
Plugin host formats on Linux / FreeBSD
Core session subdirectories
Diagnostics bundle files
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 orangeDefault 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.
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
Track Input -> Plugin A -> Plugin B -> Track Output
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.
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.
Session Storage
Sessions are directory-based, with the main project state in
session.json and supporting assets stored alongside
it.
Session Layout
session.json
Tracks, clips, connections, plugin graph topology, plugin state, transport state, metadata, export settings, MIDI learn bindings, and UI sizing values.
audio/, midi/, peaks/,
plugins/
Imported media, waveform peak cache, and plugin session assets live inside the session directory.
.maolan_autosave/snapshots/
Timestamped recovery snapshots written beside the live session.
App-Level State
~/.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.
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, and plugin state 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.
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.
Snapshot generation
Every 15 seconds, Maolan writes a snapshot to
<session>/.maolan_autosave/snapshots/<timestamp>/.
Validity check
A snapshot is considered valid when it contains
session.json.
Startup / open comparison
On startup or open, Maolan can detect when the latest autosave is newer than the live session file.
Preview and restore
Recovery preview summarizes track, audio-clip, and MIDI-clip count deltas. 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.
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.
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 forces the X11 backend by unsetting
WAYLAND_DISPLAY and WAYLAND_SOCKET.
Plugin discovery runs for LV2, VST3, and CLAP.
Debugging
Passing --debug enables tracing output to stdout for
low-level startup and runtime inspection.