silence-detector
Detect initial silence segments in audio/video using energy-based analysis. Use when you need to find low-energy periods at the start of recordings (title slides, setup time, pre-roll silence).
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- silence-detector
- description
- Detect initial silence segments in audio/video using energy-based analysis. Use when you need to find low-energy periods at the start of recordings (title slides, setup time, pre-roll silence).
02 资源文件 2
- 参考文档references/verify-opening-boundary.md18.5 KB
- 脚本scripts/detect_silence.py3.2 KB
03 SKILL.md 正文
Silence Detector
Detects initial silence segments by analyzing pre-computed energy data. Finds the transition point from low-energy silence to higher-energy content.
Use Cases
- Finding initial silence in recordings
- Detecting pre-roll silence before content
- Identifying setup/title card periods
Usage
python3 /root/.claude/skills/silence-detector/scripts/detect_silence.py \
--energies /path/to/energies.json \
--output /path/to/silence.json
Parameters
--energies: Path to energy JSON file (from energy-calculator)--output: Path to output JSON file--threshold-multiplier: Energy threshold multiplier (default: 1.5)--initial-window: Seconds for baseline calculation (default: 60)--smoothing-window: Moving average window (default: 30)
Output Format
{
"method": "energy_threshold",
"segments": [
{"start": 0, "end": 120, "duration": 120}
],
"total_segments": 1,
"total_duration_seconds": 120,
"parameters": {
"threshold_multiplier": 1.5,
"initial_window": 60,
"smoothing_window": 30
}
}
How It Works
- Load pre-computed energy data
- Calculate baseline from first N seconds (likely silent)
- Apply smoothing with moving average
- Find where smoothed energy exceeds baseline x multiplier
Dependencies
- Python 3.11+
- numpy
Verify Opening Boundary Before Downstream Use
The detector returns well-formed JSON even when the baseline window was
contaminated by real content, which silently inflates the "opening"
duration. Never pipe opening_duration straight into pause-detector or
video-processor without running the branched procedure in
references/verify-opening-boundary.md.
There are exactly five sanctioned final boundary values (Branches A/B/C/D/E in the L3 file). Any other value — a hand-picked timestamp, an energy inflection, a round number, a visually-chosen frame, or a re-run of the detector with different parameters to restore an earlier value — is a forbidden shortcut. The 20% figure below is a suspicion trigger, not a hard cap; branches may legitimately produce an opening
20% when the retry defuses the suspicion.
Minimum checks after every run (dispatch to L3 on failure, do not assert):
import json
op = json.load(open("silence.json"))["segments"]
en = json.load(open("energies.json"))
total = en["total_seconds"]
opening = op[0]["duration"] if op else 0
ratio_ok = (opening / total) <= 0.20 if total else True
if not ratio_ok:
# DO NOT assert, DO NOT hand-pick, DO NOT re-run with defaults.
# Read references/verify-opening-boundary.md and run its branches.
pass
Branch-ladder is mandatory and non-skippable. Each branch has an exit condition on the three recalibrated checks (check1 = opening fraction, check2′ = threshold vs a lower-tail energy statistic such as the 25th percentile — NOT the overall mean, which gets inflated by loud teaching sections, check3′ = either amplitude step or variance step at the boundary — quiet-to-quiet transitions are distinguished by variance, not amplitude). A branch may commit as the final boundary ONLY when its own exit condition holds on the current check values. In particular:
- Branch B commits as final when EITHER all three recalibrated checks pass on the retry output OR the Branch-B-wins override holds (check1=True AND Branch B's opening is ≥5× shorter than Branch A's). A large shrink under stricter parameters is strong evidence that Branch A's baseline was contaminated; forcing escalation to Branch C in that regime over-trims. If NEITHER clause holds, Branch C is mandatory.
- Branch C's exit is entered only after B fails both exit clauses; Branch E's exit is entered only after Branch C's post-cap re-check still has ≥1 failing check.
- Branch C's default cap when the task gives no numeric hint is
min(30, int(0.05 * total_seconds))— the earliermin(90, 0.20 * total)default was ~3× too generous for teaching videos.
Required pre-write ritual — two lines, both mandatory. Before
writing any value downstream (pause-detector --start-time,
segment-combiner, video-processor), emit in order:
-
Exactly one commitment string:
"Branch A: accepting detector output of N seconds (all recalibrated checks pass)""Branch B: accepting retry output of N seconds (stricter params, recalibrated checks or large-shrink override)""Branch C: applying cap of M seconds = min(task_hint_or_30, int(0.05 * total))""Branch D: nudged boundary to N seconds (check3′ fix)""Branch E fallback: task cap of K seconds, mismatch recorded (B and C both failed)"
-
A consistency assertion naming the committed branch's exit condition with current check values filled in, e.g.:
"Commitment Branch B requires (all recalibrated checks True) OR (check1=True AND large_shrink=True); current: check1=True check2'=False check3'=False large_shrink=True → override clause satisfied."If no clause of the exit condition is satisfied, the commitment is invalid: do not write downstream input, enter the next sanctioned branch, and re-emit both lines.
Any opening value that is not the output of one of the five branches, or whose consistency assertion fails, is forbidden. Narrating frame contents and then choosing a number is not a branch — it is the shortcut that has failed this task multiple times.
Frame sampling is record-only. It is NOT a branch and cannot override Branch B/C/D/E output. If frames disagree with a branch's numeric output, record the disagreement in the report and still use the branch number. Subjective judgments like "lecturer hasn't really started yet" are not grounds to override — the branches target low-energy pre-roll removal, not the pedagogical start of the lecture.
Read references/verify-opening-boundary.md when the detector returns
an opening longer than ~15–20% of total duration, when threshold sits
within ~2× of overall mean energy, when the task description gives
qualitative hints about opening length (e.g. "static title card",
"~30 s intro"), or when downstream output must stay within an expected
removed-duration range. Skip when the task is a short clip (< 60 s) or
when segments is empty.
Parameters Tuning
| Parameter | Lower Value | Higher Value |
|---|---|---|
| threshold_multiplier | More sensitive | More conservative |
| initial_window | Shorter baseline | Longer baseline |
| smoothing_window | Less smoothing | More smoothing |
Notes
- Requires energy data from energy-calculator skill
- Works best when initial period has distinctly lower energy
- Returns empty segments list if no clear transition found
- Output format compatible with segment-combiner
Common Pitfalls
- Mishandling a suspect opening — the branch ladder is mandatory
and non-skippable in both directions. Over the task's history,
five distinct shortcuts have each produced failures: (a)
trust-blindly — pipe the first-run value straight downstream;
(b) reject-and-invent — hand-pick from an energy drop or round
number; (c) visual-override — after Branch B, sample frames and
judge subjectively; (d) stop-at-failing-Branch-B under the old
uncalibrated checks — commit Branch B while check2/check3 is
False with no justification; (e) over-escalate-to-Branch-C —
push a large-shrink Branch B result (≥5× shorter than Branch A)
into Branch C's cap when the override clause should have committed
B. Always run
references/verify-opening-boundary.mdend-to-end and emit both pre-write lines (commitment string + consistency assertion with the specific exit clause named). - Using
overall_meanas the reference for check2. Mean energy is inflated by loud teaching sections, so a legitimate quiet opening boundary auto-fails under the mean-based rule. The recalibrated check2′ compares threshold against a lower-tail statistic (25th percentile of per-second energies, or median). If you see check2 referenced against the mean anywhere, it is the stale definition. - Requiring an amplitude step at the boundary (check3). Pre-roll room tone and the first seconds of quiet speech can be at nearly identical RMS; the distinguishing feature is variance, not amplitude. The recalibrated check3′ passes when EITHER the amplitude-step rule holds OR the post-boundary variance is ≥1.5× the pre-boundary variance.
- Re-running
detect_silence.pywith default parameters after Branch B. This is a reversion, not a branch. The default-parameter output is the value that failed the initial checks; the sanctioned successor to a failed Branch B is Branch C's cap or Branch E's fallback. - Frame sampling treated as an authorizing branch. Frame sampling is a record-only sanity step. It cannot override a numeric branch output, cannot authorize reverting to an earlier detector run, and cannot be used to justify "lecturer hasn't started yet" as a boundary extension.
- Paraphrasing the 20% suspicion trigger into a hard cap. The rule is "if opening/total > 20%, treat as suspect and run the branches," not "the final boundary must be ≤ 20% of total." Branch B may legitimately return >20% when the retry defuses the suspicion.
- Earliest energy drop is almost never the content start. Within a pre-roll (music, title card, intro animation), several sharp energy transitions occur before the lecturer begins. Picking the first inflection by eye typically lands inside the opening.
- Memorizing a Branch C default from an older iteration. The
Branch C default ceiling has been tightened to
min(30, int(0.05 * total))from an earliermin(90, int(0.20 * total)). If a cached worked example cites 90, it has been retracted. - Ignoring task-description hints. Phrases like "static frames with noise", "title card", "short intro" supply the task_hint used in Branch C's cap and Branch E's fallback. Extract them during planning, not after a check fails.
04 同仓库更多 Skills
video-frame-extraction
Extract frames from video files and save them as images using OpenCV
openai-vision
Analyze images and multi-frame sequences using OpenAI GPT vision models
image-ocr
Extract text content from images using Tesseract OCR via Python, including structured field extraction from receipts and forms
video-frame-extraction
Extract frames from video files and save them as images using OpenCV
openai-vision
Analyze images and multi-frame sequences using OpenAI GPT vision models
image-ocr
Extract text content from images using Tesseract OCR via Python, including structured field extraction from receipts and forms