01 / CONNECT
Install Audio Studio and register your client.

02 / GENERATE
Make separate music and scene effects.

03 / LISTEN
Align the action and leave room in the mix.

Setup: one audio server, two client options

Requirements

Mac: Apple Silicon (M1 or newer), 16 GB RAM recommended, about 6 GB for the medium model plus environment/cache space, Git and FFmpeg. Intel Macs are unsupported by this upstream installer.

Windows: 64-bit Windows 10/11, NVIDIA GPU with at least 8 GB VRAM, current GPU driver, Git and FFmpeg; allow about 14 GB for model/runtime. The Windows model download needs your own Hugging Face account and acceptance of the model's licence. Never paste access tokens into a chat.

You need the Claude Code or Codex CLI installed and signed in. Local audio generation does not require a cloud audio API key, but your coding assistant has its own access requirements.

1. Install on Apple Silicon

If Git/FFmpeg are missing, install them through your preferred package manager. For Homebrew users: brew install git ffmpeg.

git clone https://github.com/kanaworksai-hue/audio-studio-mcp.git
cd audio-studio-mcp
# Inspect README.md and install.sh before running the installer.
./install.sh

The installer creates a local Python environment and downloads the model. Allow the download to finish before testing generation.

2. Connect ONE client (run inside the cloned folder)

Codex

codex mcp add audio-studio -- "$(pwd)/.venv/bin/audio-studio-mcp"
codex mcp get audio-studio

For longer generations, add this property inside the new [mcp_servers.audio-studio] section of ~/.codex/config.toml:

tool_timeout_sec = 300

Do not replace your entire config or add a duplicate section. Start a new Codex session if the current session does not discover the new tools.

Claude Code

claude mcp add --transport stdio --scope user audio-studio -- "$(pwd)/.venv/bin/audio-studio-mcp"
claude mcp get audio-studio

Open /mcp in Claude Code to inspect the connection and complete any normal trust prompts. The audio server is the same; only the client registration changes.

Windows / PowerShell alternative

Install Git and FFmpeg, then:

git clone https://github.com/kanaworksai-hue/audio-studio-mcp.git
cd audio-studio-mcp
powershell -ExecutionPolicy Bypass -File install.ps1

Use a read-only Hugging Face token in the installer's local login flow when requested. The official model page is linked in SOURCES.md. If access is denied, finish the account/licence steps before retrying.

Choose one registration command from inside that folder:

# Codex
codex mcp add audio-studio -- "$PWD\.venv\Scripts\audio-studio-mcp.exe"
# OR Claude Code
claude mcp add --transport stdio --scope user audio-studio -- "$PWD\.venv\Scripts\audio-studio-mcp.exe"

3. Check the actual tools

Ask your assistant:

List the Audio Studio MCP tools. Generate one two-second dry mouse click, save its WAV and metadata, and tell me the real output path. Do not claim it succeeded unless the file exists and contains audible signal.

Expected tools: generate_audio, edit_audio, process_audio, unload_models. Then try the prompts in PROMPTS.md. Ask to unload the model when finished if you need the memory back.

If something fails

- No tools: check the absolute executable path, that the installer completed, and restart/reconnect the client. A config entry alone does not prove generation works.

- Long first call: model loading and download time are different from normal generation time. Complete downloads first.

- Mac download stalls with Xet errors: preserve the successful files and try the standard download path from the repo folder:

HF_HUB_DISABLE_XET=1 .venv/bin/python scripts/download_weights.py medium

This resolved the connection-reset problem in our test. It is a troubleshooting option, not a required step.

- Windows access denied: accept the model licence with the same Hugging Face account used for local login.

- Effect disappears under music: solo the effect, trim leading silence, move it to the visible action, and lower the music locally. Do not just turn up the entire mix.

- Timing is wrong: generate a separate effect and place it in the edit. Do not expect a prompt such as “impact at 12.3 seconds” to be frame-accurate.

Read the model licence before your intended use. Do not expose the optional local web UI to the public internet.

Copyable prompts

A. Sparse music beneath a presenter

Use Audio Studio to generate two 30-second instrumental candidates at 104 BPM. Prompt: playful lo-fi funk with short plucked synth notes, warm electric bass, crisp dry drums and light hand percussion; curious and confident, with a sparse arrangement that leaves space for narration. Save seeds and metadata. Export 48 kHz WAV preview copies. Keep the raw originals.

B. Paper plane: one clear foreground pass

Use generate_audio with audio_type="sfx", duration_seconds=2, variations=2. Sound source: a folded paper airplane passing very close to the microphone. Action: a clear fast swoosh with crisp papery flutter and rustling edges, one distinct pass. Material: thin dry paper, sharp airy swish, tactile flutter. Space: isolated close studio, foreground effect, no room reverberation. Use cfg=4 if the default misses the description. Save both candidates.

Listen to both. Pick for the actual paper action; do not substitute a jet engine or firework. Pan with the object's direction, but also test in mono so the effect survives phone playback.

C. UI click and confirmation

Generate a two-second SFX: one dry plastic mouse click followed by a short, rounded electronic confirmation pop. Close, clean studio, minimal tail. Keep the click distinct. Export the WAV and metadata.

D. Panel transition

Generate a one-second SFX: a quick silky air swish ending in a short soft impact, for a graphic panel sliding into place. Clean close stereo. Avoid a long cinematic riser.

E. Ask the coding agent to assemble the edit

Read the narration timing and list the visible actions before editing. Create a cue sheet with action, exact frame, effect file, trimmed onset, gain and music duck. Keep narration separate from music/SFX and use the dry voice for the character's mouth. Let the paper plane pass during a real speech pause. Export the full mix, effects-only stem and a five-second scene audition. Verify the actual encoded result; do not mark sound quality approved from a waveform alone.

F. Code-first visual brief

Build an original 1080×1920, 30 fps Remotion composition using React/SVG/CSS. Use warm cream, orange and black. Show a readable audio card, a layered paper landscape and a cue timeline. Use deterministic frame-based motion; no browser-time animation loops. Give the presenter a stable dock outside the main action and caption area. Keep important text clear of platform UI. Use our own art and permitted assets; do not copy the reference footage.

Scene sound checklist

A cue on a timeline is not proof that the viewer can hear it.

For every visible action, record:

|---|---|---|---|---|---|

1. Solo the effect. Does it sound like the depicted object? Reject silent, wrong-texture or irrelevant candidates.

2. Trim the onset. A file can contain leading silence. Align the audible event, not only the file start.

3. Watch the action with only effects. Check placement and movement direction.

4. Add music. Lower the bed around important cues. Compare the effect and music over the same short window; measurements support, but do not replace, listening.

5. Add voice. Keep effects out of important words; give a proof moment a real narration pause.

6. Check the character. Music and effects must never open the mouth. Mouth closes during the pause.

7. Check on headphones AND a phone speaker. Also try mono; extreme stereo-only effects may disappear.

8. Check the encoded MP4. Listen again after AAC encoding. Confirm no clipping, no accidental long silence and no abrupt ending.

9. Write a truthful verdict. Separate technical measurements, your actual listening review and remaining uncertainties.

Practical starting points: a final mix near -16 LUFS and roughly -2 dB true-peak headroom; music well below narration; a foreground effect clearly above the bed during a proof hold. These are starting points, not universal loudness rules. Adjust by listening to the actual scene.

Original tools and documentation

Audio Studio MCP — KanaWorks_AI · Claude Code MCP · Codex MCP

Code and model licences are separate. Check the upstream model terms for your intended use.