How to Cache Transcripts to Avoid Re-Transcription in video-use

video-use automatically caches every ElevenLabs Scribe transcript as a JSON file in edit/transcripts/ and skips the expensive API call on subsequent runs if the file exists.

The browser-use/video-use repository implements a file-based caching system that eliminates redundant audio extraction and transcription costs. When you process a video, the helper functions check for an existing JSON transcript before calling the ElevenLabs API. This design saves API quota and dramatically speeds up repeated editing sessions.

How Transcript Caching Works

The caching mechanism operates transparently across both single-video and batch processing workflows. It stores raw API responses as JSON files that persist between sessions.

Cache Storage Location

Every transcript is saved to a predictable path within your edit directory:

<edit_dir>/transcripts/<video-stem>.json

For example, processing clip.mp4 creates edit/transcripts/clip.json. This JSON contains the complete ElevenLabs Scribe response, including timestamps and text segments.

Single-Video Cache Logic

In helpers/transcribe.py, the transcribe_one function checks for existing cache files before executing the transcription pipeline. The code verifies out_path.exists() at lines 98-106. When the file exists, the function prints a "cached" notice and returns the path immediately, bypassing audio extraction, file upload, and the API call entirely.

# From helpers/transcribe.py (simplified logic)

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

Batch Processing with Cache Skipping

The batch runner in helpers/transcribe_batch.py optimizes parallel processing by pre-filtering cached files. At lines 72-76, the script builds an already_cached list and only submits uncached videos to the thread pool. This prevents wasting worker threads on files that already exist.

# Batch transcription automatically skips cached files

$ python -m helpers.transcribe_batch /path/to/videos

# Output:

# found 12 videos (5 cached, 7 to transcribe)

# transcribing 7 files with 4 parallel workers

Managing the Transcript Cache

Because the cache consists of simple JSON files, you have full control over cache invalidation without complex database operations.

Clearing Specific Entries

To force re-transcription of a single video, delete its corresponding JSON file:

rm edit/transcripts/clip.json
python -m helpers.transcribe clip.mp4

The next run will extract audio and call the ElevenLabs API as if processing the file for the first time.

Bulk Cache Operations

Clear the entire cache by removing the transcripts directory:

rm -rf edit/transcripts/

All subsequent transcription commands will process videos from scratch.

Working with Cached Transcripts

After accumulating transcripts, you can aggregate them into a human-readable format. The helpers/pack_transcripts.py script compiles all JSON files in the cache into a single markdown document (takes_packed.md), making it easy to review or archive completed transcriptions.

Summary

• Automatic caching: Every transcription saves a JSON file to edit/transcripts/<video-stem>.json containing the full ElevenLabs response.
• Single-video optimization: transcribe_one in helpers/transcribe.py checks out_path.exists() and returns immediately if cached.
• Batch efficiency: transcribe_batch.py filters out cached files before spawning worker threads, showing counts like "5 cached, 7 to transcribe".
• Manual invalidation: Delete individual JSON files or the entire transcripts/ folder to force re-transcription.
• Export utility: helpers/pack_transcripts.py converts the JSON cache into a consolidated markdown file.

Frequently Asked Questions

How do I know if a transcript is being loaded from cache?

When running python -m helpers.transcribe, the console output prints "cached: filename.json" if the file exists in edit/transcripts/. No upload progress or API latency appears because the function returns the existing path immediately after the existence check.

Does changing transcription settings invalidate the cache?

No, the cache system is file-based and does not detect parameter changes. If you modify language settings or prompt templates in the ElevenLabs configuration, you must manually delete the specific JSON file in edit/transcripts/ to force a fresh transcription with the new parameters.

Can I move the cache directory to a different location?

The cache path is hardcoded relative to the edit directory as transcripts/<video-stem>.json in both helpers/transcribe.py and helpers/transcribe_batch.py. To relocate the cache, you would need to modify the out_path construction logic in the source files or create a symbolic link at the expected location.

What happens if the ElevenLabs API changes response format?

The cache stores the raw JSON response from ElevenLabs Scribe. If the API schema changes, existing cached files may become incompatible with downstream processing. In this case, clear the edit/transcripts/ directory to ensure all files conform to the current API specification.

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