feat: add HF_TOKEN environment variable fallback for diarization

Previously, users had to enter their Hugging Face token in the UI
for every transcription job that used diarization. Now the token
can be set via the HF_TOKEN environment variable, which is
especially useful for Docker deployments.

Changes:
- Add HFToken to backend config (reads from HF_TOKEN env var)
- Update PyAnnote adapter to fall back to env var when no UI token
- Update WhisperX adapter to fall back to env var when no UI token
- Update documentation to clarify both configuration options

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

internal/config/config.go

@@ -38,6 +38,9 @@ type Config struct {
 	SecureCookies  bool // Explicit control over Secure flag (for HTTPS deployments)
 	// OpenAI configuration
 	OpenAIAPIKey string
+
+	// Hugging Face configuration
+	HFToken string
 }
 
 // Load loads configuration from environment variables and .env file
@@ -66,6 +69,7 @@ func Load() *Config {
 		WhisperXEnv:    getEnv("WHISPERX_ENV", "data/whisperx-env"),
 		SecureCookies:  getEnv("SECURE_COOKIES", defaultSecure) == "true",
 		OpenAIAPIKey:   getEnv("OPENAI_API_KEY", ""),
+		HFToken:        getEnv("HF_TOKEN", ""),
 	}
 }
 

internal/transcription/adapters/pyannote_adapter.go

@@ -60,9 +60,9 @@ func NewPyAnnoteAdapter(envPath string) *PyAnnoteAdapter {
 		{
 			Name:        "hf_token",
 			Type:        "string",
-			Required:    true,
+			Required:    false,
 			Default:     nil,
-			Description: "HuggingFace token for model access (required)",
+			Description: "HuggingFace token for model access (optional if HF_TOKEN env var is set)",
 			Group:       "basic",
 		},
 		{
@@ -290,11 +290,16 @@ func (p *PyAnnoteAdapter) Diarize(ctx context.Context, input interfaces.AudioInp
 		return nil, fmt.Errorf("invalid parameters: %w", err)
 	}
 
-	// Check for required HF token
+	// Check for HF token - use param first, then fall back to environment variable
 	hfToken := p.GetStringParameter(params, "hf_token")
 	if hfToken == "" {
-		return nil, fmt.Errorf("HuggingFace token is required for PyAnnote diarization")
+		hfToken = os.Getenv("HF_TOKEN")
 	}
+	if hfToken == "" {
+		return nil, fmt.Errorf("HuggingFace token is required for PyAnnote diarization. Set HF_TOKEN environment variable or provide it in the UI")
+	}
+	// Store resolved token in params for buildPyAnnoteArgs
+	params["hf_token"] = hfToken
 
 	// Create temporary directory
 	tempDir, err := p.CreateTempDirectory(procCtx)

internal/transcription/adapters/whisperx_adapter.go

@@ -182,7 +182,7 @@ func NewWhisperXAdapter(envPath string) *WhisperXAdapter {
 			Type:        "string",
 			Required:    false,
 			Default:     nil,
-			Description: "HuggingFace token for diarization models",
+			Description: "HuggingFace token for diarization models (optional if HF_TOKEN env var is set)",
 			Group:       "advanced",
 		},
 
@@ -553,8 +553,12 @@ func (w *WhisperXAdapter) buildWhisperXArgs(input interfaces.AudioInput, params
 	args = append(args, "--beam_size", strconv.Itoa(w.GetIntParameter(params, "beam_size")))
 	args = append(args, "--patience", fmt.Sprintf("%.2f", w.GetFloatParameter(params, "patience")))
 
-	// HuggingFace token
-	if hfToken := w.GetStringParameter(params, "hf_token"); hfToken != "" {
+	// HuggingFace token - use param first, then fall back to environment variable
+	hfToken := w.GetStringParameter(params, "hf_token")
+	if hfToken == "" {
+		hfToken = os.Getenv("HF_TOKEN")
+	}
+	if hfToken != "" {
 		args = append(args, "--hf_token", hfToken)
 	}
 

web/project-site/src/docs/Configuration.mdx

@@ -28,6 +28,14 @@ Visit the following model pages and accept the user agreements for each:
 You will need to get a Hugging Face access token.
 1. Go to your Hugging Face [Settings](https://huggingface.co/settings/token).
 2. Create a new token with at least `read` access.
-3. Copy this token and add it to your `.env` file or environment variables as `HF_TOKEN`.
+3. Configure the token using one of these methods:
 
-After setting up the `HF_TOKEN`, you can enable Speaker Diarization in your Transcription Profiles or Advanced settings within Scriberr.
+**Option A: Environment Variable (Recommended for Docker)**
+Set the `HF_TOKEN` environment variable. For Docker users, add `-e HF_TOKEN=your_token_here` to your docker run command or add it to your docker-compose.yml.
+
+**Option B: UI Input**
+Enter the token directly in the Scriberr UI under Transcription Profile settings when configuring diarization.
+
+> **Note:** If the `HF_TOKEN` environment variable is set, you don't need to enter the token in the UI - it will be used automatically as a fallback.
+
+After setting up the token, you can enable Speaker Diarization in your Transcription Profiles or Advanced settings within Scriberr.

web/project-site/src/docs/Diarization.mdx

@@ -30,4 +30,6 @@ Visit the following model pages and accept the user agreements for each:
 You will need to get a Hugging Face access token.
 1. Go to your Hugging Face [Settings](https://huggingface.co/settings/token).
 2. Create a new token with at least `read` access.
-3. Copy this token and pase it in the UI under Diarization settings in the transcription profile.
+3. Configure the token using one of these methods:
+   - **Environment Variable:** Set `HF_TOKEN` (recommended for Docker deployments)
+   - **UI Input:** Paste the token in the Diarization settings within your transcription profile