Audio Worker

English | 简体中文

Turn a story or chapter into directed, reviewable audio scenes, then assemble and export one 48 kHz WAV—locally.

What it does

• Turn a pasted chapter into reviewable character and scene plans, then adapt each accepted range into an audio scene.
• Edit complete dialogue, performances, sound effects, and BGM from exact text anchors in one scene script.
• Review the LLM-arranged SeedAudio prompt, generate and compare scene candidates, and retain their local provenance.
• Assemble selected scene WAVs with optional overlays, gaps, and crossfades; preview and export a canonical 48 kHz WAV locally.

Alpha boundary

This 0.1.0-alpha.1 source alpha is verified on macOS 14+ with Apple Silicon and Bun 1.3.14 or newer. The full workflow requires user-configured SeedAudio and GPT-compatible or Claude-compatible LLM profiles; the synthetic demo below needs neither. See installation and contributing for details.

Quick start

bun install --frozen-lockfile
bun run demo

The credential-free demo opens a synthetic local project shelf.

Detailed product contract

Projects are organized as project → chapter → scene. Chapters own scene order, while reusable characters belong to one project and can be selected in any of that project's chapters. Characters and voices are never shared between projects. New projects start empty; the browser asks for a chapter name before the first scene.

A complete chapter can be pasted into the existing LLM dock; there is no file upload path. The first explicit LLM action proposes a reviewable cast and scene plan, and later explicit actions adapt each accepted range into a normal pending scene interpretation. Planning covers every source unit exactly once, keeps each estimate below 90 seconds, and limits fixed characters to three per scene, including one shared project narrator. Scene-local temporary characters are unlimited. Accepting the plan creates no incomplete scenes; each scene enters the editor only after its own interpretation is accepted.

Each scene owns one anchored script editor. Selecting a character or phrase in a complete line creates an exact anchor, including an occurrence number when the phrase repeats. One anchor groups simultaneous entries, vocal actions, ordered sound items, and background transitions without asking the operator to maintain a separate relationship form. Dialogue, sound effects, and BGM use separate temporary forms behind one launcher. BGM starts at the current selection, or scene start without one, and ends at scene end by default; the summary and prompt show the resulting non-overlapping segments. There are no visual seconds, tracks, zoom controls, or output-timing promises. Edits autosave locally in order and make the current prompt stale; the user must explicitly generate a new LLM-reviewed prompt and separately request a new whole-scene SeedAudio candidate.

The editor supports English and Simplified Chinese. On first open it follows the browser language; an explicit selection is stored only in that browser. Project names, characters, dialogue, director instructions, model output, and evidence are never translated automatically.

Develop locally

Requires Bun 1.3.14 or newer.

Verified alpha support is macOS 14+ on Apple Silicon. See docs/installation.md for the support matrix and source-archive procedure.

bun install --frozen-lockfile
./scripts/check.sh

Initialize and serve one local library:

bun run adw doctor ./audio-worker-library
bun run adw serve ./audio-worker-library

serve uses http://127.0.0.1:8788 by default. The browser shelf creates, opens, renames, archives, and restores books; chapters, scenes, characters, and generated artifacts remain isolated inside each book. The library owns one library.sqlite plus project-namespaced media directories. Legacy .adw projects and the old single-project CLI are intentionally unsupported.

The HTTP server binds only to 127.0.0.1, uses no editor session token, and retains strict Host/Origin checks. Before the shelf opens, the configuration gate requires:

• SeedAudio complete baseUrl, exact model ID, and API key;
• one LLM protocol, baseUrl, exact model ID, and API key.

Settings are stored in the current user's configuration directory rather than the library. The browser receives credential presence/source plus a bounded preview of the effective key: long keys show only their first and last four characters around a fixed mask, while short keys disclose no characters. The complete key is never returned, and the empty API-key input remains replacement-only. Saving settings does not test connectivity or make a paid request. Environment credentials count as configured. Until both profiles are complete, the server allows only health, settings, and editor assets; shelf and workspace APIs remain locked.

Reusable characters are established once in the project character library. Each owns its name and stable written voice description. A newly extracted fixed character may remain pending until the user uploads or explicitly generates and confirms one local reference audio asset; only scenes that use that pending character are blocked from prompt compilation and SeedAudio generation. Character changes propagate to mutable scenes and make affected prompts stale. One-off roles such as a passer-by or crowd member may instead live only inside one scene with a local name and written voice description. These scene-local extras never enter the character library and cannot use reference audio. A scene may use at most three distinct reference-audio assets. Generated samples can be auditioned before a separate character-save action. The product contains no official reference-voice catalog.

Whole-scene duration is not a controllable SeedAudio input. The editor does not ask for a target range; it records the actual duration from validated generated and assembled WAV output. Chapter planning uses a conservative estimate strictly below 90 seconds. A validated generated WAV over 120 seconds remains playable for review but cannot be selected or assembled; revise the scene split or content and generate again.

The configured LLM has explicit, user-triggered actions. Interpret scene adapts a rough story idea into natural audiobook narration, situation-aware dialogue, sound, and performance as a validated pending review. Accepting that review is the only step that creates or replaces a scene. Generate prompt arranges the accepted scene into the final reviewable SeedAudio prompt. Neither calls SeedAudio. Every prompt-ready scene has exactly one narrator: the operator may select a fixed project narrator, otherwise the interpretation creates a scene-local reference-free narrator. The operator selects the fixed cast in the LLM composer; whole-scene LLM inputs expose only those characters as ordered indexes rather than business IDs. Output may select one of those indexes or describe a reviewed, text-only scene extra; it cannot create or revoice a project character. Scene spec version 6 preserves all accepted director capabilities, while the loopback API provides whole-scene interpret/list/review/accept/reject operations with stale-safe acceptance. Accepted content is the anchored script itself; phrase performance, vocal actions, voice treatments, sounds, and speech relations remain grouped by their exact text anchors. Whole-scene interpreter v8 gives both LLM protocols one complete minimal JSON skeleton, per-object key allowlists, and explicit field-ownership and speech-relation rules. Character selections index availableCharacters; dialogue and speech relations index the generated scene.roles; anchors index scene.turns; and bed transitions index scene.bed. One invalid model output may be regenerated from the original input with redacted validation feedback; the replacement still passes the complete strict contract before it can become pending review.

Within accepted dialogue, full-width annotations such as （停顿） and （惊恐） are prompt-time director syntax rather than spoken words. The arranger keeps their position, may express pauses with natural punctuation such as ……, and must preserve the remaining spoken words. Prompt generation does not rewrite the accepted scene stored in the project.

Arranger v11 gives the configured LLM one complete official-style draft, then asks an independent reviewer to improve or reconstruct the candidate from the same authoritative encoded draft. A valid reviewer result wins; an invalid reviewer falls back to a valid arranger result, and two invalid results save nothing. Roles are defined once and each stays on its own line; blank-line boundaries separate casting, global context/sound, and chronological dialogue/events. The LLM transport replaces every exact accepted span and layout boundary with ordered opaque tokens, verifies their exact count and interleaved order, and decodes only verified tokens before content validation and persistence. It does not send a parallel plaintext semantic payload from which a compatible model could infer and rewrite hidden facts. Tokens never enter the reviewed prompt or SeedAudio request. Exact accepted facts, narrator ownership, spoken words, references, admitted model timelines, layout, and draft occurrence bounds fail closed instead of being inferred, repaired, or duplicated. Prompt arrangement normally makes two LLM calls but no SeedAudio request. Every project role receives the ordered @音频N mapping; a text-only scene extra receives no marker. Legacy project roles without a reference remain readable but are blocked from prompt compilation and paid generation until repaired. Advanced sound and interruption directions are separately editable, and duplicate stored wording is rendered once without rewriting the accepted scene.

The routine editor shows creative content, review state, prompt text, and actionable blockers. Protocol, model, endpoint, version, hash, and internal run evidence remain persisted for diagnostics but are not repeated in the operator workspace. Required service identifiers remain visible in Settings.

After selecting one generated candidate for every scene, use Assemble & export in the project bar to set scene gaps and crossfades, import optional exact overlay WAV files, render one browser-local preview, and preserve that same 48 kHz WAV with its assembly hash and export history. This workflow is local and performs no paid request.

The project bar also opens one Cleanup dialog with two independent actions. Clean generated outputs removes candidate audio, generation runs, waveform caches, and final exports while preserving scenes, prompts, fixed character voices, overlays, and service settings. Clean LLM records removes stored chapter imports, scene proposals, and scene-interpretation reviews while preserving accepted scenes and prompt revisions. The application does not persist complete raw LLM chat transcripts or reasoning. Both actions show local counts and require an explicit confirmation; neither performs a network or paid request.

Official generation is an explicit paid action and requires the user's own environment-variable workflows remain supported and override a stored key. Prompt generation, SeedAudio generation, candidate selection, assembly, export, and both cleanup categories are explicit browser actions scoped to the open project.

export SEEDAUDIO_API_KEY="..."
bun run adw serve ./audio-worker-library

The defaults are the official SeedAudio Audio 1.0 endpoint and model. The endpoint and model can be changed for official protocol revisions, but the application still implements only that one request/response contract with no provider fallback. Automated tests use a local fake contract server and never make a paid request.

Start here

1. Read AGENTS.md.

2. Read ARCHITECTURE.md.

3. Read docs/product/PRD.md and docs/ROADMAP.md.

4. Pick the plan listed in docs/PLANS.md.

5. Run the repository gate before and after a change:

   ./scripts/check.sh

Repository map

Path	Purpose
AGENTS.md	Repository operating contract
ARCHITECTURE.md	Accepted boundaries and open architecture decisions
agents/	Development roles; never product runtime personas
docs/ROADMAP.md	Dependency-ordered delivery milestones
docs/decisions/	Durable architecture decision records
docs/exec-plans/	Active and completed implementation plans
docs/agent-runs/	Handoffs and evidence for interrupted work
docs/product/PRD.md	MVP requirements and acceptance criteria
docs/product/domain-model.md	Authoritative product vocabulary and invariants
docs/product/director-script-workflow.md	0.2 beginner workflow and capability map
docs/product/capability-coverage.md	19-case SeedAudio capability acceptance report
docs/product/acceptance-matrix.md	P0 requirement-to-evidence index
docs/product/	Additional accepted capability contracts
docs/prompt-references/	Official and project prompt-reference policy
scripts/check.sh	Stable repository verification entrypoint
scripts/check-harness.sh	Dependency-free harness validation
CONTRIBUTING.md	Contributor workflow and boundaries
SECURITY.md	Security policy, trust boundaries, and reporting
docs/installation.md	Supported install and demo workflow
docs/release-checklist.md	Reproducible source release procedure

The application entrypoint is src/entrypoints/cli.ts. docs/PLANS.md records the active implementation scope, or explicitly says when no plan is active.

License

Copyright 2026 Audio Worker contributors.

Licensed under the Apache License 2.0. See NOTICE for project notices and THIRD_PARTY_NOTICES.md for the licenses of bundled dependencies.