How to Troubleshoot Transcription Caching Issues When Source Files Haven't Changed

When video-use returns cached transcripts despite parameter changes, delete the JSON file in edit/transcripts/ or add a --force flag to bypass the existence-based cache check in transcribe_one.

The browser-use/video-use repository provides efficient video transcription through ElevenLabs Scribe, but its transcription caching mechanism can return stale results when you modify processing parameters or update source videos. Because the cache relies solely on file existence rather than content hashes or timestamps, understanding how to troubleshoot and invalidate these cached transcripts is essential for accurate results.

How the Transcription Cache Works in Video-Use

In helpers/transcribe.py, the transcribe_one function implements a simple existence-based cache to avoid redundant API calls. The code constructs an output path at edit/transcripts/<video-stem>.json and immediately returns this file if present (lines 98-106):

out_path = transcripts_dir / f"{video.stem}.json"
if out_path.exists():
    if verbose:
        print(f"cached: {out_path.name}")
    return out_path

This design prioritizes performance—transcribing large videos consumes significant time and API quota—but means the script never validates whether the source video or processing parameters have changed since the initial creation.

Common Scenarios Triggering Stale Transcripts

Changed Scribe Parameters Without Cache Clear

When you modify flags like --language or --num-speakers, the cached JSON file from a previous run masks these changes. The script returns the existing transcript before reaching the API call, ignoring your new configuration entirely.

Source Video Updated but Filename Unchanged

If you edit a video file (trimming, re-encoding, or replacing content) but keep the same filename, the cache key remains identical. The script continues serving the old transcript associated with that filename stem rather than processing the updated media.

API Errors Masked by Cache Hits

When debugging API connectivity or authentication issues, cached success responses can hide underlying problems. The script outputs the cached file and exits successfully before validating current API credentials or endpoints against ElevenLabs.

Step-by-Step Troubleshooting Workflow

Follow this sequence to identify and resolve transcription caching issues:

1. Locate the cached file
   Verify the transcript exists in your edit directory:

   ls <edit-dir>/transcripts/<video-stem>.json

2. Confirm regeneration is necessary
   Check if you have changed Scribe parameters, modified the source video, or updated the video-use codebase since the last transcription run.

3. Remove the stale cache file
   Delete the specific JSON file to invalidate the cache:

   rm <edit-dir>/transcripts/<video-stem>.json

4. Re-run the transcription
   Execute the transcription script with your desired parameters:

   python helpers/transcribe.py path/to/video.mp4 --language en --num-speakers 2

   For batch processing, clear the entire transcripts directory first:

   rm -rf path/to/videos_dir/edit/transcripts/*
   python helpers/transcribe_batch.py path/to/videos_dir --workers 4

5. Verify fresh generation
   Confirm the script prints processing messages rather than cached: and outputs a new JSON file with updated content and timestamps.

Implementing a Force Regeneration Flag

To streamline troubleshooting without manual file deletion, modify helpers/transcribe.py to accept a --force parameter. Update the transcribe_one function signature:

def transcribe_one(..., force: bool = False, ...):
    if out_path.exists() and not force:
        if verbose:
            print(f"cached: {out_path.name}")
        return out_path

Add the CLI argument to the argparse configuration:

ap.add_argument("--force", action="store_true",
                help="Ignore existing transcript and re-transcribe")

Now you can bypass the cache programmatically:

python helpers/transcribe.py video.mp4 --force --language es

Summary

• browser-use/video-use caches transcripts by checking for JSON file existence at edit/transcripts/<video-stem>.json in helpers/transcribe.py (lines 98-106)
• Stale transcripts occur when source files change but filenames remain identical, or when Scribe parameters update without cache clearing
• Delete the specific JSON file or the entire transcripts/ directory to force regeneration when source files haven't changed but transcripts need updating
• Consider implementing a --force flag in transcribe_one for workflows requiring frequent cache invalidation
• Always verify the edit directory path matches your --edit-dir argument or default <video-parent>/edit location

Frequently Asked Questions

Why does video-use use file existence instead of content hashing for caching?

The cache prioritizes performance and API quota conservation. Transcribing video via ElevenLabs Scribe requires significant processing time and costs; checking file existence is instantaneous and prevents redundant uploads. According to the browser-use/video-use source code, this trade-off requires manual cache invalidation when content changes.

How do I clear the transcript cache for an entire project?

Delete the transcripts folder within your edit directory. For a batch of videos stored in videos/, run rm -rf videos/edit/transcripts/* before executing helpers/transcribe_batch.py. This forces fresh transcription for all files in the directory by ensuring the existence check at lines 98-106 of transcribe.py evaluates to false.

Can I change the cache location from the default edit/transcripts folder?

Yes, specify a custom edit directory using the --edit-dir argument when running transcribe.py. The cache path is always <edit-dir>/transcripts/, so changing this parameter directs both cache storage and lookup to your specified location.

What happens if I delete a cache file while transcription is actively running?

If deletion occurs before the script reaches the cache check (lines 98-106), the process continues to upload and generate a fresh transcript. If deletion happens after the check but before writing completes, you may encounter file I/O errors. Always clear caches before launching new transcription jobs rather than during execution.

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