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

> Discover how Claude Video handles lengthy audio for transcription. It automatically segments audio, transcribes chunks, and reassembles them for a complete transcript. Learn more!

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-28

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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:

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

```

### Direct Python Integration

Import the transcription logic from [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) to process large video files programmatically:

```python
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:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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.