I created a Python script with Claude Code to automatically split audio files at silent intervals

#!/usr/bin/env python3
"""CLI tool to segment audio files at silent intervals.

Dependencies: ffmpeg / ffprobe (must be in PATH)
"""

import argparse
import csv
import re
import subprocess
from dataclasses import dataclass
from pathlib import Path

SILENCE_RE = re.compile(r"silence_end:\s*([\d.]+)\s*\|\s*silence_duration:\s*([\d.]+)")

@dataclass(frozen=True)
class Silence:
    """Detected silence interval."""
    start: float
    end: float
    duration: float

@dataclass(frozen=True)
class Content:
    """Content interval between Silence and Silence."""
    start: float
    end: float

@dataclass(frozen=True)
class Segment:
    """Segment to be extracted (with padding applied)."""
    index: int
    start: float
    end: float

def probe_duration(path: Path) -> float:
    """Returns the duration of an audio file in seconds using ffprobe."""
    result = subprocess.run(
        [
            "ffprobe",
            "-v", "error",
            "-show_entries", "format=duration",
            "-of", "default=noprint_wrappers=1:nokey=1",
            str(path),
        ],
        text=True,
        capture_output=True,
        check=True,
    )
    return float(result.stdout.strip())

def detect_silences(path: Path, noise_db: float, min_silence: float) -> list[Silence]:
    """Detects and returns silent intervals using ffmpeg silencedetect filter."""
    result = subprocess.run(
        [
            "ffmpeg",
            "-hide_banner",
            "-nostats",
            "-i", str(path),
            "-af", f"silencedetect=noise={noise_db}dB:d={min_silence}",
            "-f", "null", "-",
        ],
        text=True,
        capture_output=True,
        check=True,
    )
    # ffmpeg outputs filter logs to stderr, not stdout
    silences: list[Silence] = []
    for line in result.stderr.splitlines():
        m = SILENCE_RE.search(line)
        if m:
            end = float(m.group(1))
            duration = float(m.group(2))
            # Don't use silence_start line, calculate start from end - duration
            silences.append(Silence(start=end - duration, end=end, duration=duration))
    return silences

def merge_nearby(silences: list[Silence], merge_gap: float) -> list[Silence]:
    """Merges consecutive silent intervals that are within merge_gap seconds."""
    merged: list[Silence] = []
    for si in silences:
        if merged and si.start - merged[-1].end <= merge_gap:
            prev = merged[-1]
            new_end = max(prev.end, si.end)
            merged[-1] = Silence(start=prev.start, end=new_end, duration=new_end - prev.start)
        else:
            merged.append(si)
    return merged

def build_timeline(silences: list[Silence], total: float) -> list[Silence | Content]:
    """Builds a timeline with alternating Silence and Content from Silence list."""
    timeline: list[Silence | Content] = []
    pos = 0.0
    for si in silences:
        if si.start > pos:
            timeline.append(Content(start=pos, end=si.start))
        timeline.append(si)
        pos = si.end
    # Ignore tiny intervals at the end (detection error where ffmpeg's silence_end is slightly before total)
    if total - pos > 0.1:
        timeline.append(Content(start=pos, end=total))
    return timeline

def select_boundaries(timeline: list[Silence | Content], target_count: int | None, total: float) -> list[Silence]:
    """Selects boundary Silences from timeline. Excludes Silences at beginning and end."""
    # Use same 0.1s threshold as build_timeline uses for ignoring tiny intervals
    eps = 0.1
    inner = [b for b in timeline if isinstance(b, Silence) and b.start > eps and total - b.end > eps]
    if target_count is None:
        # When target_count is not specified, use all inner Silences as boundaries
        return inner
    needed = target_count - 1
    if needed < 0:
        raise ValueError(f"target-count must be >= 1, got {target_count}")
    if len(inner) < needed:
        raise ValueError(
            f"need {needed} boundaries for {target_count} segments, "
            f"but only {len(inner)} silences detected"
        )
    # Longer silences are more likely to be clear breaks, so select by duration in descending order
    selected = sorted(inner, key=lambda si: si.duration, reverse=True)[:needed]
    return sorted(selected, key=lambda si: si.start)

def build_segments(timeline: list[Silence | Content], boundaries: list[Silence], total: float, padding: float) -> list[Segment]:
    """Generates Segments from timeline and boundary Silences, adding padding seconds before and after."""
    first, last = timeline[0], timeline[-1]
    content_start = first.end if isinstance(first, Silence) else first.start
    content_end = last.start if isinstance(last, Silence) else last.end
    pairs = list(zip(
        [content_start] + [b.end for b in boundaries],
        [b.start for b in boundaries] + [content_end],
        strict=True,
    ))
    segments: list[Segment] = []
    for i, (start, end) in enumerate(pairs, 1):
        padded_start = max(0.0, start - padding)
        padded_end = min(total, end + padding)
        if padded_end <= padded_start:
            raise ValueError(f"invalid segment {i}: {start:.3f}..{end:.3f}")
        segments.append(Segment(index=i, start=padded_start, end=padded_end))
    return segments

def write_segment(
    segment: Segment,
    source: Path,
    output_dir: Path,
    prefix: str,
    extension: str,
) -> None:
    """Extracts segment using ffmpeg and saves it to a file."""
    output = output_dir / f"{prefix}{segment.index:03d}.{extension}"
    command = [
        "ffmpeg",
        "-hide_banner",
        "-loglevel", "error",
        "-y",
        # Placing -ss before -i enables fast keyframe seeking
        # Placing it after -i increases accuracy but is slower as it decodes all frames from the beginning
        "-ss", f"{segment.start:.6f}",
        "-i", str(source),
        "-t", f"{segment.end - segment.start:.6f}",
        "-vn",  # Exclude video streams
    ]
    if extension == "m4a":
        command += ["-c:a", "aac", "-b:a", "128k"]
    elif extension == "mp3":
        command += ["-af", "aresample=44100", "-c:a", "libmp3lame", "-b:a", "96k"]
    else:
        raise ValueError(f"unsupported extension: {extension}")
    command.append(str(output))
    subprocess.run(command, check=True)

def write_manifest(segments: list[Segment], output_dir: Path, prefix: str) -> None:
    """Outputs segment boundary information to a TSV file."""
    tsv_path = output_dir / f"{prefix.rstrip('-_')}-manifest.tsv"
    with tsv_path.open("w", encoding="utf-8", newline="") as f:
        writer = csv.writer(f, delimiter="\t")
        writer.writerow(["file", "start", "end", "duration"])
        for s in segments:
            writer.writerow(
                [
                    f"{prefix}{s.index:03d}",
                    f"{s.start:.3f}",
                    f"{s.end:.3f}",
                    f"{s.end - s.start:.3f}",
                ]
            )

def main() -> None:
    parser = argparse.ArgumentParser(description="Split audio files at silent intervals")
    parser.add_argument("input", help="Input audio file")
    parser.add_argument("--output-dir", default="out")
    parser.add_argument("--target-count", type=int, default=None)
    parser.add_argument("--prefix", default=None, help="Output file prefix (uses original filename if omitted)")
    parser.add_argument("--extension", choices=["mp3", "m4a"], default="mp3")
    parser.add_argument("--noise-db", type=float, default=-30.0)
    parser.add_argument("--min-silence", type=float, default=1.0)
    parser.add_argument("--merge-gap", type=float, default=0.1)
    parser.add_argument("--padding", type=float, default=0.04)
    parser.add_argument("--dry-run", action="store_true")
    args = parser.parse_args()

    source = Path(args.input)
    output_dir = Path(args.output_dir)
    prefix = args.prefix if args.prefix is not None else f"{source.stem}-"

    try:
        total = probe_duration(source)
        raw_silences = detect_silences(source, args.noise_db, args.min_silence)
        silences = merge_nearby(raw_silences, args.merge_gap)
        timeline = build_timeline(silences, total)
        boundaries = select_boundaries(timeline, args.target_count, total)
        segments = build_segments(timeline, boundaries, total, args.padding)
    except (ValueError, subprocess.CalledProcessError) as e:
        parser.exit(1, f"error: {e}\n")

    print(f"detected {len(raw_silences)} silences → merged to {len(silences)} → selected {len(boundaries)} boundaries → {len(segments)} segments")

    if args.dry_run:
        if isinstance(timeline[0], Silence):
            print(f"  silence: 0.000s .. {segments[0].start:.3f}s  ({segments[0].start:.3f}s)")
        for i, s in enumerate(segments):
            print(f"  {s.index:03d}: {s.start:.3f}s .. {s.end:.3f}s  ({s.end - s.start:.3f}s)")
            if i < len(segments) - 1:
                silence_start = s.end
                silence_end = segments[i + 1].start
                print(f"  silence: {silence_start:.3f}s .. {silence_end:.3f}s  ({silence_end - silence_start:.3f}s)")
        if isinstance(timeline[-1], Silence):
            print(f"  silence: {segments[-1].end:.3f}s .. {total:.3f}s  ({total - segments[-1].end:.3f}s)")
        return

    output_dir.mkdir(parents=True, exist_ok=True)
    write_manifest(segments, output_dir, prefix)
    for s in segments:
        write_segment(s, source, output_dir, prefix, args.extension)
    print(f"wrote {len(segments)} files to {output_dir}")

if __name__ == "__main__":
    main()