Debugging

• Logs: the app uses env_logger with the default filter info,jack=off, printed to the terminal that started it. Set RUST_LOG=debug (or RUST_LOG=daw_engine=debug) for more. Plug-in load failures and missing audio files are logged as errors; autosaves at info level; plug-in restart flags at debug level.
• Frontend errors: a failed command shows its error as a toast (report in api.ts). The app replaces the webview’s right-click menu with its own.
• Blank window on Linux: some GPU drivers need WEBKIT_DISABLE_DMABUF_RENDERER=1. Leave it unset otherwise, because WebKit then paints on the CPU at much higher cost.
• Wayland: main.rs sets GDK_BACKEND=x11 unless you set it yourself, so the interface runs through XWayland like the plug-in editors. MARBBLE_WAYLAND=1 (or GDK_BACKEND=wayland) runs it natively; the log then says “running natively on Wayland”, and GL contexts are kept apart around plug-in calls (see Editor windows). An OpenGL editor that stays black there, with “X11 error from a plug-in GUI ignored (error 10, request N)” in the log where N is the GLX opcode, is a call into the plug-in that isn’t wrapped in gl_isolated.
• Plug-in editor scale: the log says “plug-in editor scale” with where it came from when an editor opens at a scale other than 1. GDK_SCALE=2 forces 2x for X11 programs.
• Audio problems: the status line shows the device, rate and buffer; Settings › Audio shows the measured latencies. cargo run -p daw-engine --example hosts lists what cpal sees. The tick carries an overruns counter that grows when a recording ring buffer overflowed.
• Engine errors: a panic inside Engine::process is caught in the audio callback, the block is silenced, EngineStatus::engine_errors counts it, and a toast asks for a report; the panic message and backtrace are in the terminal (RUST_BACKTRACE=1). A plug-in putting out NaNs or runaway levels is contained and named in a toast (bad_audio_warning).
• “System overload”: the callbacks ran late for more than 60 ms in a row, so the engine shed load and the session stopped the transport (EngineStatus::overloads). The CPU meter in the control bar shows how close you are: Tick.cpu is the average, cpu_peak the worst recent block and late_blocks the blocks over 100%, a single one of which is a dropout but no overload (BlockLoad in dsp/status.rs). All of them are one thread’s load, so they won’t match a system monitor. fx_bench --release times the built-in effects; the audio thread runs with flush-to-zero, so denormals are not the cause.
• Plug-ins: cargo run -p vst3-host --example probe -- <name> loads and runs plug-ins outside the app. Settings › Plug-ins shows the last scan’s report, including bundles that crashed or timed out. The cache is plugins.json in the config folder; delete it (or use Rescan) to force a new scan.
• Settings and projects: settings.json and recent.json are in ~/.config/marbble ($XDG_CONFIG_HOME/marbble, %APPDATA%\marbble on Windows). A project is plain JSON in project.json; it is safe to read, and editing it by hand works if the app is closed.
• Engine state: everything the UI knows is in the Snapshot (getState().snap in src/store.ts) and the last Tick (currentTick()); a headless example is usually the quickest way to check what the engine does.
• Never test with your real projects folder: headless checks write into the scratch directory you pass; keep it away from ~/Music/Marbble.