Troubleshooting

Recordings are very quiet (or silent)

On Linux, the sound server (PipeWire or PulseAudio) has its own volume for each recording device, and it often isn’t at 100%. Marbble receives the signal after that volume, so a source at 40% lowers everything you record by about 24 dB, and a muted source records silence.

• Settings › Audio shows a warning with Set to 100% when the level is low; Marbble also shows a notice at launch.
• Or set it yourself: wpctl get-volume @DEFAULT_AUDIO_SOURCE@ shows it, and wpctl set-volume @DEFAULT_AUDIO_SOURCE@ 1.0 sets it to 100% (use the node id from wpctl status for another device). pavucontrol’s Input Devices tab does the same.
• Then set the recording level with the gain knob on your interface.

Crackles, clicks or dropouts

• Raise the I/O Buffer Size in Settings › Audio (256 or 512 samples), then Apply Changes.
• Watch the CPU meter in the control bar, its peak tick above all; freeze heavy tracks (snowflake button).
• Leave Processing Threads on Automatic. If dropouts started with a change to it, set it to 1 in Settings › Audio to see whether it makes a difference.
• Make sure real-time scheduling is available: on Linux, rtkit must be running (security.rtkit.enable = true; on NixOS). PipeWire’s own quantum can also be raised.
• Use PipeWire as the driver on Linux. Direct ALSA (hw:) devices lock the interface for Marbble alone.

Plug-in windows don’t open on Wayland

Plug-in editors are X11 windows, and GLX-based plug-in GUIs fail when GTK runs natively on Wayland in the same process. Marbble therefore runs its interface through XWayland on Linux by default (it sets GDK_BACKEND=x11 unless you set it). If you set GDK_BACKEND=wayland yourself, plug-in GUIs may fail to open; unset it. On Windows plug-in editor windows are not implemented yet; plug-ins still load and play, and their parameters can be automated.

Your computer’s audio is recorded, or loops back

Some USB devices (guitar pedals and multi-effects, some interfaces) loop the computer’s playback back into their recording input, so a recording picks up the backing track or system sounds, and monitoring can feed back.

• Check the device’s own settings or editor app for a loopback, “USB playback to input” or “re-amp” option and turn it off, or choose an input channel that doesn’t carry the loopback.
• Make sure only one of Marbble’s monitoring and the device’s direct monitoring is on (Settings › Audio › Monitoring, and the track’s I button).
• Use a different device for output than for input (Settings › Audio lets them differ), or turn down the device’s computer-playback level.
• On PipeWire, check in pw-top or a patchbay (qpwgraph, Helvum) that nothing else is linked into the device’s input.

Recordings are early or late

Set Recording Delay in Settings › Audio. See Latency compensation.

The CPU meter

The CPU meter in the control bar shows the audio load: how much of each buffer’s time it takes to finish the buffer, from when it starts until every track is done, however many threads work on it. It is not your system monitor’s CPU figure, which is shared across all cores: one audio thread at 80% on a 24-thread machine reads about 3% there. The audio load is what decides whether audio drops out, because a block that takes longer than the buffer plays arrives too late. Spreading tracks over more threads lowers it, down to what the slowest single track (with whatever feeds it) takes on its own, so one very heavy plug-in still sets the limit. Hover over the meter for the numbers and how many threads are playing just now.

• The bar is the average: amber above 50%, red above 80%.
• The thin tick is the worst single block lately. It stays for two seconds, then falls. A low bar with a high tick means the load comes in bursts, so an average alone looks fine while single blocks come close to the limit.
• The red CPU label means at least one block went over 100% since you last clicked the meter, so you probably heard a dropout. The tooltip counts them; click the meter to clear it.

A red label on its own is a dropout, and playback carries on. “System overload” is something else: blocks ran late back to back for more than about 60 ms, so Marbble also stops playback. Every overload shows on the meter too, but most late blocks never become an overload.

“System overload” and playback stops

When the computer can’t produce audio as fast as the device plays it for more than about 60 ms in a row, Marbble silences the output for a quarter of a second so the audio thread can catch up, stops playback or recording, and shows “System overload: the audio engine couldn’t keep up…”. (Without this, the system would kill Marbble for holding the processor.) Raise the I/O Buffer Size, bypass or freeze heavy plug-ins, and see Crackles, clicks or dropouts. Bounces and other offline renders are not affected.

“… put out invalid audio” and a plug-in goes quiet

Marbble checks the output of every plug-in, built-in or VST3, each block. NaNs are silenced and levels above +60 dBFS are clamped, so one unstable plug-in can’t blow up the rest of the mix or your speakers. When that happens, a message names the plug-in and the track (at most every few seconds while it continues). A built-in effect is also reset so it recovers. Bypass the plug-in or reset its settings; if a VST3 keeps doing it, report it to its maker.

“The audio engine hit an internal error and skipped some audio” means the engine itself failed for a block; the block is silenced instead of crashing. Please report it with the terminal output.

The playhead or meters freeze during a bounce

That is expected: renders run offline and the interface waits for them. Playback is silent until the render finishes.

Plug-ins are missing

Check Settings › Plug-ins: the plug-in may be switched off, its folder may not be searched (add it under VST3 Folders), or it may have failed in the last scan (expand the report). Rescan after installing plug-ins.

• On a Mac with Apple Silicon, a plug-in built only for Intel can’t load; the report says so. Install its Universal or Apple Silicon version.
• A project from another computer finds a plug-in installed in a different folder there by itself. A plug-in that isn’t installed at all shows struck through in the Mixer, and opening the project says which ones are missing. Its settings stay in the project, so it sounds as before on a computer that has it, even if you save the project here.

A blank window on Linux

Some GPU drivers need WEBKIT_DISABLE_DMABUF_RENDERER=1. Set it only if the window stays blank, because WebKit then draws on the CPU.