atmos-audio-gen

name

atmos-audio-gen

description

Create or revise clean continuous audio beds for Atmos marketing and HyperFrames videos, including cue maps that follow high-density editorial product videos. Use when generating synthetic WAV background music, adding or replacing promo video music, muxing audio into landing page videos, matching audio energy to video beats, or fixing issues like per-scene pause/play, cue-start stingers, chirpy bells, bird-like transition sounds, harsh high frequencies, or mid-track silence.

Atmos Audio Gen

Purpose

Create restrained, continuous app-promo soundtracks for Atmos videos. Pair this with hyperframes or hyperframes-cli when the video composition itself needs editing; this skill owns the audio design, generation, muxing, and verification rules.

Workflow

1. Inspect the video timeline: total duration, scene/cue starts, act breaks, visual energy, proof density, and whether the user wants pure music or music under voice.
2. Build one full-duration audio bed. Do not create separate audio clips per scene unless the user explicitly asks for source-editing of existing music.
3. Model scene changes with a cue map and smooth parameter interpolation: chord, pad, arp density, drum density, sub pulse, and shimmer.
4. Read references/audio-project-files.md before creating or revising project audio files.
5. For a new generated soundtrack, use scripts/create-continuous-audio-script.mjs to create the project-local generate-audio.mjs template, then edit the cue map to match the video.
6. Generate a WAV at the exact video duration, usually from <creative-project>/hyperframes/scripts/generate-audio.mjs to <creative-project>/artifacts/audio/*.wav.
7. Mux the WAV into the existing MP4 with video stream copy when visuals are already correct.
8. Verify duration, codec, mid-track continuity, and absence of transition stinger code before reporting completion.

Skill Resources

• references/audio-project-files.md is the source of truth for project audio file responsibilities, output paths, script reuse boundaries, package script updates, and verification commands.
• scripts/create-continuous-audio-script.mjs creates a project-local continuous soundtrack generator and patches hyperframes/package.json with npm run audio.
• This skill intentionally has no assets/ directory. Do not bundle samples, loops, or fixed brand sound files into the skill; generate synthetic audio locally or use user-provided source files from the project's source/ folder.

Template example:

node .agents/skills/atmos-audio-gen/scripts/create-continuous-audio-script.mjs marketing/creative/projects/feature-tour --duration 30 --output-name feature-tour-soundtrack.wav

Sound Design Rules

• Keep the music continuous from start to finish, with only a global fade-in and fade-out.
• Make sections feel different through arrangement changes: fewer/more drums, denser arps, chord crossfades, sub movement, and slightly different shimmer.
• Use a premium app-promo arc: calm intro, gradual build, energetic feature middle, clean resolved close.
• Keep the palette minimal: warm pads, soft pulse, controlled sub, light percussion, and restrained shimmer.
• Let visual cuts and music cues align broadly, but avoid a point sound on every scene boundary.
• Preserve headroom. Normalize or scale to a target peak around 0.72 to 0.82, then use a final limiter when encoding.

Video Energy Cueing

For editorial product videos, cue audio to the broader act energy rather than every visual cut:

• Hook/title cards can use sparse pad and low pulse.
• Dense product proof, split workflows, and montage sections can increase percussion, arp density, and sub movement.
• Dark chapter cards can thin the arrangement briefly without becoming silence or a restart.
• CTA sections should resolve with fewer moving parts and a cleaner chord shape.
• If a reference or source video has a silent or near-silent audio track, report that fact; do not infer that the target Atmos video should be silent unless the user asks.

Use the visual storyboard's beat names as cue names where possible so audio and video stay aligned during revisions.

Hard Avoids

• Do not add per-cue one-shot transition sounds. Avoid patterns named or shaped like transitionLift, bellLayer, liftNoise, riser, cue-level bell, sweep bursts, and chime hits.
• Do not stop, pause, or restart music for each segment. The listener should not hear the soundtrack resetting between scenes.
• Do not use high-pitched bells, chirps, bird-like tones, or sharp noise accents at cue starts.
• Do not make every transition sound identical. Prefer continuous crossfades and evolving instrumentation instead of repeated effects.
• Do not let shimmer or arps dominate the mix. High-frequency content should be subtle and continuous, not a foreground melody unless requested.

JavaScript Synthesis Pattern

Use a cue map with continuous fields. A good cue shape is:

const cues = [
  { name: "intro", start: 0, chord: [73.42, 110, 146.83, 220], pad: 0.9, arp: 0.05, drums: 0.05, shimmer: 0.25 },
  { name: "build", start: 4.0, chord: [58.27, 116.54, 174.61, 233.08], pad: 0.8, arp: 0.3, drums: 0.35, shimmer: 0.35 },
];

Use a transitionSeconds window of roughly 1.2 to 2.0 seconds and interpolate cue values with smoothstep. The final mono mix should look conceptually like this:

const mono = (pad + arp + drums + sub + shimmer) * globalEnvelope(time);

Keep stinger-like layers out of the mix. If a layer only exists to fire around cue.start, remove it or redesign it as a continuous background layer.

Atmos Project Conventions

• Put synthetic audio scripts inside the creative project's HyperFrames app, for example marketing/creative/projects/<project>/hyperframes/scripts/generate-audio.mjs.
• Output the canonical generated audio into the creative project's artifacts folder, for example marketing/creative/projects/<project>/artifacts/audio/.
• If the HyperFrames composition contains an <audio> element, mirror the WAV into the HyperFrames app, for example marketing/creative/projects/<project>/hyperframes/assets/audio/, because HyperFrames lint/preview only resolves media inside the composition project.
• Add or use an npm run audio script for repeatable regeneration.
• When working in this repo, use marketing/creative/projects/atmos-intro/hyperframes/scripts/generate-audio.mjs as the current baseline for a continuous synthetic soundtrack.
• Keep generated video, image, and audio outputs under marketing/creative/projects/<project>/artifacts/, and deployable landing copies under apps/landing/public/videos/.

Muxing

When the visual MP4 is already correct, replace only the audio track:

ffmpeg -y -i path/to/video.mp4 -i path/to/audio.wav \
  -map 0:v:0 -map 1:a:0 \
  -c:v copy -c:a aac -b:a 160k \
  -af afade=t=in:st=0:d=1.2,afade=t=out:st=<fade_start>:d=1.8,alimiter=limit=0.86 \
  -shortest path/to/video.with-audio.mp4

Set <fade_start> to duration - fade_out_duration, for example 28.2 for a 30 second video with a 1.8 second fade-out.

Verification

Run these checks before finishing:

ffprobe -v error -show_entries format=duration,size \
  -show_entries stream=index,codec_name,codec_type,sample_rate,channels,width,height,r_frame_rate \
  -of default=nw=1 path/to/video.mp4

ffmpeg -hide_banner -nostats -i path/to/video.mp4 \
  -map 0:a:0 -af silencedetect=noise=-45dB:d=0.22 -f null -

Only start/end fade silence is acceptable unless the user requested silence. Mid-track silence usually means the audio is still segment-based or muxed incorrectly.

Also grep the generation script for known bad transition layers:

rg -n "transitionLift|bellLayer|liftNoise|riser|bell:" path/to/generate-audio.mjs

This grep should return no matches for Atmos promo background music unless there is a deliberate user-approved sound design reason.

Final Response

Report the files changed, the final video path, the audio/video parameters, and whether the no-stinger and mid-track continuity checks passed. If verification was skipped, say why.