Sound

Sound for a studio's game

Everything here runs on this computer with Node 22 and ffmpeg: nothing is sent anywhere and nothing costs money. Sung songs and produced music from a model are the music skill (ElevenLabs, paid); this skill is effects and synthesized music. They share the studio's music/ folder and manifest, so a synthesized theme gets a song page just like a rendered one.

One script: scripts/sound.mjs in this skill's folder (Claude Code: node "${CLAUDE_PLUGIN_ROOT}/skills/sound/scripts/sound.mjs" <command>), run from inside the studio (the folder with studio.json). Every command takes --json.

node <sound.mjs> check        # node, ffmpeg and its encoders, the studio and its games
node <sound.mjs> presets      # every effect preset, instrument, groove and pattern, one line each

No ffmpeg: offer brew install ffmpeg (macOS) or the system package; the person approves. Finish in this turn: an effect set takes seconds, a one-minute score under a minute.

1. Effects

node <sound.mjs> sfx <set> --kit arcade --for-game <id>          # a kit: arcade, platformer, shooter, party, ui
node <sound.mjs> sfx <set> --only jump,coin,hit,win --style retro   # just these, crunchy 8-bit
node <sound.mjs> sfx <set> --spec music/<set>/effects.json        # your own list (below)

It writes music/<set>/sfx/<name>-<n>.wav and an Ogg copy of each, music/<set>/sfx.json (the spec and every file's measured level), a reel to listen to (<set>.mp3) and its picture (<set>-reel.png, a spectrogram over the waveform). Open the picture and look: a sound you cannot hear is still a sound you can see. Then read the warnings; each one is something a person will hear wrong, with the fix.

A spec is { "style": "clean", "variants": 3, "effects": [ { "name": "stomp", "preset": "land", "pitch": -3, "length": 1.2, "level": "big" } ] }: preset is any name from presets (the effect's name is used when it is one), pitch in semitones, length a stretch, seed another take, style clean, retro or soft, level ui, small, normal, big or a number in dB. Name effects after what happens in the game (stomp, gem, ko), not after the preset.

• Variants (three by default) are the same recipe a touch higher or lower, so a sound heard fifty times a round does not machine-gun. Signals heard once a round (win, lose, go, countdown) get one take.
• Levels are set by the loudest 50 ms of each effect into four classes (ui -20, small -16, normal -12, big -9 dB), then held under -1 dBFS. The set sits together in a mix without balancing.
• Every effect must start at once (a hit that starts 30 ms late feels laggy) and must reach a phone speaker: under about 300 Hz a phone plays almost nothing, so a thud needs a knock on top. The warnings measure both.

2. A synthesized theme or score

Write music/<slug>/score.json (the full language, with a worked example: references/SCORE.md): tempo, key, instruments (presets with a level, pan, echo in beats, reverb send, a duck under the kick), sections in whole bars with chords and one pattern per instrument, an arrangement, and the sections to loop. Then:

node <sound.mjs> score <slug> --spec music/<slug>/score.json --loops main,chase

• It renders the mix (-14 LUFS for a page; --lufs -18 for a bed under a game's effects), the page mp3, a 24-bit master kept off the site, one stem per instrument plus the room (they sum to the mix), and seamless loops of the sections you name: each is rendered three times in a row and the middle copy kept, so reverb and echoes that ring over the loop point are already in its head. The report gives each loop's seam (1 or less is seamless) and its exact bar length. A loop over 1 is in warnings and the summary says NOT SEAMLESS (loopsSeamless: false): an empty warnings list means the loops were checked and pass. The master's limiter is applied across the three copies, so a loud loop keeps its seam; nothing is faded at the loop point and no bar is shortened.
• plan.json holds the bar grid, so the video skill cuts a trailer on this music's bar lines.
• Look at <slug>.png and read the numbers: loudness, true peak, and what it measures through a phone speaker. Say them in your report, not adjectives.
• Write music a person would hum: a hook in the first bars, a clear melody over simple chords, a change every 4 or 8 bars. A score for a game is sections of the same tempo and key (calm, chase, final seconds) so the game can move between them on a bar line.

3. A mix of anything

node <sound.mjs> mix <slug> --spec music/<slug>/mix.json

Parts are audio files (a recording, a render, a loop), ffmpeg aevalsrc expressions (one, or two for left and right), or effect presets, each placed (at seconds), levelled (db), panned, faded, repeated and filtered with an ffmpeg -af chain. They are summed at exactly the levels written (no automatic normalisation), limited, and brought to master.lufs if you give one. Expressions have traps that fail silently: read references/TRAPS.md before writing one.