Wavecap Silence

WaveCap Silence Detection & Chunking Skill

Use this skill to tune how WaveCap detects speech boundaries and groups audio into chunks for transcription.

Configuration Location

Silence/chunking settings are in the whisper: section:

• User config: /Users/thw/Projects/WaveCap/state/config.yaml
• Default config: /Users/thw/Projects/WaveCap/backend/default-config.yaml

Core Parameters

Silence Threshold (amplitude floor for speech detection)

whisper:
  silenceThreshold: 0.015  # RMS amplitude (0.0-1.0)

Symptoms & Fixes:

• Speech cut off at start → Lower threshold (e.g., 0.015 → 0.01)
• False triggers on noise → Raise threshold (e.g., 0.015 → 0.025)

Silence Hold Seconds (wait before cutting)

whisper:
  silenceHoldSeconds: 1.8  # Seconds of silence before flush

Symptoms & Fixes:

• Words cut off at end → Increase (e.g., 1.2 → 1.8)
• Updates feel slow → Decrease (e.g., 1.8 → 1.2)

Silence Lookback Seconds (evaluation window)

whisper:
  silenceLookbackSeconds: 3.0  # Window for silence detection

Active Samples Percentage (VAD sensitivity)

whisper:
  activeSamplesInLookbackPct: 0.10  # 10% of samples must be active

Chunk Length (maximum chunk duration)

whisper:
  chunkLength: 20  # Maximum seconds before forced flush

Minimum Chunk Duration

whisper:
  minChunkDurationSeconds: 12  # Minimum before silence triggers flush

Context Overlap (between chunks)

whisper:
  contextSeconds: 1.5  # Overlap for Whisper context

View Current Settings

grep -E "(silence|chunk|context|active)" /Users/thw/Projects/WaveCap/state/config.yaml

Diagnose Clipping Issues

Check for premature clipping (speech cut at start)

curl -s http://localhost:8000/api/transcriptions/export | \
  jq '[.[] | select(.text | startswith("..."))] | length' | \
  xargs -I{} echo "Transcriptions starting with '...': {}"

Check for late clipping (speech cut at end)

curl -s http://localhost:8000/api/transcriptions/export | \
  jq '[.[] | select(.text | test("[a-z]$"))] | length' | \
  xargs -I{} echo "Transcriptions ending mid-word: {}"

Analyze audio amplitude at boundaries

cd /Users/thw/Projects/WaveCap/backend && source .venv/bin/activate && python3 << 'EOF'
import numpy as np
from pathlib import Path

RECORDINGS = Path("/Users/thw/Projects/WaveCap/state/recordings")

def analyze_boundaries(filepath):
    with open(filepath, 'rb') as f:
        f.read(44)
        data = f.read()
        samples = np.frombuffer(data, dtype=np.int16).astype(np.float32) / 32768.0
        if len(samples) < 1600:
            return None
        first_50ms = np.sqrt(np.mean(samples[:800]**2))
        last_50ms = np.sqrt(np.mean(samples[-800:]**2))
        return first_50ms, last_50ms

print("Boundary analysis (high RMS at start/end = potential clipping):")
print("-" * 70)
files = sorted(RECORDINGS.glob("*.wav"), key=lambda x: x.stat().st_mtime, reverse=True)[:15]
clip_start = clip_end = 0
for f in files:
    result = analyze_boundaries(f)
    if result:
        first, last = result
        issues = []
        if first > 0.06: issues.append("HIGH_START"); clip_start += 1
        if last > 0.06: issues.append("HIGH_END"); clip_end += 1
        status = ", ".join(issues) if issues else "OK"
        print(f"{f.name[-45:]}: start={first:.4f} end={last:.4f} [{status}]")
print("-" * 70)
print(f"Summary: {clip_start} potential start clips, {clip_end} potential end clips")
EOF

Tuning Scenarios

Reduce Clipping (speech being cut off)

whisper:
  silenceThreshold: 0.012        # More sensitive
  silenceHoldSeconds: 2.0        # Wait longer before cutting
  silenceLookbackSeconds: 3.5    # Larger evaluation window
  contextSeconds: 2.0            # More overlap
  activeSamplesInLookbackPct: 0.08  # Keep chunks open easier

Lower Latency (faster updates)

whisper:
  silenceThreshold: 0.025        # Less sensitive
  silenceHoldSeconds: 0.8        # Cut quickly on silence
  silenceLookbackSeconds: 1.5    # Smaller window
  chunkLength: 15                # Shorter max chunks
  minChunkDurationSeconds: 6     # Allow smaller chunks
  contextSeconds: 0.5            # Minimal overlap

Noisy Environment (false triggers)

whisper:
  silenceThreshold: 0.035        # Ignore low-level noise
  silenceHoldSeconds: 1.0        # Quick silence detection
  activeSamplesInLookbackPct: 0.20  # Require 20% active

Quiet Environment (soft speakers)

whisper:
  silenceThreshold: 0.008        # Very sensitive
  silenceHoldSeconds: 2.0        # Patient with pauses
  activeSamplesInLookbackPct: 0.05  # 5% is enough

Apply Changes

launchctl stop com.wavecap.server && sleep 2 && launchctl start com.wavecap.server

Latency vs Accuracy Trade-offs

Tips

• Changes take effect on service restart
• Test with live audio after changes
• Monitor clipping rates over 50+ transcriptions before final tuning
• silenceThreshold and silenceHoldSeconds have the biggest impact
• Higher contextSeconds helps but adds processing overhead