English · 简体中文 · 日本語

Scripts and review

The Script tab turns source prose into an annotated script. Each entry has a speaker, the words to speak, and a delivery instruction. Review the text and casting before a long audio render.

For the shortest path through the app, see First Audiobook. Connection and manual-transport instructions are in LLM Setup.

Upload and prepare one book

1. Use Select Book/Novel (Text, Markdown, or EPUB). Upload starts when you select a file. Wait for the status message before generating.
2. To use a previously uploaded source, choose Or reuse an existing upload instead of uploading another copy.
3. Set First-person narrator (optional) only when the story is narrated by a character in first person. Enter that character's exact name; the app requires at least three occurrences in the prepared source. If that check fails, inspect the name and source rather than inserting extra mentions into the story.
4. Decide whether to keep Strip known translator front matter enabled. It removes recognized translator notes and other non-story boilerplate before sending text to the LLM. Keep a copy of the original and inspect what you need included.
5. Optionally use Build cast list. It asks the LLM to identify speaking characters across the book, including descriptive names for unnamed speakers. Edit cast list lets you inspect and correct that guidance. Building a cast list adds an LLM request; it does not guarantee correct attribution.
6. With an API-connected LLM, use Test this book with the LLM to check the selected source against the configured model before the full run. For the manual copy-and-paste workflow, test a short excerpt through normal Generate Annotated Script and follow its requests.

The same privacy choice applies to tests, cast-list requests, generation, and review: check which LLM provider is selected before sending a private or unpublished manuscript.

Generate the annotated script

Click Generate Annotated Script. The current generation workflow separates three jobs:

1. Split source prose into narration and spoken segments.
2. Attribute spoken entries to speakers.
3. Add delivery directions separately from the spoken words.

Written vocalizations remain part of the source text. Do not assume an emotional instruction will replace a laugh, gasp, or other word that belongs in the text.

Preserve source words (a checkbox on this tab) keeps every source word, in order, through annotation and review. A script whose words changed is not published, and a changed chunk is not rendered. Speech preparation may still expand numbers and symbols later. It is off by default; see the literal source policy.

Two related settings are in Setup → Prompt Settings (Advanced):

• Step 1: model output format: Full text (default) or Compact labels (experimental). Compact labels sends numbered sentences and asks only for a label per sentence; a chunk whose compact answer is unusable falls back to full text. It only affects chunks the quote marks don't settle.
• Step 3: extra text around each request: read-only surrounding text for delivery-note requests, in characters per side (0–1,000,000; default 0). Step 3 no longer repeats lines that are already in the same request. No quality gain was measured at 4,000 characters, so leave it at 0 unless you are testing; values above 20,000 need a known model context.

Use Generation Logs to follow progress and errors. The log panel also provides downloads for single and batch generation and review logs. In manual transport, the app waits for each answer; use Show the prompt, copy the request, paste the answer into Model reply, and select Submit reply. An LLM answer still has to pass the app's validation.

When generation ends, inspect the script in Editor, especially chapter boundaries, dialogue mixed with narration, unnamed speakers, unusual punctuation, and names that could refer to more than one person.

Choose the attribution prompt

Setup's Attribution prompt sets how step 2 asks the model who speaks each line. michel2_full is the default. michel2_spoken asks only about the spoken lines and fills narration in code, so the model cannot move a speaker onto a "said X" tag. On Qwen3-14B without an adapter it scored 70.1% against 63.6% on a three-book gold set, with about 3× less step-2 time (measurement). Other models are not measured yet; if you serve an attribution adapter, keep the prompt it was trained on. Hover the ⓘ beside any setting for what it does and, where there is a measurement, a recommendation.

Pause, cancel, resume, or start again

These controls have different purposes:

• Pause / Resume suspends and continues a supported running worker. Pause is unavailable on Windows.
• Cancel requests a stop. Wait for the task status to confirm it has stopped; a click or a lost connection does not prove cancellation completed.
• Generate Annotated Script continues the selected book's saved checkpoint when one is usable. On Windows, use Cancel followed by Generate to return to a checkpointed run.
• Resume failed run appears when the app has a recoverable failed generation.
• Start over discards saved generation progress for the text and begins at the first chunk. Use it deliberately, not as the first response to a temporary provider error.
• Save snapshot saves the finished portion of a running generation into Saved Scripts without stopping the run. The app reports how much it saved. Cancel and wait for the run to stop before loading the snapshot to work on it.

Keep the same source and relevant settings when resuming. If the app refuses recovery because the source or state changed, read the refusal rather than trying to force an old checkpoint onto another book.

When generation needs help

The Script generation needs your help panel shows the failing passage and available recovery actions:

• Retry this chunk retries from the saved position after you address the cause.
• Copy prompt lets you get an answer from another model. Paste only the required JSON and use Validate & apply segmentation. The panel specifies the required format; during speaker attribution it asks for speaker assignments instead of segmented prose.
• Narrate as-is is a fallback for segmentation failures. It sacrifices the intended speaker segmentation, so review the resulting section.
• Mark speakers UNKNOWN is the attribution fallback. Resolve those speaker labels before relying on the cast.

Do not remove source words merely to make a reply validate. If the provider is unavailable or repeatedly truncates answers, use LLM Setup and Troubleshooting.

Choose the right review

Review Script (Optional) runs another LLM pass for speaker assignments, narration/dialogue boundaries, and delivery directions. Text-preservation checks remain active, but the result still needs human review. If the GPU is already full when review starts, review stops at once with a message instead of retrying; free the memory (for example, unload the model holding it) and start again.

Contextual Review (+/- N) gives the model neighboring entries to help with ambiguous passages. Its Context Window uses 1–12 entries on each side; the initial value is 4. This field does not change standard Review Script.

Before review:

• Check Merge duplicate character names. It is enabled initially and can unify labels such as a full name, nickname, or description into one character. Disable it when you need those distinctions preserved.
• Use Find Nicknames, then Edit aliases, if names need contextual interpretation. Inspect the proposed mappings before review applies them. The Script aliases are name-normalization guidance; Alias of in Voices simply shares a voice configuration.
• Save a distinctly named copy first if you want to compare with the earlier script.

An unchanged script with an already completed review may be skipped. Select Review again even if nothing changed since the completed review only when you intend to run it again. Read any recovery panel if a review stops partway through.

Delivery warnings

The Editor may show Needs delivery review when the delivery pass exhausted its retries and used generic instructions. The warning preserves the text and speakers but tells you which delivery directions need attention. Edit those directions manually, or use Retry delivery only when offered. Afterward, inspect the refreshed warnings and regenerate audio for changed lines.

Labels-only review (opt-in)

Set prompts.review_labels_only to true in configuration, or run review_script.py --labels-only, to have review return only each line's speaker and delivery note. It never retypes the text, so a changed comma or a moved speech tag can no longer make review throw away a batch's speaker fixes. It cannot split or merge lines; the normal review still can (details).

Check source fidelity

In Editor, use Text integrity to see dropped, added, and changed words, with links to affected entries. The check compares saved Editor text against the currently available source, including recorded generation preprocessing where available.

Important limits:

• Saved text matches source is a text-comparison result. It does not check pronunciation, speaker identity, or the words actually present in rendered audio.
• A loaded saved-script JSON may produce Source comparison unavailable because it is not the original prose input.
• A failed or unavailable check is not a match. Keep the original book for manual comparison.
• If you intentionally changed the wording, review those differences before confirming a merge.

Under Saved Scripts, Audit checks a saved script and reports blocking findings and items needing manual review. An audit without findings is still not a listening test or a guarantee of correct casting.

Save and load without losing the current work

Under Saved Scripts, enter a name and select Save Current. The saved item includes the current annotated script and, when present, voice configuration. The voices badge identifies a saved voice configuration.

Use a new name for a separate version. Saving under an existing name replaces that saved script; the single-book Save Current control does not provide the batch collision choices described below.

Load asks before replacing your current script and chunks. It also clears the active audiobook exports and generation recovery state. It is refused while incompatible work is running.

Saved Scripts is not a complete rendered-project archive. Editor-only text, speaker, delivery, inserted/deleted rows, and pause edits live in the active chunk state. Save Current does not include that chunk state or its audio. Back up the application data and download finished outputs before switching books. See Updates and Backups.

The trash button deletes the saved script. The UI warns that this cannot be undone; keep an independent backup if you may need it again.

Generate or review several books

Enable Generate multiple books, then select files and/or existing uploads. Check the queue and reading order, including each optional first-person narrator. Under When a saved script already exists, choose:

• Skip it (safest) to leave existing saved scripts alone.
• Create a new version to keep both.
• Back up and replace it to replace the saved result with a backup.

You can also enable Build a cast list for each book first. Review the batch preflight before starting. Successful books are saved directly to the library; examine the queue's individual results rather than treating one completed book as completion of the whole batch.

For batch review, enable Review saved books and select saved scripts in reading order. Each result is saved back in place. With duplicate-name merging on, names are coordinated across the selected books. Discover nicknames first is enabled initially; Two-pass (forward + backward) additionally revisits earlier books using later context. Batch Context Window is initially 0 for standard review; 1–12 enables contextual review.

After generation or review, continue with Voices, then Rendering and Export.

Sources

Checked against shipped main commit 8c7a33cb310ab9264594a09ca27e48271585094f: Script controls, generation and recovery UI, save and load behavior, and source comparison.