Skip to content

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

Python

Docs: add v0.9.0 env vars (embeddings, recording sessions, webhooks, token limits, session cookie) to env examples + install guide

Murtaza Nasir7a970c90f395
diff --git a/config/env.asr.example b/config/env.asr.example
index 158db342..9c1cb724 100644
--- a/config/env.asr.example
+++ b/config/env.asr.example
@@ -108,6 +108,15 @@ ASR_DIARIZE=true
# Common values: 600 (10 min), 1200 (20 min), 1800 (30 min), 3600 (1 hour)
# ASR_MAX_DURATION_SECONDS=7200
+# --- Transcription Model Dropdown ---
+# Comma-separated list of transcription model names offered in the per-upload
+# model dropdown. Leave empty to hide the dropdown and always use the
+# configured backend. Example: whisper-1,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
@@ -116,6 +125,15 @@ ALLOW_REGISTRATION=false
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 ---
+# Only send the session cookie over HTTPS. Set to true in HTTPS production
+# deployments. Default: false (so plain-HTTP local setups keep working).
+# SESSION_COOKIE_SECURE=false
# Timezone for displaying dates and times in the UI
# Use a valid TZ database name (e.g., "America/New_York", "Europe/London", "UTC")
@@ -151,6 +169,20 @@ ADMIN_PASSWORD=changeme
# Requires additional dependencies (already included in Docker image)
ENABLE_INQUIRE_MODE=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=
+# 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
@@ -244,10 +276,41 @@ INCOGNITO_MODE_DEFAULT=false
# Default: false (video uploads extract audio only, video stream is discarded)
VIDEO_RETENTION=false
+# --- 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
+# --- 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
+
+# --- 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
diff --git a/config/env.transcription.example b/config/env.transcription.example
index 5d91e020..61118125 100644
--- a/config/env.transcription.example
+++ b/config/env.transcription.example
@@ -84,6 +84,11 @@ TRANSCRIPTION_MODEL=gpt-4o-transcribe-diarize
# Legacy Whisper model name (used when TRANSCRIPTION_MODEL is not set)
# 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=
+
# =============================================================================
# ASR ENDPOINT CONFIGURATION (For self-hosted whisper services)
# =============================================================================
@@ -122,6 +127,9 @@ TRANSCRIPTION_MODEL=gpt-4o-transcribe-diarize
#
# To use a custom Mistral-compatible endpoint:
# TRANSCRIPTION_BASE_URL=https://api.mistral.ai
+#
+# Enable app-level chunking for the Mistral connector (default: false).
+# MISTRAL_ENABLE_CHUNKING=false
# =============================================================================
# VIBEVOICE CONFIGURATION (Self-hosted via vLLM)
@@ -214,9 +222,18 @@ ALLOW_REGISTRATION=false
# Leave empty to allow all domains. Example: company.com,subsidiary.org
REGISTRATION_ALLOWED_DOMAINS=
+# --- Session Security ---
+# Only send the session cookie over HTTPS. Set to true in HTTPS production
+# deployments. Default: false (so plain-HTTP local setups keep working).
+# SESSION_COOKIE_SECURE=false
+
# --- Token Limits ---
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
# --- Timezone ---
# Use a valid TZ database name (e.g., "America/New_York", "Europe/London", "UTC")
@@ -250,6 +267,20 @@ AUDIO_BITRATE=128k
# --- Inquire Mode (AI search across all recordings) ---
ENABLE_INQUIRE_MODE=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=
+# EMBEDDING_API_KEY=
+
+# Optional fixed embedding dimensionality. Leave empty to auto-detect from
+# the model/endpoint.
+# EMBEDDING_DIMENSIONS=
+
# --- Automated File Processing (Black Hole Directory) ---
ENABLE_AUTO_PROCESSING=false
# AUTO_PROCESS_MODE=admin_only
@@ -296,6 +327,36 @@ VIDEO_RETENTION=false
# Maximum number of simultaneous file uploads (default: 3)
MAX_CONCURRENT_UPLOADS=3
+# =============================================================================
+# 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
+
+# =============================================================================
+# WEBHOOKS (optional)
+# =============================================================================
+# Outbound webhooks notify external services when events occur (e.g. a
+# recording finishes processing). Configured per-user in the UI.
+
+# Master kill-switch for outbound webhook delivery. Set to false to disable
+# all webhook delivery globally. Default: true.
+# WEBHOOK_GLOBAL_ENABLED=true
+
+# Maximum number of webhook subscriptions allowed per user (default: 10).
+# WEBHOOK_MAX_PER_USER=10
+
# =============================================================================
# BACKGROUND PROCESSING
# =============================================================================
diff --git a/config/env.whisper.example b/config/env.whisper.example
index 4971fdf5..f664324f 100644
--- a/config/env.whisper.example
+++ b/config/env.whisper.example
@@ -92,6 +92,14 @@ 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
@@ -100,6 +108,15 @@ ALLOW_REGISTRATION=false
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 ---
+# Only send the session cookie over HTTPS. Set to true in HTTPS production
+# deployments. Default: false (so plain-HTTP local setups keep working).
+# SESSION_COOKIE_SECURE=false
# Timezone for displaying dates and times in the UI
# Use a valid TZ database name (e.g., "America/New_York", "Europe/London", "UTC")
@@ -148,6 +165,20 @@ ADMIN_PASSWORD=changeme
# Requires additional dependencies (already included in Docker image)
ENABLE_INQUIRE_MODE=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=
+# 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
@@ -241,10 +272,41 @@ INCOGNITO_MODE_DEFAULT=false
# Default: false (video uploads extract audio only, video stream is discarded)
VIDEO_RETENTION=false
+# --- 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
+# --- 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
+
+# --- 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
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 5eb2a95c..1a889d9a 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -349,6 +349,17 @@ MAX_CONCURRENT_UPLOADS=3 # default
Higher values speed up batch uploads but use more bandwidth and server resources.
+#### Server-Side Recording Sessions (optional)
+
+By default, in-app recordings are buffered in the browser's memory and uploaded when you press Stop, which limits how long a single recording can run. You can opt into server-side recording sessions instead, where audio chunks stream to the server as they are produced:
+
+```bash
+ENABLE_SERVER_RECORDING_CHUNKS=true
+RECORDING_MAX_HOURS=8 # default
+```
+
+When enabled, recordings are no longer constrained by browser RAM, so you can capture hours-long sessions, and an interrupted recording can resume if the tab is reloaded or closed. `RECORDING_MAX_HOURS` sets an absolute ceiling on a single recording (default 8 hours). For tuning the per-user storage cap and other details, see the [Server-Side Recording Sessions](../admin-guide/recording-sessions.md) guide.
+
#### Inquire Mode for Semantic Search
Inquire Mode transforms Speakr from a simple transcription tool into a knowledge base of all your recordings. When enabled, you can search across all your transcriptions using natural language questions: