Troubleshooting

Recording

"No audio detected" — meter stays flat, transcript is blank

Almost always one of:

1. Microphone permission missing.
   • macOS:System Settings → Privacy & Security → Microphone → enable NeuroBridgeEDU. Restart the app.
   • Windows:Settings → Privacy & Security → Microphone → enable NeuroBridgeEDU.
2. Wrong device selected. Open the device dropdown on the Home screen and pick your mic by name. Avoid "Default".
3. Hardware mute. Many headsets have a physical mute switch.
4. Sample rate mismatch. Quit the app, change your OS audio settings to 48 kHz if your interface supports it, then relaunch.

If still broken, watch the audio meter on the Home screen while you speak. If the bars don't move, you have either the wrong device selected or a missing permission.

Audio sounds clipped or distorted

The level meter is constantly hitting the red. Lower the input volume in your OS audio settings until peaks land roughly mid-meter. Move the mic 5–10 cm further from your mouth.

System audio not being captured

• macOS: Confirm BlackHole 2ch is installed and your Multi-Output Device is the active system output. Pick BlackHole from the System Audio dropdown. Test by playing audio and watching the meter move.
• Windows: Pick the system audio source from the System Audio dropdown. Restart the app if it doesn't pick up.
• Linux: Verify your loopback source exists with pactl list sources (PulseAudio) or pw-cli ls Node (PipeWire), then select it from the System Audio dropdown.

App crashes when starting recording on macOS

Almost certainly a permissions race. Quit fully, re-launch, and try again. If it still happens, grab the most recent log from Settings → Diagnostics → Open Log Folder.

Recording shortcut feels off

The keyboard model is:

• Cmd+Shift+R / Ctrl+Shift+R — start or stop recording (works from the Home screen).
• Space — pause / resume during recording. Doesn't start one.
• Escape — stop recording.

If Space doesn't seem to do anything, you're probably not in the recording state yet.

Transcription

Transcription is taking forever

Expected speed is roughly 0.3×–1× recording duration depending on hardware and model. If yours is much slower:

1. Switch to a smaller Whisper model (Settings → Transcription → pick small or base).
2. Close other heavy apps. Whisper needs CPU/GPU headroom.
3. Check RAM usage. Over 80% means you should free memory before transcribing.
4. macOS Apple Silicon: Metal acceleration is enabled in the shipping build.
5. Windows NVIDIA: confirm CUDA drivers are current.
6. For very long recordings, consider splitting them into shorter sessions to keep memory pressure manageable.

Wrong language transcribed

Auto-detect can guess wrong on short clips. Set the language explicitly in Settings → Transcription → Language, then Regenerate the transcript from the meeting view.

Transcript is missing chunks

• Check whether the audio meter was moving consistently throughout the recording.
• If the recording was very long, check your free disk space — WAVs are big.
• Whisper occasionally drops very quiet segments. Use a louder microphone or move closer to it.

Transcription failed entirely

1. Open the meeting and try regenerating from there.
2. Check the log for an error in the transcription module (Settings → Diagnostics → Open Log Folder) and share it via the Diagnostic Report.

Summaries

Summary is empty or partial

The summarisation model has a context window. Very long transcripts get chunked, and occasionally a chunk fails silently. Try:

• Open the meeting and press Regenerate summary — most partial-summary issues clear on a single retry.
• Switch to a larger summarisation model (Settings → Summarisation) for denser material.
• If you're using a cloud provider via your own API key, check the provider dashboard for rate-limit errors.

Summary tone or format is wrong

Change the reading-style preference in Settings → Reading style (or per-meeting via the template selector above the summary), then Regenerate. If you've authored a custom template, check that the placeholders are spelled correctly.

Cloud providers (BYOK / Pro)

"Authentication failed" or 401 errors

The API key is wrong, expired, or revoked. Open Settings → Summarisation, re-paste the key, save, and retry. Make sure you copied the key without a trailing newline.

"Rate limit exceeded" errors

You've hit the provider's rate limit. Wait a minute and retry, or upgrade your plan with the provider. NeuroBridgeEDU doesn't proxy or retry on your behalf — the limit is between you and the provider.

App startup

App won't open / crashes immediately

1. Reboot. Resolves a surprising fraction of these.
2. Try launching from the command line to capture any startup error.
3. Inspect the log folder. On macOS, ~/Library/Application Support/NeuroBridgeEDU/logs/; on Windows, %APPDATA%\NeuroBridgeEDU\logs\; on Linux, ~/.local/share/NeuroBridgeEDU/logs/.
4. File a GitHub issue with the most recent log attached. Include your OS version and app version.

Onboarding loops

Rare. If you can't get past the model-download step, your network is likely blocking Hugging Face. Try a different network, or download the model file manually from the URL shown in the log and place it in the models/ folder, then restart the app.

Diagnostics

For any issue we can't help with from the descriptions alone, the diagnostic report is the fastest way to a fix:

1. Settings → Diagnostics → Copy Diagnostic Report.
2. Paste the report into a GitHub issue (preferred) or an email to contact@neurobridgeedu.eu.
3. Describe what you were doing when the issue happened, in one or two sentences.

The report includes your OS, app version, recent log lines, and any recent error stack traces. It does not include any recordings, transcripts, or summaries.

If you'd rather email us first, that's also fine — see the contact page.