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

> Troubleshoot transcription caching issues with browser-use video-use. Learn to regenerate transcripts when source files haven't changed by deleting JSON or using the force flag.

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

---

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

```python
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:
   ```bash
   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:
   ```bash
   rm <edit-dir>/transcripts/<video-stem>.json
   ```

4. **Re-run the transcription**  
   Execute the transcription script with your desired parameters:
   ```bash
   python helpers/transcribe.py path/to/video.mp4 --language en --num-speakers 2
   ```

   For batch processing, clear the entire transcripts directory first:
   ```bash
   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`](https://github.com/browser-use/video-use/blob/main/helpers/transcribe.py) to accept a `--force` parameter. Update the `transcribe_one` function signature:

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

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

```

Now you can bypass the cache programmatically:

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