FAQ — Read Before Opening an Issue / 常见问题 — 提交 Issue 前请先阅读

[Finrandojin]

Please check this FAQ before opening a new issue. Most common problems are answered here.
提交 Issue 前请先查看本 FAQ。 大部分常见问题已在此解答。

---

Installation / 安装

Q: The install is stuck or failed

A: Click Terminal in the Pinokio sidebar to see what's happening. Common causes:

• Slow internet — PyTorch wheels are ~2 GB, patience required
• pip/uv resolver conflicts — click Reinstall in Pinokio to retry from scratch
• Disk space — you need ~20 GB free (8 GB venv, 7 GB models, working space)

Q: 安装卡住或失败

A: 点击 Pinokio 侧栏中的 Terminal 查看具体情况。常见原因：

• 网络较慢 — PyTorch 安装包约 2 GB，请耐心等待
• pip/uv 依赖冲突 — 在 Pinokio 中点击 Reinstall 重试
• 磁盘空间不足 — 需要约 20 GB 可用空间

---

Model Downloads / 模型下载

Q: The app seems frozen after I click generate for the first time

A: This is normal! The TTS model (~3.5 GB) is downloading from Hugging Face. Check the Pinokio terminal for download progress. This only happens once — after that, models load in seconds.

Q: 首次点击生成后应用似乎卡住了

A: 这是正常现象！TTS 模型（约 3.5 GB）正在从 Hugging Face 下载。请在 Pinokio 终端 中查看下载进度。这只在首次使用时发生，之后模型加载只需几秒钟。

Q: Model download is very slow or fails (China / 中国大陆)

A: Hugging Face may be slow or blocked in mainland China. Set the mirror before launching:

Set environment variable: HF_ENDPOINT=https://hf-mirror.com

Or add to start.js in the shell.run params:

env: { HF_ENDPOINT: "https://hf-mirror.com" }

If you hit rate limits (429 errors), create a free Hugging Face account and set HF_TOKEN to your access token.

---

LLM Setup / LLM 设置

Q: "Generate Script" fails immediately

A: Alexandria does not include an LLM. You need a separate LLM server running before generating scripts:

• LM Studio → http://localhost:1234/v1
• Ollama → http://localhost:11434/v1 (run ollama run qwen3 first)
• OpenAI API → https://api.openai.com/v1

Enter the URL, API key, and model name in the Setup tab and click Save.

Q: "Generate Script" 立即失败

A: Alexandria 不包含 LLM。在生成脚本前，你需要先启动一个独立的 LLM 服务器：

• LM Studio → http://localhost:1234/v1
• Ollama → http://localhost:11434/v1（先运行 ollama run qwen3）
• OpenAI API → https://api.openai.com/v1

在 Setup 标签页中输入 URL、API Key 和模型名称，然后点击 Save。

Q: Script generation produces garbage / JSON errors

A:

• Thinking models (DeepSeek-R1, GLM4, etc.) output <think> blocks that break JSON. Add <think> to Banned Tokens in the Setup tab.
• Some models struggle with structured JSON — try Qwen2.5, Qwen3, Gemma3, or Llama 3.

---

GPU & Performance / GPU 与性能

Q: Which GPUs are supported?

A:

GPU	OS	Status
NVIDIA	Windows/Linux	Full GPU support (CUDA 12.8, driver 550+)
AMD	Linux	Full GPU support (ROCm 6.3)
AMD	Windows	CPU only — GPU acceleration not supported. Use Linux for AMD GPU.
Apple Silicon	macOS	CPU only — functional but slow

Q: Out of memory / OOM errors

A: Reduce these settings in the Setup tab:

1. Parallel Workers (batch size) — try 5-10 instead of 20+
2. Max Chars/Batch — try 1500 instead of 3000
3. Close other GPU applications (games, other AI tools)

Q: First batch is very slow, then speeds up

A: This is expected. The first batch in each session has extra warmup:

• GPU kernel autotuning (30-60s, especially on AMD)
• Codec compilation warmup if enabled (30-60s, then 3-4x faster for all subsequent batches)

---

Audio Output / 音频输出

Q: MP3 files are broken or tiny (428 bytes)

A: This is a Windows issue with conda's ffmpeg missing the MP3 encoder. Alexandria auto-detects this and falls back to WAV. For MP3 output:

conda install -c conda-forge ffmpeg

Q: How do I process Chinese / non-English books?

A:

1. Set Language to "Chinese" (or your language) in the Setup tab
2. The default LLM prompts are written for English. For best results with Chinese books, edit the prompts in the Setup tab's "Prompt Customization" section to match Chinese dialogue conventions (e.g., 「」 quotes)
3. Or edit default_prompts.txt and review_prompts.txt directly for permanent changes

Q: 如何处理中文书籍？

A:

1. 在设置标签页的 Language 下拉菜单中选择"Chinese"
2. 默认 LLM 提示是为英文编写的。处理中文书籍时，建议在设置标签页的"Prompt Customization"部分修改提示，使其适配中文对话约定（如使用「」引号）
3. 也可以直接编辑 default_prompts.txt 和 review_prompts.txt 进行永久修改

---

More Resources / 更多资源

• README (English) | 中文 README
• First Launch Guide
• Wiki — Troubleshooting
• Wiki — Voice Types
• Wiki — Training Guide

---

If your question isn't answered here, please open an issue using the bug report or feature request template.