> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting & FAQ

> Common issues, solutions, and frequently asked questions

<Note>
  **Beta Software** - The BuildBetter Local Recorder is currently in beta. [Report issues on GitHub](https://github.com/buildbetter-app/bb-recorder/issues).
</Note>

# Troubleshooting & FAQ

## Common Issues

### No Audio Being Recorded

<AccordionGroup>
  <Accordion title="Microphone not working">
    **Symptoms:** Recording shows no audio from your microphone.

    **Solutions:**

    1. Check that Microphone permission is granted:
       * Open **System Settings → Privacy & Security → Microphone**
       * Ensure **BuildBetter.ai Recorder** is enabled
    2. Verify the correct microphone is selected in Settings
    3. Test your microphone in another app (e.g., Voice Memos)
    4. Try selecting "Use System Default" in audio device settings
  </Accordion>

  <Accordion title="System audio not working">
    **Symptoms:** You can hear yourself but not others on the call.

    **Solutions:**

    1. Check that Screen Recording permission is granted:
       * Open **System Settings → Privacy & Security → Screen Recording**
       * Ensure **BuildBetter.ai Recorder** is enabled
       * **Restart the app** after granting this permission
    2. Make sure the call audio is playing through your selected output device
    3. Some apps (like FaceTime) may block audio capture for privacy
  </Accordion>

  <Accordion title="Audio device settings not saving">
    **Symptoms:** Changed audio device, but it reverts after restart.

    **Solutions:**

    1. Update to version 0.1.28 or later (this was fixed)
    2. Select "Use System Default" to always use the OS default
    3. If selecting a specific device, make sure that device is still connected
  </Accordion>
</AccordionGroup>

### Transcription Issues

<AccordionGroup>
  <Accordion title="Transcription not appearing">
    **Symptoms:** Recording works but no transcript shows.

    **Solutions:**

    1. Ensure a Whisper model is downloaded (check Settings → AI Models)
    2. Verify "Auto-transcribe recordings" is enabled in Settings
    3. Check that you have enough disk space (\~500MB free)
    4. Try downloading a different Whisper model
  </Accordion>

  <Accordion title="Transcription is inaccurate">
    **Symptoms:** Many errors in the transcript.

    **Solutions:**

    1. Try a larger Whisper model (Small or Medium) for better accuracy
    2. Ensure good microphone quality and positioning
    3. Reduce background noise
    4. Note: Whisper works best with clear English speech
  </Accordion>

  <Accordion title="Transcription is slow">
    **Symptoms:** Long delay before text appears.

    **Solutions:**

    1. Use the Base English model for fastest performance
    2. On Intel Macs, transcription will be slower than Apple Silicon
    3. Close other resource-intensive apps
    4. Ensure your Mac isn't in low-power mode
  </Accordion>
</AccordionGroup>

### AI Chat Issues

<AccordionGroup>
  <Accordion title="AI Chat not available">
    **Symptoms:** Can't ask questions about recordings.

    **Solutions:**

    1. Download an LLM model in Settings → AI Models
    2. The download is large (\~2GB) - ensure stable internet
    3. Check that LLM is enabled in Settings
  </Accordion>

  <Accordion title="AI responses are slow">
    **Symptoms:** Long wait time for AI responses.

    **Solutions:**

    1. Use the smaller Llama 3.2 1B model for faster responses
    2. Apple Silicon Macs are significantly faster than Intel
    3. Close other apps to free up memory
    4. Shorter transcripts = faster responses
  </Accordion>

  <Accordion title="AI gives poor answers">
    **Symptoms:** AI responses aren't helpful or accurate.

    **Solutions:**

    1. Be specific in your questions
    2. For long recordings, ask about specific topics
    3. The local LLM is less capable than cloud AI - keep expectations reasonable
    4. Try rephrasing your question
  </Accordion>
</AccordionGroup>

### App Issues

<AccordionGroup>
  <Accordion title="App won't open">
    **Symptoms:** App crashes on launch or won't start.

    **Solutions:**

    1. Check macOS version (requires 12.0 Monterey or later)
    2. Try deleting preferences:
       ```bash theme={null}
       rm -rf ~/Library/Application\ Support/com.buildbetter.recorder/
       ```
    3. Re-download and reinstall the app
    4. Check Console.app for crash logs
  </Accordion>

  <Accordion title="App not appearing">
    **Symptoms:** App is running but you can't see it.

    **Solutions:**

    1. Check if "Hide until meeting" is enabled - disable it in the menu bar dropdown
    2. Click the dock icon to open the Dashboard
    3. Right-click the menu bar icon and select "Show Recorder"
    4. The floating bar might be off-screen - try Notch Mode to reset position
  </Accordion>

  <Accordion title="High CPU/memory usage">
    **Symptoms:** Mac running hot or slow during recording.

    **Solutions:**

    1. Use the Base English Whisper model (smallest/fastest)
    2. Close the AI Chat when not using it
    3. Disable live transcription if not needed
    4. Apple Silicon Macs are much more efficient than Intel
  </Accordion>
</AccordionGroup>

### Meeting Detection Issues

<AccordionGroup>
  <Accordion title="Meetings not being detected">
    **Symptoms:** App doesn't recognize when you're in a meeting.

    **Solutions:**

    1. Enable "Advanced detection" in Settings (requires Automation permission)
    2. Grant Automation permission in System Settings
    3. Increase detection sensitivity (try Medium or Low)
    4. Some meeting apps may not be supported yet
  </Accordion>

  <Accordion title="False meeting detections">
    **Symptoms:** App thinks you're in a meeting when you're not.

    **Solutions:**

    1. Increase detection sensitivity to High or Very High
    2. Disable "Auto-record on meeting" and use manual recording
    3. Adjust the auto-record threshold to Very High
  </Accordion>
</AccordionGroup>

***

## Frequently Asked Questions

### General

<AccordionGroup>
  <Accordion title="Is my data really private?">
    **Yes.** All processing happens locally on your Mac:

    * Audio is never uploaded to any server
    * Transcription runs locally via Whisper
    * AI chat uses a local LLM
    * No analytics or telemetry is collected

    The only exception is if you explicitly enable BuildBetter cloud sync.
  </Accordion>

  <Accordion title="Does it work offline?">
    **Yes.** Once you've downloaded the AI models, the app works completely offline. No internet connection is required for recording, transcription, or AI chat.
  </Accordion>

  <Accordion title="Is it really free?">
    **Yes.** The Local Recorder is completely free with no limitations. Optional BuildBetter cloud features require a subscription.
  </Accordion>

  <Accordion title="Does it work on Intel Macs?">
    **Yes**, but performance is significantly better on Apple Silicon (M1/M2/M3). Intel Macs will have slower transcription and AI responses.
  </Accordion>

  <Accordion title="Can I record system audio without Screen Recording permission?">
    **No.** macOS requires Screen Recording permission to capture audio from other apps. This is a security feature of macOS.
  </Accordion>
</AccordionGroup>

### Recording

<AccordionGroup>
  <Accordion title="How long can I record?">
    There's no built-in limit. Recording length is only limited by your available disk space. A typical meeting uses about 1MB per minute.
  </Accordion>

  <Accordion title="What audio format are recordings saved in?">
    Recordings are saved as M4A (AAC) files, which offer good quality with efficient compression. They can be played in any media player.
  </Accordion>

  <Accordion title="Can I record multiple audio sources?">
    The app records your selected microphone and system audio together. It doesn't currently support multiple separate microphones.
  </Accordion>

  <Accordion title="Can I record without transcription?">
    **Yes.** You can disable "Auto-transcribe recordings" in Settings. You'll still have the audio file.
  </Accordion>
</AccordionGroup>

### AI Features

<AccordionGroup>
  <Accordion title="Which AI models are used?">
    * **Transcription**: OpenAI Whisper (running locally)
    * **AI Chat**: Meta Llama 3.2 (running locally)

    Both models run entirely on your Mac with no cloud processing.
  </Accordion>

  <Accordion title="How much disk space do AI models need?">
    * Whisper Base English: \~140MB
    * Whisper Small: \~460MB
    * Llama 3.2 3B: \~2GB
    * Llama 3.2 1B: \~700MB

    You can delete models you're not using to free space.
  </Accordion>

  <Accordion title="Can I use my own AI models?">
    Not currently. The app uses specific optimized versions of Whisper and Llama.
  </Accordion>
</AccordionGroup>

### Privacy & Security

<AccordionGroup>
  <Accordion title="Can the app see my screen?">
    **No.** The Screen Recording permission is only used to capture system audio. The app never captures video or screenshots.
  </Accordion>

  <Accordion title="Is my data encrypted?">
    Recordings are stored as regular files on your Mac. They inherit your Mac's FileVault encryption if enabled. The app doesn't add additional encryption.
  </Accordion>

  <Accordion title="Can I completely delete my data?">
    **Yes.** Delete recordings from the Dashboard, or manually delete the folder:

    ```bash theme={null}
    rm -rf ~/Documents/BuildBetter\ Recordings/
    ```
  </Accordion>
</AccordionGroup>

***

## Getting Help

### Report a Bug

Found a bug? Please report it on GitHub:

<Card title="Report an Issue" icon="bug" href="https://github.com/buildbetter-app/bb-recorder/issues/new">
  Open a new issue on GitHub
</Card>

Include:

* macOS version
* App version (found in Settings → About)
* Steps to reproduce the issue
* Any error messages

### Request a Feature

Have an idea for improvement?

<Card title="Request a Feature" icon="lightbulb" href="https://github.com/buildbetter-app/bb-recorder/issues/new">
  Submit a feature request
</Card>

### Contact Support

For account or billing questions related to BuildBetter cloud services:

<Card title="Contact BuildBetter Support" icon="headset" href="mailto:support@buildbetter.ai">
  [support@buildbetter.ai](mailto:support@buildbetter.ai)
</Card>