DEBUG.md

Rama main · réplica de lectura del repositorio original.

# Debug Mode

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

## Enable Debug Logging

### Option 1: Command Line

```bash
# 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](#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`