Put the music in your project

Make a reveal land, give the boss fight some nerve, or let the last slide take a bow. Your agent composes with Audio as Code, brings the WAV into your creative project, and keeps the score for revisions.

These recipes connect your tools through a portable skill, local commands and ordinary audio files. Audio as Code supplies instrumental music and musical cues. Use your project's other tools for narration and sound effects.

For looping game music, ask for a loop candidate and audition the join in the game. Matching endpoints and managing release/effect tails need deliberate work; a render is not automatically a seamless loop. For narration-heavy videos or presentations, request sparse music and adjust its level in the consuming tool.

The source project includes an executable set of original creative briefs:

uv run --no-dev python examples/creative_workflows.py output/creative-workflows

Run it from the extracted source folder after setup. It delivers a 30-second video cue with a reveal at 20 seconds, a 12-second game loop plus two-cycle preview, and a nine-second presentation sting. Each has an initial version and a revision that preserves specified material, with WAV/MIDI/JSON, composer, inspection, reports and measured checks. Use a fresh output folder. Add --scores-only for quick editing or --brief game --version v2 for one candidate. The loop uses short articulated rests and no effect tails; it is not a general wet-loop exporter. Full rendering checks duration, finite stereo output, clipping, reproducibility and the PCM join, and takes several minutes. Listening remains a separate check. The source guide docs/creative-workflows.md explains the method.

Start in your creative project#

Use the website's Copy agent prompt, or download the full source project and give your agent the extracted folder. Ask it to read the portable skill, then describe the music and where it will go. The agent needs a shell and Python 3.10+.

If setting it up directly, run these in the folder containing pyproject.toml:

uv sync --locked --no-dev
uv run --no-dev aac instruments
uv run --no-dev aac schema

Use the quickstart for the pip/virtual-environment alternative. Audio as Code is not published to a package registry. Its renderer needs no model or provider key; your chosen agent has its own account and runtime requirements.

Codex: keep the composer beside the project#

Open the project in Codex and ask it to read skills/audio-as-code/SKILL.md from the extracted Audio as Code folder. That direct instruction requires no skill installation. For repeat use, copy the skill folder into your creative project's .agents/skills/audio-as-code/. Codex discovers repository skills there; in Codex CLI or the IDE extension, invoke it as $audio-as-code. Official Codex skill instructions.

Use the Audio as Code skill and the local source checkout. Compose an original
12-second moon-cheese launch cue: curious marimba, bass enters at second 4,
confident ending. Put v1 in output/moon-cheese/v1/. Deliver WAV, MIDI, score,
composer source and report. Check the actual WAV duration including tails.

Keep the source folder path in the brief if the creative project and framework are separate. To revise: "Keep the motif and the 12-second cut. Make the opening more suspicious, then brighten the final chord. Save v2."

Claude Code: the same skill, another host#

Claude Code can also read the portable file directly. For project discovery, copy skills/audio-as-code/ into .claude/skills/audio-as-code/ in the creative project, then invoke /audio-as-code with the same musical brief. Claude Code's documented project skill directory and slash invocation support this layout. Official Claude Code skill instructions.

The agent still composes and calls the local CLI. Copying the skill does not install Python or the renderer. Preserve WAV, JSON and source files in the project so either agent can continue the arrangement later.

Hyperframes: music becomes a video asset#

Make the score in Audio as Code and the visuals in Hyperframes. The connection is a local WAV file: Hyperframes places it on its composition timeline and mixes it into the rendered video. Its official example uses an <audio> element with a WAV source. Hyperframes repository.

1. Render the cue and inspect report.json or aac analyze song.wav. Use the measured WAV duration, including release/effect tails, to plan the video cut.
2. Create or open a Hyperframes project. For a new one, its documented local route is npx hyperframes init my-video, then work inside my-video/. Local video rendering requires Node.js 22+ and FFmpeg. The official skill installation is npx skills add heygen-com/hyperframes when you want agent authoring guidance. Hyperframes quickstart.
3. Copy your finished WAV to my-video/assets/soundtrack.wav. Keep its score, source and report in the music project; Hyperframes consumes the rendered audio, not the JSON score or MIDI.
4. Add this inside the existing root composition in index.html. Use an unused audio track index. This example assumes a confirmed 12-second cue:

<audio id="soundtrack" src="./assets/soundtrack.wav"
       data-start="0" data-duration="12" data-track-index="8"
       data-volume="0.6"></audio>

data-start and data-duration are seconds. data-media-start can trim the source start; omitting data-duration uses its remaining length. Audio elements do not need class="clip". Set the composition's visual timeline to cover the intended cut; the audio tag does not author the visuals. Hyperframes HTML schema.

Ask your video agent:

Use the existing Hyperframes project. Build a 12-second moon-cheese launch video
around assets/soundtrack.wav. Place the reveal on the bass entrance at second 4.
Use this generated soundtrack, keep its ending audible, and preserve the editable
HTML project. Preview the full result and render an MP4.

From that project's folder, Hyperframes documents npx hyperframes preview and npx hyperframes render --output launch.mp4. Hyperframes quickstart. When revising the music, render a new candidate, replace the copied WAV, and preview again. Matching a filename does not guarantee the new duration matches the video. The soundtrack remains procedural; this handoff adds no recorded instrument sources.

A small bridge for any shell-capable agent#

The runnable handoff example accepts an existing score, inspects WAV/MIDI readiness, renders WAV, analyzes the saved audio, exports MIDI, and writes handoff.json with artifact paths, duration and warnings. Its subprocess calls use the current environment's Python and argument lists, not shell strings.

To check the connection using the bundled demo, run from the source project:

uv run --no-dev aac demo -o output/integration-input.json
uv run --no-dev python docs/site/examples/06_agent_handoff.py output/integration-input.json output/integration-v1

Use a new output directory for each run. For actual work, replace the demo score with the agent's original composition. A custom agent can call this script as a local tool and read its JSON result; no provider SDK is required by the bridge.

The bridge does not copy a separately authored composer script: retain that source alongside the score. When transferring to another machine, copy the artifacts and update paths rather than expecting absolute local paths to work remotely.

Let errors guide the next edit#

CLI success is JSON on stdout with exit 0. On exit 2, read the JSON on stderr: invalid_score has issues with field path and message; operation_failed has a message and recovery hint. Cross-field issues can have an empty path. Fix the indicated score or file problem, validate again, then render and analyze the new candidate. A process timeout or missing Python executable is a separate execution problem, not a score diagnostic.

The bridge reports score_not_exportable and exits 2 for static WAV/MIDI blockers before creating the output folder. It also forwards CLI errors and exits 2; its own file/process errors use handoff_failed and exit 1. It stops on failure, so check the exit code before using any partial files. Successful signal checks cannot establish musical taste, acoustic realism or a clean loop seam. Listen when available, and say when it was not possible. See the agent guide for the full command contract.

These recipes were checked against official tool documentation on 2026-10-02. The local render/export bridge was executed; provider skill discovery and the Hyperframes MP4 render were not exercised as part of this guide's validation.