Feature: name the 29 unset Speakr settings in the ASR example env file

[branch1337]

Description

An operator who copies config/env.asr.example to .env can set the settings that file names, and cannot see the others the process already reads. The file documents SHOW_USERNAMES_IN_UI (config/env.asr.example:337) and LLM_REQUEST_TIMEOUT (config/env.asr.example:86), then describes the connect and write timeouts as a fixed 30 seconds (config/env.asr.example:85) without naming LLM_CONNECT_TIMEOUT or LLM_WRITE_TIMEOUT. The same gap repeats for ASR auth and timeout, public-share HTML, the admin-email DNS check, webhook delivery, recording-session caps, and the Inquire and audio knobs below.

Those 29 names are already live. Unset, each one falls through to the default in the reader. The example never lists them, so an operator cannot discover the name, the default, or the safe value to uncomment. Admin docs name several of them (docs/admin-guide/system-settings.md:197 and :201, docs/admin-guide/webhooks.md:268, docs/admin-guide/recording-sessions.md:132, docs/user-guide/api-reference.md:1049, docs/user-guide/pwa.md:79, docs/admin-guide/model-configuration.md:455 and :570). The template an ASR install copies does not.

Affected Version

v0.10.16-alpha

Requested Feature

Add the 29 variables below to config/env.asr.example as comments, each set to the default the code already uses when the variable is absent. Copying the file to .env must keep today's behavior: a commented line is not exported, and the reader keeps its current default.

Leave every Python reader unchanged. Leave env.email.example, env.sso.example, env.transcription.example, env.whisper.example, and env.whisperx.example unchanged. Do not add email, SSO, other transcription connectors, S3, or ENABLE_CHUNKING / CHUNK_LIMIT / CHUNK_SIZE_MB / CHUNK_OVERLAP_SECONDS. The ASR template already says ASR endpoints chunk internally and that CHUNK_LIMIT is ignored (config/env.asr.example:102).

Proposed Implementation

Edit only config/env.asr.example. Insert each group under the heading that already covers that area. Do not add a second copy of a heading that is already in the file. No function changes. The readers listed in Root Cause Analysis stay as they are.

tests/test_documented_defaults.py read_example (tests/test_documented_defaults.py:93-102) and tests/e2e/smoke_env.py read_example (tests/e2e/smoke_env.py:30-38) skip blank lines and lines that start with #. Both load config/env.whisperx.example, not this file. Commented lines in env.asr.example do not change those tests. No new test is required. Do not uncomment the lines: an active assignment would change a copied .env from "unset, code default" to "set, same value", which is a behavior change this request does not ask for.

Ready to paste. Each # --- ... --- line is the existing section to extend, not a new section to append at the end of the file.

# --- LLM Timeout & Retry --- (config/env.asr.example:82, after LLM_MAX_RETRIES)
# Seconds to open the connection and to send the body. The read timeout is
# LLM_REQUEST_TIMEOUT above. Defaults: 30 and 30.
# LLM_CONNECT_TIMEOUT=30
# LLM_WRITE_TIMEOUT=30
#
# Rewrite title and summary prompts so the transcript is a shared prefix the
# provider can cache. Default false leaves the prompt text unchanged.
# TEXT_MODEL_CACHE_BREAKPOINTS applies only when the flag above is true, and
# only adds an explicit cache breakpoint for Anthropic-style models.
# PREFIX_CACHE_OPTIMIZED_PROMPTS=false
# TEXT_MODEL_CACHE_BREAKPOINTS=false

# --- Transcription Model Dropdown --- (config/env.asr.example:130, after TRANSCRIPTION_MODELS_AVAILABLE)
# Optional labels, same order as TRANSCRIPTION_MODELS_AVAILABLE. A missing
# label falls back to the model id. Leave empty to show the ids.
# TRANSCRIPTION_MODEL_LABELS=

# Mistral duration cap, next to MISTRAL_ENABLE_CHUNKING (config/env.asr.example:136-137).
# Read only when MISTRAL_ENABLE_CHUNKING=true. Chunks are cut at 80% of this.
# MISTRAL_MAX_DURATION_SECONDS=7200

# --- ASR endpoint --- (after ASR_BASE_URL, config/env.asr.example:108)
# Bearer token for an ASR endpoint that requires one. Empty sends no key.
# ASR_API_KEY=
# HTTP read timeout in seconds for a job sent to ASR_BASE_URL. Overrides the
# admin database setting asr_timeout_seconds. Default: 1800 (30 minutes).
# ASR_TIMEOUT=1800

# --- Audio Compression --- (after AUDIO_BITRATE, config/env.asr.example:198)
# Sample rate and channel count used when converting audio. 1 is mono.
# AUDIO_SAMPLE_RATE=44100
# AUDIO_CHANNELS=1
# Compression effort for codecs that take a level (FLAC).
# AUDIO_COMPRESSION_LEVEL=2

# --- Reliability / Security (optional) --- (next to FFMPEG_TIMEOUT_SECONDS, config/env.asr.example:389)
# Wall-clock cap in seconds on each ffprobe call. Minimum applied in code: 10.
# FFPROBE_TIMEOUT_SECONDS=60

# --- Session Security --- (after the SECRET_KEY comment, config/env.asr.example:152-160)
# Path of the generated key file when SECRET_KEY is unset. Empty uses
# secret_key under the instance directory.
# SECRET_KEY_FILE=
# Skip DNS and MX checks in scripts/create_admin.py only. Registration is unchanged.
# SKIP_EMAIL_DOMAIN_CHECK=false

# --- Public Sharing Settings --- (after ENABLE_PUBLIC_SHARING, config/env.asr.example:343)
# true: public share pages render the transcript in HTML on the server.
# false: the browser fills the transcript in. Default: false.
# READABLE_PUBLIC_LINKS=false

# Inquire embeddings (after EMBEDDING_API_COOLDOWN_SECONDS, config/env.asr.example:264)
# Attempts per embeddings request, and the base delay between them.
# EMBEDDING_API_MAX_RETRIES=3
# EMBEDDING_API_BACKOFF_SECONDS=1.5
# Ask the text model for speaker names with a strict JSON schema.
# Off unless set to 1, true, or yes.
# AUTO_IDENTIFY_RESPONSE_SCHEMA=false

# API limits (after API_TOKEN_RATE_LIMIT_PROCESS, config/env.asr.example:400)
# GET /api/v1/search, per token.
# API_SEARCH_RATE_LIMIT=30 per minute
# Files shared in from the phone share sheet, per account. In-app uploads
# are not counted.
# SHARE_TARGET_RATE_LIMIT=20 per hour

# --- Webhooks (optional) --- (after WEBHOOK_MAX_PER_USER, config/env.asr.example:480)
# Per-attempt HTTP timeout, in seconds.
# WEBHOOK_DELIVERY_TIMEOUT_SECONDS=10
# Retries before a delivery is a permanent failure.
# WEBHOOK_MAX_ATTEMPTS=5
# Consecutive failures before that subscription is paused.
# WEBHOOK_AUTOPAUSE_FAILURES=10
# How often a paused subscription gets one trial delivery. 0 disables trials.
# WEBHOOK_TRIAL_INTERVAL_SECONDS=3600
# How often the dispatcher looks for due deliveries.
# WEBHOOK_DISPATCHER_INTERVAL_SECONDS=5
# Regex of private hosts that may receive webhooks. Empty keeps the SSRF block.
# WEBHOOK_INTRANET_HOST_ALLOWLIST=

# --- Server-Side Recording Sessions (optional) --- (after RECORDING_CHUNK_SECONDS, config/env.asr.example:451)
# Largest accepted chunk, in bytes, and the slice size for large file uploads.
# RECORDING_SESSION_MAX_CHUNK_BYTES=16777216
# MIME types accepted for a live recording session.
# RECORDING_SESSION_ALLOWED_MIME_TYPES=audio/webm,audio/ogg,audio/mp4,audio/mpeg,audio/wav,audio/x-m4a,video/webm,video/mp4
# How often abandoned sessions are swept, in seconds. 0 disables the sweep.
# RECORDING_SESSION_CLEANUP_INTERVAL_SECONDS=3600

Additional Context

Commented defaults are the code defaults, so uncommenting a line is safe. AUTO_IDENTIFY_RESPONSE_SCHEMA=false is off, because only 1, true, and yes enable the schema (src/services/speaker_identification.py:168). Empty ASR_API_KEY, TRANSCRIPTION_MODEL_LABELS, SECRET_KEY_FILE, and WEBHOOK_INTRANET_HOST_ALLOWLIST match the unset behavior.

Do not document asr_timeout_seconds. It is a legacy alias read in the same expression as ASR_TIMEOUT (src/services/transcription/registry.py:210).

This request does not fix doc names that are not environment variables. ENABLE_FOLDERS in docs/admin-guide/system-settings.md:185 is the database setting enable_folders, and no code reads that env var. DEFAULT_RETENTION_DAYS on that page is GLOBAL_RETENTION_DAYS, already in the example. TIMEZONE only seeds default_timezone once. CHAT_MODEL and LLM_MODEL are usage-tracking labels, not model selectors. VAPID_PUBLIC_KEY is not read; keys are generated under CONFIG_DIR. HF_TOKEN and PRELOAD_MODEL belong to the WhisperX container. SSO_DISABLE_PASSWORD_LOGIN is missing from env.sso.example and is out of scope here.

PRESERVE_TEMP_AUDIO, PRESERVE_CHUNK_DEBUG, and CONFIG_DIR are also absent. They are debug and path overrides, not part of these 29.

The admin docs already describe the settings this file will name. They do not need a new page. docs/admin-guide/model-configuration.md already tells the operator to set PREFIX_CACHE_OPTIMIZED_PROMPTS and TRANSCRIPTION_MODEL_LABELS; after this change the ASR example agrees with that page.

[murtaza-nasir]

Thank you for the suggestion. The 29 settings are now listed in config/env.asr.example, commented out at their defaults. ASR_TIMEOUT is described as an override of the timeout in the admin settings, since that is how it is applied. This will be included in the next release.

[branch1337]

Awesome, this makes things much easier! I used to have trouble finding some environment variables that were documented but missing from the template.