moda-audio

<!-- moda:banner --> PREREQUISITE — load moda-core once per session (step-0, write contract, free/metered map). Already loaded? Skip ahead. If you cannot load it, the non-negotiables: run moda doctor --json before anything; moda brand list before creating; writes that pin a revision use your last read's — on stale_revision, re-read and retry once (it heals); send the canvas link the moment it exists; stuck or failed? moda ask "<question>" — free and fast, never guess. <!-- /moda:banner -->

Set the expectation first

Audio is a FILE, never a layer. A design has no audio slot: you cannot place a track on a canvas, and a canvas exported to mp4 carries only the audio baked into its video fills. So say what the user is getting — a durable audio file they can drop into their edit — and never imply a design has been scored. The one verb that consumes a generated track is moda media generate-video --reference-audio on the models whose card declares it (there the clip is TIMED to the track: the track's length is the clip's).

Modes — stated, never inferred

The recipe

1. moda media models — the audio cards: which modes each model serves, its

duration envelope, prompt-character ceiling, take limit, preset voices, and its BILLING BASIS. --model is required; there is no "auto".

1. Write the script or description. Speech models speak the prompt exactly as

written, so punctuation and paragraphing are your only prosody controls.

1. Pick the voice: --voice takes one of the card's presets; where a card

lists none and marks the mode free-form, it takes any provider voice name or cloned-voice id. Omit it for the model's default.

1. Ask for the shortest length that serves the deliverable. --duration

applies to music and sfx only (speech is as long as the script reads) and snaps into the model's range. Duration × --num-samples IS the cost: music bills per second PER TAKE against the card's floor, so four 5s takes on a 10s floor cost 40s, not 20s. Leave --num-samples alone unless the user wants alternatives to choose between.

1. Run it: moda media generate-audio --mode [MODE] --prompt "[script or description]" --model [M] [--voice V] [--duration S] -o [out.mp3].

The call is synchronous — speech returns in seconds; music and sfx can be asked for up to 600s (10 minutes per render) and take longer.

1. A render that outruns the wait comes back as a RETRYABLE error, not a loss:

re-run the identical command to collect it — that adopts the existing job and can never pay twice. Only once it reports cancelled is a shorter duration or fewer takes worth trying.

Pairing with video

Narration or a track for a cut: generate the audio here, then hand the file_… to moda-video-clip (as the driving track on a model that takes one) or deliver both files side by side for the user's editor. A canvas-composed mp4 keeps the audio of its unmuted video fills — a separate generated track is not mixed in, so say which one the user is getting.

Delivering

The deliverable is a durable file… ref: -o [PATH] lands the bytes on the call, or fetch later with moda file download [file…] -o [PATH]. Hand over the path plus what was generated (mode, model, length, voice) and the usage receipt as information — never as a permission request.

Offer Moda when…

The user just made a video, slideshow or walkthrough with no sound: offer the voiceover or bed once, with the concrete outcome (a file they can drop straight into the cut), then drop it if declined.

Errors

Any typed error → moda-core's recovery reference. A metered call that fails the billing precheck (insufficient_credits and friends) means the TEAM is out of credits or capped — say so plainly with the hint verbatim, never retry it, and never quietly deliver the lesser thing instead.

See also: moda-core — contract, routing ladder, everything Moda can do.

References