Diagnostic Tool Manual

Version 1.1.0

1. Overview

The UB DSP Diagnostic Tool helps you troubleshoot issues with UB DSP audio plugins. It automatically scans your system and generates a diagnostic report that can be sent to UB DSP for analysis.

The tool performs three main tasks:

System scan — detects your OS, CPU architecture, RAM, and installed DAWs
Plugin scan — checks if UB DSP plugins are installed, reads log files, and detects crash locks
Report upload — sends the collected information securely to UB DSP for analysis

The tool is available for macOS, Windows, and Linux, and can run in graphical (GUI) or command-line (CLI) mode.

2. Installation

macOS

Download and open the .dmg file
Drag UB DSP Diagnostic Tool to your Applications folder
Launch from Applications or Spotlight

Note: If macOS shows a warning about an unidentified developer, right-click the app and choose Open, then click Open in the dialog.

Windows

Run the .exe installer
Follow the installation wizard
Launch from the Start Menu or desktop shortcut

Linux

Download the .AppImage file
Make it executable: chmod +x UB-DSP-Diagnostic-Tool-x86_64.AppImage
Run it: ./UB-DSP-Diagnostic-Tool-x86_64.AppImage

Note: If the AppImage won't run, make sure FUSE is installed: sudo apt install libfuse2

3. Using the Application (GUI Mode)

When you launch the tool, it immediately scans your system and displays the results. The window has four sections:

System Information

Shows your operating system, CPU architecture, RAM, and any detected DAWs (Bitwig Studio, REAPER, Ableton Live, Logic Pro, FL Studio, Cubase, Studio One, Pro Tools, Ardour, Audacity).

Plugin Status

For each known UB DSP plugin, the tool displays:

Field	Meaning
installed	Plugin binary found in standard audio plugin directories
not found	Plugin not found — it may not be installed
Log	Whether the plugin's telemetry log file exists
Last breadcrumb	The most recent log entry — useful for identifying where a crash occurred
crash lock	A `.lock` file is present, indicating a potential previous crash
Version	Plugin version extracted from the log file

Email (Optional)

You can enter your email address if you'd like UB DSP to follow up with you about the diagnostic results. This is entirely optional.

Send Report

Click Send Report to upload the diagnostic data to UB DSP. The status bar below the button shows whether the upload succeeded or failed.

4. Command-Line Mode

The tool supports a headless command-line mode, useful for servers, SSH sessions, or automated workflows. Launch with the --cli flag:

macOS

"/Applications/UB DSP Diagnostic Tool.app/Contents/MacOS/UB DSP Diagnostic Tool" --cli

Windows

"C:\Program Files\UB DSP\UB DSP Diagnostic Tool\UB DSP Diagnostic Tool.exe" --cli

Linux

./UB-DSP-Diagnostic-Tool-x86_64.AppImage --cli

CLI Workflow

The tool prints system information and plugin scan results to the terminal
You are prompted for an email address (press Enter to skip)
You are asked to confirm: Send diagnostic report? [Y/n]
The report is uploaded and a success/failure message is shown

Example Output

=================================================
  UB DSP Diagnostic Tool v1.1.0 (CLI mode)
=================================================

System Information
------------------
OS:  Mac OS X 15.3.1
CPU: arm64
RAM: 16 GB
DAWs: Bitwig Studio, REAPER

Plugin Scan Results
-------------------
Grit Blender
  Installed:     yes
  Log found:     yes
  Last breadcrumb: processBlock OK
  Crash lock:    no
  Version:       1.3.0

Vowel Blender
  Installed:     yes
  Log found:     yes
  Last breadcrumb: [init] UBTelemetry started
  Crash lock:    no
  Version:       1.0.1

Email for follow-up (press Enter to skip):
Send diagnostic report? [Y/n]: Y
Sending...
Report sent successfully!

5. What Information Is Collected

The diagnostic report contains the following data:

Category	Data
System	OS name and version, CPU architecture, RAM amount, list of detected DAWs
Plugins	For each UB DSP plugin: installed status, version, log file content, last breadcrumb entry, crash lock status
Contact	Email address (only if you provide one)
Metadata	Tool version, timestamp

Important: The tool does not collect any audio content, project files, DAW settings, license keys, personal files, or any data outside of UB DSP plugin directories.

6. Interpreting the Results

installed — Plugin Found

The plugin binary was found in the standard plugin directories on your system. This is normal and expected.

not found — Plugin Not Installed

The plugin binary could not be found. Try reinstalling it using the official installer from ubdsp.com/downloads.

crash lock detected

A .lock file was found in the plugin's data directory. This typically means the plugin did not shut down cleanly, which may indicate a crash during the last session. The lock file is automatically cleared when the plugin next starts successfully.

If you're experiencing repeated crashes, sending the diagnostic report will help UB DSP investigate the issue.

Log File & Breadcrumbs

Each UB DSP plugin writes a log file with timestamped entries called "breadcrumbs." The last breadcrumb shows what the plugin was doing most recently. If a crash occurred, this helps identify where it happened:

processBlock OK — plugin was processing audio normally
prepareToPlay — plugin was initializing for playback
stateLoad — plugin was loading saved state from the DAW
constructor — plugin was being created

7. Troubleshooting

"Failed to send report. Check your internet connection."

The upload could not reach the UB DSP server. Check that you are connected to the internet and that no firewall is blocking ubdsp.com.

Plugin shows "not found" but it is installed

The tool searches standard plugin directories:

macOS: /Library/Audio/Plug-Ins/VST3, /Library/Audio/Plug-Ins/CLAP, /Library/Audio/Plug-Ins/Components
Windows: C:\Program Files\Common Files\VST3, C:\Program Files\Common Files\CLAP
Linux: ~/.vst3, ~/.clap, /usr/lib/vst3, /usr/lib/clap

If you installed the plugin to a custom location, it may not be detected by the diagnostic tool.

macOS: "app is damaged" or cannot be opened

Right-click the app and choose Open. If that doesn't work, open Terminal and run:

xattr -cr "/Applications/UB DSP Diagnostic Tool.app"

Linux: AppImage won't run

Make sure FUSE is installed:

sudo apt install libfuse2

"Please enter a valid email address."

The email field requires a valid format (e.g., name@example.com). You can also leave it empty and skip it entirely.

8. Privacy

The UB DSP Diagnostic Tool is designed with privacy in mind:

It only reads files inside UB DSP plugin data directories
It does not access your audio projects, DAW settings, or other personal files
Your email address is optional and only used for follow-up support
Diagnostic reports are sent over HTTPS and stored securely on UB DSP servers
No analytics, tracking, or telemetry is included in the tool itself

For more information, see our Privacy Policy.

9. Support

If you have questions or need help:

Website: ubdsp.com
Contact: ubdsp.com/contact
Diagnostic page: ubdsp.com/diagnostic — view your diagnostic reports online
FAQ: ubdsp.com/faq