How to Handle Videos Larger Than 25MB for Whisper API Processing in Claude Video

Claude Video automatically chunks oversized audio files to stay within the 25 MB Whisper API limit, then stitches the transcripts back together with accurate timestamps.

The bradautomates/claude-video repository provides a watch skill that transcribes videos using Groq or OpenAI Whisper APIs. Both services enforce a strict upload ceiling of approximately 25 MB, so the codebase implements an intelligent chunking pipeline that splits audio, transcribes each segment, and reassembles the results without user intervention.

The 25 MB Limit and Safety Threshold

In skills/watch/scripts/whisper.py, the skill defines a conservative safety margin:

MAX_UPLOAD_BYTES = 24 * 1024 * 1024  # 24 MiB to stay under 25 MB limit

This constant (lines 35–38) ensures that even with metadata overhead, uploads stay within the Groq and OpenAI Whisper API limits. When extract_audio produces a file larger than this threshold, the transcribe_video function automatically triggers the chunking workflow rather than attempting a single upload.

Automatic Chunking Pipeline

The chunking system operates through a six-step pipeline orchestrated in skills/watch/scripts/whisper.py:

Step 1: Audio Extraction

The extract_audio function (lines 15–33) uses ffmpeg to generate a mono 16 kHz MP3 at approximately 480 kB per minute. This constant-bitrate encoding (64 kbps) makes size calculations predictable.

Step 2: Size Check

The transcribe_video entry point (lines 44–51) compares audio_path.stat().st_size against MAX_UPLOAD_BYTES. If the file is under the limit, it uploads directly; otherwise, it proceeds to chunking.

Step 3: Chunk Planning

The plan_chunks function (lines 40–62) calculates:

• Number of chunks required
• Byte offset for each chunk
• Duration per chunk to stay under the byte limit

Because the MP3 uses constant bitrate, the planning math remains linear and reliable.

Step 4: Audio Splitting

The split_audio function (lines 64–80) invokes ffmpeg with -c copy to slice the original MP3 into the planned segments. This preserves audio quality without re-encoding.

Step 5: Transcription and Timestamp Shifting

The transcribe_chunks function (lines 71–80) processes each chunk through _transcribe_file and _post_whisper. The shift_segments helper (lines 32–40) adjusts each segment's start and end times by the chunk's offset, ensuring the final transcript reflects the original video timeline.

Step 6: Final Assembly

The function returns a single ordered list of segments (lines 64–66), concatenating results from all chunks as if the entire audio had been processed at once.

Practical Usage Examples

CLI with Automatic Chunking

# Automatically handles any video size

watch watch "https://www.youtube.com/watch?v=example"

Force Specific Backend

# Force Groq Whisper (falls back to OpenAI if unavailable)

watch watch "my-video.mp4" --backend groq

Programmatic Python Usage

from pathlib import Path
from skills.watch.scripts.whisper import transcribe_video

video_path = "big-lecture.mp4"
audio_out = Path("audio.mp3")

# Automatically chunks if audio exceeds 24 MiB

segments, backend = transcribe_video(video_path, audio_out)

print(f"Transcribed with {backend}:")
for seg in segments:
    print(f"{seg['start']:.2f}-{seg['end']:.2f}: {seg['text']}")

Environment Configuration

Create a private configuration file for API keys (referenced in setup.py lines 40–50):

mkdir -p ~/.config/watch
cat > ~/.config/watch/.env <<EOF
GROQ_API_KEY=your_groq_key_here

# or

OPENAI_API_KEY=your_openai_key_here
EOF
chmod 600 ~/.config/watch/.env

With this configuration, all /watch invocations automatically authenticate without explicit flags.

Key Implementation Details

• No manual intervention – The transcribe_video function transparently handles any audio file exceeding 24 MiB.
• Constant bitrate encoding – The mono 16 kHz MP3 format ensures deterministic size-to-duration ratios for accurate chunk planning.
• Accurate timestamps – Each chunk's timestamps are shifted by its start offset via shift_segments, maintaining synchronization with the original video.
• API key flexibility – Set GROQ_API_KEY (preferred) or OPENAI_API_KEY in your environment or ~/.config/watch/.env.

Summary

• Claude Video handles videos larger than 25MB automatically by chunking audio in skills/watch/scripts/whisper.py.
• The 24 MiB threshold (MAX_UPLOAD_BYTES) provides a safety margin under the Whisper API limit.
• Six-step pipeline – extract, check, plan, split, transcribe with timestamp shifting, and assemble.
• Accurate timestamps are preserved through shift_segments offset calculations.
• Configure once – Store GROQ_API_KEY or OPENAI_API_KEY in ~/.config/watch/.env for seamless operation.

Frequently Asked Questions

What happens if my video's audio is exactly 25 MB?

The system uses a 24 MiB safety threshold (MAX_UPLOAD_BYTES), so a 25 MB file triggers automatic chunking. The plan_chunks function calculates the optimal split points and processes the audio in segments, then reassembles the transcript with correct timestamps.

Does chunking affect transcription accuracy or timestamps?

No. The shift_segments function (lines 32–40 in whisper.py) adjusts each segment's start and end times by the chunk's offset duration. The final output is a continuous transcript that matches the original video timeline, as if processed as a single file.

How do I configure the API keys for Whisper processing?

Set GROQ_API_KEY (preferred) or OPENAI_API_KEY in your environment variables, or create ~/.config/watch/.env as shown in setup.py. The watch skill automatically detects and uses these credentials. Groq is used by default when available due to faster processing and lower costs.

Can I force the system to use OpenAI instead of Groq?

Yes. Use the --backend openai flag in CLI mode, or specify the backend parameter when calling transcribe_video programmatically. The system will route requests to the specified provider regardless of which API keys are available.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}