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 actually playing audio or the selected input has signal.
3. Return Trim to 0.0 dB.
4. Select Use Default, then reselect the intended device.
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.

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.

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

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 4.

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

• Confirm the module is visible or detached; Astra connection demand stops when the module is hidden.
• 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.
• Do not expect TIDAL to connect yet; it is marked Coming soon.

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, restarted capture, or changed duration clears/refills the buffer.

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 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 entire .vst3 or .component bundle must be present. 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, confirm the host can provide the required WebKit/GUI environment and is not sandboxing the plugin from display resources. Test another host or the matching standalone build if available to separate a host problem from an installation problem.

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 or VST3 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.