SonicCraft

Plan a SonicCraft timeline without synthesizing audio: free, never calls paid TTS APIs. Lays out every cue, pause and clip with cached or estimated speech durations (mock voices are measured exactly), applies the speech-overlap policy and computes the ducking regions. Returns a PlanReport: valid, diagnostics, duration_ms (estimated total length), items (id, kind, track_id, start_ms, end_ms, duration_source, and pushed_from_ms for cues the overlap policy moved), ducking regions per ducked track, synthesis (cues, cached, characters_to_synthesize, i.e. what a render will bill) and an ASCII timeline diagram, which the text result also shows. A long timeline (more than about 40 items) gets a compact report: totals, cost, ducking, errors and warnings, the diagram's track lanes, the first and last 10 items and every item the overlap policy moved or a diagnostic names (items_total and items_truncated say what was left out); pass `detail: "full"` for every item. Call it after validation passes and before soniccraft_render to check order, timing and cost; show the diagram to the user when timing matters. Estimates are within about ±15%; a render measures exact durations and lays out again. Takes `yaml_content` or `yaml_path` like soniccraft_validate_timeline; an invalid timeline is a successful call with valid: false.

Get the SonicCraft timeline DSL (v1.0): a compact quick reference (document rules, every field with its default, timing and anchor rules, ducking, loudness presets, providers, a complete example and the common diagnostic fixes) as text. structuredContent is {dsl_version, schema_id, quick_reference}. Pass `detail: "full"` to also get the complete JSON Schema (draft 2020-12, about 35,000 characters) as text and as structuredContent.schema; the quick reference is enough to write timelines. Call it once before writing your first timeline; afterwards rely on soniccraft_validate_timeline, whose diagnostics name the exact field to fix.

List the built-in TTS providers (elevenlabs, openai, cartesia, kokoro, piper, macos_say, command, mock) and whether each can be used right now: API key present in the environment, local binary found, local server answering (a quick probe of at most 300 ms), operating system supported. Returns {providers: [{name, aliases, display_name, local, word_timestamps, available, status, api_key_env, default_voice, default_model, notes}]}. `mock` (deterministic synthetic voice, any OS) and `macos_say` (macOS) need no API key. Call it before choosing `provider:` values. If a provider lacks its key, ask the user to export the environment variable named here; never put API keys in a timeline.

List the voices of one TTS provider, given its built-in name or alias (e.g. elevenlabs, openai, cartesia, kokoro, piper, macos_say, mock). Returns {provider, voices: [{id, name, language, gender, description}]}; put a voice's `id` into `voice_id` in the timeline. Cloud providers are queried over their API (needs the provider's API key in the environment); local providers list what is installed.

Render a SonicCraft timeline to a mastered audio file. Synthesizes the speech (cached by content hash, so re-renders only pay for changed cues), places every item sample-accurately, ducks music under speech, normalizes to the loudness target (EBU R128) with a true-peak limiter, encodes (wav, mp3, flac; ogg, opus and m4a need ffmpeg) and writes the subtitles, stems and manifest the timeline or arguments ask for. It writes files (inside the base directory unless `output_path` names another place) and may call paid TTS APIs; API keys go only to each provider's official host, servers on this machine (own key variable only), or SONICCRAFT_ALLOWED_HOSTS. Programs named by a timeline (`command` providers, a piper `command`) run only if the server was started with --allow-command. Run soniccraft_validate_timeline and soniccraft_dry_run first. Pass `yaml_content` or `yaml_path`; `output_path` chooses the file and `format` the encoding (`format: mp3` for an .mp3 path when the timeline sets another format). Returns a RenderReport: output {path (absolute), format, sample_rate, channels, duration_ms, bytes}, loudness {integrated_lufs vs target_lufs, true_peak_dbtp vs true_peak_target_dbtp, measured on the delivered file; for mp3, ogg, opus and m4a, pre_encode has the master's values}, files {subtitles, stems, manifest} with absolute paths, synthesis, diagnostics and items with exact timings (a long timeline lists the first and last 10; `detail: "full"` lists all), plus links to the files (audio is never inlined). A failure returns isError: true with {message, diagnostics}: fix what they name and render again. Long renders report progress, may first wait for another render to finish, and stop cleanly when the call is cancelled. Files are put in place only when the whole render succeeds: a failed or cancelled render removes its partial files and leaves earlier outputs untouched.

Validate a SonicCraft audio timeline (YAML or JSON) without rendering. Parses it and checks every field, reference, timing anchor and the environment (asset files exist, TTS providers available, API keys present, ffmpeg for ogg/opus/m4a), reporting ALL problems in one pass. Call it after every edit, before soniccraft_dry_run and soniccraft_render. Pass exactly one of `yaml_content` (the document text) or `yaml_path` (a file; `path` also works). Returns a ValidationReport {valid, diagnostics, summary}; an invalid timeline is still a successful call, with valid: false. Each diagnostic has a severity, a stable `code`, a `path` such as tracks[1].sequence[0].start_relative.after_cue, the line and column, a `message` and usually a `hint` you can apply mechanically (rename `fade_in` to `fade_in_ms`, use a suggested id): fix every error, then validate again until valid is true. Warnings and infos do not block rendering. A report with many diagnostics comes back compact (every error and warning up to 50, plus counts); `detail: "full"` returns all. Never calls paid APIs; `check_credentials: true` sends one free authenticated request per provider to test its key. API keys only ever go to the provider's official API host, a server on this machine (the provider's own key variable only), or a host listed in SONICCRAFT_ALLOWED_HOSTS.