Skip to content

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

Python

Add VIDEO_PASSTHROUGH_ASR option to send raw video files directly to ASR backends

Murtaza Nasir1d8a93b51e63
diff --git a/config/env.transcription.example b/config/env.transcription.example
index 01edea8c..abb58581 100644
--- a/config/env.transcription.example
+++ b/config/env.transcription.example
@@ -241,6 +241,14 @@ USERS_CAN_DELETE=true
# 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
diff --git a/docs/admin-guide/system-settings.md b/docs/admin-guide/system-settings.md
index d9e7ee07..a18d8616 100644
--- a/docs/admin-guide/system-settings.md
+++ b/docs/admin-guide/system-settings.md
@@ -173,6 +173,13 @@ Jobs are persisted to the database and survive application restarts. If Speakr r
**VIDEO_RETENTION**: When enabled, uploaded video files keep their video stream for in-browser playback instead of extracting audio and discarding the video. The audio is extracted to a temporary file for transcription only, then cleaned up after processing. The video renders with a native `<video>` player alongside the transcript, with full seeking support via HTTP Range requests. All player controls (play/pause, seek, speed, volume) work identically. Ideal for presentations, lectures, and screen recordings. Default: `false`.
+### Video Passthrough to ASR
+
+**VIDEO_PASSTHROUGH_ASR**: When enabled, original video files are sent directly to the ASR backend without extracting audio first. This is useful for custom ASR backends that accept video files and handle audio extraction internally — for example, containers that extract multiple audio tracks from a video for separate processing. When active, video files bypass audio extraction, codec conversion, and chunking entirely. Audio file uploads are unaffected. This setting is independent of `VIDEO_RETENTION` — you can use either or both. Default: `false`.
+
+!!! warning
+ Only enable this if your ASR backend actually accepts video files. Standard services like OpenAI's Whisper API will reject video input.
+
### Concurrent Uploads
**MAX_CONCURRENT_UPLOADS**: Controls how many files can be uploaded simultaneously when batch uploading. Higher values speed up batch uploads but use more bandwidth and server resources. Default: `3`.
@@ -220,6 +227,9 @@ DELETE_ORPHANED_SPEAKERS=false
# Video retention (keep video files for playback)
VIDEO_RETENTION=false
+# Video passthrough (send raw video to ASR, for custom backends)
+# VIDEO_PASSTHROUGH_ASR=false
+
# Concurrent uploads (default: 3)
MAX_CONCURRENT_UPLOADS=3
diff --git a/docs/features.md b/docs/features.md
index 73ea16e9..6b7475b7 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -227,6 +227,10 @@ When enabled (`VIDEO_RETENTION=true`), uploaded video files preserve their video
<p style="text-align: center; margin-top: 0.5rem; font-style: italic; color: #666;">In-browser video playback alongside speaker-labeled transcript and summary</p>
</div>
+### Video Passthrough to ASR
+
+For advanced self-hosted setups, Speakr can send original video files directly to the ASR backend without extracting audio first (`VIDEO_PASSTHROUGH_ASR=true`). This is designed for custom ASR containers that accept video input and handle audio extraction internally — for example, backends that process multiple audio tracks from a single video file. When enabled, video uploads skip audio extraction, codec conversion, and chunking entirely, letting the ASR backend control the full pipeline. Audio file uploads continue to work normally. This setting is independent of `VIDEO_RETENTION` — you can combine both to keep the video for playback while also sending it raw to ASR.
+
### Playback Speed Control
Adjust audio playback speed from 0.5x to 3x on all audio/video players throughout the application. This is useful for quickly reviewing long recordings or slowing down complex content. Your speed preference is saved to localStorage and persists across sessions.
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 8821ce84..04479ddc 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -298,6 +298,19 @@ VIDEO_RETENTION=true
When enabled, the original video file is kept and served with a native `<video>` player. Audio is extracted to a temporary file for transcription only, then cleaned up automatically. All player controls (seek, speed, volume) work identically. This is particularly useful for presentations, lectures, and screen recordings where the visual context adds value. Storage overhead is modest — video streams are typically only 10-20% of the total file size for presentation-style content.
+#### Video Passthrough to ASR
+
+If you run a custom ASR backend that accepts video files directly (e.g., one that extracts multiple audio tracks internally), you can skip Speakr's audio extraction entirely:
+
+```bash
+VIDEO_PASSTHROUGH_ASR=true
+```
+
+When enabled, video files are sent as-is to the ASR connector — no audio extraction, codec conversion, or chunking is performed. This only affects video uploads; audio files are processed normally. You can combine this with `VIDEO_RETENTION=true` to also keep the video for in-browser playback.
+
+!!! warning
+ Only enable this if your ASR backend actually accepts video files. Standard transcription APIs (OpenAI, etc.) will reject raw video input.
+
#### Concurrent Upload Limit
Control how many files upload simultaneously when batch uploading:
diff --git a/src/api/recordings.py b/src/api/recordings.py
index 1bf05996..d02135e6 100644
--- a/src/api/recordings.py
+++ b/src/api/recordings.py
@@ -49,6 +49,7 @@ DELETION_MODE = os.environ.get('DELETION_MODE', 'full_recording') # 'audio_only
USERS_CAN_DELETE = os.environ.get('USERS_CAN_DELETE', 'true').lower() == 'true'
ENABLE_INTERNAL_SHARING = os.environ.get('ENABLE_INTERNAL_SHARING', 'false').lower() == 'true'
VIDEO_RETENTION = os.environ.get('VIDEO_RETENTION', 'false').lower() == 'true'
+VIDEO_PASSTHROUGH_ASR = os.environ.get('VIDEO_PASSTHROUGH_ASR', 'false').lower() == 'true'
USE_ASR_ENDPOINT = os.environ.get('USE_ASR_ENDPOINT', 'false').lower() == 'true'
ENABLE_CHUNKING = os.environ.get('ENABLE_CHUNKING', 'true').lower() == 'true'
@@ -1977,22 +1978,22 @@ def upload_file():
current_app.logger.warning(f"Failed to probe {original_filename} (timeout={probe_timeout}s): {e}. Will attempt conversion.")
codec_info = None
- # Video retention: skip conversion for videos, processing pipeline handles extraction
+ # Video retention/passthrough: skip conversion for videos, processing pipeline handles extraction
has_video = codec_info.get('has_video', False) if codec_info else False
- # Fallback: if probe failed but VIDEO_RETENTION is on, check file extension
+ # Fallback: if probe failed but VIDEO_RETENTION or VIDEO_PASSTHROUGH_ASR is on, check file extension
# to avoid silently discarding video from files we couldn't probe
- if codec_info is None and VIDEO_RETENTION and not has_video:
+ if codec_info is None and (VIDEO_RETENTION or VIDEO_PASSTHROUGH_ASR) and not has_video:
video_extensions = {'.mp4', '.mov', '.mkv', '.avi', '.webm', '.m4v', '.wmv', '.flv', '.ts', '.mts'}
file_ext = os.path.splitext(original_filename)[1].lower()
if file_ext in video_extensions:
has_video = True
current_app.logger.info(
f"Probe failed but file extension '{file_ext}' indicates video — "
- f"treating as video for VIDEO_RETENTION"
+ f"treating as video for {'VIDEO_PASSTHROUGH_ASR' if VIDEO_PASSTHROUGH_ASR else 'VIDEO_RETENTION'}"
)
- if VIDEO_RETENTION and has_video:
- current_app.logger.info(f"Video retention: keeping original video, skipping conversion")
+ if (VIDEO_RETENTION or VIDEO_PASSTHROUGH_ASR) and has_video:
+ current_app.logger.info(f"Video {'passthrough' if VIDEO_PASSTHROUGH_ASR else 'retention'}: keeping original video, skipping conversion")
else:
# Use shared conversion utility - handles ALL conversion needs (codec conversion + compression)
try:
diff --git a/src/config/app_config.py b/src/config/app_config.py
index cae52cd1..af3a1d70 100644
--- a/src/config/app_config.py
+++ b/src/config/app_config.py
@@ -66,6 +66,10 @@ AUDIO_COMPRESS_UPLOADS = os.environ.get('AUDIO_COMPRESS_UPLOADS', 'true').lower(
AUDIO_CODEC = os.environ.get('AUDIO_CODEC', 'mp3').lower() # mp3, flac, opus
AUDIO_BITRATE = os.environ.get('AUDIO_BITRATE', '128k') # For lossy codecs
+# Video passthrough - send original video files directly to ASR without extracting audio
+# Useful for custom ASR backends that handle video/multi-track audio internally
+VIDEO_PASSTHROUGH_ASR = os.environ.get('VIDEO_PASSTHROUGH_ASR', 'false').lower() == 'true'
+
# Unsupported codecs - comma-separated list of codecs to exclude from the default supported list
# Useful when your transcription service doesn't support certain codecs (e.g., vllm doesn't support opus)
# Example: AUDIO_UNSUPPORTED_CODECS=opus,vorbis
diff --git a/src/file_monitor.py b/src/file_monitor.py
index f5d2591e..f7755fba 100644
--- a/src/file_monitor.py
+++ b/src/file_monitor.py
@@ -23,6 +23,9 @@ from src.utils.audio_conversion import convert_if_needed
# Video retention - when enabled, video files keep their video stream for playback
VIDEO_RETENTION = os.environ.get('VIDEO_RETENTION', 'false').lower() == 'true'
+# Video passthrough - send original video files directly to ASR without extracting audio
+VIDEO_PASSTHROUGH_ASR = os.environ.get('VIDEO_PASSTHROUGH_ASR', 'false').lower() == 'true'
+
# Flask app components will be imported inside functions to avoid circular imports
class FileMonitor:
@@ -351,9 +354,9 @@ class FileMonitor:
# Check if this is a video file (for video retention logic)
has_video = codec_info.get('has_video', False) if codec_info else False
- # Video retention: skip conversion for videos, processing pipeline handles extraction
- if VIDEO_RETENTION and has_video:
- self.logger.info(f"Video retention: keeping original video, skipping conversion")
+ # Video passthrough or retention: skip conversion for videos
+ if (VIDEO_PASSTHROUGH_ASR or VIDEO_RETENTION) and has_video:
+ self.logger.info(f"Video {'passthrough' if VIDEO_PASSTHROUGH_ASR else 'retention'}: keeping original video, skipping conversion")
final_path = destination_path
else:
# Convert/compress file if necessary - convert_if_needed handles ALL conversion needs
diff --git a/src/tasks/processing.py b/src/tasks/processing.py
index aeebb4b5..52c6f1f4 100644
--- a/src/tasks/processing.py
+++ b/src/tasks/processing.py
@@ -29,7 +29,7 @@ from src.utils.ffprobe import get_codec_info, is_video_file, is_lossless_audio,
from 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, ConversionResult
from src.utils.error_formatting import format_error_for_storage
-from src.config.app_config import AUDIO_COMPRESS_UPLOADS, AUDIO_CODEC, AUDIO_BITRATE
+from src.config.app_config import AUDIO_COMPRESS_UPLOADS, AUDIO_CODEC, AUDIO_BITRATE, VIDEO_PASSTHROUGH_ASR
from src.audio_chunking import AudioChunkingService, ChunkProcessingError, ChunkingNotSupportedError
from src.config.app_config import (
ASR_DIARIZE, ASR_BASE_URL, ASR_RETURN_SPEAKER_EMBEDDINGS,
@@ -1497,7 +1497,16 @@ def transcribe_with_connector(app_context, recording_id, filepath, original_file
)
if is_video:
- if VIDEO_RETENTION:
+ if VIDEO_PASSTHROUGH_ASR:
+ # Video passthrough: send original video directly to ASR without audio extraction
+ current_app.logger.info(f"Video passthrough: sending original video to ASR (no audio extraction)")
+ actual_filepath = filepath # Send video as-is to connector
+ if VIDEO_RETENTION:
+ # Also keep the video for playback
+ recording.audio_path = filepath
+ recording.mime_type = mimetypes.guess_type(filepath)[0] or 'video/mp4'
+ db.session.commit()
+ elif VIDEO_RETENTION:
# Video retention: keep original video, extract audio to temp for transcription only
current_app.logger.info(f"Video container detected, retaining video and extracting audio to temp...")
try:
@@ -1545,37 +1554,42 @@ def transcribe_with_connector(app_context, recording_id, filepath, original_file
# - AUDIO_COMPRESS_UPLOADS setting (lossless compression)
connector_specs = connector.specifications
converted_filepath = None # Track converted file for cleanup and retry
+ video_passthrough_active = is_video and VIDEO_PASSTHROUGH_ASR
- 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 video_passthrough_active:
+ # Skip conversion and chunking — ASR backend handles the raw video
+ current_app.logger.info(f"Video passthrough: skipping codec conversion and chunking")
+ else:
+ 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)
+ )
- 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"
+ 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
)
- 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")
+
+ 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 diarize
if diarize is None:
@@ -1595,17 +1609,21 @@ 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)
- 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:
+ if video_passthrough_active:
should_chunk = False
- current_app.logger.warning("Chunking service is disabled (ENABLE_CHUNKING=false or service not initialized)")
+ current_app.logger.info(f"Video passthrough: chunking skipped (ASR backend handles internally)")
+ else:
+ 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:
+ should_chunk = False
+ current_app.logger.warning("Chunking service is disabled (ENABLE_CHUNKING=false or service not initialized)")
# Retry loop for handling format/codec errors with MP3 conversion
max_attempts = 2
@@ -1963,47 +1981,57 @@ def transcribe_incognito(filepath, original_filename, language=None, min_speaker
actual_content_type = mime_type
# Check if file is video and needs audio extraction
+ is_video = False
try:
is_video = is_video_file(filepath, timeout=10)
- if is_video:
- current_app.logger.info(f"[Incognito] Video detected, extracting audio...")
- audio_filepath, audio_mime_type = extract_audio_from_video(filepath, cleanup_original=False)
- actual_filepath = audio_filepath
- actual_content_type = audio_mime_type
- actual_filename = os.path.basename(audio_filepath)
except FFProbeError as e:
current_app.logger.warning(f"[Incognito] Failed to probe file: {e}")
# Check by extension
video_extensions = ['.mp4', '.mov', '.avi', '.mkv', '.webm', '.wmv', '.flv', '.m4v']
- if any(original_filename.lower().endswith(ext) for ext in video_extensions):
- audio_filepath, audio_mime_type = extract_audio_from_video(filepath, cleanup_original=False)
- actual_filepath = audio_filepath
- actual_content_type = audio_mime_type
- actual_filename = os.path.basename(audio_filepath)
+ is_video = any(original_filename.lower().endswith(ext) for ext in video_extensions)
+
+ video_passthrough_active = is_video and VIDEO_PASSTHROUGH_ASR
+
+ if is_video:
+ if VIDEO_PASSTHROUGH_ASR:
+ current_app.logger.info(f"[Incognito] Video passthrough: sending original video to ASR (no audio extraction)")
+ else:
+ current_app.logger.info(f"[Incognito] Video detected, extracting audio...")
+ try:
+ audio_filepath, audio_mime_type = extract_audio_from_video(filepath, cleanup_original=False)
+ actual_filepath = audio_filepath
+ actual_content_type = audio_mime_type
+ actual_filename = os.path.basename(audio_filepath)
+ except Exception as e:
+ current_app.logger.error(f"[Incognito] Failed to extract audio from video: {e}")
+ raise
# Convert audio format if needed
- try:
- needs_chunking_check = (
- chunking_service and
- chunking_service.needs_chunking(actual_filepath, False, connector_specs)
- )
+ if video_passthrough_active:
+ current_app.logger.info(f"[Incognito] Video passthrough: skipping codec conversion")
+ else:
+ try:
+ 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,
- delete_original=False,
- connector_specs=connector_specs
- )
+ conversion_result = convert_if_needed(
+ filepath=actual_filepath,
+ original_filename=actual_filename,
+ needs_chunking=needs_chunking_check,
+ is_asr_endpoint=False,
+ delete_original=False,
+ connector_specs=connector_specs
+ )
- if conversion_result.was_converted:
- current_app.logger.info(f"[Incognito] Audio converted: {conversion_result.original_codec} -> {conversion_result.final_codec}")
+ if conversion_result.was_converted:
+ current_app.logger.info(f"[Incognito] Audio converted: {conversion_result.original_codec} -> {conversion_result.final_codec}")
actual_filepath = conversion_result.output_path
actual_content_type = conversion_result.mime_type
actual_filename = os.path.basename(conversion_result.output_path)
- except Exception as e:
- current_app.logger.warning(f"[Incognito] Audio conversion check failed: {e}, proceeding with original")
+ except Exception as e:
+ current_app.logger.warning(f"[Incognito] Audio conversion check failed: {e}, proceeding with original")
# Get audio duration if chunking service is available
if chunking_service:
@@ -2020,8 +2048,12 @@ def transcribe_incognito(filepath, original_filename, language=None, min_speaker
language = user.transcription_language
# Check if chunking is needed
- should_chunk = (chunking_service and
- chunking_service.needs_chunking(actual_filepath, False, connector_specs))
+ if video_passthrough_active:
+ should_chunk = False
+ current_app.logger.info(f"[Incognito] Video passthrough: chunking skipped (ASR backend handles internally)")
+ else:
+ should_chunk = (chunking_service and
+ chunking_service.needs_chunking(actual_filepath, False, connector_specs))
current_app.logger.info(f"[Incognito] Starting transcription: diarize={should_diarize}, language={language}, chunking={should_chunk}")
diff --git a/tests/test_video_passthrough.py b/tests/test_video_passthrough.py
new file mode 100644
index 00000000..eb2c133b
--- /dev/null
+++ b/tests/test_video_passthrough.py
@@ -0,0 +1,435 @@
+"""
+Test suite for the VIDEO_PASSTHROUGH_ASR feature.
+
+Tests configuration, code path correctness, and interaction with VIDEO_RETENTION
+across all entry points (processing pipeline, upload handler, file monitor, incognito).
+Uses static analysis — no running server or real video files required.
+
+Run with: python tests/test_video_passthrough.py
+"""
+
+import os
+import re
+import sys
+import unittest
+from pathlib import Path
+
+TEST_DIR = os.path.dirname(os.path.abspath(__file__))
+PROJECT_ROOT = os.path.dirname(TEST_DIR)
+sys.path.insert(0, PROJECT_ROOT)
+
+
+def read_file(rel_path):
+ with open(os.path.join(PROJECT_ROOT, rel_path), 'r') as f:
+ return f.read()
+
+
+# Cache file contents once — they don't change during the run
+PROCESSING = read_file('src/tasks/processing.py')
+RECORDINGS = read_file('src/api/recordings.py')
+FILE_MONITOR = read_file('src/file_monitor.py')
+APP_CONFIG = read_file('src/config/app_config.py')
+ENV_EXAMPLE = read_file('config/env.transcription.example')
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def get_function_body(source, func_name):
+ """Extract the body of a top-level function from source code."""
+ pattern = rf'^def {func_name}\('
+ lines = source.split('\n')
+ start = None
+ for i, line in enumerate(lines):
+ if re.match(pattern, line):
+ start = i
+ break
+ if start is None:
+ return ''
+ # Collect until next top-level def or class or EOF
+ body_lines = [lines[start]]
+ for line in lines[start + 1:]:
+ if line and not line[0].isspace() and (line.startswith('def ') or line.startswith('class ')):
+ break
+ body_lines.append(line)
+ return '\n'.join(body_lines)
+
+
+def split_at_incognito(source):
+ """Split processing.py into main and incognito sections."""
+ marker = 'def transcribe_incognito('
+ idx = source.find(marker)
+ if idx == -1:
+ return source, ''
+ return source[:idx], source[idx:]
+
+
+PROCESSING_MAIN, PROCESSING_INCOGNITO = split_at_incognito(PROCESSING)
+
+
+# ===========================================================================
+# 1. Configuration
+# ===========================================================================
+
+class TestPassthroughConfig(unittest.TestCase):
+ """VIDEO_PASSTHROUGH_ASR env var is defined and defaults to false."""
+
+ FILES_THAT_NEED_IT = [
+ ('src/config/app_config.py', APP_CONFIG),
+ ('src/tasks/processing.py', PROCESSING),
+ ('src/api/recordings.py', RECORDINGS),
+ ('src/file_monitor.py', FILE_MONITOR),
+ ]
+
+ def test_defined_in_all_files(self):
+ for rel_path, content in self.FILES_THAT_NEED_IT:
+ with self.subTest(file=rel_path):
+ self.assertIn('VIDEO_PASSTHROUGH_ASR', content,
+ f"VIDEO_PASSTHROUGH_ASR missing from {rel_path}")
+
+ def test_default_is_false_everywhere(self):
+ for rel_path, content in self.FILES_THAT_NEED_IT:
+ match = re.search(
+ r"VIDEO_PASSTHROUGH_ASR\s*=\s*os\.environ\.get\('VIDEO_PASSTHROUGH_ASR',\s*'(\w+)'\)",
+ content
+ )
+ if match:
+ with self.subTest(file=rel_path):
+ self.assertEqual(match.group(1), 'false',
+ f"Default should be 'false' in {rel_path}")
+
+ def test_canonical_definition_in_app_config(self):
+ self.assertIn(
+ "VIDEO_PASSTHROUGH_ASR = os.environ.get('VIDEO_PASSTHROUGH_ASR', 'false').lower() == 'true'",
+ APP_CONFIG
+ )
+
+ def test_documented_in_env_example(self):
+ self.assertIn('VIDEO_PASSTHROUGH_ASR', ENV_EXAMPLE)
+
+ def test_processing_imports_from_config(self):
+ self.assertIn('VIDEO_PASSTHROUGH_ASR', PROCESSING)
+ # Should import from app_config, not read os.environ directly
+ self.assertIn('import', PROCESSING)
+ # Verify it's in an import line from app_config
+ import_lines = [l for l in PROCESSING.split('\n')
+ if 'from src.config.app_config import' in l]
+ found = any('VIDEO_PASSTHROUGH_ASR' in l for l in import_lines)
+ self.assertTrue(found, "processing.py should import VIDEO_PASSTHROUGH_ASR from app_config")
+
+
+# ===========================================================================
+# 2. Processing pipeline — main transcription path
+# ===========================================================================
+
+class TestProcessingMainPath(unittest.TestCase):
+ """Test transcribe_with_connector() video passthrough code paths."""
+
+ def test_passthrough_branch_exists_before_retention(self):
+ """VIDEO_PASSTHROUGH_ASR is checked before VIDEO_RETENTION in the is_video block."""
+ # Inside the `if is_video:` block, passthrough should be the first check
+ video_block_start = PROCESSING_MAIN.find('if is_video:')
+ self.assertNotEqual(video_block_start, -1)
+
+ after_video = PROCESSING_MAIN[video_block_start:]
+ passthrough_pos = after_video.find('if VIDEO_PASSTHROUGH_ASR:')
+ retention_pos = after_video.find('elif VIDEO_RETENTION:')
+
+ self.assertNotEqual(passthrough_pos, -1, "Missing VIDEO_PASSTHROUGH_ASR check in is_video block")
+ self.assertNotEqual(retention_pos, -1, "Missing elif VIDEO_RETENTION check")
+ self.assertLess(passthrough_pos, retention_pos,
+ "VIDEO_PASSTHROUGH_ASR should be checked before VIDEO_RETENTION")
+
+ def test_passthrough_does_not_call_extract_audio(self):
+ """The passthrough branch must not call extract_audio_from_video."""
+ video_block = PROCESSING_MAIN[PROCESSING_MAIN.find('if is_video:'):]
+ # Find the passthrough branch (from `if VIDEO_PASSTHROUGH_ASR:` to `elif VIDEO_RETENTION:`)
+ pt_start = video_block.find('if VIDEO_PASSTHROUGH_ASR:')
+ pt_end = video_block.find('elif VIDEO_RETENTION:')
+ passthrough_block = video_block[pt_start:pt_end]
+ self.assertNotIn('extract_audio_from_video', passthrough_block,
+ "Passthrough branch should NOT extract audio")
+
+ def test_passthrough_keeps_original_filepath(self):
+ """Passthrough sets actual_filepath = filepath (the original video)."""
+ video_block = PROCESSING_MAIN[PROCESSING_MAIN.find('if is_video:'):]
+ pt_start = video_block.find('if VIDEO_PASSTHROUGH_ASR:')
+ pt_end = video_block.find('elif VIDEO_RETENTION:')
+ passthrough_block = video_block[pt_start:pt_end]
+ self.assertIn('actual_filepath = filepath', passthrough_block)
+
+ def test_passthrough_with_retention_sets_recording_path(self):
+ """When both passthrough and retention are on, recording.audio_path is set."""
+ video_block = PROCESSING_MAIN[PROCESSING_MAIN.find('if is_video:'):]
+ pt_start = video_block.find('if VIDEO_PASSTHROUGH_ASR:')
+ pt_end = video_block.find('elif VIDEO_RETENTION:')
+ passthrough_block = video_block[pt_start:pt_end]
+ self.assertIn('if VIDEO_RETENTION:', passthrough_block,
+ "Passthrough branch should conditionally handle retention")
+ self.assertIn('recording.audio_path = filepath', passthrough_block)
+ self.assertIn("mimetypes.guess_type(filepath)", passthrough_block)
+
+ def test_video_passthrough_active_flag_set(self):
+ """video_passthrough_active flag is computed from is_video and VIDEO_PASSTHROUGH_ASR."""
+ self.assertIn('video_passthrough_active = is_video and VIDEO_PASSTHROUGH_ASR',
+ PROCESSING_MAIN)
+
+ def test_conversion_skipped_when_passthrough(self):
+ """convert_if_needed is inside an else block gated by video_passthrough_active."""
+ self.assertIn('if video_passthrough_active:', PROCESSING_MAIN)
+ # The conversion call should be in the else branch
+ flag_pos = PROCESSING_MAIN.find('video_passthrough_active = is_video and VIDEO_PASSTHROUGH_ASR')
+ after_flag = PROCESSING_MAIN[flag_pos:]
+ passthrough_if = after_flag.find('if video_passthrough_active:')
+ else_pos = after_flag.find('else:', passthrough_if)
+ convert_pos = after_flag.find('convert_if_needed(', else_pos)
+ self.assertGreater(convert_pos, else_pos,
+ "convert_if_needed should be in else branch after passthrough check")
+
+ def test_chunking_skipped_when_passthrough(self):
+ """Chunking evaluates to False when video_passthrough_active."""
+ # Find the chunking decision area after the flag
+ flag_pos = PROCESSING_MAIN.find('video_passthrough_active = is_video and VIDEO_PASSTHROUGH_ASR')
+ after_flag = PROCESSING_MAIN[flag_pos:]
+ self.assertIn('if video_passthrough_active:\n should_chunk = False', after_flag)
+
+ def test_conversion_still_runs_for_non_passthrough(self):
+ """convert_if_needed still runs when passthrough is off or file is audio."""
+ # The else branch of the passthrough check should contain convert_if_needed
+ self.assertIn('conversion_result = convert_if_needed(', PROCESSING_MAIN)
+
+ def test_chunking_still_evaluated_for_non_passthrough(self):
+ """Chunking is still evaluated normally when passthrough is not active."""
+ self.assertIn('chunking_service.needs_chunking(actual_filepath, False, connector_specs)',
+ PROCESSING_MAIN)
+
+
+# ===========================================================================
+# 3. Processing pipeline — VIDEO_RETENTION paths still intact
+# ===========================================================================
+
+class TestRetentionNotBroken(unittest.TestCase):
+ """Existing VIDEO_RETENTION behavior must be preserved."""
+
+ def test_retention_branch_still_extracts_audio(self):
+ """elif VIDEO_RETENTION branch still calls extract_audio_from_video."""
+ video_block = PROCESSING_MAIN[PROCESSING_MAIN.find('if is_video:'):]
+ ret_start = video_block.find('elif VIDEO_RETENTION:')
+ # Find next else: at the same indent level
+ after_ret = video_block[ret_start:]
+ else_pos = after_ret.find('\n else:')
+ retention_block = after_ret[:else_pos] if else_pos != -1 else after_ret[:500]
+ self.assertIn('extract_audio_from_video(filepath, cleanup_original=False)',
+ retention_block)
+
+ def test_default_branch_still_extracts_and_deletes(self):
+ """The final else branch extracts audio with default cleanup (deletes video)."""
+ video_block = PROCESSING_MAIN[PROCESSING_MAIN.find('if is_video:'):]
+ # The last else in the is_video block
+ self.assertIn('extract_audio_from_video(filepath)', video_block)
+
+ def test_temp_audio_cleanup_still_present(self):
+ """Temp audio from retention is still cleaned up after transcription."""
+ self.assertIn('is_video and VIDEO_RETENTION and audio_filepath', PROCESSING_MAIN)
+ self.assertIn('Cleaned up temp audio from video retention', PROCESSING_MAIN)
+
+
+# ===========================================================================
+# 4. Incognito path
+# ===========================================================================
+
+class TestIncognitoPassthrough(unittest.TestCase):
+ """Test passthrough in the incognito transcription path."""
+
+ def test_passthrough_flag_set_in_incognito(self):
+ """video_passthrough_active is computed in incognito path."""
+ self.assertIn('video_passthrough_active = is_video and VIDEO_PASSTHROUGH_ASR',
+ PROCESSING_INCOGNITO)
+
+ def test_passthrough_skips_extraction_in_incognito(self):
+ """When passthrough is on, incognito skips extract_audio_from_video."""
+ # The passthrough branch logs and does NOT extract
+ self.assertIn('[Incognito] Video passthrough: sending original video to ASR',
+ PROCESSING_INCOGNITO)
+
+ def test_passthrough_skips_conversion_in_incognito(self):
+ """When passthrough is on, incognito skips convert_if_needed."""
+ self.assertIn('[Incognito] Video passthrough: skipping codec conversion',
+ PROCESSING_INCOGNITO)
+
+ def test_passthrough_skips_chunking_in_incognito(self):
+ """When passthrough is on, incognito chunking is False."""
+ body = PROCESSING_INCOGNITO
+ self.assertIn('if video_passthrough_active:\n should_chunk = False', body)
+
+ def test_incognito_does_not_reference_video_retention(self):
+ """Incognito path should NOT reference VIDEO_RETENTION (no retention in incognito)."""
+ self.assertNotIn('VIDEO_RETENTION', PROCESSING_INCOGNITO)
+
+ def test_incognito_still_extracts_without_passthrough(self):
+ """Without passthrough, incognito still extracts audio from video."""
+ self.assertIn('extract_audio_from_video(filepath, cleanup_original=False)',
+ PROCESSING_INCOGNITO)
+
+ def test_incognito_still_converts_without_passthrough(self):
+ """Without passthrough, incognito still runs convert_if_needed."""
+ self.assertIn('convert_if_needed(', PROCESSING_INCOGNITO)
+
+
+# ===========================================================================
+# 5. Upload handler (recordings.py)
+# ===========================================================================
+
+class TestUploadHandlerPassthrough(unittest.TestCase):
+ """Test recordings.py upload handler respects VIDEO_PASSTHROUGH_ASR."""
+
+ def test_skip_conversion_for_passthrough_video(self):
+ """Upload handler skips conversion when passthrough or retention + video."""
+ self.assertIn('VIDEO_RETENTION or VIDEO_PASSTHROUGH_ASR) and has_video', RECORDINGS)
+
+ def test_extension_fallback_checks_passthrough(self):
+ """Extension-based video detection also fires for VIDEO_PASSTHROUGH_ASR."""
+ self.assertIn('VIDEO_RETENTION or VIDEO_PASSTHROUGH_ASR', RECORDINGS)
+
+ def test_convert_if_needed_still_in_else(self):
+ """convert_if_needed still runs for audio files or when both flags are off."""
+ self.assertIn('convert_if_needed(', RECORDINGS)
+
+ def test_passthrough_log_message(self):
+ """Upload handler logs which mode caused the skip."""
+ self.assertIn("'VIDEO_PASSTHROUGH_ASR'", RECORDINGS)
+
+
+# ===========================================================================
+# 6. File monitor
+# ===========================================================================
+
+class TestFileMonitorPassthrough(unittest.TestCase):
+ """Test file_monitor.py respects VIDEO_PASSTHROUGH_ASR."""
+
+ def test_passthrough_defined(self):
+ self.assertIn('VIDEO_PASSTHROUGH_ASR', FILE_MONITOR)
+
+ def test_skip_conversion_for_passthrough_or_retention(self):
+ """File monitor skips conversion when passthrough or retention + video."""
+ self.assertIn('VIDEO_PASSTHROUGH_ASR or VIDEO_RETENTION) and has_video', FILE_MONITOR)
+
+ def test_convert_if_needed_in_else_branch(self):
+ """convert_if_needed is in the else branch, not inside the skip block."""
+ lines = FILE_MONITOR.split('\n')
+ in_skip_block = False
+ found_else = False
+ for i, line in enumerate(lines):
+ if 'VIDEO_PASSTHROUGH_ASR or VIDEO_RETENTION) and has_video' in line:
+ in_skip_block = True
+ elif in_skip_block and line.strip().startswith('else:'):
+ in_skip_block = False
+ found_else = True
+ elif in_skip_block and 'convert_if_needed' in line:
+ self.fail(f"convert_if_needed inside skip block at line {i + 1}")
+ self.assertTrue(found_else, "Should have else branch after passthrough/retention skip")
+
+ def test_log_distinguishes_passthrough_from_retention(self):
+ """Log message indicates whether passthrough or retention caused the skip."""
+ self.assertIn("'passthrough'", FILE_MONITOR)
+ self.assertIn("'retention'", FILE_MONITOR)
+
+
+# ===========================================================================
+# 7. Audio files unaffected by passthrough
+# ===========================================================================
+
+class TestAudioUnaffected(unittest.TestCase):
+ """VIDEO_PASSTHROUGH_ASR must only affect video files, never audio."""
+
+ def test_passthrough_flag_gated_on_is_video(self):
+ """video_passthrough_active is always `is_video and VIDEO_PASSTHROUGH_ASR`."""
+ # Main path
+ self.assertIn('video_passthrough_active = is_video and VIDEO_PASSTHROUGH_ASR',
+ PROCESSING_MAIN)
+ # Incognito path
+ self.assertIn('video_passthrough_active = is_video and VIDEO_PASSTHROUGH_ASR',
+ PROCESSING_INCOGNITO)
+
+ def test_upload_handler_gated_on_has_video(self):
+ """Upload handler skip is gated on `has_video`."""
+ self.assertIn('and has_video', RECORDINGS)
+
+ def test_file_monitor_gated_on_has_video(self):
+ """File monitor skip is gated on `has_video`."""
+ self.assertIn('and has_video', FILE_MONITOR)
+
+
+# ===========================================================================
+# 8. Documentation
+# ===========================================================================
+
+class TestDocumentation(unittest.TestCase):
+ """VIDEO_PASSTHROUGH_ASR is documented in all relevant places."""
+
+ DOC_FILES = [
+ 'config/env.transcription.example',
+ 'docs/admin-guide/system-settings.md',
+ 'docs/features.md',
+ 'docs/getting-started/installation.md',
+ ]
+
+ def test_documented_in_all_relevant_files(self):
+ for rel_path in self.DOC_FILES:
+ content = read_file(rel_path)
+ with self.subTest(file=rel_path):
+ self.assertIn('VIDEO_PASSTHROUGH_ASR', content,
+ f"VIDEO_PASSTHROUGH_ASR missing from {rel_path}")
+
+ def test_env_example_commented_out_by_default(self):
+ """The env example has the option commented out (opt-in)."""
+ self.assertIn('# VIDEO_PASSTHROUGH_ASR=false', ENV_EXAMPLE)
+
+ def test_docs_warn_about_asr_compatibility(self):
+ """Docs warn that standard APIs will reject video input."""
+ system_settings = read_file('docs/admin-guide/system-settings.md')
+ installation = read_file('docs/getting-started/installation.md')
+ self.assertIn('reject', system_settings.lower())
+ self.assertIn('reject', installation.lower())
+
+
+# ===========================================================================
+# 9. Interaction matrix — structural verification
+# ===========================================================================
+
+class TestInteractionMatrix(unittest.TestCase):
+ """
+ Verify the 3-way branch structure in processing.py:
+ if VIDEO_PASSTHROUGH_ASR → passthrough
+ elif VIDEO_RETENTION → retention
+ else → default extraction
+ """
+
+ def test_three_way_branch_in_main_path(self):
+ """Main path has if/elif/else for passthrough/retention/default."""
+ video_block = PROCESSING_MAIN[PROCESSING_MAIN.find('if is_video:'):]
+ # All three branches present in order
+ pt_pos = video_block.find('if VIDEO_PASSTHROUGH_ASR:')
+ ret_pos = video_block.find('elif VIDEO_RETENTION:')
+ else_pos = video_block.find('\n else:', ret_pos)
+ self.assertNotEqual(pt_pos, -1)
+ self.assertNotEqual(ret_pos, -1)
+ self.assertNotEqual(else_pos, -1)
+ self.assertLess(pt_pos, ret_pos)
+ self.assertLess(ret_pos, else_pos)
+
+ def test_incognito_two_way_branch(self):
+ """Incognito has if/else for passthrough/extract (no retention)."""
+ video_block = PROCESSING_INCOGNITO[PROCESSING_INCOGNITO.find('if is_video:'):]
+ pt_pos = video_block.find('if VIDEO_PASSTHROUGH_ASR:')
+ else_pos = video_block.find('\n else:', pt_pos)
+ self.assertNotEqual(pt_pos, -1)
+ self.assertNotEqual(else_pos, -1)
+ # No VIDEO_RETENTION in incognito
+ incognito_video_block = video_block[:500]
+ self.assertNotIn('VIDEO_RETENTION', incognito_video_block)
+
+
+if __name__ == '__main__':
+ unittest.main(verbosity=2)