# How to Configure Speaker Diarization with the `--num-speakers` Flag in `transcribe.py`

> Learn how to configure speaker diarization using the --num-speakers flag in transcribe.py. Improve accuracy by setting a hardcoded speaker count for ElevenLabs Scribe.

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

---

**The `--num-speakers` flag in [`helpers/transcribe.py`](https://github.com/browser-use/video-use/blob/main/helpers/transcribe.py) sends a hardcoded speaker count to ElevenLabs Scribe, improving diarization accuracy by overriding automatic speaker detection.**

The `browser-use/video-use` repository provides a Python wrapper for ElevenLabs Scribe that enables speaker diarization on video transcripts. While the script automatically enables diarization by default, it leverages the optional `--num-speakers` flag to let you specify exactly how many distinct speakers are present in the audio. Supplying this value can significantly improve transcription accuracy when the speaker count is known in advance.

## How Speaker Diarization Is Configured

The configuration process follows a straightforward pipeline from CLI argument to API payload. Here is how the [`transcribe.py`](https://github.com/browser-use/video-use/blob/main/transcribe.py) script handles the speaker count.

### CLI Argument Parsing

In the `main()` function of [`helpers/transcribe.py`](https://github.com/browser-use/video-use/blob/main/helpers/transcribe.py), the script defines an optional integer argument `--num-speakers` at lines 51–55. When provided, this value is captured as `args.num_speakers` and passed downstream to the transcription functions.

### Payload Construction and API Submission

The `transcribe_one()` function receives the speaker count and passes it to `call_scribe()`, where the actual HTTP request is constructed. At lines 70–73, the script checks for the presence of `num_speakers` and injects it into the POST payload as a string value, since the ElevenLabs Scribe API expects the speaker count in string format. The complete payload is then sent to the `SCRIBE_URL` endpoint for processing.

If the flag is omitted, the payload excludes the `num_speakers` key entirely, allowing Scribe to infer the speaker count automatically.

## Command-Line and Programmatic Usage

You can invoke this feature either from the terminal or within Python scripts.

### Basic CLI Usage

Run the transcription script with the `--num-speakers` flag followed by an integer:

```bash

# Automatic speaker detection (default behavior)

python helpers/transcribe.py path/to/video.mp4

# Explicitly define 2 speakers for improved accuracy

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

```

### Programmatic Integration

When calling `transcribe_one()` from another module, pass the speaker count as the `num_speakers` parameter:

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

video_path = Path("interview.mp4")
edit_dir = Path("output/")

# Load API key from environment

api_key = load_api_key()

# Transcribe with exactly 3 speakers specified

transcript_path = transcribe_one(
    video=video_path,
    edit_dir=edit_dir,
    api_key=api_key,
    language="en",
    num_speakers=3,
    verbose=True,
)
print(f"Diarized transcript saved to: {transcript_path}")

```

## Related Files and Architecture

The transcription pipeline relies on several coordinated modules:

- **[`helpers/transcribe.py`](https://github.com/browser-use/video-use/blob/main/helpers/transcribe.py)**: Core CLI driver that parses `--num-speakers` and constructs the Scribe request payload (lines 51–55 and 70–73).
- **[`helpers/transcribe_batch.py`](https://github.com/browser-use/video-use/blob/main/helpers/transcribe_batch.py)**: Wrapper for processing multiple videos using the same `transcribe_one()` function.
- **[`helpers/pack_transcripts.py`](https://github.com/browser-use/video-use/blob/main/helpers/pack_transcripts.py)**: Post-processing utilities for merging JSON transcripts produced by the diarization workflow.

## Summary

- **`--num-speakers`** is an optional integer argument defined in `main()` at lines 51–55 of [`helpers/transcribe.py`](https://github.com/browser-use/video-use/blob/main/helpers/transcribe.py).
- When provided, the value is converted to a string and injected into the Scribe API payload as `"num_speakers"` at lines 70–73.
- Omitting the flag allows ElevenLabs Scribe to automatically infer the speaker count.
- The flag improves diarization accuracy when you know the exact number of participants in the audio.

## Frequently Asked Questions

### What happens if I don't specify `--num-speakers`?

If you omit the flag, the script sends a diarization request without the `num_speakers` parameter. ElevenLabs Scribe then attempts to automatically detect the number of speakers in the audio, which may be less accurate than providing a known count.

### Why does the API require `num_speakers` as a string?

The ElevenLabs Scribe API expects the `num_speakers` value as a string in the JSON payload. The [`transcribe.py`](https://github.com/browser-use/video-use/blob/main/transcribe.py) script handles this conversion automatically at lines 70–73, ensuring compatibility with the API specification.

### Can I use `--num-speakers` with batch processing?

Yes. The [`helpers/transcribe_batch.py`](https://github.com/browser-use/video-use/blob/main/helpers/transcribe_batch.py) module utilizes the same `transcribe_one()` function internally, so any `num_speakers` value passed through the batch wrapper will propagate to the individual transcription requests.

### Does enabling `--num-speakers` disable automatic diarization?

No. The script always enables diarization by setting `"diarize": "true"` in the payload. The `--num-speakers` flag simply adds a hint to the algorithm about how many speakers to expect, rather than replacing the diarization feature entirely.