Skip to content

DEBUG.md

Latest commit

 

History

History
102 lines (67 loc) · 3.94 KB

DEBUG.md

File metadata and controls

102 lines (67 loc) · 3.94 KB
Raw

Debug Mode

Enable verbose logging to diagnose issues like "no audio detected" or transcription failures.

Enable Debug Logging

Option 1: Command Line

# macOS
/Applications/OpenWhispr.app/Contents/MacOS/OpenWhispr --log-level=debug

# Windows
OpenWhispr.exe --log-level=debug

Option 2: Environment File

Add to your .env file and restart:

OPENWHISPR_LOG_LEVEL=debug

Env file locations:

  • macOS: ~/Library/Application Support/open-whispr/.env
  • Windows: %APPDATA%\open-whispr\.env
  • Linux: ~/.config/open-whispr/.env ($XDG_CONFIG_HOME/open-whispr/.env when XDG_CONFIG_HOME is set)

These are the release-build folders; development and staging builds use their own (see Log File Locations).

Option 3: In-App Toggle

Open Settings → System → Debug Logging and turn on Debug mode. It takes effect right away in every window, with no restart, and is saved to the .env file above. The panel then shows the current log file and an Open Logs Folder button.

A --log-level flag (Option 1) takes precedence over the .env file and the toggle for as long as the app runs with it, so the toggle can't change the level in that session.

Log File Locations

  • macOS: ~/Library/Application Support/open-whispr/logs/debug-*.log
  • Windows: %APPDATA%\open-whispr\logs\debug-*.log
  • Linux: ~/.config/open-whispr/logs/debug-*.log ($XDG_CONFIG_HOME/open-whispr/logs/ when XDG_CONFIG_HOME is set)

These folders are for release builds. Development and staging builds use OpenWhispr-development and OpenWhispr-staging in the same parent folder instead. The Open Logs Folder button (Option 3) always opens the folder for the build you are running.

What Gets Logged

Stage Details
FFmpeg Path resolution, permissions, ASAR unpacking
Audio Recording Permission requests, chunk sizes, audio levels
Audio Processing File creation, Whisper command, process output
IPC Messages between renderer and main process
Agent Mode Streaming responses, conversation management, model selection
Meeting Detection Process monitoring, audio activity, calendar event matching
Meeting Transcription WebSocket connection, Realtime API session, audio buffering
Google Calendar OAuth flow, token refresh, event sync
Media Control Pause/resume events, player detection (MediaRemote/GSMTC/MPRIS2)
Audio Storage File retention, cleanup cycles, storage usage

Common Issues

"No Audio Detected"

Look for:

  • Speech gate skipped transcription with reason: "silence" → Audio too quiet; peakRms shows how loud the recording got
  • No text transcribed → Audio too short, silent, or in an unsupported format
  • FFmpeg not available → Path resolution failed

Transcription Fails

Look for:

  • whisper-server stderr → whisper.cpp errors
  • whisper-server process exited with a non-zero code → Process failure
  • Failed to parse Whisper output → Invalid JSON

Permission Issues

Look for:

  • Microphone Access Denied
  • isExecutable: false → FFmpeg permission issue

Sharing Logs

When reporting issues:

  1. Enable debug mode and reproduce the issue
  2. Locate the log file
  3. Redact any sensitive information
  4. Include relevant log sections in your issue report

Disable Debug Mode

Debug mode is off by default. To ensure it's disabled:

  • Turn off Debug mode in Settings → System → Debug Logging (this sets OPENWHISPR_LOG_LEVEL=info in .env)
  • Remove --log-level=debug from command
  • Remove OPENWHISPR_LOG_LEVEL from .env