SONICCRAFT v0.1.0

> declarative audio for AI agents

Your agent writes the script as one YAML timeline. SonicCraft compiles it into TTS voices, music beds and sound effects: measured to the sample, ducked under every word, mastered to broadcast loudness, with subtitles that match the audio. A CLI, an MCP server and an Agent Skill.

$curl -fsSL https://raw.githubusercontent.com/user-github-me/soniccraft/main/install.sh | sh
★ star on github quickstart releases crates.io

01how it works

Intent goes in as data; SonicCraft does the geometry. Everything below is real output for this one timeline, rendered with the built-in mock voice: no API key needed.

1 write the timeline
~/episode — timeline.yaml
version: "1.0"
output: { path: episode.mp3, format: mp3, export_subtitles: [vtt, srt] }
speakers:
  host:  { provider: mock, voice_id: host }   # or elevenlabs, openai, kokoro, piper...
  guest: { provider: mock, voice_id: guest }
tracks:
  - id: voice
    type: speech
    start_at_ms: 1500
    sequence:
      - { speaker: host, text: "Welcome back to the show." }
      - pause: 300ms
      - { id: thanks, speaker: guest, text: "Thanks! Today: audio for AI agents." }
  - id: bed
    type: music
    source: music/bed.wav
    loop: true
    end_relative: { after_cue: thanks, offset_ms: 2000 }
    ducking: { trigger_tracks: [voice], reduction_db: -18 }
2 dry run: free, no TTS calls
~/episode — zsh
$ soniccraft plan timeline.yaml
SonicCraft plan
duration 0:08.6 | 48000 Hz | 2 tracks | 2 cues, 1 pause, 1 clip

time         0s     1s      2s      3s      4s     5s      6s      7s      8s
             |--+---|---+---|---+---|---+---|--+---|---+---|---+---|---+---|---+
voice                   ##############  #########################
bed          ===========------------------------------------------------------==============
legend: # speech  = music/sfx  - ducked  blank = silence  (1 col = 0.13 s)
3 render
~/episode — zsh
$ soniccraft render timeline.yaml
Rendered episode.mp3 in 0.28 s
  format      mp3, 48000 Hz, stereo, 192 kbps, 208.5 kB
  duration    8.62 s
  loudness    -16.0 LUFS (target -16.0), true peak -7.3 dBTP (ceiling -1.0), LRA 0.6 LU
  subtitles   episode.vtt, episode.srt
  synthesis   2 cues: 2 synthesized, 0 from cache (called mock)

02errors an agent can fix

Every problem comes with a stable code, the exact line and column, and a hint. People read the text; agents get the same report as JSON with --json.

~/episode — zsh
$ soniccraft validate timeline.yaml
error[unknown_reference]: `after_cue` refers to `intr`, which is not the id of a cue, clip or track
  --> timeline.yaml:10:38
   |
10 |         start_relative: { after_cue: intr, offset_ms: "350 ms" }
   |                                      ^^^^
   |
   = hint: Did you mean `intro`? Known ids: `voice`, `intro`, `voice.cue2`, `bed`

error[unknown_field]: unknown field `file` in music track `bed`
  --> timeline.yaml:13:5
   |
13 |     file: assets/audio/synthwave_loop.wav
   |     ^^^^
   |
   = hint: Did you mean `source`? Write `source: "assets/audio/synthwave_loop.wav"`

error: timeline.yaml is invalid: 2 errors (1 note hidden, use -v to show)

03what's inside

A Rust engine built like a compiler: parse, lower, lay out, synthesize, mix, master.

04plug it into your agent

Install the CLI above, then give your agent the skill and the MCP server, or just the link.

claude code
$claude plugin marketplace add user-github-me/soniccraft
$claude plugin install soniccraft@soniccraft
codex
$codex mcp add soniccraft -- soniccraft mcp
$npx skills add user-github-me/soniccraft -g -a codex
cursor
$npx skills add user-github-me/soniccraft -g -a cursor
any mcp client
$npx -y soniccraft-mcp
// or paste this into any coding agent:Use github.com/user-github-me/soniccraft to make a 30-second voiceover with background music for my product video.