How Claude Video Manages Long Videos Exceeding the Upload Limit for Transcription

Claude Video automatically splits audio files larger than 24 MiB into smaller chunks, transcribes each segment via the Whisper API, and reassembles the results with timestamp adjustments to deliver a seamless, continuous transcript.

The bradautomates/claude-video skill provides a transcription pipeline built around the Whisper API (Groq or OpenAI), both services enforcing a maximum upload size of approximately 25 MiB. To manage long videos exceeding the upload limit for transcription, the skill implements an intelligent chunking strategy that splits, processes, and stitches audio segments internally without requiring manual intervention.

Understanding the Upload Constraint

Whisper API providers including Groq and OpenAI reject audio files larger than roughly 25 MiB. To stay safely below this threshold, Claude Video defines MAX_UPLOAD_BYTES = 24 * 1024 * 1024 (24 MiB) in skills/watch/scripts/whisper.py. Before uploading, the transcribe_video() function compares the extracted audio file size against this constant to determine if chunking is required.

Audio Extraction and Compression

First, extract_audio() converts the input video to a mono 16 kHz MP3, generating approximately 480 kB per minute of audio. This compression ensures most videos remain under the limit naturally. However, for lengthy recordings, the file may still exceed 24 MiB, triggering the chunking workflow to partition the audio into manageable segments.

Chunk Planning and Splitting

When transcribe_video() detects an oversized file, it delegates to plan_chunks() to calculate a list of (offset, duration) tuples based on the total duration and file size. This plan divides the audio into segments whose estimated size remains under the limit. The split_audio() function then executes ffmpeg -ss … -t … -c copy for each entry, creating independent MP3 files without re-encoding, which preserves audio quality while ensuring compatibility.

Distributed Transcription and Timestamp Stitching

The transcribe_chunks() function uploads each slice via _post_whisper(). If a single chunk fails, the error is logged and skipped, allowing the remainder of the video to process without total failure. Since Whisper returns timestamps relative to each chunk’s start, shift_segments() offsets every start and end time by the chunk’s original position within the full timeline before concatenation. The final output is a unified list of segments that preserves the original chronological flow despite the underlying segmented uploads.

Practical Usage Examples

Command Line Interface

Simply provide a video URL or path; chunking happens automatically when the extracted audio exceeds the limit:

watch https://www.youtube.com/watch?v=LONG_VIDEO_ID

Direct Python Integration

Import the transcription logic from skills/watch/scripts/whisper.py to process large video files programmatically:

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

video_path = "/path/to/very-long-video.mp4"
audio_out = Path("audio.mp3")

segments, backend = transcribe_video(
    video_path,
    audio_out,
    backend=None,        # Auto-detects Groq → OpenAI

    api_key=None         # Reads from ~/.config/watch/.env

)

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

Inspecting the Chunk Plan

Debug the segmentation logic for large files to verify how the audio will be partitioned:

from pathlib import Path
from skills.watch.scripts.whisper import plan_chunks, audio_duration

audio_path = Path("audio.mp3")
duration = audio_duration(audio_path)
size_bytes = audio_path.stat().st_size
chunks = plan_chunks(duration, size_bytes)

print("Chunk plan (offset, duration):", chunks)

Summary

• Claude Video handles videos exceeding the upload limit by splitting audio into sub-24 MiB chunks using logic defined in skills/watch/scripts/whisper.py.
• The plan_chunks() function calculates optimal segmentation based on duration and file size to stay within MAX_UPLOAD_BYTES.
• split_audio() uses ffmpeg with stream copy (-c copy) to create chunks without quality loss or re-encoding.
• shift_segments() mathematically adjusts timestamps to maintain chronological continuity across the full transcript.
• Failed chunks are logged and skipped rather than halting the entire process, ensuring partial results for corrupted or extremely long videos.

Frequently Asked Questions

What is the maximum video length Claude Video can process?

There is no hardcoded duration limit; the system processes arbitrarily long content by chunking. Practical limits depend on available disk space for temporary MP3 files and API rate limits, not the upload size constraint.

Does chunking affect transcript accuracy or synchronization?

No. The ffmpeg -c copy command splits audio without re-encoding, preserving original quality. Each chunk is transcribed with the same Whisper model, and shift_segments() adjusts timestamps mathematically to reconstruct the exact timeline.

How does Claude Video handle API failures in individual chunks?

The transcribe_chunks() function implements error isolation. If _post_whisper() fails for a specific chunk, the exception is logged and that segment is skipped, allowing remaining chunks to complete. The final transcript reflects only the successfully processed portions.

Where are temporary audio files stored during processing?

Intermediate MP3 files are written to the path specified by the audio_out parameter in transcribe_video(). By default, these reside in the working directory or a system temporary location, depending on how the skill is invoked.

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