Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
# -----------------------------------------------------------------------------
# Speakr Configuration: Standard Whisper API (Legacy)
#
# ⚠️ 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: See TRANSCRIPTION_CONNECTOR documentation in env.transcription.example
# For OpenAI Whisper, simply set:
# TRANSCRIPTION_API_KEY=your_key
# TRANSCRIPTION_MODEL=whisper-1 (or gpt-4o-transcribe-diarize for diarization)
#
# Instructions:
# 1. Copy this file to a new file named .env
# cp env.whisper.example .env
# 2. Fill in the required API keys and settings below.
# -----------------------------------------------------------------------------
# --- 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
# --- 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"}}
# --- LLM Timeout & Retry ---
# Read timeout for LLM requests in seconds (default 600). Increase for local
# models (Ollama, vLLM) that need more time for long transcripts.
# Connect/write timeouts stay at 30s so bad URLs fail fast.
# LLM_REQUEST_TIMEOUT=1800
#
# Max retries on timeout (default 2). Set to 0 for local inference to avoid
# queuing duplicate requests when your model is still processing the first one.
# LLM_MAX_RETRIES=0
# --- LLM Streaming Compatibility ---
# Some LLM servers (e.g., certain vLLM configurations) don't support OpenAI's
# stream_options parameter. If chat streaming hangs or fails, try disabling this.
# Note: When disabled, token usage tracking for chat will not be available.
# ENABLE_STREAM_OPTIONS=false
# --- Transcription Service (OpenAI Whisper API) ---
# New connector architecture is enabled by default.
# Available models:
# whisper-1 - Legacy, no diarization
# gpt-4o-transcribe - High quality, no diarization
# gpt-4o-mini-transcribe - Cost-effective, no diarization
# gpt-4o-transcribe-diarize - Speaker diarization! (recommended)
TRANSCRIPTION_BASE_URL=https://api.openai.com/v1
TRANSCRIPTION_API_KEY=your_openai_api_key
TRANSCRIPTION_MODEL=whisper-1
# Legacy model name (deprecated, use TRANSCRIPTION_MODEL instead)
# WHISPER_MODEL=whisper-1
# Comma-separated list of transcription model names offered in the per-upload
# model dropdown. Leave empty to hide the dropdown and always use the model
# configured above. Example: whisper-1,gpt-4o-transcribe,gpt-4o-transcribe-diarize
# TRANSCRIPTION_MODELS_AVAILABLE=
# Enable app-level chunking for the Mistral transcription connector (default: false).
# MISTRAL_ENABLE_CHUNKING=false
# --- 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
# Max tokens for auto title generation (default: 5000)
# TITLE_MAX_TOKENS=5000
# Max tokens for event extraction (default: 3000)
# EVENT_MAX_TOKENS=3000
# --- Session Security ---
# Flask secret key: signs session cookies and email/password-reset tokens. It
# does NOT encrypt stored data, so a lost key means a one-time re-login for
# everyone, never data loss. If unset, the app auto-generates a strong key and
# persists it under the instance directory (captured by a normal data-volume
# backup); the old publicly-known built-in default is refused at startup. Set
# this explicitly for multi-host deployments or to control key rotation:
# `python -c "import secrets; print(secrets.token_hex(32))"`.
# SECRET_KEY=change-me-to-a-long-random-string
# Only send the session cookie over HTTPS. STRONGLY recommended (true) for any
# HTTPS deployment. Default: false so plain-HTTP LAN setups keep working.
# SESSION_COOKIE_SECURE=false
# Days a sign-in with "Remember me" lasts (password or SSO). Default: 30.
# REMEMBER_COOKIE_DAYS=30
# --- Security headers ---
# The app sets X-Frame-Options, X-Content-Type-Options, Referrer-Policy,
# Permissions-Policy, a Content-Security-Policy, and (over HTTPS) HSTS, so a
# deployment without a hardening proxy is still protected. Set
# SECURITY_HEADERS_ENABLED=false only if your proxy already sets all of these.
# Override the CSP wholesale with CONTENT_SECURITY_POLICY, or tune HSTS with
# HSTS_HEADER (empty disables it, e.g. if your proxy already sends HSTS).
# SECURITY_HEADERS_ENABLED=true
# CONTENT_SECURITY_POLICY=
# HSTS_HEADER=max-age=63072000; includeSubDomains
# Number of trusted reverse-proxy hops in front of the app (X-Forwarded-For/
# Proto). Default: 1 (one proxy, e.g. nginx/Traefik). Increase if you chain
# additional proxies/load balancers so client IPs and HTTPS detection are read
# from the correct forwarded header.
# TRUSTED_PROXY_HOPS=1
# Set the logging level for the application.
# Options: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL="INFO"
# --- Large File Chunking ---
# Chunking is now connector-aware:
# - openai_transcribe/asr_endpoint: Handled internally, these settings ignored
# - openai_whisper: Uses these settings for files >25MB
#
# ENABLE_CHUNKING=false # Uncomment to disable (only for openai_whisper)
# Chunk limit - supports size (20MB) or duration (600s, 10m)
CHUNK_LIMIT=20MB
# Overlap between chunks (seconds)
CHUNK_OVERLAP_SECONDS=3
# --- 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
# Unsupported codecs - comma-separated list of codecs to exclude from supported list
# Use this if your transcription service doesn't support certain codecs
# Supported codecs by default: pcm_s16le, pcm_s24le, pcm_f32le, mp3, flac, opus, vorbis, aac
# Example: AUDIO_UNSUPPORTED_CODECS=opus,vorbis
# AUDIO_UNSUPPORTED_CODECS=
# --- 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
# Embedding model for Inquire-mode semantic search.
# Default is a local sentence-transformers model (no API needed).
# EMBEDDING_MODEL=all-MiniLM-L6-v2
# To use an OpenAI-compatible embeddings API instead of the local model,
# set the endpoint and API key below. When EMBEDDING_BASE_URL is set,
# Inquire embeddings are generated via the API instead of locally.
# EMBEDDING_BASE_URL=
#
# Chunking for search indexing. Diarized transcripts are chunked
# segment-aware ("Speaker: text" lines, whole turns kept together, speaker
# and timestamps stored per chunk). Set CHUNKING_STRATEGY=legacy to keep the
# old plain 500-character windows instead. Existing chunks are unaffected
# either way until a recording is reindexed.
# CHUNKING_STRATEGY=segment
# CHUNK_TARGET_CHARS=1400
#
# Embedding API robustness: inputs per request (providers cap this), and how
# long to skip a failing embeddings endpoint before probing again (searches
# fall back to keyword matching in the meantime).
# EMBEDDING_API_BATCH_SIZE=96
# EMBEDDING_API_COOLDOWN_SECONDS=120
# EMBEDDING_API_KEY=
# Optional fixed embedding dimensionality. Leave empty to auto-detect from
# the model/endpoint.
# EMBEDDING_DIMENSIONS=
# --- 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
# --- Incognito Mode (HIPAA-friendly) ---
# Enable incognito mode for privacy-sensitive transcriptions
# When enabled, users can upload recordings that are:
# - Processed on the server but NOT saved to the database
# - Stored only in the browser's sessionStorage (lost when tab closes)
# - Audio files are immediately deleted after processing
# Useful for HIPAA compliance or sensitive recordings
# Default: false (feature hidden)
ENABLE_INCOGNITO_MODE=false
# Make incognito mode the default for in-app recordings (toggle starts ON)
INCOGNITO_MODE_DEFAULT=false
# --- 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
# --- Video Passthrough to ASR ---
# Send original video files directly to ASR without extracting audio.
# Useful for custom ASR backends that handle video internally (e.g., multi-track audio extraction).
# When enabled, video files bypass audio extraction, codec conversion, and chunking.
# Only affects video files — audio uploads are processed normally.
# Default: false
# VIDEO_PASSTHROUGH_ASR=false
# --- 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
# --- Server-Side Recording Sessions (optional) ---
# Opt-in: in-app recordings stream audio chunks to the server as they record,
# instead of buffering the entire recording in browser RAM. This enables
# hours-long recordings and resume-on-reload if the tab is closed or refreshed.
# Default: false (recordings are buffered in the browser).
# ENABLE_SERVER_RECORDING_CHUNKS=false
#
# Absolute ceiling (in hours) on a single in-app recording when server
# chunking is enabled.
# RECORDING_MAX_HOURS=8
#
# Per-user soft storage cap (in bytes) for in-progress server recording
# sessions. Default: 5368709120 (5 GB).
# RECORDING_SESSION_MAX_BYTES_PER_USER=5368709120
#
# MediaRecorder timeslice (seconds): how often each in-app recording emits
# and uploads a chunk. Smaller = finer crash recovery; larger = fewer
# requests/files/DB writes. Default: 5 (range 1-60).
# RECORDING_CHUNK_SECONDS=5
#
# How many chunks to accumulate before committing session bookkeeping to the
# DB. Chunk files always hit disk immediately; only the row counters lag, and
# finalize re-derives the true count from disk. Raising this cuts DB write
# pressure at scale (important on SQLite, which is single-writer). Default: 1
# (commit every chunk). For many concurrent recorders, consider 6 (~30s at 5s
# chunks) and/or move to PostgreSQL.
# RECORDING_SESSION_COMMIT_BATCH_SIZE=1
#
# Inactivity TTL (hours) before an abandoned in-progress session is reaped.
# Abandoned sessions that have audio are auto-finalized into the user's
# library (not discarded), so a crashed or closed-tab recording is not lost.
# Default: 24.
# RECORDING_SESSION_TTL_HOURS=24
# How often (seconds) a sliced-upload ingest stamps its session as alive while
# it reassembles and ingests the file. A session that misses three stamps is
# treated as abandoned (its worker died, usually a container recreate) and a
# retry of the same file takes it over instead of waiting out the TTL.
# Default: 30 (minimum 5).
# RECORDING_SESSION_INGEST_HEARTBEAT_SECONDS=30
# --- Webhooks (optional) ---
# Outbound webhooks notify external services when events occur. Configured
# per-user in the UI.
# Master kill-switch for outbound webhook delivery (default: true).
# WEBHOOK_GLOBAL_ENABLED=true
# Maximum number of webhook subscriptions allowed per user (default: 10).
# WEBHOOK_MAX_PER_USER=10
# --- 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