Silence Detector

Overview

Detects the initial silence segment of a recording by analyzing a pre-computed energy series. It finds the single transition point where low-energy silence gives way to higher-energy content (someone starts talking, music begins, the screen-share goes live).

The whole design rests on one observation: the start of many recordings is predictably quiet. Lectures open on a title slide, webinars wait for attendees to join, screencasts begin with mic and screen setup. That quiet lead-in has measurably lower energy than the content that follows, so a cheap threshold test is enough to find where it ends — no voice-activity model or full audio-decode pass required.

When to Use

• Finding initial silence in recordings. The opening seconds are assumed silent and used as the baseline, so detection is most reliable here. Trigger keywords: initial silence, pre-roll, trim silence, title card, setup period, dead air, leading silence, silence detection, energy threshold.
• Trimming pre-roll silence before content. Useful for auto-generating a start offset so playback or transcription can skip dead air.
• Identifying setup/title-card periods. A title slide or "waiting room" screen produces a long, flat, low-energy run that this skill isolates as a single segment.

Reach for this skill when the cost of a full voice-activity-detection (VAD) pipeline is not justified and you only need the first silence→content boundary.

When NOT to use

• No energy data available. This skill consumes the JSON emitted by the energy-calculator skill; it never decodes audio itself. Without that input there is nothing to analyze.
• Silence in the middle or end of a recording. The algorithm scans for the first rise above the threshold and then stops. It models exactly one leading silence, so any later gaps are invisible by design. For interior pauses, use a pause-detector that scans the full series.
• The opening is not distinctly quieter than the rest. The baseline is the mean energy of the opening window, assuming it is silent. If the recording opens on loud content, the baseline is already high and the threshold becomes meaningless — you will get a near-zero or false boundary.
• Real-time / streaming detection. Detection needs the complete energy series plus a baseline window computed up front. A live stream would require an online algorithm with a rolling baseline, which this skill does not implement.

Prerequisites

• Python 3.12+ — the implementation uses built-in generic types (list[float], tuple[int, ...]) and numpy.typing annotations.
• numpy 1.26.0 — provides the vectorized mean, convolution (smoothing), and flatnonzero crossing search. These run in C, so even long recordings analyze near-instantly.
• pandas 2.1.0 — listed for environment parity with the rest of the skill toolchain; the core detection path relies only on numpy.
• Input file from energy-calculator — you must run energy-calculator first to produce the energies + total_seconds JSON this skill requires.

Pin these versions when reproducibility matters. If you upgrade numpy, re-run the verification checklist, since np.convolve edge behavior and dtype promotion are the parts most sensitive to version changes.

Procedure

Step 1 — Ensure prerequisites are met

python --version    # Must be 3.12+
python -c "import numpy; print(numpy.__version__)"    # Must be 1.26.0
python -c "import pandas; print(pandas.__version__)"  # Must be 2.1.0

If any dependency is missing or mismatched, install the pinned versions:

pip install numpy==1.26.0 pandas==2.1.0

Step 2 — Confirm the input energy JSON exists

The input file must be a JSON object with a non-empty energies array and a numeric total_seconds field, as produced by energy-calculator:

{
  "energies": [0.001, 0.002, 0.001, ...],
  "total_seconds": 3600
}

Step 3 — Run the silence detector

python scripts/detect_silence.py `
    --energies /path/to/energies.json `
    --output /path/to/silence.json

Windows note: On PowerShell, use backtick (`) for line continuation instead of backslash (\). On bash/zsh, use backslash (\).

Step 4 — Inspect the output

The script writes a JSON result to the --output path:

{
  "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
  },
  "analysis": {
    "initial_avg": 0.012,
    "threshold": 0.018
  }
}

segments is empty (and total_segments/total_duration_seconds are 0) when no clear transition is found — for example, when the whole recording is quiet or when it opens loud. The analysis block reports the computed baseline and threshold so you can sanity-check why a boundary was or was not detected.

Parameters

How the algorithm works

1. Load and validate the energy data. The loader rejects non-objects, empty energies arrays, non-numeric total_seconds, and non-finite values (NaN/inf) up front with a clear SystemExit message.
2. Compute the baseline from the first N seconds. The mean of the first initial_window samples stands in for "what silence looks like" in this particular recording, which makes the threshold adapt to each file's noise floor instead of a hard-coded constant.
3. Smooth with a moving average. A single loud spike (a cough, a click) should not end the silence. Averaging over smoothing_window samples suppresses transient blips so only a sustained rise crosses the threshold.
4. Find the first crossing. The end of silence is the first smoothed sample that exceeds baseline × threshold_multiplier. Because we want only the leading silence, the scan stops at that first crossing.

When to load scripts/detect_silence.py

• Read the script when you need to understand the exact detection logic, modify the algorithm, or debug unexpected output.
• Do not modify the script unless you have a specific tuning requirement; the defaults are calibrated for typical lecture/webinar/screencast recordings.

Examples

Detect initial silence with the defaults:

python scripts/detect_silence.py `
    --energies energies.json `
    --threshold-multiplier 1.5 `
    --output silence.json
# -> Initial silence detected: 120s (2.00 min); results saved to silence.json

Be more conservative (require a larger jump before declaring content) for a recording with a noisy title card:

python scripts/detect_silence.py `
    --energies energies.json `
    --threshold-multiplier 2.5 `
    --initial-window 90 `
    --smoothing-window 45 `
    --output silence.json

Parameter tuning guide

Pitfalls

• No energy data — skill cannot run. This skill never decodes audio. It consumes the JSON emitted by energy-calculator. Without that input there is nothing to analyze. Always run energy-calculator first.
• Recording opens loud — false or near-zero boundary. The baseline is computed from the opening window assuming it is silent. If the recording opens on loud content, the baseline is already high and the threshold becomes meaningless. You will get segments: [] with total_segments: 0.
• Interior silence is invisible. The algorithm scans for the first rise above the threshold and then stops. It models exactly one leading silence. Any later gaps are invisible by design. Use a pause-detector for interior pauses.
• Single transient ends silence too early. A cough, click, or door slam in the opening seconds can cross the threshold if smoothing is insufficient. Raise --smoothing-window to suppress brief transients.
• Malformed input causes SystemExit, not a traceback. The loader validates structure (object shape, non-empty energies array, numeric total_seconds, finite values) and surfaces a clear error. If you wire this into an automated pipeline, validate or sandbox the paths upstream before they reach the script.
• NaN or inf in energy data is rejected. The script explicitly checks np.isfinite on all samples. If energy-calculator emits non-finite values, fix the upstream calculation.
• numpy version sensitivity. np.convolve edge behavior and dtype promotion can change across numpy versions. Re-run the verification checklist after any numpy upgrade.
• PowerShell line continuation. On Windows PowerShell, use backtick (`) for multi-line commands, not backslash (\). Using \ will cause a syntax error.

Verification

Run through this checklist after any change to the script, dependencies, or input pipeline:

• Basic run exits 0. Run the script against a sample energies.json and confirm it exits 0:

  python scripts/detect_silence.py `
      --energies energies.json `
      --output silence.json
  echo $LASTEXITCODE  # Should print 0
  

• Output schema matches documentation. Confirm the output JSON has keys method, segments, total_segments, total_duration_seconds, parameters, analysis with correct types.
• Threshold sweep behaves correctly. Sweep --threshold-multiplier (e.g. 1.2, 1.5, 2.5) and check the detected boundary moves later as the multiplier rises:

  python scripts/detect_silence.py `
      --energies energies.json --threshold-multiplier 1.2 --output silence_12.json
  python scripts/detect_silence.py `
      --energies energies.json --threshold-multiplier 2.5 --output silence_25.json
  # silence_25.json total_duration_seconds should be >= silence_12.json
  

• No-quiet-opening returns empty segments. Feed a recording with no quiet opening and confirm segments comes back empty with total_segments: 0.
• Round-trip through segment-combiner. Pass the segments array through segment-combiner to confirm format compatibility (same start/end/duration shape).
• Malformed input produces clean error. Pass a malformed energy file (missing energies, non-numeric entries, invalid JSON) and confirm a clear SystemExit message instead of a traceback:

  echo '{"foo": "bar"}' | Out-File -Encoding utf8 bad.json
  python scripts/detect_silence.py `
      --energies bad.json --output out.json
  # Should print: "Energy file 'bad.json' must contain a non-empty 'energies' array"
  

• Dependency version regression check. Re-run on the pinned numpy/pandas versions after any dependency upgrade to catch convolution or dtype regressions.

Related skills

• energy-calculator — produces the energies + total_seconds JSON this skill requires as input. Run it first.
• segment-combiner — consumes the segments array emitted here (same start/end/duration shape), so the two compose without a translation step.