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

# Troubleshoot Common Origami AI Issues — Fixes & Solutions

> Troubleshoot the most common Origami AI problems — TTS slowdowns, garbled audio, render failures, AI errors, and project import issues.

This guide covers the most frequently encountered issues in Origami AI and walks you through how to resolve each one. Work through the steps in order — most problems clear up within the first one or two steps. If something is still broken after trying everything here, jump to the [Reporting Bugs](#reporting-bugs) section at the bottom.

<AccordionGroup>
  <Accordion title="TTS generation takes forever">
    **Symptoms:** TTS generation is stuck at 0% or a very low percentage, or it takes more than ten minutes to produce audio for just a few slides.

    **Steps to resolve:**

    1. **Check your internet connection.** The voice model must fully download before generation can begin. An unstable connection causes the download to stall silently.
    2. **Clear browser cache and site data.** Open DevTools (`F12`) → **Application** → **Storage** → **Clear site data**, then reload Origami AI and retry.
    3. **Switch to q4 quantization.** Go to **Settings → TTS Model** and change the quantization from `q8` to `q4`. The `q4` setting generates audio significantly faster at slightly reduced quality.
    4. **Reduce the batch size.** Generate audio for a smaller number of slides at once rather than queuing every slide in one go.
    5. **Check for background downloads.** Downloads run sequentially — TTS, then FFmpeg, then WebLLM. If another download is in progress, TTS generation will wait. Let any active download finish first.
  </Accordion>

  <Accordion title="Audio quality sounds garbled or distorted">
    **Symptoms:** Generated speech sounds garbled, distorted, unnaturally clipped, or the volume is inconsistent across slides.

    **Steps to resolve:**

    1. **Review your quantization setting.** In **Settings → TTS Model**, `q8` produces higher-quality audio (slightly larger download) while `q4` is faster with acceptable quality. If you are on `q4` and quality is unacceptable, switch to `q8` and regenerate.
    2. **Toggle audio normalization.** If the dynamic range sounds unnatural or levels jump between slides, enable or disable **Disable Audio Normalization** in **Settings → TTS Model** and regenerate to compare.
    3. **Try a different voice.** Open **Settings → General** or the **Slide Editor** and switch to a different voice — options like `af_heart`, `af_bella`, `am_adam`, and `am_michael` each have a distinct pitch and style. Regenerate after changing the voice.
    4. **Regenerate the affected slides.** After adjusting any setting, regenerate audio for the problem slides to apply the new configuration.
  </Accordion>

  <Accordion title="No audio playback">
    **Symptoms:** Generated audio does not play, the speaker icon appears muted and cannot be changed, or the volume reads as 0.

    **Steps to resolve:**

    1. **Check your system volume.** Make sure your device is not muted and the volume is turned up.
    2. **Check browser tab volume and media permissions.** Some browsers allow per-tab muting — right-click the Origami AI tab and confirm audio is not muted. Also check **browser Settings → Permissions** to confirm audio playback is allowed for the site.
    3. **Check per-slide volume.** Open the **Slide Editor** or **Audio Mixing** settings and verify the volume for the individual slide is not set to 0.
    4. **Regenerate TTS audio for the slide.** A corrupted audio blob can prevent playback. Delete and regenerate the audio for the affected slide.
    5. **Test in incognito mode.** Some browser extensions block audio autoplay. Open Origami AI in an incognito window to isolate the issue.
  </Accordion>

  <Accordion title="Video rendering fails or is very slow">
    **Symptoms:** The render process is stuck at 0%, rendering takes hours for a short video, or memory usage climbs continuously during rendering.

    **Steps to resolve:**

    1. **Reduce export resolution.** Switch from 1080p to 720p in the export settings. This is the single biggest performance improvement for most machines.
    2. **Split long projects.** Break large projects into smaller segments and render each one separately.
    3. **Simplify slide transitions.** Complex transition effects increase processing time. Switch to simpler or no transitions for a faster render.
    4. **Close other browser tabs.** Free up CPU and memory before starting a long render.
    5. **Run via Docker** for better resource isolation:
       ```bash theme={null}
       docker compose up --build
       ```
    6. **Restart the browser before rendering.** This clears any memory leaks that have accumulated during earlier work.
  </Accordion>

  <Accordion title="Audio/video sync issues">
    **Symptoms:** Narration does not match what is on screen, audio cuts off too early, or the video ends before the narration finishes.

    **Steps to resolve:**

    1. **Adjust the post-audio delay.** Go to **Settings → General → Post-Audio Delay** (or adjust it per-slide in the **Slide Editor**). Increase the delay value if narration is cutting off before the next slide appears.
    2. **Verify all audio was fully generated.** Incomplete audio on any slide can throw off the entire timeline. Check each slide for a generated audio waveform before rendering.
    3. **Preview before final export.** Use the **Preview** mode to catch sync problems before committing to a full render.
    4. **Re-export the project.** After confirming audio is complete and delay is set correctly, re-render from scratch.
  </Accordion>

  <Accordion title="Video export file is 0 bytes or corrupted">
    **Symptoms:** The export finishes but the resulting MP4 is 0 bytes, will not open, or appears corrupted.

    **Steps to resolve:**

    1. **Check available disk space.** You need at least 2 GB free. If your disk is nearly full, clear space and re-render.
    2. **Try opening the file in VLC.** Some media players struggle with certain encoding parameters. VLC is more tolerant and can confirm whether the file has any valid data.
    3. **Re-render at 720p.** Lower resolution exports are more reliable on machines with limited resources.
    4. **Clear browser cache and reload.** Open DevTools (`F12`) → **Application** → **Storage** → **Clear site data**, reload the app, and try the export again.
    5. **Check the browser console for FFmpeg errors.** Press `F12`, open the **Console** tab, and look for any FFmpeg-related error messages that indicate what went wrong.
  </Accordion>

  <Accordion title="Shorts visual generation fails or hangs">
    **Symptoms:** Image or video generation in the Shorts storyboard fails, the progress spinner spins indefinitely, or you see an error such as "Failed to generate visual" or "Rate limit exceeded."

    **Steps to resolve:**

    1. **Select the Free model.** If you do not have a Pollinations API key, open the model dropdown and choose **Free (slow model)**. This uses a rate-limited free tier that does not require a key.
    2. **Connect or reconnect your Pollinations account.** Go to **Settings → API → Pollinations Account** and click **Connect with Pollinations**. If your session has expired, click **Reconnect** to refresh your token.
    3. **Switch to a different model.** For images, try `flux`, `zimage`, `nanobanana`, or `krea`. For video clips, try `wan-fast` or `seedance-2.0-fast`.
    4. **Retry individual scenes.** Click the regenerate button on the specific scene card rather than rebuilding the entire project. This avoids re-generating scenes that already completed successfully.
    5. **Wait and retry.** If upstream rate limits are the cause, waiting a few minutes before retrying is usually sufficient.
  </Accordion>

  <Accordion title="Project import/export fails">
    **Symptoms:** You cannot import a `.origami` project archive, or you see an error such as "Invalid project archive format."

    **Steps to resolve:**

    1. **Verify archive integrity.** Confirm the `.origami` file was created by Origami AI and has not been partially downloaded or modified. Try re-downloading or re-exporting the project if possible.
    2. **Check that embedded assets are intact.** If slide images or audio blobs inside the archive are corrupted, import will fail. Export a fresh copy from the original project if you have access to it.
    3. **Check browser storage quota.** Large projects with high-resolution slides require available IndexedDB quota. Open DevTools (`F12`) → **Application** → **Storage** to see how much space is in use and clear old data if needed.
    4. **Ensure enough RAM for large archives.** Importing on a device with limited memory can cause the unzip operation to fail mid-way. Close other applications to free system RAM before importing.
  </Accordion>

  <Accordion title="Model download fails">
    **Symptoms:** The model download stops or hangs, you see a "Failed to fetch model" error, or the download percentage is stuck at 0%.

    **Steps to resolve:**

    1. **Check your internet connection.** Model files are large — a dropped or throttled connection is the most common cause of a stalled download.
    2. **Clear browser cache and site data.** Go to DevTools (`F12`) → **Application** → **Storage** → **Clear site data**. This removes any partially cached files that may be blocking a fresh download.
    3. **Free up disk space.** Caching multiple large models requires substantial storage. Plan for **50 GB or more** of free space if you intend to keep several models available. Delete unused models or browser data to make room.
    4. **Retry the download.** After clearing cache and confirming you have a stable connection, start the model download again.
    5. **Try a smaller model.** If you are on a device with limited storage or a slow connection, start with a compact model such as **Llama 3.2 1B** (\~800 MB) or **Gemma 2 2B** (\~1.4 GB).
    6. **Use a remote API instead.** If local model downloads are not working for your setup, connect a cloud AI provider in **Settings → API** to use all AI features without local model storage.
  </Accordion>

  <Accordion title="'Out of Memory' during AI generation">
    **Symptoms:** The GPU crashes during inference, you see a "Device lost" or OOM error, or the browser tab becomes unresponsive.

    **Steps to resolve:**

    1. **Switch to a smaller model.** Use **Llama 3.2 1B** or **Gemma 2 2B** instead of larger 3B or higher models. If you are using a vision model, switch to a text-only model for tasks that do not require image analysis.
    2. **Close other browser tabs.** Each open tab consumes GPU and system memory. Close everything except Origami AI before running inference.
    3. **Reduce batch size.** Process a smaller number of slides at one time rather than queuing all of them at once.
    4. **Restart the browser.** This flushes GPU memory that may have been held by a previous crashed session.
    5. **Switch to a remote API.** Go to **Settings → API** and connect an OpenAI-compatible or Gemini endpoint to offload inference to the cloud entirely.
  </Accordion>
</AccordionGroup>

***

## Reporting Bugs

If none of the steps above resolve your issue, please open a report so the team can investigate.

**Open an issue at:** [https://github.com/TechMitten/Origami-AI/issues](https://github.com/TechMitten/Origami-AI/issues)

Include the following details to help reproduce and fix the problem quickly:

* **Browser name and version** (e.g. Chrome 125.0.6422.112)
* **Operating system and version** (e.g. Windows 11 22H2, macOS 14.4)
* **Steps to reproduce** — a numbered list of exactly what you did before the problem appeared
* **Console errors** — press `F12`, open the **Console** tab, and copy any red error messages
* **Screenshots or screen recording** of the issue

<Note>
  Origami AI includes a built-in **Issue Reporter** powered by the AI assistant. If the feature is available in your version of the app, you can use it to record a short clip of the problem, generate a structured debugging prompt automatically, and copy it directly into your GitHub issue for faster triage.
</Note>