[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6DB1H6AESZ5972EWM4WY7AE":3,"skill-same:01M6DB1H6AESZ5972EWM4WY7AE":69},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":14,"repositoryHtmlUrl":52,"repositoryHomepageUrl":6,"ownerHtmlUrl":53,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":54,"install":55,"resources":68},"01M6DB1H6AESZ5972EWM4WY7AE","audio-extract-mix",null,"Use when you need to EXTRACT, MIX, REPLACE, DUCK, or LOUDNESS-NORMALIZE audio on a video\u002Fclip with ffmpeg — e.g. pull a wav out of a clip, lay a music bed or VO UNDER a speaker so it auto-dips when they talk (sidechain ducking), normalize an export to a per-platform LUFS target (-14 for TikTok\u002FReels\u002FShorts\u002FYouTube, -23 EBU R128 broadcast, -24 ATSC), mux\u002Freplace\u002Fstrip an audio track while preserving all other streams, or turn the soundtrack into laughter\u002Fapplause\u002F music\u002Floudness saliency signals. The exact filter graphs, argv lists, codec\u002Fmap choices, and the pitfalls that actually bite (amix auto-attenuation, -shortest duration, stream-index = list-order coupling, mono\u002F32k decode for PANNs, loudnorm single-pass drift) come from the real media_studio source cited below. Do NOT use for: per-word transcription\u002Falignment (use ASR\u002FCTC modules), TTS dub GENERATION (this only muxes a finished dub), pitch\u002Ftempo time-stretch, or pure visual edits. Do NOT use as a generic \"run ffmpeg\" reference — it is scoped to these audio ops with the project's frozen wire surface.","Prekzursil\u002Fagent-skills-toolchain","Prekzursil","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F54636077?v=4","01M6DACZ1PCQHD99SCR1YXG28B","Andrei Mihai Visalon","01M6DACZ670WZF535V3WYYSS4Z",0,"MIT","https:\u002F\u002Fgithub.com\u002FPrekzursil\u002Fagent-skills-toolchain\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Faudio-extract-mix\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"audio extract mix","Audio","extract","alignment","as","normalize","platform","project","time","map","tiktok","do","pull","modules","only","clip","Word","tts","Media","Video","2026-11-10 10:12:30",false,"---\nname: audio-extract-mix\ndescription: >-\n  Use when you need to EXTRACT, MIX, REPLACE, DUCK, or LOUDNESS-NORMALIZE audio\n  on a video\u002Fclip with ffmpeg — e.g. pull a wav out of a clip, lay a music bed or\n  VO UNDER a speaker so it auto-dips when they talk (sidechain ducking), normalize\n  an export to a per-platform LUFS target (-14 for TikTok\u002FReels\u002FShorts\u002FYouTube,\n  -23 EBU R128 broadcast, -24 ATSC), mux\u002Freplace\u002Fstrip an audio track while\n  preserving all other streams, or turn the soundtrack into laughter\u002Fapplause\u002F\n  music\u002Floudness saliency signals. The exact filter graphs, argv lists, codec\u002Fmap\n  choices, and the pitfalls that actually bite (amix auto-attenuation, -shortest\n  duration, stream-index = list-order coupling, mono\u002F32k decode for PANNs,\n  loudnorm single-pass drift) come from the real media_studio source cited below.\n  Do NOT use for: per-word transcription\u002Falignment (use ASR\u002FCTC modules), TTS dub\n  GENERATION (this only muxes a finished dub), pitch\u002Ftempo time-stretch, or pure\n  visual edits. Do NOT use as a generic \"run ffmpeg\" reference — it is scoped to\n  these audio ops with the project's frozen wire surface.\n---\n\n# audio-extract-mix\n\nExtract \u002F mix \u002F replace \u002F duck \u002F loudness-normalize audio on a clip, the way the\nReframe media_studio sidecar actually does it. Every command below is copied from\nreal source — no invented flags.\n\n## Source modules (read these for ground truth)\n\n- `sidecar\u002Fmedia_studio\u002Ffeatures\u002Faudiomix.py` — `audiomix.merge` (duck→mix→loudnorm)\n  + `audiomix.normalize` (loudnorm only). Owns `build_mix_filter`,\n  `build_mix_argv`, `build_loudnorm_argv`, `PLATFORM_LOUDNESS`,\n  `resolve_loudness_target`.\n- `sidecar\u002Fmedia_studio\u002Ffeatures\u002Ftracks_audio.py` — `tracks.audio.{list,mux,replace,strip}`.\n  Owns `build_mux_argv`, `build_replace_argv`, `build_strip_audio_argv`,\n  `probe_streams`, `original_tracks_from_probe`.\n- `sidecar\u002Fmedia_studio\u002Ffeatures\u002Faudio_saliency.py` — PANNs CNN14 audio tagging +\n  pure RMS `loudness_curve`. Owns `compute_audio_signals`, `peak_windows`,\n  `sample_windows`, the decode argv in `_default_audio_loader`.\n- `sidecar\u002Fmedia_studio\u002Fffmpeg.py` — the shared seam: `ffmpeg_path` \u002F\n  `ffprobe_path` (resolve binary by absolute path), `run` (argv-list Popen,\n  both pipes drained, `-progress` parsing, cooperative cancel),\n  `ffprobe_duration` (drives the progress %).\n\nThe whole module follows one law (audiomix.py docstring, CONTRACTS §4\u002F§6\u002F§7):\n**argv LISTS only, never `shell=True`**; the filter graph and every path is a\nsingle argv element; the ffmpeg binary is resolved by absolute path; both stdout\nand stderr are drained by the shared `run`. Keep that when you hand-run these.\n\n---\n\n## Recipe 1 — Mix a music bed \u002F VO UNDER speech with sidechain ducking + loudnorm\n\nThis is `audiomix.merge`. The entire operation is ONE `-filter_complex` graph\nwith two inputs: `0` = the clip, `1` = the bg bed.\n\nThe graph (`build_mix_filter`, audiomix.py:146-152), with defaults\n`bg_gain_db=-10.0`, `duck_threshold=0.03`, `duck_ratio=8.0`,\n`I=-14:TP=-1.5:LRA=11`:\n\n```\n[1:a]volume=-10.0dB[bg];\n[0:a]asplit=2[fg_key][fg_mix];\n[bg][fg_key]sidechaincompress=threshold=0.03:ratio=8.0[ducked];\n[fg_mix][ducked]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[mixed];\n[mixed]loudnorm=I=-14.0:TP=-1.5:LRA=11.0[out]\n```\n\nWhat each stage does:\n1. `volume=\u003Cbg_gain_db>dB` pre-attenuates the bed (negative dB = quieter).\n2. `asplit=2` forks the foreground: one copy is the **sidechain key**, one is mixed.\n3. `sidechaincompress` ducks the bed keyed off the speaker — bed dips when they\n   talk, swells back in gaps. `threshold` (0..1 linear) = how loud the speaker\n   must get to trigger ducking; `ratio` = gain-reduction strength.\n4. `amix` SUMS foreground + ducked bed. `normalize=0` is **load-bearing**:\n   without it amix divides each input by N, halving the foreground. `dropout_transition=0`\n   stops a gain ramp when one input ends. `duration=first` ties length to the clip.\n5. `loudnorm` does the final EBU R128 leveling to the platform LUFS target.\n\nFull argv (`build_mix_argv`, audiomix.py:183-207):\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i clip.mp4 \\\n  -i bed.mp3 \\\n  -filter_complex \"[1:a]volume=-10.0dB[bg];[0:a]asplit=2[fg_key][fg_mix];[bg][fg_key]sidechaincompress=threshold=0.03:ratio=8.0[ducked];[fg_mix][ducked]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[mixed];[mixed]loudnorm=I=-14.0:TP=-1.5:LRA=11.0[out]\" \\\n  -map 0:v -map \"[out]\" \\\n  -c:v copy -c:a aac \\\n  -shortest \\\n  -progress pipe:1 -nostats \\\n  out.mp4\n```\n\nKey choices: **video is stream-copied** (`-map 0:v -c:v copy`) — only audio is\nrebuilt and re-encoded to AAC. `-shortest` + `duration=first` trims a longer bed\nto the clip. `ffmpeg` here means the absolute path from `ffmpeg.ffmpeg_path(settings)`.\n\nWire surface: `audiomix.merge({videoId|path, bgPath, bgGainDb?, duckThreshold?,\nduckRatio?, loudnessTarget?, loudnessTp?, loudnessLra?, platform?}) -> {jobId} -> {path}`.\n\n---\n\n## Recipe 2 — Loudness-normalize an export (no bed)\n\nThis is `audiomix.normalize` \u002F `build_loudnorm_argv` (audiomix.py:225-247). Uses\n`-af` (single audio stream), not `-filter_complex`:\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i in.mp4 \\\n  -map 0:v? -map 0:a \\\n  -c:v copy -c:a aac \\\n  -af \"loudnorm=I=-14.0:TP=-1.5:LRA=11.0\" \\\n  -progress pipe:1 -nostats \\\n  out.mp4\n```\n\nNote `-map 0:v?` (the `?` makes video optional — works on audio-only inputs too).\nWire: `audiomix.normalize({videoId|path, loudnessTarget?, loudnessTp?,\nloudnessLra?, platform?}) -> {jobId} -> {path}`.\n\n### Per-platform LUFS targets (`PLATFORM_LOUDNESS`, audiomix.py:67-80)\n\nPass `platform` instead of hard-coding the number; an explicit `loudnessTarget`\nstill overrides it. `resolve_loudness_target` is **fail-loud** — an unknown\nplatform raises `INVALID_PARAMS`, never a silent fallback (so a typo can't ship\naudio at the wrong loudness).\n\n| platform | LUFS (I) |\n|---|---|\n| tiktok \u002F reels \u002F shorts \u002F instagram \u002F facebook \u002F youtube \u002F x \u002F twitter \u002F spotify | **-14.0** |\n| broadcast \u002F ebu | **-23.0** (EBU R128) |\n| atsc | **-24.0** (ATSC A\u002F85) |\n\n`TP` defaults to -1.5 dBTP, `LRA` to 11 LU regardless of platform.\n\n---\n\n## Recipe 3 — Extract \u002F decode audio to raw samples\n\nThere is no `extract.wav` wire method; extraction lives inside\n`audio_saliency._default_audio_loader` (audio_saliency.py:343-360), which decodes\nto **mono float32 @ 32 kHz** (the rate PANNs CNN14 was trained on, `TARGET_SR`):\n\n```bash\nffmpeg -hide_banner -nostdin \\\n  -i in.mp4 \\\n  -ac 1 -ar 32000 -f f32le -\n```\n\nstdout is read straight into numpy: `np.frombuffer(raw, dtype=np.float32)`. To\nadapt for a real WAV file, swap `-f f32le -` for an output path (e.g. `-vn\nout.wav`) and pick your `-ar`\u002F`-ac`. Keep `-vn` to drop video when extracting.\n\n---\n\n## Recipe 4 — Mux \u002F replace \u002F strip an audio track (preserve everything else)\n\nThese keep ALL other streams under stream copy — nothing re-encoded, nothing\nsilently dropped (tracks_audio.py docstring, A2\u002FA6 lesson).\n\n**Mux** a new audio stream (`build_mux_argv`, tracks_audio.py:184-203):\n`-map 0` keeps every source stream (video + all existing audio + all subtitles),\n`-map 1:a` appends the new audio, `-c copy` re-encodes nothing. Language is tagged\non the NEW stream's audio index `existing_audio_count`:\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i in.mp4 -i dub.aac \\\n  -map 0 -map 1:a -c copy \\\n  -metadata:s:a:1 language=es \\\n  -progress pipe:1 -nostats \\\n  out.mp4\n```\n\n**Replace** stream `a:\u003Cn>` (`build_replace_argv`, tracks_audio.py:223-244):\n`-map 0` then NEGATIVE-map the one stream out, then append the replacement:\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i in.mp4 -i new.aac \\\n  -map 0 -map -0:a:1 -map 1:a -c copy \\\n  -metadata:s:a language=es \\\n  -progress pipe:1 -nostats \\\n  out.mp4\n```\n\n**Strip** stream `a:\u003Cn>` (`build_strip_audio_argv`, tracks_audio.py:261-278):\njust the negative map, copy the rest:\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i in.mp4 \\\n  -map 0 -map -0:a:1 -c copy \\\n  -progress pipe:1 -nostats \\\n  out.mp4\n```\n\nWire surface (names FROZEN by CONTRACTS A2):\n- `tracks.audio.list({videoId}) -> {audioTracks:[AudioTrack]}`\n- `tracks.audio.mux({videoId, path, lang, name, kind}) -> {audioTrack}`\n- `tracks.audio.replace({videoId, audioTrackId, path}) -> {audioTrack}`\n- `tracks.audio.strip({videoId, audioTrackId}) -> {path}`\n\n`AudioTrack {id, lang, name, kind:\"original\"|\"dub\", voice?, path}`.\n\n---\n\n## Pitfalls that actually bite\n\n1. **`amix` auto-attenuates — you MUST pass `normalize=0`.** ffmpeg's `amix`\n   divides each input by the input count, so a 2-input mix halves your\n   foreground. The graph sets `normalize=0` precisely because the bed is already\n   ducked and loudnorm does final leveling (audiomix.py:142-144). Drop it and the\n   speaker goes quiet.\n\n2. **Stream-index = list-order coupling.** `tracks.audio.replace`\u002F`strip` derive\n   the container `a:\u003Cn>` index from the track's POSITION in `Project.audioTracks`\n   (`audio_track_index`, tracks_audio.py:136-141). Originals are seeded in ffprobe\n   stream order and dubs appended as muxed, so order MUST mirror the freshest\n   derivative. Reorder the list out of band and you'll negative-map the wrong\n   stream. The seed only runs once (skips if any `kind==\"original\"` row exists,\n   tracks_audio.py:378).\n\n3. **`-shortest` alone is not enough for a music bed.** Length is tied to the clip\n   by BOTH `-shortest` AND `duration=first` inside `amix`. A bed shorter than the\n   clip won't loop — it just ends (`dropout_transition=0` prevents a gain bump at\n   that point). If you want a looping bed, add `-stream_loop -1` before the bed\n   `-i`, which is NOT in the stock argv.\n\n4. **loudnorm here is SINGLE-PASS (dynamic).** `build_loudnorm_argv` runs one-pass\n   `loudnorm` — it adapts in real time and can drift \u002F pump on material with wide\n   dynamics, and won't hit the integrated target as precisely as two-pass. For a\n   precise master you'd run loudnorm once with `print_format=json`, capture\n   `measured_I\u002FTP\u002FLRA\u002Fthresh\u002Foffset`, then feed them back (`measured_I=…:linear=true`).\n   The module deliberately keeps one pass for speed in a job pipeline. Know the\n   tradeoff before claiming \"broadcast-exact\".\n\n5. **Negative map order matters.** In replace, `-map 0` must come BEFORE\n   `-map -0:a:1` before `-map 1:a`. ffmpeg applies maps in sequence; reordering can\n   leave the stream you meant to drop, or fail to append. Copy the exact order.\n\n6. **`-c:v copy` requires a compatible container.** The mix\u002Fnormalize paths copy\n   video and write `.mp4`. Copying e.g. VP9\u002FWebM video into `.mp4` will fail —\n   stream copy can't transcode. The source always outputs `.mp4` because the\n   library is H.264\u002FAAC; match that or re-encode video explicitly.\n\n7. **Language metadata target differs between ops.** mux tags\n   `-metadata:s:a:\u003Cexisting_count>` (the specific new stream); replace tags\n   `-metadata:s:a` (all audio). That's intentional — mux adds one stream among\n   many; replace swaps the stream set. Don't \"normalize\" them to the same form.\n\n8. **probe \u002F duration failures degrade gracefully, never crash.** `probe_streams`\n   returns `{}` on any ffprobe failure (tracks_audio.py:300-306); `ffprobe_duration`\n   returns 0.0; a 0.0 total just coarsens the progress % (audiomix.py:313-314).\n   So a missing\u002Fgarbage probe won't fail the op — but your progress bar will be\n   flat. Don't read \"0%\" as a hang.\n\n9. **`-nostdin` is mandatory in a pipeline.** Every argv sets `-nostdin` so ffmpeg\n   never blocks reading the controlling terminal, plus `-progress pipe:1 -nostats`\n   so the shared `run` parses machine-readable `out_time`\u002F`progress` lines instead\n   of the human stderr bar. If you hand-run without `-nostdin`, a backgrounded\n   ffmpeg can stall waiting on stdin.\n\n---\n\n## GPU \u002F HF-model notes (audio_saliency only)\n\n- **Model:** PANNs CNN14 AudioSet tagger (`ASSET_NAME=\"panns-cnn14\"`, MIT,\n  ~300 MB, CPU-designed — **no GPU required**). Pinned checkpoint on Zenodo:\n  `Cnn14_mAP=0.431.pth`, sha256 `0dc499e40e9761ef5ea061ffc77697697f277f6a960894903df3ada000e34b31`\n  (audio_saliency.py:79-87). Verified against the asset before use.\n- **Decode contract for the model:** mono, 32 kHz, float (`TARGET_SR=32000`).\n  Feed any other rate and the tag probabilities are garbage — the loader enforces\n  `-ac 1 -ar 32000` (Recipe 3). Don't skip the resample.\n- **Degrade rules (NEVER fabricate, NEVER raise)** (`compute_audio_signals`,\n  audio_saliency.py:405-485):\n  - No \u002F silent audio → tag channels (audioSalience\u002Flaughter\u002Fapplause\u002Fmusic)\n    `present=False`; `loudness` is `present=True` with a single honest `0.0`\n    window (silence is measured, not faked).\n  - Offline AND model missing → tag channels `present=False`; loudness still runs\n    (it needs no model). Online-but-missing falls through (a real backend would\n    download).\n  - Cancelled before tagging → tag channels absent; whatever loudness computed is\n    returned.\n- **Channels** (`AUDIO_CHANNELS`): `audioSalience` (DERIVED = per-window max over\n  the event classes), `laughter` (AudioSet idx 16), `applause` (63), `music` (137),\n  `loudness` (pure RMS, no model — always present). Indices are FROZEN so a model\n  swap can re-map without touching the pure windowing logic.\n- **Windowing:** `sample_windows(duration, win_sec=1.0, hop_sec=1.0)` is the\n  shared grid every Phase-8 module aligns to; values are min-max normalized to\n  0..1 per channel (`loudness_curve` \u002F `peak_windows`). A flat\u002Fsilent track\n  normalizes to all zeros — an honest \"no relative peak\".\n\n---\n\n## Worked example: lay a -10 dB music bed under a TikTok clip at -14 LUFS\n\nGoal: mix `lofi.mp3` under `clip.mp4`, duck it when the speaker talks, export at\nthe TikTok loudness target.\n\n1. Resolve the target loudness from the platform (don't hard-code -14):\n   `resolve_loudness_target(\"tiktok\")` → `-14.0` (raises on a typo like `\"tik-tok\"`).\n2. Build + run the merge graph (Recipe 1) with `platform=\"tiktok\"`:\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i clip.mp4 -i lofi.mp3 \\\n  -filter_complex \"[1:a]volume=-10.0dB[bg];[0:a]asplit=2[fg_key][fg_mix];[bg][fg_key]sidechaincompress=threshold=0.03:ratio=8.0[ducked];[fg_mix][ducked]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[mixed];[mixed]loudnorm=I=-14.0:TP=-1.5:LRA=11.0[out]\" \\\n  -map 0:v -map \"[out]\" -c:v copy -c:a aac -shortest \\\n  -progress pipe:1 -nostats \\\n  clip-mixed-1751299200.mp4\n```\n\n3. Verify: speaker stays dominant (bed dips under speech, swells in gaps),\n   output duration == clip duration (bed trimmed by `-shortest`), and integrated\n   loudness lands near -14 LUFS — re-measure with a loudnorm analysis pass\n   (`ffmpeg -i out.mp4 -af loudnorm=I=-14:print_format=summary -f null -`) rather\n   than trusting the single-pass result (pitfall #4). The output name is\n   `\u003Cstem>-mixed-\u003Cunixtime>.mp4` (`AudioMix._out_path`, audiomix.py:306-309).\n\nTuning knobs if the bed is too aggressive \u002F not aggressive enough: lower\n`bgGainDb` (e.g. `-14`) to make the bed quieter overall; raise `duckThreshold`\nso quiet speech doesn't trigger ducking; raise `duckRatio` for a deeper dip.\n","# audio-extract-mix\n\nExtract \u002F mix \u002F replace \u002F duck \u002F loudness-normalize audio on a clip, the way the\nReframe media_studio sidecar actually does it. Every command below is copied from\nreal source — no invented flags.\n\n## Source modules (read these for ground truth)\n\n- `sidecar\u002Fmedia_studio\u002Ffeatures\u002Faudiomix.py` — `audiomix.merge` (duck→mix→loudnorm)\n  + `audiomix.normalize` (loudnorm only). Owns `build_mix_filter`,\n  `build_mix_argv`, `build_loudnorm_argv`, `PLATFORM_LOUDNESS`,\n  `resolve_loudness_target`.\n- `sidecar\u002Fmedia_studio\u002Ffeatures\u002Ftracks_audio.py` — `tracks.audio.{list,mux,replace,strip}`.\n  Owns `build_mux_argv`, `build_replace_argv`, `build_strip_audio_argv`,\n  `probe_streams`, `original_tracks_from_probe`.\n- `sidecar\u002Fmedia_studio\u002Ffeatures\u002Faudio_saliency.py` — PANNs CNN14 audio tagging +\n  pure RMS `loudness_curve`. Owns `compute_audio_signals`, `peak_windows`,\n  `sample_windows`, the decode argv in `_default_audio_loader`.\n- `sidecar\u002Fmedia_studio\u002Fffmpeg.py` — the shared seam: `ffmpeg_path` \u002F\n  `ffprobe_path` (resolve binary by absolute path), `run` (argv-list Popen,\n  both pipes drained, `-progress` parsing, cooperative cancel),\n  `ffprobe_duration` (drives the progress %).\n\nThe whole module follows one law (audiomix.py docstring, CONTRACTS §4\u002F§6\u002F§7):\n**argv LISTS only, never `shell=True`**; the filter graph and every path is a\nsingle argv element; the ffmpeg binary is resolved by absolute path; both stdout\nand stderr are drained by the shared `run`. Keep that when you hand-run these.\n\n---\n\n## Recipe 1 — Mix a music bed \u002F VO UNDER speech with sidechain ducking + loudnorm\n\nThis is `audiomix.merge`. The entire operation is ONE `-filter_complex` graph\nwith two inputs: `0` = the clip, `1` = the bg bed.\n\nThe graph (`build_mix_filter`, audiomix.py:146-152), with defaults\n`bg_gain_db=-10.0`, `duck_threshold=0.03`, `duck_ratio=8.0`,\n`I=-14:TP=-1.5:LRA=11`:\n\n```\n[1:a]volume=-10.0dB[bg];\n[0:a]asplit=2[fg_key][fg_mix];\n[bg][fg_key]sidechaincompress=threshold=0.03:ratio=8.0[ducked];\n[fg_mix][ducked]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[mixed];\n[mixed]loudnorm=I=-14.0:TP=-1.5:LRA=11.0[out]\n```\n\nWhat each stage does:\n1. `volume=\u003Cbg_gain_db>dB` pre-attenuates the bed (negative dB = quieter).\n2. `asplit=2` forks the foreground: one copy is the **sidechain key**, one is mixed.\n3. `sidechaincompress` ducks the bed keyed off the speaker — bed dips when they\n   talk, swells back in gaps. `threshold` (0..1 linear) = how loud the speaker\n   must get to trigger ducking; `ratio` = gain-reduction strength.\n4. `amix` SUMS foreground + ducked bed. `normalize=0` is **load-bearing**:\n   without it amix divides each input by N, halving the foreground. `dropout_transition=0`\n   stops a gain ramp when one input ends. `duration=first` ties length to the clip.\n5. `loudnorm` does the final EBU R128 leveling to the platform LUFS target.\n\nFull argv (`build_mix_argv`, audiomix.py:183-207):\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i clip.mp4 \\\n  -i bed.mp3 \\\n  -filter_complex \"[1:a]volume=-10.0dB[bg];[0:a]asplit=2[fg_key][fg_mix];[bg][fg_key]sidechaincompress=threshold=0.03:ratio=8.0[ducked];[fg_mix][ducked]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[mixed];[mixed]loudnorm=I=-14.0:TP=-1.5:LRA=11.0[out]\" \\\n  -map 0:v -map \"[out]\" \\\n  -c:v copy -c:a aac \\\n  -shortest \\\n  -progress pipe:1 -nostats \\\n  out.mp4\n```\n\nKey choices: **video is stream-copied** (`-map 0:v -c:v copy`) — only audio is\nrebuilt and re-encoded to AAC. `-shortest` + `duration=first` trims a longer bed\nto the clip. `ffmpeg` here means the absolute path from `ffmpeg.ffmpeg_path(settings)`.\n\nWire surface: `audiomix.merge({videoId|path, bgPath, bgGainDb?, duckThreshold?,\nduckRatio?, loudnessTarget?, loudnessTp?, loudnessLra?, platform?}) -> {jobId} -> {path}`.\n\n---\n\n## Recipe 2 — Loudness-normalize an export (no bed)\n\nThis is `audiomix.normalize` \u002F `build_loudnorm_argv` (audiomix.py:225-247). Uses\n`-af` (single audio stream), not `-filter_complex`:\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i in.mp4 \\\n  -map 0:v? -map 0:a \\\n  -c:v copy -c:a aac \\\n  -af \"loudnorm=I=-14.0:TP=-1.5:LRA=11.0\" \\\n  -progress pipe:1 -nostats \\\n  out.mp4\n```\n\nNote `-map 0:v?` (the `?` makes video optional — works on audio-only inputs too).\nWire: `audiomix.normalize({videoId|path, loudnessTarget?, loudnessTp?,\nloudnessLra?, platform?}) -> {jobId} -> {path}`.\n\n### Per-platform LUFS targets (`PLATFORM_LOUDNESS`, audiomix.py:67-80)\n\nPass `platform` instead of hard-coding the number; an explicit `loudnessTarget`\nstill overrides it. `resolve_loudness_target` is **fail-loud** — an unknown\nplatform raises `INVALID_PARAMS`, never a silent fallback (so a typo can't ship\naudio at the wrong loudness).\n\n| platform | LUFS (I) |\n|---|---|\n| tiktok \u002F reels \u002F shorts \u002F instagram \u002F facebook \u002F youtube \u002F x \u002F twitter \u002F spotify | **-14.0** |\n| broadcast \u002F ebu | **-23.0** (EBU R128) |\n| atsc | **-24.0** (ATSC A\u002F85) |\n\n`TP` defaults to -1.5 dBTP, `LRA` to 11 LU regardless of platform.\n\n---\n\n## Recipe 3 — Extract \u002F decode audio to raw samples\n\nThere is no `extract.wav` wire method; extraction lives inside\n`audio_saliency._default_audio_loader` (audio_saliency.py:343-360), which decodes\nto **mono float32 @ 32 kHz** (the rate PANNs CNN14 was trained on, `TARGET_SR`):\n\n```bash\nffmpeg -hide_banner -nostdin \\\n  -i in.mp4 \\\n  -ac 1 -ar 32000 -f f32le -\n```\n\nstdout is read straight into numpy: `np.frombuffer(raw, dtype=np.float32)`. To\nadapt for a real WAV file, swap `-f f32le -` for an output path (e.g. `-vn\nout.wav`) and pick your `-ar`\u002F`-ac`. Keep `-vn` to drop video when extracting.\n\n---\n\n## Recipe 4 — Mux \u002F replace \u002F strip an audio track (preserve everything else)\n\nThese keep ALL other streams under stream copy — nothing re-encoded, nothing\nsilently dropped (tracks_audio.py docstring, A2\u002FA6 lesson).\n\n**Mux** a new audio stream (`build_mux_argv`, tracks_audio.py:184-203):\n`-map 0` keeps every source stream (video + all existing audio + all subtitles),\n`-map 1:a` appends the new audio, `-c copy` re-encodes nothing. Language is tagged\non the NEW stream's audio index `existing_audio_count`:\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i in.mp4 -i dub.aac \\\n  -map 0 -map 1:a -c copy \\\n  -metadata:s:a:1 language=es \\\n  -progress pipe:1 -nostats \\\n  out.mp4\n```\n\n**Replace** stream `a:\u003Cn>` (`build_replace_argv`, tracks_audio.py:223-244):\n`-map 0` then NEGATIVE-map the one stream out, then append the replacement:\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i in.mp4 -i new.aac \\\n  -map 0 -map -0:a:1 -map 1:a -c copy \\\n  -metadata:s:a language=es \\\n  -progress pipe:1 -nostats \\\n  out.mp4\n```\n\n**Strip** stream `a:\u003Cn>` (`build_strip_audio_argv`, tracks_audio.py:261-278):\njust the negative map, copy the rest:\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i in.mp4 \\\n  -map 0 -map -0:a:1 -c copy \\\n  -progress pipe:1 -nostats \\\n  out.mp4\n```\n\nWire surface (names FROZEN by CONTRACTS A2):\n- `tracks.audio.list({videoId}) -> {audioTracks:[AudioTrack]}`\n- `tracks.audio.mux({videoId, path, lang, name, kind}) -> {audioTrack}`\n- `tracks.audio.replace({videoId, audioTrackId, path}) -> {audioTrack}`\n- `tracks.audio.strip({videoId, audioTrackId}) -> {path}`\n\n`AudioTrack {id, lang, name, kind:\"original\"|\"dub\", voice?, path}`.\n\n---\n\n## Pitfalls that actually bite\n\n1. **`amix` auto-attenuates — you MUST pass `normalize=0`.** ffmpeg's `amix`\n   divides each input by the input count, so a 2-input mix halves your\n   foreground. The graph sets `normalize=0` precisely because the bed is already\n   ducked and loudnorm does final leveling (audiomix.py:142-144). Drop it and the\n   speaker goes quiet.\n\n2. **Stream-index = list-order coupling.** `tracks.audio.replace`\u002F`strip` derive\n   the container `a:\u003Cn>` index from the track's POSITION in `Project.audioTracks`\n   (`audio_track_index`, tracks_audio.py:136-141). Originals are seeded in ffprobe\n   stream order and dubs appended as muxed, so order MUST mirror the freshest\n   derivative. Reorder the list out of band and you'll negative-map the wrong\n   stream. The seed only runs once (skips if any `kind==\"original\"` row exists,\n   tracks_audio.py:378).\n\n3. **`-shortest` alone is not enough for a music bed.** Length is tied to the clip\n   by BOTH `-shortest` AND `duration=first` inside `amix`. A bed shorter than the\n   clip won't loop — it just ends (`dropout_transition=0` prevents a gain bump at\n   that point). If you want a looping bed, add `-stream_loop -1` before the bed\n   `-i`, which is NOT in the stock argv.\n\n4. **loudnorm here is SINGLE-PASS (dynamic).** `build_loudnorm_argv` runs one-pass\n   `loudnorm` — it adapts in real time and can drift \u002F pump on material with wide\n   dynamics, and won't hit the integrated target as precisely as two-pass. For a\n   precise master you'd run loudnorm once with `print_format=json`, capture\n   `measured_I\u002FTP\u002FLRA\u002Fthresh\u002Foffset`, then feed them back (`measured_I=…:linear=true`).\n   The module deliberately keeps one pass for speed in a job pipeline. Know the\n   tradeoff before claiming \"broadcast-exact\".\n\n5. **Negative map order matters.** In replace, `-map 0` must come BEFORE\n   `-map -0:a:1` before `-map 1:a`. ffmpeg applies maps in sequence; reordering can\n   leave the stream you meant to drop, or fail to append. Copy the exact order.\n\n6. **`-c:v copy` requires a compatible container.** The mix\u002Fnormalize paths copy\n   video and write `.mp4`. Copying e.g. VP9\u002FWebM video into `.mp4` will fail —\n   stream copy can't transcode. The source always outputs `.mp4` because the\n   library is H.264\u002FAAC; match that or re-encode video explicitly.\n\n7. **Language metadata target differs between ops.** mux tags\n   `-metadata:s:a:\u003Cexisting_count>` (the specific new stream); replace tags\n   `-metadata:s:a` (all audio). That's intentional — mux adds one stream among\n   many; replace swaps the stream set. Don't \"normalize\" them to the same form.\n\n8. **probe \u002F duration failures degrade gracefully, never crash.** `probe_streams`\n   returns `{}` on any ffprobe failure (tracks_audio.py:300-306); `ffprobe_duration`\n   returns 0.0; a 0.0 total just coarsens the progress % (audiomix.py:313-314).\n   So a missing\u002Fgarbage probe won't fail the op — but your progress bar will be\n   flat. Don't read \"0%\" as a hang.\n\n9. **`-nostdin` is mandatory in a pipeline.** Every argv sets `-nostdin` so ffmpeg\n   never blocks reading the controlling terminal, plus `-progress pipe:1 -nostats`\n   so the shared `run` parses machine-readable `out_time`\u002F`progress` lines instead\n   of the human stderr bar. If you hand-run without `-nostdin`, a backgrounded\n   ffmpeg can stall waiting on stdin.\n\n---\n\n## GPU \u002F HF-model notes (audio_saliency only)\n\n- **Model:** PANNs CNN14 AudioSet tagger (`ASSET_NAME=\"panns-cnn14\"`, MIT,\n  ~300 MB, CPU-designed — **no GPU required**). Pinned checkpoint on Zenodo:\n  `Cnn14_mAP=0.431.pth`, sha256 `0dc499e40e9761ef5ea061ffc77697697f277f6a960894903df3ada000e34b31`\n  (audio_saliency.py:79-87). Verified against the asset before use.\n- **Decode contract for the model:** mono, 32 kHz, float (`TARGET_SR=32000`).\n  Feed any other rate and the tag probabilities are garbage — the loader enforces\n  `-ac 1 -ar 32000` (Recipe 3). Don't skip the resample.\n- **Degrade rules (NEVER fabricate, NEVER raise)** (`compute_audio_signals`,\n  audio_saliency.py:405-485):\n  - No \u002F silent audio → tag channels (audioSalience\u002Flaughter\u002Fapplause\u002Fmusic)\n    `present=False`; `loudness` is `present=True` with a single honest `0.0`\n    window (silence is measured, not faked).\n  - Offline AND model missing → tag channels `present=False`; loudness still runs\n    (it needs no model). Online-but-missing falls through (a real backend would\n    download).\n  - Cancelled before tagging → tag channels absent; whatever loudness computed is\n    returned.\n- **Channels** (`AUDIO_CHANNELS`): `audioSalience` (DERIVED = per-window max over\n  the event classes), `laughter` (AudioSet idx 16), `applause` (63), `music` (137),\n  `loudness` (pure RMS, no model — always present). Indices are FROZEN so a model\n  swap can re-map without touching the pure windowing logic.\n- **Windowing:** `sample_windows(duration, win_sec=1.0, hop_sec=1.0)` is the\n  shared grid every Phase-8 module aligns to; values are min-max normalized to\n  0..1 per channel (`loudness_curve` \u002F `peak_windows`). A flat\u002Fsilent track\n  normalizes to all zeros — an honest \"no relative peak\".\n\n---\n\n## Worked example: lay a -10 dB music bed under a TikTok clip at -14 LUFS\n\nGoal: mix `lofi.mp3` under `clip.mp4`, duck it when the speaker talks, export at\nthe TikTok loudness target.\n\n1. Resolve the target loudness from the platform (don't hard-code -14):\n   `resolve_loudness_target(\"tiktok\")` → `-14.0` (raises on a typo like `\"tik-tok\"`).\n2. Build + run the merge graph (Recipe 1) with `platform=\"tiktok\"`:\n\n```bash\nffmpeg -hide_banner -nostdin -y \\\n  -i clip.mp4 -i lofi.mp3 \\\n  -filter_complex \"[1:a]volume=-10.0dB[bg];[0:a]asplit=2[fg_key][fg_mix];[bg][fg_key]sidechaincompress=threshold=0.03:ratio=8.0[ducked];[fg_mix][ducked]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[mixed];[mixed]loudnorm=I=-14.0:TP=-1.5:LRA=11.0[out]\" \\\n  -map 0:v -map \"[out]\" -c:v copy -c:a aac -shortest \\\n  -progress pipe:1 -nostats \\\n  clip-mixed-1751299200.mp4\n```\n\n3. Verify: speaker stays dominant (bed dips under speech, swells in gaps),\n   output duration == clip duration (bed trimmed by `-shortest`), and integrated\n   loudness lands near -14 LUFS — re-measure with a loudnorm analysis pass\n   (`ffmpeg -i out.mp4 -af loudnorm=I=-14:print_format=summary -f null -`) rather\n   than trusting the single-pass result (pitfall #4). The output name is\n   `\u003Cstem>-mixed-\u003Cunixtime>.mp4` (`AudioMix._out_path`, audiomix.py:306-309).\n\nTuning knobs if the bed is too aggressive \u002F not aggressive enough: lower\n`bgGainDb` (e.g. `-14`) to make the bed quieter overall; raise `duckThreshold`\nso quiet speech doesn't trigger ducking; raise `duckRatio` for a deeper dip.\n",{"name":5,"description":7},"main","a298c929b6cbd662e1fce54302ce520d5ceea1a5",".agents\u002Fskills\u002Faudio-extract-mix","https:\u002F\u002Fgithub.com\u002FPrekzursil\u002Fagent-skills-toolchain","https:\u002F\u002Fgithub.com\u002FPrekzursil","2026-11-02 14:30:57",{"source":8,"skillName":5,"commands":56,"prompt":66,"zipAvailable":67},[57,60,63],{"tool":58,"command":59},"npx","npx skills add Prekzursil\u002Fagent-skills-toolchain --skill audio-extract-mix",{"tool":61,"command":62},"bunx","bunx skills add Prekzursil\u002Fagent-skills-toolchain --skill audio-extract-mix",{"tool":64,"command":65},"pnpm","pnpm dlx skills add Prekzursil\u002Fagent-skills-toolchain --skill audio-extract-mix","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FPrekzursil\u002Fagent-skills-toolchain\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Faudio-extract-mix\u002FSKILL.md",true,[],[70,92,120,147,160,176],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":44},"01M6DF7D7478R55P46REYH4QAC","clarify-requirements","Resolve genuine pre-execution ambiguity by scanning repo context, generating 1-6 grounded options, and asking 1-3 focused questions via AskUserQuestion. NOT for mid-task use (injection risk); NOT when the goal is already unambiguous; use to disambiguate vague prompts before any file edits.","https:\u002F\u002Fgithub.com\u002FPrekzursil\u002Fagent-skills-toolchain\u002Fblob\u002Fmain\u002Ftools\u002Fworkspace-hooks\u002Fskills\u002Fclarify-requirements\u002FSKILL.md",[],[77,78,79,80,81,82,83,84,85,86,87,88,89,90,91],"clarify requirements","clarify","requirements","risk","options","task","prompts","goal","scanning","use","context","repo","injection","execution","file",{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":101,"publishedAt":44},"01M6DF79CA4BHJS66J8EZDBPWJ","openmm-md","Run FREE, open-source, Windows-native GPU molecular dynamics via the openmm-md MCP (OpenMM + CUDA on the local NVIDIA GPU). Use for protein \u002F protein-ligand MD when you want a free stack or are on Windows without a Schrodinger license. Covers the full workflow (prepare, solvate, minimize, equilibrate, production, analyze, mmgbsa) AND an honest decision guide vs Schrodinger Desmond, including how to run Desmond legitimately on Linux or a cloud GPU with a real license. This is a deliberately LESSER free alternative and does NOT replace the schrodinger MCP tools. Do NOT use it to pick a free tool when a validated FEP+, WaterMap, IFD-MD, or Prime MM-GBSA result is actually required.","https:\u002F\u002Fgithub.com\u002FPrekzursil\u002Fagent-skills-toolchain\u002Fblob\u002Fmain\u002Ftools\u002Fmcp\u002Fopenmm-md-mcp\u002Fskill\u002Fopenmm-md\u002FSKILL.md",[98],{"categoryNo":99,"categoryName":100,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[102,103,104,105,106,107,108,109,110,111,112,113,114,115,86,116,117,118,35,119],"openmm md","how","decision","pick","linux","analyze","tool","stack","open","NVIDIA","gpu","license","workflow","windows","free","molecular dynamics","local","MCP",{"skillNo":121,"name":122,"nameZh":6,"description":123,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":124,"categories":125,"keywords":132,"publishedAt":44},"01M6DF76C1MG85VEWP8VZCBNMN","visual-review","Take screenshots of web pages and UI using Playwright for visual review and iteration","https:\u002F\u002Fgithub.com\u002FPrekzursil\u002Fagent-skills-toolchain\u002Fblob\u002Fmain\u002Ftools\u002Feditor\u002Fmetaswarm\u002Fskills\u002Fvisual-review\u002FSKILL.md",[126,129],{"categoryNo":127,"categoryName":128,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000003","演示文稿",{"categoryNo":130,"categoryName":131,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",[133,134,135,136,137,138,139,140,141,142,103,143,144,145,146],"review","visual","visual review","pages","web","false","iteration","take","check","slides","ui","screenshot","playwright","screenshots",{"skillNo":148,"name":149,"nameZh":6,"description":150,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":151,"categories":152,"keywords":153,"publishedAt":44},"01M6DF73AQVCBZKEN0YXEX9FXP","status","Diagnostic status report — shows metaswarm installation state, project setup, and potential issues","https:\u002F\u002Fgithub.com\u002FPrekzursil\u002Fagent-skills-toolchain\u002Fblob\u002Fmain\u002Ftools\u002Feditor\u002Fmetaswarm\u002Fskills\u002Fstatus\u002FSKILL.md",[],[149,154,155,31,156,157,158,159],"setup","report","installation","project setup","issues","state",{"skillNo":161,"name":162,"nameZh":6,"description":163,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":164,"categories":165,"keywords":167,"publishedAt":44},"01M6DF6X6C2XB0P6GX76P7TTYV","start","Use when starting work on any task, when the user mentions metaswarm, or when the user wants to begin tracked development work","https:\u002F\u002Fgithub.com\u002FPrekzursil\u002Fagent-skills-toolchain\u002Fblob\u002Fmain\u002Ftools\u002Feditor\u002Fmetaswarm\u002Fskills\u002Fstart\u002FSKILL.md",[166],{"categoryNo":99,"categoryName":100,"taxonomyType":21,"taxonomyTypeDesc":22},[162,168,82,169,170,171,86,172,173,174,175],"start issue","issue","ready","work on issue","user","work","work on","development",{"skillNo":177,"name":154,"nameZh":6,"description":178,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":179,"categories":180,"keywords":181,"publishedAt":44},"01M6DF6QMJ9AJKFKHHKRT005PQ","Interactive project setup — detects your project, configures metaswarm, writes project-local files","https:\u002F\u002Fgithub.com\u002FPrekzursil\u002Fagent-skills-toolchain\u002Fblob\u002Fmain\u002Ftools\u002Feditor\u002Fmetaswarm\u002Fskills\u002Fsetup\u002FSKILL.md",[],[154,31,118,182,157,183],"files","interactive"]