How the Video-Use Transcript Caching Mechanism Prevents Re-Transcription of Unchanged Sources

The video-use transcript caching mechanism stores transcripts as JSON files in transcripts/<video-stem>.json and skips API calls to ElevenLabs Scribe when a matching file exists, ensuring unchanged sources are never re-transcribed.

The browser-use/video-use repository implements a durable file-based caching system to avoid redundant transcription costs. By persisting transcripts as JSON artifacts keyed to the video filename, the tool eliminates unnecessary HTTP requests to the ElevenLabs Scribe API when processing identical video sources multiple times.

How the Caching Mechanism Works

Single Video Processing with transcribe_one

In helpers/transcribe.py, the transcribe_one function implements the core cache check. Before initiating any upload to the Scribe API, the function constructs the output path and verifies existence:

if out_path.exists():
    print(f"cached: {out_path.name}")
    return out_path

This check appears alongside the comment "Cached: if the output file already exists, the upload is skipped" (lines 90-110). When the transcript JSON is found, the function returns the existing path immediately without extracting audio or contacting the API.

Batch Processing with transcribe_batch

For bulk operations, helpers/transcribe_batch.py optimizes the queue by pre-filtering the video list. The batch helper builds a list of already-cached videos using a list comprehension that checks for the existence of the corresponding JSON file:

already_cached = [v for v in videos if (edit_dir / "transcripts" / f"{v.stem}.json").exists()]

Only videos not present in this list are submitted to the Scribe API, while cached entries are bypassed entirely (lines 70-78). This approach prevents rate-limit consumption and duplicate billing across large media libraries.

Cache Key Structure and Idempotency

The cache key is derived from the stem of the video file—the filename without extension. The transcript is stored at edit_dir / "transcripts" / f"{video.stem}.json".

This design ensures:

• Content stability: Renaming a video invalidates the cache, triggering a fresh transcription
• Immutability: The JSON output remains a durable artifact of the original input
• Idempotency: Repeated runs on the same source are cheap and fast, producing identical results without API costs

Practical Implementation Examples

Single video transcription demonstrating cache reuse:

from pathlib import Path
from helpers.transcribe import transcribe_one, load_api_key

video_path = Path("media/example.mp4")
edit_dir = Path("my_edit")
api_key = load_api_key()

# First run creates the transcript

transcript_path = transcribe_one(video_path, edit_dir, api_key)

# Subsequent runs return cached result:

# cached: example.json

Batch processing with cache statistics:

from pathlib import Path
from helpers.transcribe_batch import transcribe_batch
from helpers.transcribe import load_api_key

videos = list(Path("media").glob("*.mp4"))
edit_dir = Path("my_edit")
api_key = load_api_key()

# Output shows cache utilization:

# found 10 videos (7 cached, 3 to transcribe)

transcribe_batch(videos, edit_dir, api_key)

Summary

• The video-use transcript caching mechanism stores outputs in transcripts/<video-stem>.json within the edit directory
• Single-file processing: transcribe_one in helpers/transcribe.py checks out_path.exists() and skips the ElevenLabs Scribe API call when a cached JSON is found
• Batch processing: transcribe_batch in helpers/transcribe_batch.py filters videos using list comprehension to separate cached from pending items
• Cache invalidation: Occurs automatically when video filenames change, ensuring fresh transcription for new content
• Cost optimization: Eliminates redundant API calls, preventing duplicate billing and rate-limit exhaustion

Frequently Asked Questions

How does video-use detect whether a transcript already exists?

Before uploading to ElevenLabs Scribe, the code checks for a JSON file at transcripts/{video_stem}.json relative to the edit directory. If the file exists, the helper returns the cached path immediately without network requests.

What happens if I rename a video file?

Renaming changes the file stem, which serves as the cache key. The system will not find a matching JSON file and will treat the renamed video as a new source, performing a fresh transcription via the Scribe API.

Where are cached transcripts stored?

Transcripts are stored as JSON files in the transcripts/ subdirectory of the specified edit directory, using the naming convention {video_stem}.json where video_stem is the filename without extension.

Does the cache check work for batch operations?

Yes. The transcribe_batch function in helpers/transcribe_batch.py builds a list of cached videos using the expression [v for v in videos if (edit_dir / "transcripts" / f"{v.stem}.json").exists()], processing only the pending items and skipping API calls for cached entries.

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