Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python
15.3 KB
Raw Blame
# -----------------------------------------------------------------------------
# Speakr Configuration: WhisperX ASR Endpoint (with Voice Profiles)
#
# ⚠️  DEPRECATION NOTICE: This configuration style is still supported but
# we recommend using the new unified configuration in env.transcription.example
# which supports all transcription providers with auto-detection.
#
# Migration: Simply set ASR_BASE_URL and the connector will auto-detect ASR mode.
# USE_ASR_ENDPOINT=true is no longer required (but still works for backwards compat).
#
# This configuration is for use with the WhisperX ASR Service:
# https://github.com/murtaza-nasir/whisperx-asr-service
#
# Features supported:
# - Speaker diarization with pyannote/speaker-diarization-community-1
# - Voice profile embeddings (256-dimensional) for speaker recognition
# - Automatic speaker matching across recordings
# - Better timestamp alignment between speakers and words
#
# Instructions:
# 1. Copy this file to a new file named .env
#    cp config/env.whisperx.example .env
# 2. Fill in the required URLs, API keys, and settings below.
# 3. Set up WhisperX ASR Service (see installation guide)
# -----------------------------------------------------------------------------

# --- Text Generation Model (for summaries, titles, etc.) ---
TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL_API_KEY=your_openrouter_api_key
TEXT_MODEL_NAME=openai/gpt-4o-mini

# --- GPT-5 Specific Settings (only used with OpenAI API and GPT-5 models) ---
# If using GPT-5 models (gpt-5, gpt-5-mini, gpt-5-nano, gpt-5-chat-latest) with OpenAI API,
# these parameters will be used instead of temperature.
#
# By default GPT-5 parameter handling (reasoning_effort/verbosity,
# max_completion_tokens) activates only for GPT-5 model names on the official
# OpenAI API. Set this to force it on for GPT-5 models served through Azure AI
# Foundry or other gateways the URL check cannot detect:
# GPT5_FORCE_MODE=true
# Same, for a separately configured chat model (not inherited from the above):
# CHAT_GPT5_FORCE_MODE=true
#
# Example GPT-5 configuration:
# TEXT_MODEL_BASE_URL=https://api.openai.com/v1
# TEXT_MODEL_NAME=gpt-5-mini
#
# Reasoning effort: minimal, low, medium, high (default: medium)
# - minimal: Fastest responses, minimal reasoning tokens
# - low: Fast responses with basic reasoning
# - medium: Balanced reasoning and speed (recommended)
# - high: Maximum reasoning for complex tasks
GPT5_REASONING_EFFORT=medium
#
# Verbosity: low, medium, high (default: medium)
# - low: Concise responses
# - medium: Balanced detail
# - high: Detailed explanations
GPT5_VERBOSITY=medium

# --- Auto-Identify Speaker Response Format ---
# When enabled, auto-identify uses JSON Schema response format (structured outputs)
# to constrain LLM output to valid SPEAKER_XX keys. Falls back to json_object mode
# if the model doesn't support it. Leave disabled for widest model compatibility.
# AUTO_IDENTIFY_RESPONSE_SCHEMA=1

# --- Chat Model Configuration (Optional) ---
# Configure a separate model for real-time chat interactions.
# If not set, chat will use the TEXT_MODEL_* settings above.
#
# Use cases:
# - Use a faster model for chat while using a more capable model for summarization
# - Use a cheaper model for interactive chat to reduce costs
# - Use different service tiers for different operations
#
# CHAT_MODEL_API_KEY=your_chat_api_key
# CHAT_MODEL_BASE_URL=https://openrouter.ai/api/v1
# CHAT_MODEL_NAME=openai/gpt-4o

# --- Chat GPT-5 Settings (only used with OpenAI API and GPT-5 chat models) ---
# These settings allow independent control of GPT-5 parameters for chat.
# If not set, falls back to the main GPT5_* settings above.
#
# CHAT_GPT5_REASONING_EFFORT=medium
# CHAT_GPT5_VERBOSITY=medium

# --- Provider-Specific Request Parameters (Optional) ---
# A JSON object added to every request to the model, for settings such as
# reasoning effort that differ between providers. Examples:
#   OpenRouter:               {"reasoning": {"effort": "low"}}
#   OpenAI:                   {"reasoning_effort": "minimal"}
#   vLLM or llama.cpp, Qwen3: {"chat_template_kwargs": {"enable_thinking": false}}
# CHAT_MODEL_EXTRA_BODY is used only for a separately configured chat model.
# See docs/admin-guide/model-configuration.md.
# TEXT_MODEL_EXTRA_BODY={"reasoning": {"effort": "low"}}
# CHAT_MODEL_EXTRA_BODY={"reasoning": {"effort": "low"}}

# --- Transcription Service (WhisperX ASR Endpoint) ---
# New connector architecture auto-detects ASR mode when ASR_BASE_URL is set.
# USE_ASR_ENDPOINT=true is deprecated but still works for backwards compatibility.
#
# Note: ASR endpoints handle chunking internally - CHUNK_LIMIT settings are ignored.

# WhisperX ASR Endpoint URL (setting this auto-enables ASR mode)
# For containers in same docker-compose: Use container name and internal port
# Example: http://whisperx-asr:9000 (NOT the host port or external IP)
# For external ASR: Use http://192.168.1.100:9000 or http://asr.example.com:9000
ASR_BASE_URL=http://whisperx-asr:9000

# Deprecated: No longer needed, kept for backwards compatibility
# USE_ASR_ENDPOINT=true

# Speaker diarization options
ASR_DIARIZE=true
# ASR_MIN_SPEAKERS=1         # Hint for minimum speakers
# ASR_MAX_SPEAKERS=5         # Default maximum speakers

# Enable speaker embeddings for voice profile matching (WhisperX only)
ASR_RETURN_SPEAKER_EMBEDDINGS=true

# Transcription model
# Speakr sends a model with each request when one is configured: the upload's
# choice, a tag or folder default, or the default model chosen in the admin
# settings. Otherwise the request names no model and the ASR service uses its
# own default: PRELOAD_MODEL on whisperx-asr-service (or DEFAULT_MODEL from
# service version 0.4.2). Keep PRELOAD_MODEL set on the service, or choose a
# default model in Speakr's admin settings. TRANSCRIPTION_MODEL has no effect
# with this connector.

# Voice embedding compatibility check
# Voice profiles are only comparable with embeddings from the model that made
# them. If the backend starts returning embeddings from a different model,
# existing profiles silently stop matching. Speakr detects that at startup by
# sending a short bundled clip and comparing the result with a stored
# reference, and on demand from the admin page. Set to true to disable it.
# Costs one short transcription per run.
# DISABLE_VOICE_EMBEDDING_CHECK=false

# Voice profiles: a speaker needs at least this much speech in a recording
# before it trains a voice profile or is auto-labelled (seconds, default 15).
# VOICE_PROFILE_MIN_SPEECH_SECONDS=15

# --- Application Settings ---
# Set to "true" to allow user registration, "false" to disable
ALLOW_REGISTRATION=false
# Comma-separated list of allowed email domains for registration.
# Leave empty to allow all domains. Example: company.com,subsidiary.org
REGISTRATION_ALLOWED_DOMAINS=
SUMMARY_MAX_TOKENS=8000
CHAT_MAX_TOKENS=5000

# Set the logging level for the application.
# Options: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL="INFO"

# --- Audio Compression ---
# Automatically compress lossless uploads (WAV, AIFF) to save storage
AUDIO_COMPRESS_UPLOADS=true

# Target codec: mp3 (lossy, smallest), flac (lossless), opus (lossy, efficient)
AUDIO_CODEC=mp3

# Bitrate for lossy codecs (ignored for FLAC)
AUDIO_BITRATE=128k

# --- Admin User (created on first run) ---
ADMIN_USERNAME=admin
[email protected]
ADMIN_PASSWORD=changeme

# --- Help Center Link (optional) ---
# Adds a link to your own help/FAQ/tutorial page in the user menu.
# Label defaults to "Help Center" (localized) if not set.
# HELP_CENTER_URL=https://intranet.example.com/speakr-help
# HELP_CENTER_LABEL=Company FAQ

# --- Inquire Mode (AI search across all recordings) ---
# Set to "true" to enable semantic search and chat across all recordings
# Requires additional dependencies (already included in Docker image)
ENABLE_INQUIRE_MODE=false

# Agentic Inquire (opt-in beta). Replaces the single-shot Inquire pipeline
# with a tool-using agent that can search, list and read your recordings
# iteratively before answering, with live activity shown in the UI.
# Requires ENABLE_INQUIRE_MODE=true. Falls back to the classic pipeline on
# any agent failure.
# ENABLE_INQUIRE_AGENT=false
# Tool-calling mode: auto (probe native, fall back to prompted JSON),
# native, or prompt. Default: auto.
# INQUIRE_AGENT_TOOL_MODE=auto
# Loop limits (defaults shown): max tool steps per answer, per-tool-result
# token cap, wall-clock cap, and the conversation context budget that
# triggers history compaction.
# INQUIRE_AGENT_MAX_STEPS=8
# INQUIRE_AGENT_TOOL_RESULT_TOKENS=4000
# INQUIRE_AGENT_TIMEOUT_SECONDS=120
# INQUIRE_CONTEXT_BUDGET_TOKENS=24000
# Defaults for the per-user content availability toggles (users override in
# Account settings; transcripts are always available):
# INQUIRE_DEFAULT_ALLOW_SUMMARIES=true
# INQUIRE_DEFAULT_ALLOW_NOTES=false

# --- Automated File Processing (Black Hole Directory) ---
# Set to "true" to enable automated file processing
ENABLE_AUTO_PROCESSING=false

# --- Automated Export Settings ---
# Automatically export transcriptions and summaries to markdown files
ENABLE_AUTO_EXPORT=false

# Directory where exports will be saved (per-user subdirectories created automatically)
AUTO_EXPORT_DIR=/data/exports

# What to include in exports
AUTO_EXPORT_TRANSCRIPTION=true
AUTO_EXPORT_SUMMARY=true

# Processing mode: admin_only, user_directories, or single_user
# In user_directories mode, per-user subfolders of the watch directory may be
# named after the user id (user123 or 123) or the username itself (matching
# the per-user export folder names).
AUTO_PROCESS_MODE=admin_only

# Directory to watch for new audio files
AUTO_PROCESS_WATCH_DIR=/data/auto-process

# How often to check for new files (seconds)
AUTO_PROCESS_CHECK_INTERVAL=30

# How long to wait (seconds) to confirm a file has stopped changing before processing.
# Increase for slow network transfers (NFS, SMB). Default: 5
# AUTO_PROCESS_STABILITY_TIME=5

# Default username for single_user mode (only used if AUTO_PROCESS_MODE=single_user)
# AUTO_PROCESS_DEFAULT_USERNAME=admin

# --- Auto-Deletion & Retention Settings ---
# Enable automated deletion of old recordings
ENABLE_AUTO_DELETION=false

# Number of days to retain recordings (0 = disabled)
# Example: 90 means recordings older than 90 days will be processed
GLOBAL_RETENTION_DAYS=90

# Deletion mode: 'audio_only' keeps transcription, 'full_recording' deletes everything
# audio_only: Deletes audio file but keeps transcription/summary/notes (recommended)
# full_recording: Permanently deletes the entire recording from database
DELETION_MODE=audio_only

# --- Permission-Based Deletion Controls ---
# Allow all users to delete their recordings, or restrict to admins only
# true: All users can delete their own recordings (default)
# false: Only admins can delete recordings
USERS_CAN_DELETE=true

# Delete speaker profiles when all their recordings are removed.
# Default: false (speaker profiles and voice embeddings are preserved)
# Set to true for privacy-sensitive deployments where biometric voice data
# should not outlive the recordings it was derived from.
# DELETE_ORPHANED_SPEAKERS=false

# --- Internal Sharing Settings ---
# Enable user-to-user sharing of recordings (works independently of groups)
ENABLE_INTERNAL_SHARING=false

# Show usernames in the UI (when sharing/viewing shared recordings)
# true: Display usernames throughout the interface
# false: Hide usernames (users must know each other's usernames to share)
SHOW_USERNAMES_IN_UI=false

# --- Public Sharing Settings ---
# Enable creation of public share links (anonymous access)
# true: Users can create public links to share recordings externally (default)
# false: Public sharing is disabled globally
ENABLE_PUBLIC_SHARING=true

# Note: Admins can control public sharing permissions per-user in the admin dashboard
# even when ENABLE_PUBLIC_SHARING is true

# --- Video Retention ---
# When enabled, uploaded video files keep their video stream for in-browser playback
# The audio is extracted to a temp file for transcription, then cleaned up
# Also enables the in-app recorder's "Also record video" option for system-audio
# and mic+system recordings (captures the shared tab/window/screen as video)
# Default: false (video uploads extract audio only, video stream is discarded)
VIDEO_RETENTION=false

# Video bitrate cap (kbps) for in-app tab/window/screen video capture.
# Screen content compresses well; 2500 kbps keeps an hour of capture near 1 GB.
# RECORDING_VIDEO_KBPS=2500

# --- Concurrent Uploads ---
# Maximum number of simultaneous file uploads (default: 3)
MAX_CONCURRENT_UPLOADS=3

# --- Reliability / Security (optional) ---
# Hard wall-clock cap (seconds) on any single ffmpeg/ffprobe invocation, so a
# malformed or adversarial media file can't hang a processing worker forever.
# Default: 3600 (1 hour).
# FFMPEG_TIMEOUT_SECONDS=3600
#
# Per-endpoint rate limiting on auth routes (login, register, password reset).
# Set to false only if a reverse proxy in front of Speakr already rate-limits
# these. Default: true.
# RATELIMIT_ENABLED=true

# API token limits, one budget per token per kind of request (read, write,
# process). A request over the limit gets 429 with Retry-After.
# API_TOKEN_RATE_LIMIT_READ=120 per minute
# API_TOKEN_RATE_LIMIT_WRITE=30 per minute
# API_TOKEN_RATE_LIMIT_PROCESS=10 per minute
#
# Account limits: on each endpoint, all tokens of one user share one budget per
# kind, so another token adds no throughput. Counted per endpoint, like the
# token limits. Default: twice the token limit of the same kind.
# API_USER_RATE_LIMIT_READ=240 per minute
# API_USER_RATE_LIMIT_WRITE=60 per minute
# API_USER_RATE_LIMIT_PROCESS=20 per minute
#
# Active API tokens one account may hold; 0 means no limit. Default: 10.
# API_MAX_TOKENS_PER_USER=10
#
# Shared storage for the rate-limit counters. By default the counters are kept
# in the memory of each gunicorn worker (three in the standard image), so each
# limit, login and registration included, is in effect up to about three times
# its value. With a Redis or Valkey URI the limits are exact. The image includes
# the Redis client; the Redis server is run as a separate container. While the
# server is unreachable, counting falls back to memory.
# RATELIMIT_STORAGE_URI=redis://redis:6379/0

# Set to true only when the text, chat and embedding models all run on machines
# you control. API clients read it from /api/v1/capabilities (models_local).
# Default: false.
# MODELS_ARE_LOCAL=false

# Days to keep records of deleted recordings for API clients that sync with
# the changes feed (/api/v1/recordings/changes). Default: 90.
# RECORDING_TOMBSTONE_DAYS=90

# How long the previous webhook secret still signs Speakr-Signature-V2 after
# a rotation, in hours. Default: 24.
# WEBHOOK_SECRET_GRACE_HOURS=24

# --- Background Processing Queues ---
# Separate queues for transcription (slow) and summary (fast) jobs
# This prevents slow ASR jobs from blocking quick summary generation

# Transcription queue workers (for ASR processing, default: 2)
JOB_QUEUE_WORKERS=2

# Summary queue workers (for LLM summarization, default: 2)
SUMMARY_QUEUE_WORKERS=2

# Maximum retry attempts for failed jobs (default: 3)
JOB_MAX_RETRIES=3

# --- Docker Settings (rarely need to be changed) ---
# Database URI - SQLite (default) or PostgreSQL
SQLALCHEMY_DATABASE_URI=sqlite:////data/instance/transcriptions.db
# For PostgreSQL, use: postgresql://username:password@hostname:5432/database_name
# Example: postgresql://speakr:password@postgres:5432/speakr
UPLOAD_FOLDER=/data/uploads