Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
Fix connector chunking and add missing TEXT_MODEL docs
Murtaza Nasir3fdb48d1e141
diff --git a/README.md b/README.mdindex ec3f4d15..84efb25c 100644--- a/README.md+++ b/README.md@@ -119,6 +119,10 @@ docker compose up -d# Access at http://localhost:8899```+**Required API Keys:**+- `TRANSCRIPTION_API_KEY` - For speech-to-text (OpenAI) or `ASR_BASE_URL` for self-hosted+- `TEXT_MODEL_API_KEY` - For summaries, titles, and chat (OpenRouter or OpenAI)+### Transcription OptionsSpeakr uses a **connector-based architecture** that auto-detects your transcription provider:diff --git a/config/docker-compose.example.yml b/config/docker-compose.example.ymlindex 81901762..6d08e74c 100644--- a/config/docker-compose.example.yml+++ b/config/docker-compose.example.yml@@ -26,7 +26,9 @@ services:# - config/env.whisperx.example - WhisperX with voice profiles# - config/env.asr.example - Basic ASR with diarization#- # 3. Edit the .env file to add your API keys and settings.+ # 3. Edit the .env file to add your API keys:+ # - TRANSCRIPTION_API_KEY (for OpenAI) or ASR_BASE_URL (for self-hosted)+ # - TEXT_MODEL_API_KEY (REQUIRED for summaries, titles, and chat)## 4. Start Speakr:# docker compose up -ddiff --git a/config/env.transcription.example b/config/env.transcription.exampleindex edc91346..11d2d5e7 100644--- a/config/env.transcription.example+++ b/config/env.transcription.example@@ -16,6 +16,37 @@# 3. TRANSCRIPTION_MODEL contains 'gpt-4o' - uses OpenAI Transcribe connector# 4. Default - uses OpenAI Whisper connector with TRANSCRIPTION_MODEL or whisper-1+# =============================================================================+# TEXT GENERATION MODEL (REQUIRED for summaries, titles, chat)+# =============================================================================+# Speakr uses a text/LLM model for generating summaries, titles, and chat.+# This is separate from the transcription model (STT).+#+# You can use OpenRouter (recommended - access to many models) or direct OpenAI API.++# OpenRouter example (recommended - supports many models):+TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1+TEXT_MODEL_API_KEY=your_openrouter_api_key+TEXT_MODEL_NAME=openai/gpt-4o-mini++# OpenAI direct example:+# TEXT_MODEL_BASE_URL=https://api.openai.com/v1+# TEXT_MODEL_API_KEY=sk-your_openai_api_key+# TEXT_MODEL_NAME=gpt-4o-mini++# --- GPT-5 Specific Settings (only used with OpenAI API and GPT-5 models) ---+# Reasoning effort: minimal, low, medium, high (default: medium)+GPT5_REASONING_EFFORT=medium+# Verbosity: low, medium, high (default: medium)+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.+# CHAT_MODEL_API_KEY=your_chat_api_key+# CHAT_MODEL_BASE_URL=https://openrouter.ai/api/v1+# CHAT_MODEL_NAME=openai/gpt-4o+# =============================================================================# CONNECTOR SELECTION (Auto-detected if not set)# =============================================================================@@ -125,6 +156,99 @@ CHUNK_OVERLAP_SECONDS=3# TRANSCRIPTION_BASE_URL=http://localhost:8080/v1# TRANSCRIPTION_MODEL=Systran/faster-distil-whisper-large-v3+# =============================================================================+# APPLICATION SETTINGS+# =============================================================================++# --- Admin User (created on first run) ---+ADMIN_USERNAME=admin+ADMIN_PASSWORD=changeme++# --- Registration & Access ---+ALLOW_REGISTRATION=false++# --- Token Limits ---+SUMMARY_MAX_TOKENS=8000+CHAT_MAX_TOKENS=5000++# --- Timezone ---+# Use a valid TZ database name (e.g., "America/New_York", "Europe/London", "UTC")+TIMEZONE="UTC"++# --- Logging ---+LOG_LEVEL="INFO"++# =============================================================================+# AUDIO PROCESSING+# =============================================================================++# --- 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+# Example: AUDIO_UNSUPPORTED_CODECS=opus,vorbis+# AUDIO_UNSUPPORTED_CODECS=++# =============================================================================+# OPTIONAL FEATURES+# =============================================================================++# --- Inquire Mode (AI search across all recordings) ---+ENABLE_INQUIRE_MODE=false++# --- Automated File Processing (Black Hole Directory) ---+ENABLE_AUTO_PROCESSING=false+# AUTO_PROCESS_MODE=admin_only+# AUTO_PROCESS_WATCH_DIR=/data/auto-process++# --- Automated Export ---+ENABLE_AUTO_EXPORT=false+# AUTO_EXPORT_DIR=/data/exports++# --- Auto-Deletion & Retention ---+ENABLE_AUTO_DELETION=false+# GLOBAL_RETENTION_DAYS=90+# DELETION_MODE=audio_only++# --- Sharing Settings ---+ENABLE_INTERNAL_SHARING=false+ENABLE_PUBLIC_SHARING=true+# SHOW_USERNAMES_IN_UI=false++# --- Permission Controls ---+USERS_CAN_DELETE=true++# =============================================================================+# BACKGROUND PROCESSING+# =============================================================================++# Transcription queue workers (default: 2)+JOB_QUEUE_WORKERS=2++# Summary queue workers (default: 2)+SUMMARY_QUEUE_WORKERS=2++# Maximum retry attempts for failed jobs (default: 3)+JOB_MAX_RETRIES=3++# =============================================================================+# DOCKER/DATABASE SETTINGS+# =============================================================================++# Database URI - SQLite (default) or PostgreSQL+SQLALCHEMY_DATABASE_URI=sqlite:////data/instance/transcriptions.db+# For PostgreSQL: postgresql://username:password@hostname:5432/database_name++UPLOAD_FOLDER=/data/uploads+# =============================================================================# FUTURE: Additional Provider Notes# =============================================================================diff --git a/docs/getting-started.md b/docs/getting-started.mdindex b5387143..a26af5f5 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -19,77 +19,75 @@ cd speakr## Step 2: Download Configuration Files-Download the Docker Compose configuration and choose the appropriate environment template based on your transcription service:+Download the Docker Compose configuration and the unified environment template:```bash# Download docker compose examplewget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/docker-compose.example.yml -O docker-compose.yml-```--Now download the environment configuration template. You have two options depending on which transcription service you want to use.-For standard OpenAI Whisper API (recommended for most users):-```bash-wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.whisper.example -O .env+# Download the unified configuration template (supports all providers)+wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.transcription.example -O .env```-Or for a custom ASR endpoint with speaker diarization (requires additional ASR container - see note below):-```bash-wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.asr.example -O .env-```+The unified configuration auto-detects your transcription provider based on your settings:-> **Important:** The ASR endpoint option requires running an additional Docker container (`onerahmet/openai-whisper-asr-webservice`) alongside Speakr. For complete setup instructions including docker-compose configurations for both containers, see [Running ASR Service for Speaker Diarization](getting-started/installation.md#running-asr-service-for-speaker-diarization).+- **OpenAI with diarization**: Set `TRANSCRIPTION_MODEL=gpt-4o-transcribe-diarize`+- **Self-hosted ASR/WhisperX**: Set `ASR_BASE_URL=http://your-asr:9000`+- **Legacy Whisper**: Set `TRANSCRIPTION_MODEL=whisper-1`-## Step 3: Configure Your Transcription Service+> **Note:** For self-hosted ASR with speaker diarization, you'll need an additional Docker container. See [Running ASR Service for Speaker Diarization](getting-started/installation.md#running-asr-service-for-speaker-diarization) for complete setup instructions.-Open the `.env` file in your preferred text editor and configure it based on your chosen service.+## Step 3: Configure Your API Keys-### Option A: OpenAI Whisper Configuration+Open the `.env` file in your preferred text editor. Speakr requires **two types of API keys**:-If you're using OpenAI Whisper, you'll need to set up both the transcription service and the text generation model. The text generation model is used for creating summaries, generating titles, and powering the chat features.--Edit your `.env` file and update these key variables:+### Required: Text Generation Model (for summaries, titles, chat)```bash-# For text generation (summaries, chat, titles)+# For text generation - OpenRouter (recommended, access to many models)TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1TEXT_MODEL_API_KEY=your_openrouter_api_key_hereTEXT_MODEL_NAME=openai/gpt-4o-mini--# For transcription-TRANSCRIPTION_BASE_URL=https://api.openai.com/v1-TRANSCRIPTION_API_KEY=your_openai_api_key_here-WHISPER_MODEL=whisper-1```-The text model can use OpenRouter for access to various AI models, or you can point it directly to OpenAI by using the same base URL and API key as your transcription service. OpenRouter provides access to multiple models including GPT-4, Claude, and others, which can be more cost-effective for text generation tasks.+OpenRouter provides access to multiple models including GPT-4, Claude, and others. Alternatively, you can use OpenAI directly:-For OpenAI's latest GPT-5 models (`gpt-5`, `gpt-5-mini`, `gpt-5-nano`), you must use the OpenAI API directly with `TEXT_MODEL_BASE_URL=https://api.openai.com/v1`. See the [Model Configuration Guide](admin-guide/model-configuration.md) for detailed GPT-5 setup and optimization.+```bash+# For text generation - OpenAI direct+TEXT_MODEL_BASE_URL=https://api.openai.com/v1+TEXT_MODEL_API_KEY=sk-your_openai_api_key+TEXT_MODEL_NAME=gpt-4o-mini+```-### Option B: Custom ASR Endpoint Configuration+For OpenAI's latest GPT-5 models (`gpt-5`, `gpt-5-mini`, `gpt-5-nano`), you must use the OpenAI API directly. See the [Model Configuration Guide](admin-guide/model-configuration.md) for detailed GPT-5 setup.-> **Prerequisites:** This option requires running an additional ASR service container (`onerahmet/openai-whisper-asr-webservice`). You can either:->-> - Run both containers in the same Docker Compose stack (recommended) - see [complete setup guide](getting-started/installation.md#running-asr-service-for-speaker-diarization)-> - Run the ASR service separately on the same or different machine-> - Use an existing ASR service if you already have one deployed+### Required: Transcription Service-If you're using a custom ASR service like WhisperX or a self-hosted Whisper server, configure these variables:+Choose ONE of the following options:+**Option A: OpenAI with Speaker Diarization (Recommended)**```bash-# For text generation (summaries, chat, titles)-TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1-TEXT_MODEL_API_KEY=your_openrouter_api_key_here-TEXT_MODEL_NAME=openai/gpt-4o-mini--# Enable ASR endpoint-USE_ASR_ENDPOINT=true+TRANSCRIPTION_API_KEY=sk-your_openai_api_key+TRANSCRIPTION_MODEL=gpt-4o-transcribe-diarize+```+This provides high-quality transcription with automatic speaker identification - no GPU or self-hosted service required.-# ASR service URL (use container name if in same docker compose)+**Option B: Self-hosted ASR/WhisperX (Best for privacy)**+```bashASR_BASE_URL=http://whisper-asr:9000+ASR_DIARIZE=true+# Optional: Enable voice profiles (WhisperX only)+ASR_RETURN_SPEAKER_EMBEDDINGS=true+```+Requires running an additional ASR container. See [Running ASR Service for Speaker Diarization](getting-started/installation.md#running-asr-service-for-speaker-diarization) for setup instructions.++**Option C: Legacy Whisper (No diarization)**+```bash+TRANSCRIPTION_API_KEY=sk-your_openai_api_key+TRANSCRIPTION_MODEL=whisper-1```-When using an ASR endpoint, [speaker diarization](features.md#speaker-diarization) is automatically enabled, allowing Speakr to identify different speakers in your recordings. After transcription, you'll need to [identify speakers](user-guide/transcripts.md#speaker-identification) to build your speaker library. The ASR_BASE_URL should point to your ASR service. If you're running the ASR service in the same Docker Compose stack, use the container name and internal port (like `http://whisper-asr:9000`). For external services, use the full URL with the appropriate IP address or domain name.+When using ASR or OpenAI diarization models, [speaker diarization](features.md#speaker-diarization) is automatically enabled, allowing Speakr to identify different speakers in your recordings. After transcription, you'll need to [identify speakers](user-guide/transcripts.md#speaker-identification) to build your speaker library.## Step 4: Configure Admin Accountdiff --git a/src/api/system.py b/src/api/system.pyindex 94bb8cb7..a3d71a33 100644--- a/src/api/system.py+++ b/src/api/system.py@@ -126,6 +126,7 @@ def get_system_info():# Get transcription connector infotranscription_info = {'connector': 'unknown',+ 'model': None,'supports_diarization': USE_ASR_ENDPOINT, # Backwards compatible default'supports_speaker_embeddings': False,}@@ -138,6 +139,7 @@ def get_system_info():if connector:transcription_info = {'connector': registry.get_active_connector_name(),+ 'model': getattr(connector, 'model', None), # Model name if available'supports_diarization': connector.supports_diarization,'supports_speaker_embeddings': connector.supports(TranscriptionCapability.SPEAKER_EMBEDDINGS),}diff --git a/src/audio_chunking.py b/src/audio_chunking.pyindex f025b2f3..7e0f4dd4 100644--- a/src/audio_chunking.py+++ b/src/audio_chunking.py@@ -43,12 +43,16 @@ def get_effective_chunking_config("""Determine effective chunking configuration based on connector specs and ENV settings.- Priority order:- 1. If connector handles_chunking_internally=True → no app-level chunking- 2. If ENABLE_CHUNKING=false → no chunking- 3. If CHUNK_LIMIT or CHUNK_SIZE_MB is explicitly set → use ENV settings- 4. If connector has specs → use connector defaults (max_file_size or recommended_chunk_seconds)- 5. Fallback: 20MB size-based chunking+ Logic:+ 1. Gather connector constraints (max_duration_seconds, max_file_size_bytes)+ 2. Gather user settings (CHUNK_LIMIT, CHUNK_SIZE_MB, ENABLE_CHUNKING)+ 3. If connector has hard limits:+ - Chunking is REQUIRED (can't disable)+ - Use MIN(connector_limit, user_limit) - user can go smaller but not larger+ 4. If connector has no hard limits:+ - If handles_chunking_internally=True → no app chunking+ - If ENABLE_CHUNKING=false → no chunking+ - Otherwise use user settings or app defaultsArgs:connector_specs: Optional ConnectorSpecifications from the active connector@@ -57,126 +61,150 @@ def get_effective_chunking_config(EffectiveChunkingConfig with resolved settings"""overlap_seconds = int(os.environ.get('CHUNK_OVERLAP_SECONDS', '3'))+ enable_chunking_env = os.environ.get('ENABLE_CHUNKING', '').lower()- # Priority 1: Connector handles chunking internally- if connector_specs and connector_specs.handles_chunking_internally:- logger.debug("Chunking: Connector handles chunking internally, no app-level chunking needed")- return EffectiveChunkingConfig(- enabled=False,- mode='none',- limit_value=0,- overlap_seconds=overlap_seconds,- source='connector_internal'- )+ # --- Step 1: Determine connector's hard limits ---+ connector_duration_limit = None+ connector_size_limit_mb = None- # Priority 2: User explicitly disabled chunking- enable_chunking_env = os.environ.get('ENABLE_CHUNKING', '').lower()- if enable_chunking_env == 'false':- logger.debug("Chunking: Disabled via ENABLE_CHUNKING=false")- return EffectiveChunkingConfig(- enabled=False,- mode='none',- limit_value=0,- overlap_seconds=overlap_seconds,- source='disabled'- )+ if connector_specs:+ if connector_specs.max_duration_seconds:+ # Use recommended if available, otherwise 85% of max for safety+ if connector_specs.recommended_chunk_seconds:+ connector_duration_limit = connector_specs.recommended_chunk_seconds+ else:+ connector_duration_limit = int(connector_specs.max_duration_seconds * 0.85)++ if connector_specs.max_file_size_bytes:+ # Use 80% of max for safety margin+ connector_size_limit_mb = (connector_specs.max_file_size_bytes / (1024 * 1024)) * 0.8++ has_hard_limits = connector_duration_limit is not None or connector_size_limit_mb is not None++ # --- Step 2: Parse user settings ---+ user_duration_limit = None+ user_size_limit_mb = None- # Priority 3: User has set CHUNK_LIMIT or CHUNK_SIZE_MB explicitlychunk_limit = os.environ.get('CHUNK_LIMIT', '').strip()chunk_size_mb_env = os.environ.get('CHUNK_SIZE_MB', '').strip()if chunk_limit:- # Parse CHUNK_LIMIT (20MB, 600s, 10m)chunk_limit_upper = chunk_limit.upper()-- if chunk_limit_upper.endswith('MB'):- try:- size_mb = float(re.sub(r'[^0-9.]', '', chunk_limit_upper))- logger.debug(f"Chunking: Using ENV CHUNK_LIMIT={size_mb}MB")- return EffectiveChunkingConfig(- enabled=True,- mode='size',- limit_value=size_mb,- overlap_seconds=overlap_seconds,- source='env'- )- except ValueError:- logger.warning(f"Invalid CHUNK_LIMIT format: {chunk_limit}")-- elif chunk_limit_upper.endswith('S'):- try:- seconds = float(re.sub(r'[^0-9.]', '', chunk_limit_upper))- logger.debug(f"Chunking: Using ENV CHUNK_LIMIT={seconds}s")- return EffectiveChunkingConfig(- enabled=True,- mode='duration',- limit_value=seconds,- overlap_seconds=overlap_seconds,- source='env'- )- except ValueError:- logger.warning(f"Invalid CHUNK_LIMIT format: {chunk_limit}")-- elif chunk_limit_upper.endswith('M') and not chunk_limit_upper.endswith('MB'):- try:- minutes = float(re.sub(r'[^0-9.]', '', chunk_limit_upper))- logger.debug(f"Chunking: Using ENV CHUNK_LIMIT={minutes}m ({minutes * 60}s)")- return EffectiveChunkingConfig(- enabled=True,- mode='duration',- limit_value=minutes * 60,- overlap_seconds=overlap_seconds,- source='env'- )- except ValueError:- logger.warning(f"Invalid CHUNK_LIMIT format: {chunk_limit}")-+ try:+ if chunk_limit_upper.endswith('MB'):+ user_size_limit_mb = float(re.sub(r'[^0-9.]', '', chunk_limit_upper))+ elif chunk_limit_upper.endswith('S'):+ user_duration_limit = float(re.sub(r'[^0-9.]', '', chunk_limit_upper))+ elif chunk_limit_upper.endswith('M') and not chunk_limit_upper.endswith('MB'):+ user_duration_limit = float(re.sub(r'[^0-9.]', '', chunk_limit_upper)) * 60+ except ValueError:+ logger.warning(f"Invalid CHUNK_LIMIT format: {chunk_limit}")elif chunk_size_mb_env:- # Legacy CHUNK_SIZE_MBtry:- size_mb = float(chunk_size_mb_env)- logger.debug(f"Chunking: Using legacy ENV CHUNK_SIZE_MB={size_mb}MB")- return EffectiveChunkingConfig(- enabled=True,- mode='size',- limit_value=size_mb,- overlap_seconds=overlap_seconds,- source='env'- )+ user_size_limit_mb = float(chunk_size_mb_env)except ValueError:logger.warning(f"Invalid CHUNK_SIZE_MB format: {chunk_size_mb_env}")- # Priority 4: Use connector specifications- if connector_specs:- # Prefer max_file_size_bytes if set- if connector_specs.max_file_size_bytes:- size_mb = connector_specs.max_file_size_bytes / (1024 * 1024)- # Use 80% of max to leave safety margin- safe_size_mb = size_mb * 0.8- logger.debug(f"Chunking: Using connector max_file_size ({size_mb}MB, safe: {safe_size_mb}MB)")+ # --- Step 3: If connector has hard limits, chunking is REQUIRED ---+ if has_hard_limits:+ # Prefer duration-based if connector has duration limit+ if connector_duration_limit is not None:+ # Use minimum of connector limit and user limit (if user set one)+ if user_duration_limit is not None:+ effective_limit = min(connector_duration_limit, user_duration_limit)+ source = 'user_and_connector'+ logger.info(f"Chunking: Using MIN(connector={connector_duration_limit}s, user={user_duration_limit}s) = {effective_limit}s")+ else:+ effective_limit = connector_duration_limit+ source = 'connector_limit'+ logger.info(f"Chunking: Connector requires duration limit {effective_limit}s (max_duration={connector_specs.max_duration_seconds}s)")+return EffectiveChunkingConfig(enabled=True,- mode='size',- limit_value=safe_size_mb,+ mode='duration',+ limit_value=effective_limit,overlap_seconds=overlap_seconds,- source='connector_default'+ source=source)- # Fall back to recommended_chunk_seconds- if connector_specs.recommended_chunk_seconds:- logger.debug(f"Chunking: Using connector recommended_chunk_seconds={connector_specs.recommended_chunk_seconds}s")+ # Fall back to size-based if only size limit exists+ elif connector_size_limit_mb is not None:+ if user_size_limit_mb is not None:+ effective_limit = min(connector_size_limit_mb, user_size_limit_mb)+ source = 'user_and_connector'+ logger.info(f"Chunking: Using MIN(connector={connector_size_limit_mb:.1f}MB, user={user_size_limit_mb}MB) = {effective_limit:.1f}MB")+ else:+ effective_limit = connector_size_limit_mb+ source = 'connector_limit'+ logger.info(f"Chunking: Connector requires size limit {effective_limit:.1f}MB (max_size={connector_specs.max_file_size_bytes/(1024*1024):.1f}MB)")+return EffectiveChunkingConfig(enabled=True,- mode='duration',- limit_value=connector_specs.recommended_chunk_seconds,+ mode='size',+ limit_value=effective_limit,overlap_seconds=overlap_seconds,- source='connector_default'+ source=source)- # Priority 5: App defaults (only if ENABLE_CHUNKING wasn't explicitly 'false')- # If ENABLE_CHUNKING is not set or is 'true', use defaults+ # --- Step 4: No hard limits - chunking is optional ---++ # Connector handles chunking internally+ if connector_specs and connector_specs.handles_chunking_internally:+ logger.info("Chunking: Connector handles chunking internally, no app-level chunking needed")+ return EffectiveChunkingConfig(+ enabled=False,+ mode='none',+ limit_value=0,+ overlap_seconds=overlap_seconds,+ source='connector_internal'+ )++ # User explicitly disabled chunking+ if enable_chunking_env == 'false':+ logger.info("Chunking: Disabled via ENABLE_CHUNKING=false")+ return EffectiveChunkingConfig(+ enabled=False,+ mode='none',+ limit_value=0,+ overlap_seconds=overlap_seconds,+ source='disabled'+ )++ # User set explicit limits - use them+ if user_duration_limit is not None:+ logger.info(f"Chunking: Using user CHUNK_LIMIT={user_duration_limit}s")+ return EffectiveChunkingConfig(+ enabled=True,+ mode='duration',+ limit_value=user_duration_limit,+ overlap_seconds=overlap_seconds,+ source='env'+ )++ if user_size_limit_mb is not None:+ logger.info(f"Chunking: Using user CHUNK_LIMIT={user_size_limit_mb}MB")+ return EffectiveChunkingConfig(+ enabled=True,+ mode='size',+ limit_value=user_size_limit_mb,+ overlap_seconds=overlap_seconds,+ source='env'+ )++ # Connector has recommended settings (but no hard limits)+ if connector_specs and connector_specs.recommended_chunk_seconds:+ logger.info(f"Chunking: Using connector recommended={connector_specs.recommended_chunk_seconds}s")+ return EffectiveChunkingConfig(+ enabled=True,+ mode='duration',+ limit_value=connector_specs.recommended_chunk_seconds,+ overlap_seconds=overlap_seconds,+ source='connector_recommended'+ )++ # App defaultsif enable_chunking_env != 'false':- logger.debug("Chunking: Using app defaults (20MB size-based)")+ logger.info("Chunking: Using app defaults (20MB size-based)")return EffectiveChunkingConfig(enabled=True,mode='size',@@ -431,19 +459,25 @@ class AudioChunkingService:logger.warning(f"Invalid CHUNK_SIZE_MB format: {legacy_size}")return 'size', 20.0 # Ultimate fallback- def calculate_optimal_chunking(self, converted_size: float, total_duration: float) -> Tuple[int, float]:+ def calculate_optimal_chunking(self, converted_size: float, total_duration: float, connector_specs=None) -> Tuple[int, float]:"""Calculate optimal number of chunks and chunk duration based on the configured limit.-+Args:converted_size: Size of the converted audio file in bytestotal_duration: Total duration of the audio file in seconds-+ connector_specs: Optional ConnectorSpecifications with hard limits+Returns:Tuple of (num_chunks, chunk_duration_seconds)"""try:- mode, limit_value = self.parse_chunk_limit()+ # Use effective chunking config which respects connector hard limits+ chunking_config = get_effective_chunking_config(connector_specs)+ mode = chunking_config.mode+ limit_value = chunking_config.limit_value++ logger.info(f"Chunking config: mode={mode}, limit={limit_value}, source={chunking_config.source}")if mode == 'size':# Size-based chunking@@ -480,29 +514,30 @@ class AudioChunkingService:fallback_duration = total_duration / fallback_chunksreturn fallback_chunks, fallback_duration- def create_chunks(self, file_path: str, temp_dir: str) -> List[Dict[str, Any]]:+ def create_chunks(self, file_path: str, temp_dir: str, connector_specs=None) -> List[Dict[str, Any]]:"""Split audio file into overlapping chunks.-+First converts the file to MP3 format to get accurate size information,then calculates optimal chunk duration based on the actual MP3 file size.-+Args:file_path: Path to the source audio filetemp_dir: Directory to store temporary chunk files-+ connector_specs: Optional ConnectorSpecifications with hard limits+Returns:List of chunk information dictionaries"""chunks = []wav_path = None-+try:# Step 1: Convert to MP3 and get accurate size/duration infomp3_path, mp3_duration, mp3_size = self.convert_to_mp3_and_get_info(file_path, temp_dir)-- # Step 2: Calculate optimal chunking strategy- num_chunks, chunk_duration = self.calculate_optimal_chunking(mp3_size, mp3_duration)++ # Step 2: Calculate optimal chunking strategy (respects connector hard limits)+ num_chunks, chunk_duration = self.calculate_optimal_chunking(mp3_size, mp3_duration, connector_specs)# If only 1 chunk needed, no actual chunking requiredif num_chunks == 1:diff --git a/src/config/app_config.py b/src/config/app_config.pyindex 1016edcb..cd2a6a64 100644--- a/src/config/app_config.py+++ b/src/config/app_config.py@@ -68,7 +68,10 @@ _unsupported_codecs_str = os.environ.get('AUDIO_UNSUPPORTED_CODECS', '')AUDIO_UNSUPPORTED_CODECS = {c.strip().lower() for c in _unsupported_codecs_str.split(',') if c.strip()}# Create chunking service at module level so it can be imported by processing.py-chunking_service = AudioChunkingService(CHUNK_SIZE_MB, CHUNK_OVERLAP_SECONDS) if ENABLE_CHUNKING else None+# Always initialize the service - the needs_chunking() method will check ENABLE_CHUNKING+# and return False when appropriate. This allows connectors with hard limits (e.g.,+# max_duration_seconds) to still enforce chunking even when ENABLE_CHUNKING=false.+chunking_service = AudioChunkingService(CHUNK_SIZE_MB, CHUNK_OVERLAP_SECONDS)def initialize_config(app):diff --git a/src/services/transcription/connectors/openai_transcribe.py b/src/services/transcription/connectors/openai_transcribe.pyindex 18367f36..8ce3409f 100644--- a/src/services/transcription/connectors/openai_transcribe.py+++ b/src/services/transcription/connectors/openai_transcribe.py@@ -36,36 +36,49 @@ class OpenAITranscribeConnector(BaseTranscriptionConnector):PROVIDER_NAME = "openai_transcribe"# GPT-4o Transcribe models have specific constraints- # - 25MB file size limit- # - 1400 second max duration for diarize model- # - chunking_strategy="auto" handles files >30s internally+ # - 25MB file size limit (all models)+ # - Duration limits vary by model:+ # - gpt-4o-transcribe / gpt-4o-mini-transcribe: 1500 seconds (25 min)+ # - gpt-4o-transcribe-diarize: 1400 seconds (~23 min)+ # - chunking_strategy="auto" handles files internally up to the duration limit# Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm, flac, ogg, oga# NOT supported: opus (used by WhatsApp voice notes, Discord)++ # Default specifications (will be overridden per-model in __init__)SPECIFICATIONS = ConnectorSpecifications(max_file_size_bytes=25 * 1024 * 1024, # 25MB- max_duration_seconds=1400, # ~23.3 minutes max for diarize model+ max_duration_seconds=1400, # Default to most restrictive (diarize model)min_duration_for_chunking=30, # >30s needs chunking_strategy param- handles_chunking_internally=True, # Uses chunking_strategy="auto"+ handles_chunking_internally=False, # App must chunk files > max_duration_secondsrequires_chunking_param=True, # Must send chunking_strategy for >30s+ recommended_chunk_seconds=1200, # 20 minutes - safe marginunsupported_codecs=frozenset({'opus'}), # OpenAI API doesn't support opus)- # Models and their capabilities+ # Models and their capabilities with duration limitsMODELS = {'gpt-4o-transcribe': {'supports_diarization': False,+ 'max_duration_seconds': 1500, # 25 minutes+ 'recommended_chunk_seconds': 1200, # 20 minutes'description': 'High quality transcription'},'gpt-4o-mini-transcribe': {'supports_diarization': False,+ 'max_duration_seconds': 1500, # 25 minutes+ 'recommended_chunk_seconds': 1200, # 20 minutes'description': 'Cost-effective transcription'},'gpt-4o-mini-transcribe-2025-12-15': {'supports_diarization': False,+ 'max_duration_seconds': 1500, # 25 minutes+ 'recommended_chunk_seconds': 1200, # 20 minutes'description': 'Cost-effective transcription (dated version)'},'gpt-4o-transcribe-diarize': {'supports_diarization': True,+ 'max_duration_seconds': 1400, # ~23 minutes (more restrictive)+ 'recommended_chunk_seconds': 1200, # 20 minutes'description': 'Speaker diarization with labels A, B, C, D'}}@@ -84,6 +97,19 @@ class OpenAITranscribeConnector(BaseTranscriptionConnector):# Store model before calling super().__init__ since _validate_config needs itself.model = config.get('model', 'gpt-4o-transcribe')+ # Set model-specific specifications (override class defaults)+ # Use SPECIFICATIONS (uppercase) to shadow the class attribute+ model_info = self.MODELS.get(self.model, {})+ self.SPECIFICATIONS = ConnectorSpecifications(+ max_file_size_bytes=25 * 1024 * 1024, # 25MB (same for all)+ max_duration_seconds=model_info.get('max_duration_seconds', 1400),+ min_duration_for_chunking=30,+ handles_chunking_internally=False,+ requires_chunking_param=True,+ recommended_chunk_seconds=model_info.get('recommended_chunk_seconds', 1200),+ unsupported_codecs=frozenset({'opus'}),+ )+super().__init__(config)# Set up HTTP client with custom headersdiff --git a/src/tasks/processing.py b/src/tasks/processing.pyindex 922e5c3d..32954a8e 100644--- a/src/tasks/processing.py+++ b/src/tasks/processing.py@@ -27,6 +27,7 @@ from src.services.llm import is_using_openai_api, call_llm_completion, format_apfrom src.utils import extract_json_object, safe_json_loadsfrom src.utils.ffprobe import get_codec_info, is_video_file, is_lossless_audio, FFProbeErrorfrom src.utils.ffmpeg_utils import convert_to_mp3, extract_audio_from_video as ffmpeg_extract_audio, compress_audio, FFmpegError, FFmpegNotFoundError+from src.utils.audio_conversion import convert_if_needed, ConversionResultfrom src.utils.error_formatting import format_error_for_storagefrom src.config.app_config import AUDIO_COMPRESS_UPLOADS, AUDIO_CODEC, AUDIO_BITRATEfrom src.audio_chunking import AudioChunkingService, ChunkProcessingError, ChunkingNotSupportedError@@ -1017,11 +1018,14 @@ def transcribe_chunks_with_connector(connector, filepath, filename, mime_type, limport tempfilefrom src.services.transcription import TranscriptionRequest+ # Get connector specs for proper chunking (respects hard limits like max_duration_seconds)+ connector_specs = connector.specifications+with tempfile.TemporaryDirectory() as temp_dir:try:- # Create chunks+ # Create chunks (passes connector_specs for duration-based chunking if needed)current_app.logger.info(f"Creating chunks for large file: {filepath}")- chunks = chunking_service.create_chunks(filepath, temp_dir)+ chunks = chunking_service.create_chunks(filepath, temp_dir, connector_specs)if not chunks:raise ChunkProcessingError("No chunks were created from the audio file")@@ -1193,6 +1197,45 @@ def transcribe_with_connector(app_context, recording_id, filepath, original_filedb.session.commit()raise # Re-raise so job queue marks the job as failed+ # Validate and convert audio format if needed using unified conversion utility+ # This respects:+ # - connector_specs.unsupported_codecs (e.g., opus for OpenAI)+ # - AUDIO_UNSUPPORTED_CODECS environment variable (user-specified exclusions)+ # - AUDIO_COMPRESS_UPLOADS setting (lossless compression)+ connector_specs = connector.specifications+ converted_filepath = None # Track converted file for cleanup and retry++ try:+ # Check if chunking will be needed (affects which codecs are supported)+ needs_chunking_check = (+ chunking_service and+ chunking_service.needs_chunking(actual_filepath, False, connector_specs)+ )++ conversion_result = convert_if_needed(+ filepath=actual_filepath,+ original_filename=actual_filename,+ needs_chunking=needs_chunking_check,+ is_asr_endpoint=False, # Using connector architecture+ delete_original=False, # Keep original, we may need it for retry+ connector_specs=connector_specs+ )++ if conversion_result.was_converted:+ current_app.logger.info(+ f"Audio converted: {conversion_result.original_codec} → {conversion_result.final_codec}, "+ f"size: {conversion_result.original_size_mb:.1f}MB → {conversion_result.final_size_mb:.1f}MB"+ )+ converted_filepath = conversion_result.output_path+ actual_filepath = converted_filepath+ actual_content_type = conversion_result.mime_type+ actual_filename = os.path.basename(converted_filepath)+ except (FFmpegError, FFmpegNotFoundError) as conv_error:+ current_app.logger.error(f"Audio conversion failed: {conv_error}")+ raise # Let the job fail - can't process this file+ except Exception as e:+ current_app.logger.warning(f"Could not validate/convert audio: {e}, proceeding with original file")+# Determine if we should diarizeif diarize is None:# Use connector's default diarization setting@@ -1211,52 +1254,120 @@ def transcribe_with_connector(app_context, recording_id, filepath, original_file# 3. User's CHUNK_LIMIT setting → use their settings# 4. Connector defaults (max_file_size, recommended_chunk_seconds)# 5. App default (20MB)- connector_specs = connector.specifications- should_chunk = (- chunking_service and- chunking_service.needs_chunking(actual_filepath, False, connector_specs)- )-- if should_chunk:- # Use chunking for large files- file_size_mb = os.path.getsize(actual_filepath) / (1024 * 1024)- current_app.logger.info(f"File {actual_filepath} is large ({file_size_mb:.1f}MB), using chunking for transcription")- transcription_text = transcribe_chunks_with_connector(- connector, actual_filepath, actual_filename, actual_content_type, language- )- # Store as plain text (chunked transcription doesn't preserve diarization)- recording.transcription = transcription_text- current_app.logger.info(f"Chunked transcription completed: {len(transcription_text)} characters")+ current_app.logger.info(f"Chunking service available: {chunking_service is not None}")+ current_app.logger.info(f"Connector specs: max_duration={connector_specs.max_duration_seconds}s, "+ f"handles_internally={connector_specs.handles_chunking_internally}, "+ f"recommended_chunk={connector_specs.recommended_chunk_seconds}s")++ if chunking_service:+ should_chunk = chunking_service.needs_chunking(actual_filepath, False, connector_specs)+ current_app.logger.info(f"Chunking decision: should_chunk={should_chunk}")else:- # Build the transcription request for single file- with open(actual_filepath, 'rb') as audio_file:- request = TranscriptionRequest(- audio_file=audio_file,- filename=actual_filename,- mime_type=actual_content_type,- language=language,- diarize=should_diarize,- min_speakers=min_speakers,- max_speakers=max_speakers- )+ should_chunk = False+ current_app.logger.warning("Chunking service is disabled (ENABLE_CHUNKING=false or service not initialized)")- current_app.logger.info(f"Transcribing with connector: diarize={should_diarize}, language={language}")- response = connector.transcribe(request)+ # Retry loop for handling format/codec errors with MP3 conversion+ max_attempts = 2+ last_error = None- # Store the result- if response.segments and response.has_diarization():- # Store as JSON with segments (diarized format)- recording.transcription = response.to_storage_format()- current_app.logger.info(f"Transcription completed with {len(response.segments)} segments and {len(response.speakers or [])} speakers")- else:- # Store as plain text- recording.transcription = response.text- current_app.logger.info(f"Transcription completed: {len(response.text)} characters")+ for attempt in range(max_attempts):+ try:+ if should_chunk:+ # Use chunking for large files+ file_size_mb = os.path.getsize(actual_filepath) / (1024 * 1024)+ current_app.logger.info(f"File {actual_filepath} is large ({file_size_mb:.1f}MB), using chunking for transcription")+ transcription_text = transcribe_chunks_with_connector(+ connector, actual_filepath, actual_filename, actual_content_type, language+ )+ # Store as plain text (chunked transcription doesn't preserve diarization)+ recording.transcription = transcription_text+ current_app.logger.info(f"Chunked transcription completed: {len(transcription_text)} characters")+ else:+ # Build the transcription request for single file+ with open(actual_filepath, 'rb') as audio_file:+ request = TranscriptionRequest(+ audio_file=audio_file,+ filename=actual_filename,+ mime_type=actual_content_type,+ language=language,+ diarize=should_diarize,+ min_speakers=min_speakers,+ max_speakers=max_speakers+ )++ current_app.logger.info(f"Transcribing with connector: diarize={should_diarize}, language={language}")+ response = connector.transcribe(request)- # Store speaker embeddings if available- if response.speaker_embeddings:- recording.speaker_embeddings = response.speaker_embeddings- current_app.logger.info(f"Stored speaker embeddings for speakers: {list(response.speaker_embeddings.keys())}")+ # Store the result+ if response.segments and response.has_diarization():+ # Store as JSON with segments (diarized format)+ recording.transcription = response.to_storage_format()+ current_app.logger.info(f"Transcription completed with {len(response.segments)} segments and {len(response.speakers or [])} speakers")+ else:+ # Store as plain text+ recording.transcription = response.text+ current_app.logger.info(f"Transcription completed: {len(response.text)} characters")++ # Store speaker embeddings if available+ if response.speaker_embeddings:+ recording.speaker_embeddings = response.speaker_embeddings+ current_app.logger.info(f"Stored speaker embeddings for speakers: {list(response.speaker_embeddings.keys())}")++ # If we reach here, transcription succeeded+ break++ except Exception as e:+ last_error = e+ error_msg = str(e).lower()++ # Check if this is a format/codec error that might be fixed by MP3 conversion+ is_format_error = any(phrase in error_msg for phrase in [+ 'corrupted', 'unsupported', 'invalid', 'format', 'codec',+ 'could not find codec', 'audio file', 'decode'+ ])++ # Only retry with MP3 conversion on first attempt for format errors+ if attempt == 0 and is_format_error and not converted_filepath:+ current_app.logger.warning(f"Transcription failed with possible format error: {e}")+ current_app.logger.info(f"Attempting MP3 conversion and retry...")++ # Check if file is already MP3+ try:+ codec_info = get_codec_info(actual_filepath, timeout=10)+ audio_codec = codec_info.get('audio_codec', '').lower()+ needs_conversion = audio_codec != 'mp3'+ except FFProbeError:+ needs_conversion = not actual_filename.lower().endswith('.mp3')++ if needs_conversion:+ try:+ converted_filepath = convert_to_mp3(actual_filepath)+ current_app.logger.info(f"Successfully converted to MP3: {converted_filepath}")+ actual_filepath = converted_filepath+ actual_content_type = 'audio/mpeg'+ actual_filename = os.path.basename(converted_filepath)+ # Recalculate if chunking is needed after conversion+ should_chunk = (+ chunking_service and+ chunking_service.needs_chunking(actual_filepath, False, connector_specs)+ )+ continue # Retry with converted file+ except (FFmpegError, FFmpegNotFoundError) as conv_error:+ current_app.logger.error(f"Failed to convert to MP3: {conv_error}")+ # Fall through to raise original error+ else:+ current_app.logger.warning(f"File is already MP3 but still getting format error")++ # Not a format error or already retried - propagate the error+ raise++ # Clean up converted file if we created one and transcription succeeded+ if converted_filepath and os.path.exists(converted_filepath):+ try:+ os.remove(converted_filepath)+ current_app.logger.debug(f"Cleaned up converted file: {converted_filepath}")+ except OSError:+ pass # Best effort cleanup# Calculate and save transcription durationtranscription_end_time = time.time()@@ -1296,6 +1407,22 @@ def transcribe_with_connector(app_context, recording_id, filepath, original_fileerror_type = type(e).__name__current_app.logger.error(f"Connector transcription FAILED for recording {recording_id}: [{error_type}] {error_msg}", exc_info=True)+ # Handle timeout errors specifically - log the configured timeout for debugging+ if "timed out" in error_msg.lower() or "timeout" in error_msg.lower() or "Timeout" in error_type:+ try:+ from src.services.transcription import get_registry+ registry = get_registry()+ # Get timeout from connector config if available+ connector_timeout = getattr(registry.get_active_connector(), 'timeout', None)+ if connector_timeout:+ current_app.logger.error(f"Timeout details - configured connector timeout: {connector_timeout}s")+ else:+ # Fall back to database/env setting+ asr_timeout = SystemSetting.get_setting('asr_timeout_seconds', 1800)+ current_app.logger.error(f"Timeout details - configured timeout: {asr_timeout}s")+ except Exception:+ pass # Don't fail the error handling if we can't get timeout info+# Don't set recording.status = 'FAILED' here - let the job queue handle it# The job queue will decide whether to retry or permanently fail,# and only set FAILED status when all retries are exhausteddiff --git a/static/js/modules/composables/reprocess.js b/static/js/modules/composables/reprocess.jsindex 8b2e58ef..776f651f 100644--- a/static/js/modules/composables/reprocess.js+++ b/static/js/modules/composables/reprocess.js@@ -346,6 +346,29 @@ export function useReprocess(state, utils) {}} else if (statusData.status === 'FAILED') {stopReprocessingPoll(recordingId);++ // Fetch full recording data to get error details for display+ try {+ const failedResponse = await fetch(`/api/recordings/${recordingId}`);+ if (failedResponse.ok) {+ const failedData = await failedResponse.json();++ // Update in recordings list+ const currentIndex = recordings.value.findIndex(r => r.id === recordingId);+ if (currentIndex !== -1) {+ recordings.value[currentIndex] = failedData;+ }++ // Update selectedRecording to show error in transcription panel+ if (selectedRecording.value?.id === recordingId) {+ selectedRecording.value = failedData;+ await nextTick();+ }+ }+ } catch (err) {+ console.error('Failed to fetch error details:', err);+ }+showToast('Processing failed', 'fa-exclamation-circle');}} catch (error) {diff --git a/static/js/modules/composables/upload.js b/static/js/modules/composables/upload.jsindex 7c95e4c5..57f99f0b 100644--- a/static/js/modules/composables/upload.js+++ b/static/js/modules/composables/upload.js@@ -519,12 +519,24 @@ export function useUpload(state, utils) {processingProgress.value = 100;fileItem.status = 'failed';- // Fetch full data to get error details+ // Fetch full data to get error details and update UItry {const failedResponse = await fetch(`/api/recordings/${recordingId}`);if (failedResponse.ok) {const failedData = await failedResponse.json();fileItem.error = failedData.error_message || 'Processing failed on server.';++ // Update recordings list so error shows in detail view+ const galleryIndex = recordings.value.findIndex(r => r.id === recordingId);+ if (galleryIndex !== -1) {+ recordings.value[galleryIndex] = failedData;+ }++ // Update selectedRecording to show error in transcription panel+ if (selectedRecording.value?.id === recordingId) {+ selectedRecording.value = failedData;+ await nextTick();+ }} else {fileItem.error = 'Processing failed on server.';}diff --git a/templates/account.html b/templates/account.htmlindex c09727c2..0220dd3e 100644--- a/templates/account.html+++ b/templates/account.html@@ -1121,16 +1121,20 @@ curl "https://your-speakr-instance.com/api/recordings?token=YOUR_TOKEN_HERE"</co<h4 class="font-medium text-[var(--text-primary)] mb-2" data-i18n="aboutPage.speechRecognition">Speech Recognition</h4><div class="space-y-1 text-sm"><p class="text-[var(--text-secondary)]">- <span class="font-medium" data-i18n="aboutPage.whisperApi">Whisper API:</span>+ <span class="font-medium" data-i18n="aboutPage.model">Model:</span>+ <span id="transcription-model" class="font-mono text-xs bg-[var(--bg-tertiary)] px-2 py-0.5 rounded text-[var(--text-primary)] ml-1">Loading...</span>+ </p>+ <p class="text-[var(--text-secondary)]">+ <span class="font-medium" data-i18n="aboutPage.endpoint">Endpoint:</span><span id="whisper-endpoint" class="font-mono text-xs text-[var(--text-muted)] ml-1">Loading...</span></p><p class="text-[var(--text-secondary)]">- <span class="font-medium" data-i18n="aboutPage.asrEnabled">ASR Enabled:</span>+ <span class="font-medium" data-i18n="aboutPage.asrEnabled">ASR Enabled:</span><span id="asr-status" class="ml-1">Loading...</span></p><div id="asr-endpoint-row" style="display: none;"><p class="text-[var(--text-secondary)]">- <span class="font-medium" data-i18n="aboutPage.asrEndpoint">ASR Endpoint:</span>+ <span class="font-medium" data-i18n="aboutPage.asrEndpoint">ASR Endpoint:</span><span id="asr-endpoint" class="font-mono text-xs text-[var(--text-muted)] ml-1">-</span></p></div>@@ -2951,10 +2955,13 @@ curl "https://your-speakr-instance.com/api/recordings?token=YOUR_TOKEN_HERE"</codocument.getElementById('llm-endpoint').textContent = data.llm_endpoint;document.getElementById('llm-model').textContent = data.llm_model;- // Update Whisper/ASR info+ // Update Speech Recognition info+ // Display model name from connector info, with fallback+ const transcriptionModel = data.transcription?.model || data.transcription?.connector || 'whisper-1';+ document.getElementById('transcription-model').textContent = transcriptionModel;document.getElementById('whisper-endpoint').textContent = data.whisper_endpoint;document.getElementById('asr-status').textContent = data.asr_enabled ? 'Yes' : 'No';-+if (data.asr_enabled && data.asr_endpoint) {document.getElementById('asr-endpoint').textContent = data.asr_endpoint;document.getElementById('asr-endpoint-row').style.display = 'block';@@ -2963,6 +2970,7 @@ curl "https://your-speakr-instance.com/api/recordings?token=YOUR_TOKEN_HERE"</codocument.getElementById('system-version').textContent = 'Failed to load';document.getElementById('llm-endpoint').textContent = 'Failed to load';document.getElementById('llm-model').textContent = 'Failed to load';+ document.getElementById('transcription-model').textContent = 'Failed to load';document.getElementById('whisper-endpoint').textContent = 'Failed to load';document.getElementById('asr-status').textContent = 'Failed to load';}