Skip to main content

HuggingFace Token Setup

Detecting speakers on this server requires access to a gated PyAnnote model on HuggingFace. This page guides you through obtaining a free token and accepting the model agreement.

Required for speaker detection on this server

Speaker detection on this server will NOT work without a valid HuggingFace token and acceptance of the pyannote/speaker-diarization-community-1 model agreement. Transcription will still work, but speakers will not be identified.

When you do not need it for speakers

Speakers detected by a cloud provider do not use this token: a cloud transcription model that returns speakers, or the pyannote.ai cloud service (a separate pyannote.ai API key, not a HuggingFace token). The lite image never detects speakers on this server. The diar-native sidecar's models, which also compute the voiceprints used for cross-file speaker matching, are exported from the same gated repository, so a lite install that runs the sidecar still needs the token. See Deployment Variants.

Why is HuggingFace Required?​

When speakers are detected on this server, OpenTranscribe uses the PyAnnote speaker-diarization-community-1 weights (identifying "who spoke when"), either through the diar-native sidecar or the in-process PyAnnote engine. PyAnnote's pre-trained models are hosted on HuggingFace as "gated" repositories, meaning you must:

  1. Create a free HuggingFace account
  2. Accept the model license agreements
  3. Use an access token to download the models

This is a one-time setup process. Once configured, models are cached locally and don't require internet access.

This same token also provisions the native diarization engine

As of v0.5.0, local diarization defaults to a native diar-native sidecar rather than the in-process PyAnnote pipeline described on this page (see Speaker Diarization). It reuses the identical HUGGINGFACE_TOKEN you configure here to export its own ONNX/PLDA model set automatically on the backend's first startup — there is nothing extra to set up. If that export fails for any reason (missing token, gate not accepted), diarization falls back to the PyAnnote path this page walks through, so following the steps below keeps you covered either way.

Step 1: Create HuggingFace Account​

If you don't already have a HuggingFace account:

  1. Visit https://huggingface.co/join
  2. Sign up with email or GitHub/Google account
  3. Verify your email address

Time required: 2 minutes

Step 2: Generate Access Token​

  1. Go to https://huggingface.co/settings/tokens
  2. Click "New token"
  3. Configure the token:
    • Name: OpenTranscribe (or any descriptive name)
    • Role: Select "Read" (default)
    • Description: Optional
  4. Click "Generate token"
  5. IMPORTANT: Copy the token and save it securely (you won't see it again)

Example token format: hf_ followed by random characters

Token Storage

Save your token in a password manager or secure note. You'll need it during OpenTranscribe setup. Tokens don't expire unless you delete them.

Time required: 2 minutes

Step 3: Accept the Model Agreement​

Speaker diarization needs access to one gated model: pyannote/speaker-diarization-community-1. It's CC-BY-4.0 and auto-approved — there's no waiting list or human review, but you still have to click through the agreement once per account.

pyannote/speaker-diarization-community-1​

  1. Visit https://huggingface.co/pyannote/speaker-diarization-community-1
  2. Scroll to the model card
  3. Click "Agree and access repository"
  4. ✅ You should see "You have been granted access to this model"
The token and the acceptance must be the SAME HuggingFace account

The gate is checked per account, not just per repo. If HUGGINGFACE_TOKEN was generated under a different account than the one that clicked "Agree and access repository" above, every request fails with HTTP 403 — identically to a token that never accepted anything. This is the single most common way this setup step goes wrong. If diarization still fails after you're sure you accepted the agreement, check which account actually issued the token.

What about segmentation-3.0 and speaker-diarization-3.1?

Older docs and forum posts reference pyannote/segmentation-3.0 and pyannote/speaker-diarization-3.1 — that was the model pair OpenTranscribe used before moving to speaker-diarization-community-1. community-1 bundles its own segmentation, embedding, and PLDA weights in one self-contained repo, so accepting the old pair grants nothing for it, and the native diar-native sidecar's export deliberately never touches them (their weights differ from community-1's own). The in-process PyAnnote engine — the failover used when the sidecar is unavailable — does keep speaker-diarization-3.1 as an internal last-resort fallback if loading community-1 itself fails for a non-licensing reason. Accepting the old pair is optional, only helps that inner fallback, and is never a substitute for accepting community-1.

Time required: 2 minutes

Step 4: Configure OpenTranscribe​

Quick Install Method​

If using the one-liner installer:

curl -fsSL https://raw.githubusercontent.com/attevon-llc/OpenTranscribe/master/setup-opentranscribe.sh | bash

The installer asks whether you have a token to enter now (answer n to skip and add it later), then prompts for it with the input hidden:

Please enter your HuggingFace token:
(Token will be hidden for security)

Paste your token and press Enter. The installer will:

  • Check that it starts with hf_ (it does not contact HuggingFace to test it, and does not check that you accepted the model agreement)
  • Write it to .env as HUGGINGFACE_TOKEN
  • Offer to download the models now (the speaker models are about 500MB; the total depends on the Whisper model you chose)

To test a saved token against HuggingFace, use Test under Settings > Speaker Identification > Speaker Engine (below).

Manual Install Method​

If installing from source:

  1. Copy the environment template:

    cp .env.example .env
  2. Edit .env and add your token:

    # Required for speaker detection on this server
    HUGGINGFACE_TOKEN=hf_your_token_here
  3. Start OpenTranscribe:

    ./opentr.sh start dev

Models will download automatically on first use (~10-30 minutes).

Set or change the token in Settings​

You do not need to edit .env, and you can change the token later without restarting. Sign in as a super admin and open Settings > Speaker Identification > Speaker Engine. The Hugging Face access token card shows whether a token is saved in Settings, comes from the server environment, or is not set. Paste a token, press Save token, and use Test to ask Hugging Face whether it is accepted.

  • A token saved in Settings takes precedence over HUGGINGFACE_TOKEN in .env. Remove deletes only the saved one, after which the .env token (if any) applies again.
  • The token is stored encrypted and is never shown again, including to super admins. To replace it, paste a new one.
  • A running worker picks up a new token the next time it loads a model, within about a minute. No restart is needed.
Local Whisper models do not need this token

The local transcription model library (Settings > Transcription > Local models) downloads public models, so no token is required for it; a token saved here is used if present. See Local Transcription Models.

Verification​

Method 1: Check Model Cache​

After first transcription with speaker diarization:

# Check if the diarization pipeline was downloaded
ls -lh models/huggingface/hub/ | grep pyannote

# You should see (this is the only one required):
# models--pyannote--speaker-diarization-community-1

If the in-process PyAnnote engine's internal last-resort fallback ever ran, you'll also see models--pyannote--speaker-diarization-3.1 and models--pyannote--segmentation-3.0 here — that isn't an error, just evidence the fallback fired at some point.

Method 2: Test Transcription​

  1. Upload a test file with multiple speakers
  2. Enable speaker diarization
  3. Process the file
  4. Check for speaker labels (Speaker 1, Speaker 2, etc.)

If diarization works, you'll see:

  • ✅ Speaker segments identified
  • ✅ Different speakers color-coded
  • ✅ Speaker analytics in dashboard

Method 3: Check Container Logs​

./opentr.sh logs celery-worker | grep -i pyannote

Success indicators (./opentr.sh logs backend for the native diarizer, ./opentr.sh logs celery-worker for the in-process PyAnnote fallback):

✅ "diar-native models already provisioned" / "diar-native models exported to ..."
✅ "Loading PyAnnote v4 pipeline: pyannote/speaker-diarization-community-1"
✅ "Loaded PyAnnote v4 model: pyannote/speaker-diarization-community-1"

Error indicators:

"diar-native provisioning failed (exit 5)" — TOKEN_DENIED, native engine
"Failed to load v4 model ... Trying fallback" — in-process engine falling back to 3.1
HTTP 403 / PermissionError mentioning speaker-diarization-community-1

Troubleshooting​

Error: "Cannot access gated repository" / HTTP 403 / exit 5 (TOKEN_DENIED)​

Cause: The speaker-diarization-community-1 agreement was not accepted by the account that issued HUGGINGFACE_TOKEN, or the token itself is invalid.

What this looks like now: the native diarizer's model export runs at backend startup and exits with code 5 (TOKEN_DENIED) on a rejected token. That failure is never fatal to the stack — /readyz stays 503 for the native diarizer and every diarization job falls back to the in-process PyAnnote engine, which loads the identical gated repo and hits the identical 403. The practical result is a healthy-looking stack with no working diarizer, not a crash. Look for diar-native provisioning failed (exit 5) in the backend's startup log.

Solution:

  1. Confirm the agreement was accepted (see Step 3) — by the same HuggingFace account that generated HUGGINGFACE_TOKEN. A token from one account and an "Agree and access repository" click from another fails identically to a token that never accepted anything.
  2. Check HUGGINGFACE_TOKEN is correct in .env
  3. Regenerate the token if needed
  4. Restart OpenTranscribe: ./opentr.sh restart-backend (re-runs provisioning) or ./opentr.sh restart-all

Error: "Invalid HuggingFace token"​

Cause: Token format incorrect or expired

Solution:

  1. Verify token starts with hf_
  2. Check for extra spaces or quotes in .env
  3. Regenerate token from HuggingFace settings
  4. Update .env and restart

Models Download on Every Restart​

Cause: Model cache not persisting

Solution:

  1. Check MODEL_CACHE_DIR in .env (default: ./models)
  2. Verify directory permissions:
    ls -la models/
    # Should be owned by user running Docker
  3. Fix permissions:
    ./scripts/fix-model-permissions.sh

Slow Model Download​

Cause: Large model files (~500MB total)

Solution:

  • Be patient on first setup (10-30 minutes)
  • Models are cached permanently after first download
  • Use wired connection for faster downloads
  • Check internet speed: https://fast.com

Speaker Diarization Not Working​

Checklist:

  • HuggingFace token configured in .env
  • speaker-diarization-community-1 agreement accepted — by the token's own account
  • Models downloaded successfully (check logs)
  • Speaker detection in Settings → Speaker Identification is set to Automatic (with a local transcription model, or a text-only cloud model on the full image) or to this server, not Off, and was not skipped for the file
  • Audio file has multiple speakers
  • MIN_SPEAKERS and MAX_SPEAKERS configured correctly

Security Considerations​

Token Security​

Your HuggingFace token is sensitive information:

  • ✅ DO: Store in .env file (git-ignored)
  • ✅ DO: Use read-only token permissions
  • ✅ DO: Regenerate if compromised
  • DON'T: Commit to version control
  • DON'T: Share publicly
  • DON'T: Use write permissions (unnecessary)

Revoking Access​

If your token is compromised:

  1. Go to https://huggingface.co/settings/tokens
  2. Click "Revoke" next to the compromised token
  3. Generate a new token
  4. Update .env with new token
  5. Restart OpenTranscribe

Model Caching​

Storage Location​

Models are cached at:

${MODEL_CACHE_DIR}/huggingface/hub/models--pyannote--speaker-diarization-community-1/

Default: ./models/huggingface/hub/models--pyannote--speaker-diarization-community-1/. This is the standard huggingface_hub cache layout pyannote.audio 4.x uses for every gated model, not a PyAnnote-specific directory — ./models/huggingface/hub/ also holds every other HuggingFace model the app downloads.

Disk Space​

speaker-diarization-community-1 is a single self-contained repo — segmentation, embedding, and PLDA weights bundled together — ~500MB total.

Plus, downloaded by scripts/download-models.sh:

  • WhisperX transcription models — the largest single item, and the one that varies most with WHISPER_MODEL
  • The wav2vec2 gender classifier (speaker attributes; OpenTranscribe runs no alignment model)
  • NLTK tokenizers and sentence-transformers embeddings
  • Chat reranker (cross-encoder, used by RAG chat)
  • OpenSearch neural-search models
  • Content-redaction models (PII / toxicity)

Total: several GB. It is not a fixed number — it depends on WHISPER_MODEL and on whether you set DOWNLOAD_ALL_OPENSEARCH_MODELS=true, so budget disk generously rather than to a specific figure.

Offline Use​

Once models are downloaded:

  • ✅ No internet required for transcription
  • ✅ Models cached permanently
  • ✅ Works in airgapped environments
  • Initial download requires internet

Alternative: Offline Installation​

For airgapped/offline environments:

  1. Download models on internet-connected machine:

    # Set token and download the pipeline the app actually loads
    export HUGGINGFACE_TOKEN=hf_your_token_here
    python3 -c "from pyannote.audio import Pipeline; Pipeline.from_pretrained('pyannote/speaker-diarization-community-1')"
  2. Copy model cache to offline machine:

    # On internet machine
    tar -czf pyannote-models.tar.gz ~/.cache/huggingface/hub/models--pyannote--speaker-diarization-community-1/

    # On offline machine
    tar -xzf pyannote-models.tar.gz -C /path/to/opentranscribe/models/huggingface/hub/
  3. Configure .env on offline machine:

    HUGGINGFACE_TOKEN=hf_your_token_here # Still required
    MODEL_CACHE_DIR=./models

See Offline Installation for complete airgapped setup guide.

Quick Reference​

URLs​

Environment Variables​

# Required for speaker detection on this server
HUGGINGFACE_TOKEN=hf_your_token_here

# Model cache location
MODEL_CACHE_DIR=./models

# Speaker detection range
MIN_SPEAKERS=1
MAX_SPEAKERS=20

Verification Commands​

# Check token configured
grep HUGGINGFACE_TOKEN .env

# Check the diarization pipeline was downloaded
ls -lh models/huggingface/hub/ | grep speaker-diarization-community-1

# Check backend startup for native diarizer provisioning
./opentr.sh logs backend | grep -i diar-native

# Check container logs for the in-process PyAnnote fallback
./opentr.sh logs celery-worker | grep -i pyannote

Next Steps​