Troubleshooting

Troubleshooting

Start with the visible symptom and preserve Prism's exact error message. Reinstalling is rarely the first useful step because audio permissions, device selection, DAW scan paths, and terminal environment are independent.

The scopes are flat or frozen

1. Open Settings > Audio > Source and read the status.
2. If it says Capturing, confirm the selected output is playing audio, the input has signal, or the DAW is processing the selected Bridge. Check L/R routing and channel activity for a device source.
3. Return Trim to 0.0 dB.
4. For a device source, select Use Default, then reselect the intended device. For a waiting Bridge, restore or choose the intended DAW instance.
5. Select Retry after correcting permissions or reconnecting hardware.
6. Set Performance to 60 or 30 FPS only if data is arriving but drawing is visibly stuttering.

A flat display during silence is normal even when the status says Capturing. Hidden modules do not request their analyzer stream; re-enable the module under Modules.

If Prism unexpectedly shows Default Input, read the notice before dismissing it. System-output capture failed or was unavailable and Prism started the default input as a fallback. Correct the platform output-capture problem, then reselect the desired output and retry.

Channels are missing or the matrix moves but the scopes are silent

The matrix lists channels exposed by the selected OS device, not every physical connector that an interface could theoretically use. Check the interface's current OS/driver channel configuration and select the correct endpoint. Windows capture uses shared WASAPI; Linux needs PulseAudio or PipeWire's PulseAudio compatibility service.

Activity fills cover all source channels before routing and trim. If they move but the scopes do not, select an active channel in L and R and return Trim to 0.0 dB. Selecting one channel in both rows is valid for mono inspection. The matrix applies to system/input capture, not Bridge's mono/stereo DAW stream.

After a channel-layout change, a saved route may reset to the default pair. Reselect the intended channels. After upgrading from an older browser input ID, a Default Input notice means you should choose the intended native input again. See Channel Routing.

Prism Bridge is missing, waiting, or silent

If the DAW cannot find the insert, check plugin installation. If Prism shows no connected Bridges, open the desktop app on the same computer and confirm the Prism Bridge insert is loaded in the DAW. Its status dot distinguishes waiting, available, and selected.

Waiting in desktop capture means the selected instance is unavailable; Prism deliberately keeps that selection. Reopen its project, restore the insert, or choose another instance under DAW Bridges. A connected but silent instance instead calls for checking playback/input monitoring and the DAW's mute, bypass, or suspended-track behavior.

Duplicate saved instances can require explicit reselection. Keep any desktop listener error text; sandboxed hosts must allow the local connection. See Prism Bridge.

A DAW timeline is missing or shows seconds instead of beats

Select Bridge as the desktop audio source, then check Timeline in Waveform or Spectrogram settings. Off hides the ruler. Bars + Beats requires musical position information from the DAW and falls back to labeled seconds when that information is missing. System/input capture does not carry the host timeline.

Loop, Jump, and Gap markers explain discontinuities in retained history; they are not recording edits. See Bridge timelines.

A reference track will not load or Match level is disabled

Load one readable mono/stereo WAV, AIFF, FLAC, or MP3 through Spectrum's Reference tab, or drop that single file onto Spectrum. Check the import error before replacing or converting the file. A canceled or failed replacement preserves the prior reference.

Wait for analysis to finish, then play at least one second of non-silent audio into Spectrum to enable Match level. It adjusts the reference once using recent audio; it is not automatic LUFS normalization. Difference is relative to the reference, and silence may leave no useful comparison. See Spectrum Reference Tracks.

macOS cannot capture system audio

System-output capture requires macOS 14.2 or newer.

Open System Settings > Privacy & Security and allow Prism in the relevant system-audio recording category. For a microphone or interface input, also check Microphone. Quit and reopen Prism after changing permission.

An installed release and a locally built Prism app may appear as different permission identities. Approving one does not necessarily approve the other.

If prism-tui fails while the desktop app succeeds, keep its exact terminal error and confirm that the terminal-launched executable is allowed to capture system audio under the current macOS privacy settings.

Windows output capture stopped

Prism uses WASAPI loopback. Sleep, an unplugged interface, driver replacement, or a sample-rate change can invalidate a device.

Choose Use Default, wait for Windows to expose the device again, then reselect it. Confirm that the selected endpoint is the one receiving playback and that applications are not using an unexpected exclusive path.

Linux shows no usable outputs

Prism needs PulseAudio monitor sources. On PipeWire, confirm the PulseAudio compatibility service is running in the same graphical user session.

Check that:

• the chosen sink exists and has a monitor source;
• Prism is not isolated from the session audio socket by a sandbox;
• the desktop app and terminal were launched as the same normal user;
• the sound service recovered after sleep or device hot-plug.

Native Wayland also prevents Prism from choosing exact screen coordinates or programmatically moving the rack to the top/bottom. Those are compositor limitations, not capture failures.

Settings do not appear until the window is moved on Hyprland

On Hyprland with Prism running through native Wayland, settings may not appear until you move the Prism window. This is a Hyprland compositor behavior outside Prism's control, not a limitation of every Wayland compositor and not a new 0.4.0 regression.

Moving the window can reveal the settings. The workaround confirmed by testers is to run Prism through XWayland:

1. Quit Prism, including the tray process if Close to tray is enabled.
2. Add --ozone-platform=x11 to Prism's launch command or its launcher's application arguments.
3. Start Prism again using that command or launcher.

For example, append the option after the path to the executable or AppImage you normally launch. Preserve the existing executable path and other needed arguments. This is a startup option, not a setting inside Prism, and it must be used on subsequent launches to keep using XWayland.

Windows screen-space reservation is unavailable or unexpected

Reserve screen space is a Windows-only option in the rack's Reposition window menu and its tray equivalent. It requires the native docking support included in a supported build; ordinary Top/Bottom positioning alone does not reserve workspace.

Minimizing or hiding Prism releases the strip. A foreground fullscreen application can cover the dock. If the selected monitor disappears, Prism restores a floating rack on the primary display and does not automatically redock after reconnection. Choose the desired monitor/edge again.

Drag the grab handle to float the rack, or disable Reserve screen space to restore its saved floating geometry. Profile changes do not turn docking off. See Rack Layout and Windows.

The display is moving but looks slow

• Check the measured FPS pill beside Settings > Performance.
• Try Sync, then a fixed 60 or 30 target.
• Reduce large FFT sizes, Waterfall ridge density, or Spectrogram Sharp/Sharper work.
• Disable unnecessary Spectrum heat history or close unused plugin editors.
• Hide rack modules that are not needed.

Frame target affects drawing only. Do not change audio devices to solve a purely graphical frame-rate issue. For what the published latency result does and does not measure, see Understanding the Scopes.

A window is missing or off-screen

Use the tray menu to Show Prism, then use Window > Position to move the main rack to the top or bottom where supported.

For detached modules, load a profile with the module docked or use the module's Pop in control if the window remains reachable. Shareable .prsm files omit coordinates, so an imported profile should let the operating system place its popouts safely.

On Wayland, exact placement is controlled by the compositor. On every platform, a monitor-layout change can make old local bounds unsuitable; switch profiles or recreate the popout after returning the main window to a visible display.

Blur is unavailable or transparency behaves differently

Blurred mode is supported on macOS and Windows 11 build 22621 or newer. Use Clear or Solid elsewhere.

Transparent modes use different native windows, disable normal snapping, and can be recreated when the mode changes. Some capture applications or compositors do not preserve alpha; use a solid chroma-key theme in that case.

A profile will not import

Confirm the file has a .prsm extension and was not truncated, renamed from another format, or hand-edited into invalid data. Current desktop profiles use format version 7 and support importing older formats. A profile written by a newer release may not be understood by an older app.

Keep the original file. If it came from a different Prism release, open it with that release and save/export a fresh copy before rebuilding the layout manually. TUI profiles are not desktop .prsm files.

A custom theme does not appear

1. Put the .iro file in Documents/Prism Themes.
2. Keep all required fields and the value formats from _TEMPLATE.iro.
3. Select Refresh and read any reported parse error.
4. Correct the file, save it as plain text, and refresh again.

Do not overwrite the protected Default theme. DAW plugins follow the active desktop theme; restart or reopen a plugin editor if a host has suspended its interface.

Now Playing is empty or stale

• Show the module or open Now Playing > Configure... so provider checks stay active. The rack's general settings alone do not activate them.
• Check provider priority and make sure the intended provider is actually playing.
• Open the provider status and select Retry.
• For Astra, verify the local API address and securely stored token.
• For Spotify on macOS, check Automation permission; on Linux, check the MPRIS session.
• For TIDAL on Windows, start the local app and playback so its media session appears. On Linux, use a compatible dedicated client with MPRIS enabled and gdbus available in the desktop session; browser tabs are not supported.
• On macOS, TIDAL must own system Now Playing. Missing TIDAL transport controls are expected; use the player itself. Artwork depends on what macOS supplies. See TIDAL integration.

On Linux, saving an Astra token requires a supported keyring. Prism reports an error instead of storing the secret insecurely when no supported keyring is available.

Rolling capture will not drag a full clip

Wait until the Clip chip reaches Ready. A new source or restarted capture clears the buffer. Increasing duration retains existing audio but needs time to fill the extra space; decreasing duration keeps the newest portion. Changing WAV format does not clear history.

If the destination rejects file drops, open Documents/Prism Captures and import the generated WAV manually. Check available disk space if the drag begins but no file can be created. Remember that existing clips are not deleted automatically.

A captured WAV is clipped or rejected by another app

16-bit PCM provides broad compatibility but clips values beyond full scale when exported. 32-bit float preserves those captured values for attenuation in a compatible editor; it does not repair a signal already clipped before Prism captured it. Try 16-bit PCM if the destination cannot import float WAVs, or use an editor that supports float when retaining those samples matters.

Neither format normalizes or dithers the recording. Check Trim and the original source level before exporting again. See Rolling Audio Capture.

A DAW cannot find Prism plugins

Confirm you installed a package that contains plugins. Linux AppImage and portable packages do not perform normal plugin installation.

Check the host's scan paths, then run a full rescan and restart it. The host must support the chosen VST3, CLAP, or macOS AU format. Keep complete VST3/AU and macOS CLAP bundles intact; Windows/Linux CLAP products are single files. See DAW Plugins for platform locations.

A plugin window is blank

On Windows, install or repair Microsoft Edge WebView2 Evergreen Runtime if the plugin displays Prism's WebView2 fallback. Restart the DAW afterward.

On Linux, analyzer editors need compatible WebKitGTK in the DAW environment. For a Flatpak DAW, installing it only on the host is insufficient; the runtime must provide it. Successful plugin scanning is separate from editor support. Check the display session and graphics environment too.

Bridge uses a native nameplate and does not need the analyzer editors' browser runtime. See DAW Plugins.

Analyzer settings saved in one DAW instance do not automatically change another instance. The active desktop theme is global, but per-instance settings take precedence over the active desktop profile.

prism-tui is not found

Open a new terminal after installing. The complete installers place or link the executable as follows:

• macOS PKG: /usr/local/bin;
• Windows installer: Prism's TUI resource directory is added to machine PATH;
• Linux DEB/RPM: /usr/bin.

ZIP, portable Windows, Linux tar.gz, and AppImage do not all perform this integration; AppImage does not include the TUI at all. Run the packaged executable by its full path or install a package that integrates it.

The TUI is garbled, too small, or too expensive

• Enlarge the terminal to at least 44 × 12 cells.
• Under Appearance, choose Compatible for 256 colors or Safe for ANSI colors.
• Lower refresh rate from experimental 120 to 60 or 30 FPS.
• Reduce Vectorscope Point detail or Spectrogram clarity.
• Use r to reset analyzers; use q, Esc, or Ctrl-C from the normal rack to quit.

If interactive mode says it requires a terminal, do not pipe the dashboard. Use --list-outputs for scriptable device listing.

Reporting a useful issue

Before opening a GitHub issue, collect only non-sensitive details:

• Prism version and package type;
• operating system version and display session (Wayland/X11 where relevant);
• selected source type and audio backend;
• exact error text;
• DAW name/version and AU, VST3, or CLAP when applicable;
• terminal emulator and Terminal mode for TUI problems;
• repeatable steps and whether the Default profile/theme reproduces it.

Do not post Astra API tokens, private filenames, captured audio, or other credentials. If a custom profile/theme reproduces the issue, inspect it before attaching it.