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

> Discover how the video-use transcript caching mechanism prevents re-transcription of unchanged sources by storing JSON files and skipping redundant API calls. Optimize your workflow.

- Repository: [Browser Use/video-use](https://github.com/browser-use/video-use)
- Tags: internals
- Published: 2026-07-07

---

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

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

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

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

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