---
url: "https://docs.on-book.app/rehearsal/reference/troubleshooting.md"
description: "Solutions for common issues with On Book Rehearsal."
status: "proposed"
---

# Troubleshooting

> **Status: Proposed / pre-launch. On Book Rehearsal docs describe intended behavior and may not match a shipped app yet.**

> **Solutions for common issues with On Book Rehearsal.**

***

## Microphone Permissions {#microphone-permissions}

Voice Rehearsal and Italian Run require microphone access. If the app can't hear you:

### iOS

1. Open the **Settings** app on your device
2. Scroll down and tap **On Book Rehearsal**
3. Toggle **Microphone** to **On**

### Android

1. Open **Settings → Apps → On Book Rehearsal**
2. Tap **Permissions**
3. Tap **Microphone** and select **"Allow only while using the app"**

::: tip Permission Prompt
The app will ask for microphone permission the first time you start a Voice Rehearsal or Italian Run session. If you accidentally denied it, follow the steps above to enable it manually.
:::

***

## Audio Playback Issues

If you can't hear the AI speaking during Voice Rehearsal or Italian Run:

| Check | Solution |
|:---|:---|
| **Device volume** | Make sure your media volume is turned up (not just the ringer) |
| **Silent / Do Not Disturb mode** | Turn off silent mode or Do Not Disturb |
| **Bluetooth audio** | If using Bluetooth headphones, make sure they're connected and selected as the audio output |
| **Other audio apps** | Close other apps that may be using audio (music players, video calls) |

***

## Script Upload Problems

If your script fails to upload or process:

| Problem | Solution |
|:---|:---|
| **Upload fails** | Check your internet connection and try again |
| **Processing hangs** | Close and reopen the app; the processing will resume automatically |
| **Characters missing after processing** | The AI may have extracted names differently — check for abbreviations or alternate spellings |
| **"Unsupported format" error** | Make sure your file is a **PDF**. Other file types (Word, Pages, images) are not supported |
| **File too large** | Try a smaller file; very large scripts may take longer to process |

::: tip Any PDF Works
Both text-based and scanned PDFs are supported. The AI uses OCR to read every page before extracting dialogue and structure.
:::

***

## App Crashes or Freezes

If the app becomes unresponsive:

1. **Force-close the app** and reopen it
   * **iOS:** Swipe up from the bottom and swipe the app away
   * **Android:** Tap the recent apps button and swipe the app away
2. **Check for updates** using the pre-release or release channel provided by the owner/operator
3. **Clear the app cache** (Android: Settings → Apps → On Book Rehearsal → Storage → Clear Cache)
4. **Restart your device** if the problem persists

If crashes continue, please contact support with details about what you were doing when the crash occurred.

***

## Connection & Sync Issues

### Voice Rehearsal and Italian Run

These modes require a **stable internet connection** because they stream audio in real time through the Gemini Multimodal Live API. If you experience issues:

* Switch from mobile data to Wi-Fi (or vice versa)
* Move closer to your router if on Wi-Fi
* Avoid using a VPN, which can add latency

### Flashcard Mode

Flashcard Mode works **offline** once you've opened the script at least once while connected to the internet. If script data isn't appearing offline:

* Open the script while connected to download and cache the data
* Close and reopen the app to trigger the cache sync

### Production Scripts Not Appearing

If a stage manager sent you a script but it's not in your library:

1. Make sure you're signed in with the **same account** your stage manager added to the production
2. Pull down to **refresh** the script library
3. Ask your stage manager to verify you've been added to the production in On Book Pro

***

## Still Need Help?

If your issue isn't covered here, check the [FAQ](./faq.md) or contact support through the app's Settings screen.

***

## Related Guides

* [Adding Your First Script](../getting-started/first-script.md)
* [Voice Rehearsal](../modes/voice-rehearsal.md)
* [Settings & Stats](../guide/settings.md)
* [FAQ](./faq.md)

***

*Last updated: February 19, 2026*