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.