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 and Wayland

Plug-in editors on Linux are X11 windows, which a Wayland desktop shows through XWayland. By default Marbble runs its own interface through XWayland too (it sets GDK_BACKEND=x11 unless you set it). To run the interface natively on Wayland, start it with MARBBLE_WAYLAND=1 (MARBBLE_WAYLAND=1 marbble); without a Wayland session it falls back to X11. Plug-in editors still open as XWayland windows, and Marbble keeps their OpenGL drawing apart from its own, which OpenGL editors such as Zam’s and Dragonfly’s need. It’s new and less tried than the default: the desktop decides where windows open, so a detached Mixer or Editor doesn’t reopen where you left it. If something looks wrong, start Marbble without the variable. Setting GDK_BACKEND=wayland yourself has the same effect.

On Windows plug-in editor windows are not implemented yet; plug-ins still load and play, and their parameters can be automated.

Plug-in windows are small or blurry on a HiDPI screen

On Linux, Marbble tells each plug-in editor the display’s scale as it opens, and plug-ins that support it draw at that size (all those tried do: LSP, Dragonfly, Zam, CHOW Tape, TONE3000). The scale is the one your desktop gives X11 programs: GDK_SCALE, then the desktop’s GTK scale setting, then Xft.dpi divided by 96 (so Xft.dpi: 192 in ~/.Xresources is 2x). A plug-in window opened before you changed it keeps its size until you close and reopen it.

• Small: your desktop runs X11 programs at their own resolution without telling them a scale (Hyprland with xwayland:force_zero_scaling, for example). Set Xft.dpi (and GDK_SCALE=2 for 2x, which also enlarges Marbble’s interface).
• Blurry but the right size: the desktop enlarges X11 windows itself, as Hyprland and GNOME do by default. That’s the desktop, not Marbble; switching it to let X11 programs scale themselves, as above, makes them sharp.
• A few plug-ins with bitmap panels (Zam’s) open a larger window but draw at their usual size in its top-left corner; they do the same in any host on a scaled desktop.

On macOS the system handles it, and plug-ins draw at the screen’s resolution.

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 and the figure beside “CPU” are the average: the bar turns amber above 50% and 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.

When the message says a processing thread “stayed in” a track, a plug-in on that track didn’t finish its work for a tenth of a second. That thread is left out from then on, so the plug-in can’t take Marbble down with it even if it never finishes, and the other threads play on. Reset Audio Engine in Settings › Audio brings it back. Until then Settings › Audio says how many threads play.

“… stopped responding” and a track goes quiet

When a plug-in on one of the extra processing threads (Settings › Audio › Processing Threads) doesn’t return from its work for a tenth of a second, Marbble leaves it there and plays on without it. After a moment of silence, the rest of the mix carries on. The plug-in’s track, and anything that track feeds (an aux it sends to, the summing stack it plays through, a track it keys a side-chain for), are silent from then on, and a message names the plug-in and the track. Playback doesn’t stop, but a recording does, as the take now has a gap.

If the plug-in responds again later, the track comes back by itself, with the plug-in loaded afresh, and a message says so. Otherwise Reset Audio Engine in Settings › Audio loads the plug-ins again and brings the tracks back, along with the thread. Meanwhile bounces, exports, Freeze and Bounce in Place are refused, as those tracks would be missing from them, and saving keeps the settings the stuck plug-in was last saved with rather than asking it, as it may never answer. A plug-in that stops responding on the audio thread itself can’t be left like this.

“… 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.

“File Dialogs Unavailable” on Linux

GTK’s file chooser (Open, Save As, Import, Export, choosing a folder) needs GTK’s settings schema org.gtk.Settings.FileChooser, and without it GTK would end the program. When it isn’t installed, Marbble says so instead of opening the dialog, and your project stays open. The packages (Nix, AppImage, .deb, .rpm) bring the schema; if you see the message, install your distribution’s GTK 3 package (on Debian and Ubuntu, libgtk-3-common), or start Marbble from its package rather than a copied binary.