insert-silence-beat

name	insert-silence-beat
description	mute precise audio windows in a video or audio file to create deliberate silence beats — the tension-beat / act-break device from CREATOR_GRAMMAR.md §6. Does not change video length or frame content; only zeros the audio within the specified windows. Use when an EDL calls for `audio_beats[].type = "silence-beat"` or when you want to punch in an audio dropout before a reveal.

insert-silence-beat

Purpose

Insert deliberate audio dropouts ("silence beats") at precise timestamps without changing the total duration or video frames. Each beat mutes the audio from at to at + dur seconds. This is the mechanical implementation of the "silence beat" device described in CREATOR_GRAMMAR.md §6:

A deliberate 0.25–0.6s audio dropout used as a tension beat or act break — placed before a reveal or between acts.

If the source is a video file, the video stream passes through untouched; only the audio is modified. If the source is an audio-only file, the output is an audio-only file.

Inputs

• --source (required) — path to the source audio or video file.
• --beats (optional) — a JSON array string of beat specs: [{"at": <seconds>, "dur": <seconds>}, ...]. Either --beats or at least one --beat must be provided.
• --beat (optional, repeatable) — a single beat as at,dur (comma-separated seconds, e.g. 1.0,0.5). Can be repeated for multiple beats.
• --output (required) — output file path. Extension determines container format (.mp4 for video, .mp3/.aac/.m4a for audio).

At least one beat must be provided via --beats or --beat.

Workflow

1. Verify ffmpeg/ffprobe are on PATH and the source file exists.
2. Parse all beat specs from --beats (JSON) and/or --beat (repeatable) arguments.
3. Validate each beat: at ≥ 0, dur > 0, at + dur ≤ source_duration (warn if a beat extends past end).
4. Build an ffmpeg volume filter expression that zeros audio within each beat window: volume=enable='between(t,AT,AT+DUR)':volume=0 Multiple beats are composed with + in the enable expression.
5. If source is video: pass [0:v] through with -c:v copy (no re-encode); apply volume filter to [0:a].
6. If source is audio-only: apply volume filter to [0:a] and re-encode as AAC.
7. Write output file and manifest.json to the output file's parent directory.

Run:

python3 skills/atoms/audio-editing/insert-silence-beat/scripts/insert_silence.py \
  --source /path/to/source.mp4 \
  --beats '[{"at": 2.5, "dur": 0.4}, {"at": 8.1, "dur": 0.3}]' \
  --output /path/to/output.mp4

Or using repeatable --beat flags:

python3 skills/atoms/audio-editing/insert-silence-beat/scripts/insert_silence.py \
  --source /path/to/source.mp4 \
  --beat 2.5,0.4 \
  --beat 8.1,0.3 \
  --output /path/to/output.mp4

Output

• Output file at the specified path with silence beats applied.
• manifest.json in the same directory as the output, containing: skill_name, run_id, source, beats_applied (list of {at, dur} dicts), source_duration_seconds, output_file, status, warnings, errors.

Note: video duration and frame content are unchanged. Only the audio within the specified windows is zeroed.

Quality Checks

• Output file exists and is non-zero size.
• ffprobe reports the same duration as the source (±0.1s).
• For video sources: ffprobe reports the same video codec and resolution as the source.
• Audio within each beat window is silent or near-silent (RMS < −60 dBFS).
• Audio outside beat windows is unchanged (no clipping or distortion artifacts).
• manifest.json exists with status: "pass" and all beats listed under beats_applied.

Failure Modes

• Source not found — script exits with a clear error before processing.
• No beats provided — script exits with a usage error.
• Beat extends past source duration — the beat is clamped to the source end and a warning is written to manifest.json.
• Beat with dur ≤ 0 — that beat is skipped and recorded in manifest.json errors.
• ffmpeg not installed — install via brew install ffmpeg.
• Source has no audio stream — script exits with an error; there is nothing to silence.
• Overlapping beats — overlapping windows merge correctly in the enable expression (the between() addition is OR-semantics); no error is raised, but a warning is added.