Home / All Skills / Content & Media Creation / cut-silences
English (EN)简体中文 (ZH)日本語 (JA)
Content & Media Creation · nateherkai/hyperframes-student-kit

cut-silences

Agent 1 of the video editing pipeline. Removes silences and dead air from a talking-head recording. Use when asked to cut silences, trim pauses, remove dead air / gaps, or tighten the pacing of a raw video, given a word-level transcript. Produces an edit list (EDL), a re-timed transcript for downstream agents, and optionally the cut video via ffmpeg. Does NOT cut mistakes, repeats, or false starts — that is the cut-mistakes agent.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Author nateherkaiGitHub nateherkai/hyperframes-student-kit ↗Stars 1070License NOASSERTION（仓库根 LICENSE，实为 MIT 文本）Commit 0d30152a82
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The entire pipeline relies on a deterministic algorithm rather than model judgment: it only processes head/tail dead air and inter-word pauses exceeding --gap, without altering a single word.

.claude/skills/cut-silences/scripts/cut-silences.mjs
Pure pause/silence trimmer. Takes any word-level transcript (ElevenLabs Scribe … shape, or { words: [{ text, start, end }] }) and removes silences only:
The same comment explicitly defines boundaries: 'It does NOT cut repeats, false starts, or mistakes — that is Agent 2's job.' Therefore, the output is inherently reproducible, making it ideal as the pipeline's first stage.

Head and tail dead air are trimmed directly according to --head-pad / --tail-pad and merged as two independent deletion ranges.

.claude/skills/cut-silences/scripts/cut-silences.mjs
// head + tail dead air const headEnd = words[0].start - opts.headPad; if (headEnd > 0) deleteRanges.push({ start: 0, end: headEnd, reason: "head trim before first word" });
Default head-pad is 0.22s and tail-pad is 0.34s, sourced from the parameter table in SKILL.md; when no video is provided, the total duration falls back to audio_duration_secs from the transcript or the end timestamp of the last word.

Inter-word pauses are not cut down to 0; instead, a context-dependent 'natural breath' buffer is retained: 0.24s for long pauses, 0.20s for sentence ends, and 0.14s for others.

.claude/skills/cut-silences/scripts/cut-silences.mjs
if (gap < opts.gap) continue; … const sentenceBreak = /[.!?]$/.test(prev.text ?? ""); const keep = gap >= 2 ? 0.24 : sentenceBreak ? 0.2 : 0.14;
Pauses below --gap (default 0.55s) are left completely untouched, serving as a toggle to preserve conversational rhythm; decreasing --gap tightens the cut but increases the risk of over-chopping.

Retained breath intervals are intentionally biased toward the beginning of the following sentence: 55% remains at the end of the previous sentence, and 45% at the start of the next.

.claude/skills/cut-silences/scripts/cut-silences.mjs
// Bias the kept breath slightly toward the end of the previous phrase. const delStart = prev.end + keep * 0.55; const delEnd = next.start - keep * 0.45;
This is an auditory nuance consideration: leaving more padding after the previous sentence's trailing sound prevents clipping the onset of the next sentence.

Deletion ranges are merged first before computing the complement to obtain keep ranges, discarding fragment intervals smaller than 40ms.

.claude/skills/cut-silences/scripts/cut-silences.mjs
if (cursor < duration) keepRanges.push({ start: cursor, end: duration }); const usableKeepRanges = keepRanges.filter((r) => r.end - r.start >= 0.04);
The complement approach makes the EDL serve as both a deletion and retention list; the 40ms floor prevents ffmpeg from generating meaningless micro-segments.

The transcript is re-timed to the edited timeline using the same deletion list, preserving source_start/source_end for cross-referencing with the original footage.

.claude/skills/cut-silences/scripts/cut-silences.mjs
const editedWords = []; for (const word of words) { if (inDeleted(word)) continue; … start: Number((word.start - removedBefore(word.start)).toFixed(3)),
removedBefore(t) accumulates deleted seconds prior to t, equivalent to a linear mapping; downstream beat timestamps and validate-beat-sync.mjs thus require no secondary recalculation.

Rendering uses an ffmpeg trim/atrim + concat filtergraph, written first to *.silence-filter.txt and supplied via -/filter_complex; by default, it calculates without rendering.

.claude/skills/cut-silences/scripts/cut-silences.mjs
lines.push(`[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS[v${i}];`); … const ffArgs = [ "-y", "-i", videoPath, "-/filter_complex", scriptPath, "-map", "[v]", "-map", "[a]", "-c:v", "libx264", "-preset", "medium", "-crf", "18", "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", outputPath, ];
Video and audio are trimmed synchronously using the same interval set to avoid A/V drift; without --apply, it only prints 'hint: re-run with --apply to render the cut video'.

2Core Capabilities

01Cut head/tail dead air and inter-word pauses exceeding the threshold (pure silence, without altering words)
02Retain context-aware 'natural breaths' (three tiers: long pause / sentence end / other) instead of hard zero gaps
03Output an EDL (delete ranges + keep ranges + params + duration) ready for downstream consumption or manual review
04Generate a re-timed transcript for Agent 2 and beat validation, eliminating the need for subsequent timeline realignment
05Provide a human-readable decision summary (including the top 15 largest cut pauses) for easy verification against over-cutting
06Decouple dry-run from rendering: writes EDL, transcript, and summary by default while printing the ffmpeg command; modifies video only with --apply
07Support parametric tuning (--gap / --head-pad / --tail-pad / --output / --out-dir) with provided empirical defaults
08Compatible with multiple word-level transcript formats (ElevenLabs Scribe / generic) and filter non-word events by type

3External Dependencies

KindDependency / Endpoint
cliNode.js（跑 cut-silences.mjs）
cliffmpeg（trim/atrim + concat 重编码，仅 --apply 时执行）
cliffprobe（无 audio_duration_secs 时探源片时长）
apiElevenLabs Scribe（**前置步骤**：由仓库级 scripts/transcribe-elevenlabs.mjs 上传音频取词级时间戳；本次侦察未在本 skill 目录内发现任何调用代码）
cli本地 Whisper / whisper.cpp（文档列出的无 key 替代转录路线）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
  • scripts/: Execute local script or command: node .claude/skills/cut-silences/scripts/cut-silences.mjs <transcript.json>
  • 网络端点: Declared external network access: External endpoint used in prerequisite step (from repo-level helper, not this directory): api.elevenlabs.io/v1/speech-to-text (POST audio to fetch word-level transcript)
  • 本地工作目录: File I/O and artifact output: <stem>.silence-edl.json (keep/delete ranges + params + duration)
Audit Notes: The evaluation target is this skill's own directory (SKILL.md + one 11.8KB mjs file): the only executable code is a purely local Node script that reads word-level transcripts, calculates intervals, and writes EDL/transcripts/summaries/filters, with its only child processes being two fixed binaries, ffprobe and ffmpeg; 0 network calls, 0 credential reads, 0 env accesses, and 0 deletion or destructive operations. Adjacent aspects that must be noted but **do not escalate the tier**: the Prerequisites in SKILL.md point to the repo-level `scripts/transcribe-elevenlabs.mjs` to fetch transcripts, which reads ELEVENLABS_API_KEY and uploads audio to api.elevenlabs.io (outbound data transfer and credit consumption)—this helper is outside this skill directory, and this skill only requires 'any word-level transcript' and explicitly accepts generic `{ words: [...] }` as well as keyless local Whisper workflows, treating transcription as an upstream artifact rather than this skill's responsibility. This is precisely what distinguishes it from the contemporaneous edit-video (🟠), whose SKILL.md includes service calls directly in step 2 of its main workflow along with cost and authorization documentation.

5Second-Pass Verification

  • [ok] 目录文件清单与 Outputs 表对照 — 目录仅 SKILL.md + scripts/cut-silences.mjs；SKILL.md 列出的 5 类产物中 3 类无条件写、filter.txt 与 mp4 受 --video/--apply 门控，与源码 writeFileSync/spawnSync 分支一致。
  • [ok] 网络面反例搜索 — 目录内 0 处 fetch/URL/网络模块导入；SKILL.md 出现的 `node scripts/transcribe-elevenlabs.mjs ...` 是仓库级前置命令，文件名不含 http，且未被本脚本引用。
  • [ok] 凭证面反例搜索 — 0 处 process.env/API_KEY/TOKEN/.env；脚本对 process 的导入仅 argv/exit（`import { argv, exit } from "node:process";`）。
  • [ok] 「只删沉默」是否被代码强制 — 删除区间只由 head/tail pad 与 gap>opts.gap 的停顿生成三处 push 产生，源码无重复词/相似度/语义判断，与文档声明一致，无夸大。
  • [ok] 重定时映射正确性 — start = word.start - removedBefore(word.start)，removedBefore 只累加严格位于其前的删除量，因此不会出现负值或跳变；edited_duration = duration - removedTotal 与被删总量自洽。
  • [ok] 文档参数 vs 脚本 argv — --video/--out-dir/--output/-o/--gap/--head-pad/--tail-pad/--apply 全部在 argv 解析中定位到，未知 --flag 会 die，与 SKILL.md 表格一致。

6Verdict & Scenarios

  • Purely deterministic algorithm with zero model judgment; the initial stage is fully reproducible and regression-testable, yielding identical results regardless of who runs it.
  • Meticulous psychoacoustic handling: preserves 0.24/0.20/0.14s breath pauses by context and shifts padding toward sentence onsets (55%/45%), far more natural than crude zero-gap cuts.
  • Built-in auditability: EDL includes params/removed/removedPct, and decisions.md lists the top 15 excised pauses so humans can quickly check for over-cutting.
  • The re-timed transcript absorbs timeline shifts in the very first stage, so downstream beat sync and delivery validation need no further alignment.
  • Comprehensive tuning knobs and empirical benchmarks (--gap 0.55 cuts ~15-20% pure silence), accompanied by guidance for two corrective directions if cuts are too aggressive.
    • Best for: Best for: initial rough cuts of talking-head long videos with word-level transcripts (automating the removal of 15-20% pure silence), pipelines requiring auditable EDLs, and serving as a deterministic starting point for multi-agent video editing workflows.
    Not for: Not suitable for: transcripts lacking word-level timestamps (paragraph-level or SRT won't work), cutting mistakes or false starts (handled by cut-mistakes), interview footage where all breathing pauses must be preserved, or scenarios expecting the script to decide 'where to cut'—it strictly follows numerical rules.
    Install Agent-Ready
    ① Verified Mirror 2026-09-28
    Option A · Direct DownloadDownload cut-silences.tar.gz
    sha256: 484001b000655549…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 0d30152a82.