Panniantong/Agent-Reach · error · TranscribeError

audio duration exceeds safety limit of {max_minutes} minutes

Error message

audio duration exceeds safety limit of {max_minutes} minutes

What it means

Raised by _require_duration_within_budget (transcribe.py:144-152) when ffprobe reports an audio duration above MAX_AUDIO_SECONDS = 14400s (24 chunks x 600s = 240 minutes / 4 hours). The library enforces a bounded chunk budget so a single transcription job can never explode into unbounded API calls. The message renders the limit in minutes (240).

Source

Thrown at agent_reach/transcribe.py:149

    try:
        duration = float(raw_duration)
    except (TypeError, ValueError):
        raise TranscribeError(
            "ffprobe could not parse a valid audio duration"
        ) from None
    if not math.isfinite(duration) or duration <= 0:
        raise TranscribeError(
            "ffprobe could not parse a valid positive audio duration"
        )
    return duration


def _require_duration_within_budget(path: Path) -> float:
    """Reject audio that cannot fit within the bounded chunk budget."""
    duration = _probe_audio_duration(path)
    if duration > MAX_AUDIO_SECONDS:
        max_minutes = MAX_AUDIO_SECONDS // 60
        raise TranscribeError(
            f"audio duration exceeds safety limit of {max_minutes} minutes"
        )
    return duration


def _run(cmd: List[str], timeout: int = 600) -> None:
    """Run a subprocess, raising TranscribeError on nonzero exit or timeout.

    cmd carries user-supplied URLs/paths into yt-dlp/ffmpeg — a stalled
    network read or a hung probe must not block the CLI forever.
    """
    try:
        proc = subprocess.run(
            cmd,
            capture_output=True,
            encoding="utf-8",
            errors="replace",
            timeout=timeout,

View on GitHub (pinned to 93ae1d18c3)

Solutions

1. Trim the media to under 4 hours before calling transcribe(), e.g. ffmpeg -ss 0 -t 14390 -i input.m4a -c copy cut.m4a, and transcribe in parts
2. Verify the real duration first: ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 file.m4a
3. If you genuinely need longer input, transcribe consecutive time windows (ffmpeg -ss/-t) and join the returned texts yourself
4. Only as a last resort, raise MAX_CHUNKS in your own fork — the limit also guards MAX_TOTAL_CHUNK_BYTES (96 MiB) and per-chunk 24 MiB API caps

Example fix

// before
transcribe("https://example.com/8h-livestream")  # TranscribeError: 240 minutes

// after: split into <4h windows
for i, ss in enumerate(range(0, 8*3600, 14_000)):
    part = workdir / f"part{i}.m4a"
    subprocess.run(["ffmpeg", "-ss", str(ss), "-t", "14000", "-i", src, "-c", "copy", str(part)], check=True)
    text += transcribe(str(part), provider="groq") + "\n"

import subprocess
from pathlib import Path

def fits_duration_budget(path: Path, max_seconds: int = 14400) -> bool:
    out = subprocess.run(
        ["ffprobe", "-v", "error", "-show_entries", "format=duration",
         "-of", "default=noprint_wrappers=1:nokey=1", str(path)],
        capture_output=True, text=True,
    )
    try:
        return 0 < float(out.stdout.strip()) <= max_seconds
    except ValueError:
        return False

from agent_reach.transcribe import TranscribeError
try:
    text = transcribe(source)
except TranscribeError as e:
    if "exceeds safety limit" in str(e):
        # split source into <4h windows yourself and transcribe each
        ...
    raise

When it happens

Trigger: transcribe(source) where source is a local file or downloaded media longer than 14400 seconds; _transcribe_in_dir calls _require_duration_within_budget(audio) at line 455 and ffprobe successfully parses duration > MAX_AUDIO_SECONDS. Typical with 4h+ podcast compilations, livestream recordings, or audiobook rips.

Common situations: Pointing the transcriber at long livestream VODs, multi-hour DJ sets, sleep-sound/white-noise videos, or accidentally passing a playlist-style compilation. Also hitting this right after a release that lowered MAX_CHUNKS/CHUNK_SECONDS constants.

Related errors

• chunk segment duration must be positive
• unknown provider: {provider}
• unknown provider: {provider} (use groq|openai|auto)
• allow_provider_fallback requires provider='auto'
• audio produced {len(chunks)} chunks; safety limit is {MAX_CH

AI-assisted analysis of Panniantong/Agent-Reach@93ae1d18c3 (2026-08-14). Data as JSON: /api/errors/83305d5f6a87c4ea. Report an issue: GitHub.