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

The --num-speakers flag in 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 script handles the speaker count.

CLI Argument Parsing

In the main() function of 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:

# 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:

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: Core CLI driver that parses --num-speakers and constructs the Scribe request payload (lines 51–55 and 70–73).
• helpers/transcribe_batch.py: Wrapper for processing multiple videos using the same transcribe_one() function.
• 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.
• 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 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 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.

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