Skip to content

Script Generation

Jump to bottom
pinokio edited this page Feb 10, 2026 · 5 revisions

Script Generation

Alexandria uses an LLM to convert raw book text into a structured script with speakers, dialogue, and TTS voice directions.

Pipeline

  1. Upload a text file (.txt or .md) in the Script tab
  2. Generate Script — The LLM processes the text in chunks, producing a JSON array
  3. (Optional) Review Script — A second LLM pass fixes common annotation errors
  4. Parse Voices — Extract unique speakers for voice configuration

Script Format

The generated script is a JSON array:

[
  {"speaker": "NARRATOR", "text": "The door creaked open slowly.", "instruct": "Calm, even narration."},
  {"speaker": "ELENA", "text": "Ah! Who's there?", "instruct": "Startled and fearful, sharp whispered question, voice cracking with panic."},
  {"speaker": "MARCUS", "text": "Haha... did you miss me?", "instruct": "Menacing confidence, low smug drawl with a dark chuckle, savoring the moment."}
]

Fields

  • speaker — Character name (uppercase) or NARRATOR
  • text — The spoken dialogue or narration
  • instruct — 2-3 sentence TTS voice direction. Describes tone, delivery style, and specific vocal qualities.

Instruct Writing

The instruct field is sent directly to the TTS engine as voice direction. Good instructs:

  • Set the emotional tone first ("Devastated by grief")
  • Describe delivery ("Sniffing between words and pausing to collect herself")
  • Give specific references ("End with a wracking sob")

Non-verbal Sounds

Vocalizations are written as real pronounceable text — no bracket tags or special tokens:

  • Gasps: "Ah!", "Oh!" with instruct "Fearful, sharp gasp."
  • Sighs: "Haah...", "Hff..."
  • Laughter: "Haha!", "Ahaha..."
  • Crying: "Hic... sniff..."
  • Exclamations: "Mmm...", "Hmm...", "Ugh..."

LLM Configuration

Setup Tab Settings

  • Base URL — LLM server endpoint (e.g., http://localhost:1234/v1 for LM Studio)
  • API Key — Your API key (use local for local servers)
  • Model Name — The model to use

Sampling Parameters

Parameter Default Notes
Temperature 0.6 Lower = more deterministic
Top P 0.8 Nucleus sampling
Top K 20 Top-K sampling
Min P 0 Minimum probability
Presence Penalty 0.0 Penalize repeated tokens
Banned Tokens (empty) Comma-separated list (e.g., <think> for thinking models)

Smart Chunking

The LLM processes text in chunks (default 3000 chars) to handle books of any length. Between chunks:

  • The character roster is passed forward for name consistency
  • The last 3 script entries provide style continuity
  • The chunk size is configurable in Setup > Prompt Settings

Script Review

After generation, click Review Script for a second LLM pass that fixes common errors:

  1. Attribution tags in dialogue — Strips "said he", "she replied" etc. from spoken text
  2. Misattributed narration — Splits narration mixed into character entries as NARRATOR
  3. Dialogue in narrator entries — Extracts character dialogue embedded in narration
  4. Over-split narrator entries — Merges short consecutive narrator entries covering the same scene
  5. Invalid instructs — Corrects physical actions (not voice-appropriate) to proper voice directions

Review prompts are customizable in review_prompts.txt.

Prompt Customization

LLM prompts are stored in plain-text files at the project root:

  • default_prompts.txt — Script generation prompts
  • review_prompts.txt — Script review prompts

Each file contains a system prompt and user prompt separated by ---SEPARATOR---.

How to customize:

  • Per-session: Edit in the Setup tab's Prompt Customization section
  • Permanent: Edit the text files directly — changes hot-reload on next request
  • Reset: Click "Reset to Defaults" in Setup to reload from files

Non-English Books

The default prompts are written for English text. For other languages, edit prompts to match that language's conventions:

  • French guillemets (<<>>)
  • Japanese brackets
  • Language-appropriate attribution patterns
  • Set the TTS Language dropdown to match

Recommended LLM Models

Non-thinking models work best for script generation:

Model Notes
Qwen3-next (80B-A3B) Excellent JSON output and instruct directions
Gemma3 (27B) Strong JSON output
Qwen2.5 (any size) Reliable JSON output
Llama 3.1/3.2 Good character distinction
Mistral/Mixtral Fast and reliable

Thinking models (DeepSeek-R1, GLM4-air, etc.) can interfere with JSON output. Add <think> to Banned Tokens to disable thinking mode.

Saved Scripts

Scripts can be saved and loaded from the Editor tab:

  • Save preserves the annotated script, voice configuration, and all chunk data
  • Load restores everything, allowing you to resume editing or regenerate specific chunks
  • Scripts are stored in the saved_scripts/ directory

Clone this wiki locally