Skip to content

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

Python
52.5 KB
Raw Blame
"""
Audio Chunking Service for Large File Processing with OpenAI Whisper API

This module provides functionality to split large audio files into smaller chunks
that comply with OpenAI's 25MB file size limit, process them individually,
and reassemble the transcriptions while maintaining accuracy and speaker continuity.
"""

import os
import json
import subprocess
import tempfile
import logging
import math
import re
from dataclasses import dataclass
from typing import List, Dict, Any, Optional, Tuple, TYPE_CHECKING
from datetime import datetime
import mimetypes

from src.utils.ffmpeg_utils import convert_to_mp3, decode_ffmpeg_output, FFmpegError, FFmpegNotFoundError

if TYPE_CHECKING:
    from src.services.transcription.base import ConnectorSpecifications

# Configure logging
logger = logging.getLogger(__name__)

# Wall-clock cap on ffmpeg/ffprobe subprocesses in the chunking path. Without
# it a malformed/adversarial media file can stall the subprocess forever and
# permanently wedge a job-queue worker. Shares the ffmpeg_utils env knob.
try:
    _SUBPROCESS_TIMEOUT_SECONDS = max(30, int(os.getenv('FFMPEG_TIMEOUT_SECONDS', '3600')))
except (TypeError, ValueError):
    _SUBPROCESS_TIMEOUT_SECONDS = 3600


@dataclass
class EffectiveChunkingConfig:
    """Effective chunking configuration after resolving connector specs and ENV settings."""
    enabled: bool
    mode: str  # 'size' or 'duration'
    limit_value: float  # MB for size, seconds for duration
    overlap_seconds: int
    source: str  # 'disabled', 'connector_internal', 'env', 'connector_default', 'app_default'


def get_effective_chunking_config(
    connector_specs: Optional['ConnectorSpecifications'] = None
) -> EffectiveChunkingConfig:
    """
    Determine effective chunking configuration based on connector specs and ENV settings.

    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 defaults

    Args:
        connector_specs: Optional ConnectorSpecifications from the active connector

    Returns:
        EffectiveChunkingConfig with resolved settings
    """
    overlap_seconds = int(os.environ.get('CHUNK_OVERLAP_SECONDS', '3'))
    enable_chunking_env = os.environ.get('ENABLE_CHUNKING', '').lower()

    # --- Step 1: Determine connector's hard limits ---
    connector_duration_limit = None
    connector_size_limit_mb = None

    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

    chunk_limit = os.environ.get('CHUNK_LIMIT', '').strip()
    chunk_size_mb_env = os.environ.get('CHUNK_SIZE_MB', '').strip()

    if chunk_limit:
        chunk_limit_upper = chunk_limit.upper()
        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:
        try:
            user_size_limit_mb = float(chunk_size_mb_env)
        except ValueError:
            logger.warning(f"Invalid CHUNK_SIZE_MB format: {chunk_size_mb_env}")

    # --- 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='duration',
                limit_value=effective_limit,
                overlap_seconds=overlap_seconds,
                source=source
            )

        # 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='size',
                limit_value=effective_limit,
                overlap_seconds=overlap_seconds,
                source=source
            )

    # --- 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 defaults. The ENABLE_CHUNKING=false case has already returned a
    # 'disabled' config above, so this is the only remaining path (the previous
    # 'final fallback: disabled' return here was unreachable dead code).
    logger.info("Chunking: Using app defaults (20MB size-based)")
    return EffectiveChunkingConfig(
        enabled=True,
        mode='size',
        limit_value=20.0,
        overlap_seconds=overlap_seconds,
        source='app_default'
    )

class AudioChunkingService:
    """Service for chunking large audio files and processing them with OpenAI Whisper API."""
    
    def __init__(self, max_chunk_size_mb: int = 20, overlap_seconds: int = 3, max_chunk_duration_seconds: int = None):
        """
        Initialize the chunking service.
        
        Args:
            max_chunk_size_mb: Maximum size for each chunk in MB (default 20MB for safety margin)
            overlap_seconds: Overlap between chunks in seconds for context continuity
            max_chunk_duration_seconds: Maximum duration for each chunk in seconds (optional)
        """
        self.max_chunk_size_mb = max_chunk_size_mb
        self.overlap_seconds = overlap_seconds
        self.max_chunk_size_bytes = max_chunk_size_mb * 1024 * 1024
        self.max_chunk_duration_seconds = max_chunk_duration_seconds
        self.chunk_stats = []  # Track processing statistics
        
    def needs_chunking(
        self,
        file_path: str,
        use_asr_endpoint: bool = False,
        connector_specs: Optional['ConnectorSpecifications'] = None
    ) -> bool:
        """
        Check if a file needs to be chunked based on connector specs, ENV settings, and file size.

        Priority order for chunking configuration:
        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
        5. Fallback: 20MB size-based chunking

        NOTE: For duration-based limits, this may return True even if chunking isn't needed,
        because we need to convert the file first to check duration. The actual chunking
        decision is made after conversion in calculate_optimal_chunking().

        Args:
            file_path: Path to the audio file
            use_asr_endpoint: DEPRECATED - use connector_specs instead
            connector_specs: Optional ConnectorSpecifications from the active connector

        Returns:
            True if file might need chunking, False otherwise
        """
        # Get effective chunking configuration
        chunking_config = get_effective_chunking_config(connector_specs)

        # If chunking is disabled (by connector or user), return False
        if not chunking_config.enabled:
            logger.info(f"Chunking disabled (source: {chunking_config.source})")
            return False

        # Legacy fallback: if no connector_specs provided, check use_asr_endpoint
        if connector_specs is None and use_asr_endpoint:
            logger.info("Chunking: ASR endpoint detected (legacy), no chunking needed")
            return False

        try:
            file_size = os.path.getsize(file_path)

            if chunking_config.mode == 'size':
                # For size-based limits, we can determine immediately
                chunk_size_bytes = chunking_config.limit_value * 1024 * 1024
                needs_it = file_size > chunk_size_bytes
                logger.info(f"Chunking check (size, source={chunking_config.source}): "
                           f"{file_size/1024/1024:.1f}MB vs limit {chunking_config.limit_value}MB - needs chunking: {needs_it}")
                return needs_it
            elif chunking_config.mode == 'duration':
                # For duration-based limits, we need to check the actual duration
                # Try to get duration without conversion first (fast check)
                duration = self.get_audio_duration(file_path)
                if duration:
                    needs_it = duration > chunking_config.limit_value
                    logger.info(f"Chunking check (duration, source={chunking_config.source}): "
                               f"{duration:.1f}s vs limit {chunking_config.limit_value}s - needs chunking: {needs_it}")
                    return needs_it
                else:
                    # Can't determine duration without conversion, assume might need chunking
                    logger.info(f"Duration-based limit set ({chunking_config.limit_value}s) but can't check duration yet - will check after conversion")
                    return True  # Proceed to conversion and check
            else:
                # Mode is 'none', shouldn't reach here but handle gracefully
                return False

        except OSError:
            logger.error(f"Could not get file size for {file_path}")
            return False

    def needs_chunking_with_config(
        self,
        file_path: str,
        connector_specs: Optional['ConnectorSpecifications'] = None
    ) -> Tuple[bool, EffectiveChunkingConfig]:
        """
        Check if a file needs chunking and return the effective configuration.

        This is useful when you need both the decision and the configuration
        for subsequent processing.

        Args:
            file_path: Path to the audio file
            connector_specs: Optional ConnectorSpecifications from the active connector

        Returns:
            Tuple of (needs_chunking, EffectiveChunkingConfig)
        """
        chunking_config = get_effective_chunking_config(connector_specs)
        needs_it = self.needs_chunking(file_path, connector_specs=connector_specs)
        return needs_it, chunking_config
    
    def get_audio_duration(self, file_path: str) -> Optional[float]:
        """
        Get the duration of an audio file in seconds using ffprobe.
        
        Args:
            file_path: Path to the audio file
            
        Returns:
            Duration in seconds, or None if unable to determine
        """
        try:
            result = subprocess.run([
                'ffprobe', '-v', 'error', '-show_entries', 'format=duration',
                '-of', 'default=noprint_wrappers=1:nokey=1', file_path
            ], capture_output=True, check=True, timeout=_SUBPROCESS_TIMEOUT_SECONDS)

            duration = float(decode_ffmpeg_output(result.stdout).strip())
            return duration
        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, ValueError, FileNotFoundError) as e:
            logger.error(f"Error getting audio duration for {file_path}: {e}")
            return None
    
    def convert_to_mp3_and_get_info(self, file_path: str, temp_dir: str) -> Tuple[str, float, float]:
        """
        Convert the input file to MP3 format for consistency and get its size and duration info.

        If the input is already MP3, skips conversion and just copies it.

        Args:
            file_path: Path to the source audio file
            temp_dir: Directory to store the temporary MP3 file

        Returns:
            Tuple of (mp3_file_path, duration_seconds, size_bytes)
        """
        try:
            import shutil

            # Generate MP3 filename
            base_name = os.path.splitext(os.path.basename(file_path))[0]
            mp3_filename = f"{base_name}_converted.mp3"
            mp3_path = os.path.join(temp_dir, mp3_filename)

            # Check if input is already MP3 - skip conversion
            file_ext = os.path.splitext(file_path)[1].lower()
            if file_ext == '.mp3':
                logger.info(f"Input {file_path} is already MP3, skipping conversion")
                shutil.copy2(file_path, mp3_path)
            else:
                logger.info(f"Converting {file_path} to 128kbps MP3 format for chunking...")
                # Use centralized FFmpeg utility for conversion
                convert_to_mp3(file_path, mp3_path)

            if not os.path.exists(mp3_path):
                raise ValueError("MP3 file was not created")

            # Get the size and duration of the MP3 file
            mp3_size = os.path.getsize(mp3_path)
            mp3_duration = self.get_audio_duration(mp3_path)

            if not mp3_duration:
                raise ValueError("Could not determine MP3 file duration")

            logger.info(f"MP3 ready for chunking: {mp3_size/1024/1024:.1f}MB, {mp3_duration:.1f}s")

            # Optionally preserve converted file for debugging (set PRESERVE_CHUNK_DEBUG=true in env)
            if os.getenv('PRESERVE_CHUNK_DEBUG', 'false').lower() == 'true':
                # Save debug files in /data/uploads/debug/ directory
                debug_dir = '/data/uploads/debug'
                os.makedirs(debug_dir, exist_ok=True)
                debug_filename = os.path.basename(mp3_path).replace('_converted', '_converted_debug')
                debug_path = os.path.join(debug_dir, debug_filename)
                shutil.copy2(mp3_path, debug_path)
                logger.info(f"Debug: Preserved converted file as {debug_path}")

            return mp3_path, mp3_duration, mp3_size

        except (FFmpegError, FFmpegNotFoundError) as e:
            logger.error(f"Error converting file to MP3: {e}")
            raise
        except Exception as e:
            logger.error(f"Error converting file to MP3: {e}")
            raise

    def parse_chunk_limit(self) -> Tuple[str, float]:
        """
        Parse the CHUNK_LIMIT environment variable to determine chunking mode and value.
        
        Supports formats:
        - Size-based: "20MB", "10MB" 
        - Duration-based: "1200s", "20m"
        - Legacy: CHUNK_SIZE_MB environment variable (for backwards compatibility)
        
        Returns:
            Tuple of (mode, value) where mode is 'size' or 'duration'
        """
        chunk_limit = os.environ.get('CHUNK_LIMIT', '').strip().upper()
        
        # Check for new CHUNK_LIMIT format
        if chunk_limit:
            # Size-based: ends with MB
            if chunk_limit.endswith('MB'):
                try:
                    size_mb = float(re.sub(r'[^0-9.]', '', chunk_limit))
                    return 'size', size_mb
                except ValueError:
                    logger.warning(f"Invalid CHUNK_LIMIT format: {chunk_limit}")
            
            # Duration-based: ends with s or m
            elif chunk_limit.endswith('S'):
                try:
                    seconds = float(re.sub(r'[^0-9.]', '', chunk_limit))
                    return 'duration', seconds
                except ValueError:
                    logger.warning(f"Invalid CHUNK_LIMIT format: {chunk_limit}")
            
            elif chunk_limit.endswith('M'):
                try:
                    minutes = float(re.sub(r'[^0-9.]', '', chunk_limit))
                    return 'duration', minutes * 60
                except ValueError:
                    logger.warning(f"Invalid CHUNK_LIMIT format: {chunk_limit}")
        
        # Fallback to legacy CHUNK_SIZE_MB for backwards compatibility
        legacy_size = os.environ.get('CHUNK_SIZE_MB', '20')
        try:
            size_mb = float(legacy_size)
            logger.info(f"Using legacy CHUNK_SIZE_MB: {size_mb}MB")
            return 'size', size_mb
        except ValueError:
            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, 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 bytes
            total_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:
            # 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
                max_size_bytes = limit_value * 1024 * 1024 * 0.95  # 95% safety factor
                num_chunks = max(1, math.ceil(converted_size / max_size_bytes))
                
                logger.info(f"Size-based chunking: {limit_value}MB limit")
                logger.info(f"File size {converted_size/1024/1024:.1f}MB requires {num_chunks} chunks")
                
            else:  # duration-based
                # Use the limit from the connector/config directly — connectors already
                # declare their recommended_chunk_seconds with appropriate safety margins
                num_chunks = max(1, math.ceil(total_duration / limit_value))

                logger.info(f"Duration-based chunking: {limit_value}s limit")
                logger.info(f"File duration {total_duration:.1f}s requires {num_chunks} chunks")
            
            # Calculate chunk duration
            chunk_duration = total_duration / num_chunks
            
            # Apply minimum duration (5 minutes) but don't exceed file duration
            chunk_duration = min(max(300, chunk_duration), total_duration)
            
            # Log final chunking plan
            expected_chunk_size_mb = (converted_size / num_chunks) / (1024 * 1024)
            logger.info(f"Chunking plan: {num_chunks} chunks of ~{chunk_duration:.1f}s each (~{expected_chunk_size_mb:.1f}MB each)")
            
            return num_chunks, chunk_duration
            
        except Exception as e:
            logger.error(f"Error calculating optimal chunking: {e}")
            # Conservative fallback
            fallback_chunks = max(2, math.ceil(total_duration / 600))  # 10-minute chunks
            fallback_duration = total_duration / fallback_chunks
            return fallback_chunks, fallback_duration
    
    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 file
            temp_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 info
            mp3_path, mp3_duration, mp3_size = self.convert_to_mp3_and_get_info(file_path, temp_dir)

            # 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 required
            if num_chunks == 1:
                logger.info(f"File duration {mp3_duration:.1f}s is within limit - no chunking needed")
                # Return the single "chunk" as the whole file
                base_name = os.path.splitext(os.path.basename(file_path))[0]
                chunk_filename = f"{base_name}_chunk_000.mp3"
                chunk_path = os.path.join(temp_dir, chunk_filename)
                
                # Copy the converted file as the single chunk
                import shutil
                shutil.copy2(mp3_path, chunk_path)
                
                chunk_info = {
                    'index': 0,
                    'path': chunk_path,
                    'filename': chunk_filename,
                    'start_time': 0,
                    'end_time': mp3_duration,
                    'duration': mp3_duration,
                    'size_bytes': mp3_size,
                    'size_mb': mp3_size / (1024 * 1024)
                }
                chunks.append(chunk_info)
                logger.info(f"Created single chunk for entire file: {mp3_duration:.1f}s")
                return chunks
            
            # Calculate step size to create exactly num_chunks with overlap
            # Total coverage needed: mp3_duration + (overlap * (num_chunks - 1))
            # Each chunk covers: chunk_duration
            # Step between chunks to get exactly num_chunks
            if num_chunks > 1:
                step_duration = (mp3_duration - chunk_duration) / (num_chunks - 1)
            else:
                step_duration = mp3_duration
            
            current_start = 0
            chunk_index = 0
            
            logger.info(f"Splitting {file_path} into {num_chunks} chunks of ~{chunk_duration:.1f}s with {self.overlap_seconds}s overlap")
            
            for chunk_index in range(num_chunks):
                # Calculate start position for this chunk
                if chunk_index > 0:
                    current_start = chunk_index * step_duration
                
                # Calculate end time for this chunk
                chunk_end = min(current_start + chunk_duration, mp3_duration)
                actual_duration = chunk_end - current_start
                
                # Skip very short chunks at the end (shouldn't happen with proper calculation)
                if actual_duration < 10:  # Less than 10 seconds
                    logger.warning(f"Skipping short chunk {chunk_index}: {actual_duration:.1f}s")
                    break
                
                # Generate chunk filename
                base_name = os.path.splitext(os.path.basename(file_path))[0]
                chunk_filename = f"{base_name}_chunk_{chunk_index:03d}.mp3"
                chunk_path = os.path.join(temp_dir, chunk_filename)
                
                # Extract chunk from the converted MP3 file (more efficient than re-converting)
                cmd = [
                    'ffmpeg', '-i', mp3_path,
                    '-ss', str(current_start),
                    '-t', str(actual_duration),
                    '-acodec', 'copy',  # Copy codec since it's already in the right format
                    '-y',  # Overwrite output file
                    chunk_path
                ]
                
                try:
                    result = subprocess.run(cmd, capture_output=True, timeout=_SUBPROCESS_TIMEOUT_SECONDS)
                except subprocess.TimeoutExpired:
                    logger.error(f"ffmpeg timed out extracting chunk {chunk_index} after {_SUBPROCESS_TIMEOUT_SECONDS}s")
                    continue
                if result.returncode != 0:
                    logger.error(f"ffmpeg failed for chunk {chunk_index}: {decode_ffmpeg_output(result.stderr)}")
                    continue
                
                # Verify chunk was created and get its size
                if os.path.exists(chunk_path):
                    chunk_size = os.path.getsize(chunk_path)
                    
                    # Verify chunk size is within limits (only relevant for size-based chunking)
                    if chunk_size > self.max_chunk_size_bytes:
                        logger.debug(f"Chunk {chunk_index} is {chunk_size/1024/1024:.1f}MB (size limit: {self.max_chunk_size_mb}MB)")
                    
                    chunk_info = {
                        'index': chunk_index,
                        'path': chunk_path,
                        'filename': chunk_filename,
                        'start_time': current_start,
                        'end_time': chunk_end,
                        'duration': actual_duration,
                        'size_bytes': chunk_size,
                        'size_mb': chunk_size / (1024 * 1024)
                    }
                    
                    chunks.append(chunk_info)
                    logger.info(f"Created chunk {chunk_index}: {current_start:.1f}s-{chunk_end:.1f}s ({chunk_size/1024/1024:.1f}MB)")
                    
                    # Optionally preserve chunks for debugging (set PRESERVE_CHUNK_DEBUG=true in env)
                    if os.getenv('PRESERVE_CHUNK_DEBUG', 'false').lower() == 'true':
                        import shutil
                        # Save debug chunks in /data/uploads/debug/ directory
                        debug_dir = '/data/uploads/debug'
                        os.makedirs(debug_dir, exist_ok=True)
                        debug_filename = os.path.basename(chunk_path).replace('.mp3', '_debug.mp3')
                        debug_path = os.path.join(debug_dir, debug_filename)
                        shutil.copy2(chunk_path, debug_path)
                        logger.info(f"Debug: Preserved chunk as {debug_path}")
                else:
                    logger.error(f"Chunk file not created: {chunk_path}")
            
            logger.info(f"Created {len(chunks)} chunks for {file_path}")
            return chunks
            
        except Exception as e:
            logger.error(f"Error creating chunks for {file_path}: {e}")
            # Clean up any partial chunks
            for chunk in chunks:
                try:
                    if os.path.exists(chunk['path']):
                        os.remove(chunk['path'])
                except Exception:
                    pass
            raise
        finally:
            # Clean up the temporary WAV file
            if wav_path and os.path.exists(wav_path):
                try:
                    os.remove(wav_path)
                    logger.debug(f"Cleaned up temporary WAV file: {wav_path}")
                except Exception as e:
                    logger.warning(f"Error cleaning up temporary WAV file: {e}")
    
    def merge_transcriptions(self, chunk_results: List[Dict[str, Any]]) -> str:
        """
        Merge transcription results from multiple chunks, handling overlaps.
        
        Args:
            chunk_results: List of transcription results from chunks
            
        Returns:
            Merged transcription text
        """
        if not chunk_results:
            return ""
        
        if len(chunk_results) == 1:
            return chunk_results[0].get('transcription', '')
        
        # Sort chunks by start time to ensure correct order
        sorted_chunks = sorted(chunk_results, key=lambda x: x.get('start_time', 0))
        
        merged_text = ""
        
        for i, chunk in enumerate(sorted_chunks):
            chunk_text = chunk.get('transcription', '').strip()
            
            if not chunk_text:
                continue
            
            if i == 0:
                # First chunk: use entire transcription
                merged_text = chunk_text
            else:
                # Subsequent chunks: try to handle overlap
                merged_text = self._merge_overlapping_text(
                    merged_text, 
                    chunk_text, 
                    chunk.get('start_time', 0),
                    sorted_chunks[i-1].get('end_time', 0)
                )
        
        return merged_text
    
    def _merge_overlapping_text(self, existing_text: str, new_text: str, 
                               new_start_time: float, prev_end_time: float) -> str:
        """
        Merge overlapping transcription text, attempting to remove duplicates.
        
        Args:
            existing_text: Previously merged text
            new_text: New chunk text to merge
            new_start_time: Start time of new chunk
            prev_end_time: End time of previous chunk
            
        Returns:
            Merged text with overlaps handled
        """
        # If there's no overlap, just concatenate
        overlap_duration = prev_end_time - new_start_time
        if overlap_duration <= 0:
            return f"{existing_text}\n{new_text}"
        
        # For overlapping chunks, try to find common text and merge intelligently
        # This is a simplified approach - in practice, you might want more sophisticated
        # text similarity matching
        
        # Split texts into sentences/phrases
        existing_sentences = self._split_into_sentences(existing_text)
        new_sentences = self._split_into_sentences(new_text)
        
        if not existing_sentences or not new_sentences:
            return f"{existing_text}\n{new_text}"
        
        # Try to find overlap by comparing last few sentences of existing text
        # with first few sentences of new text
        overlap_found = False
        merge_point = len(existing_sentences)
        
        # Look for common sentences (simple approach)
        for i in range(min(3, len(existing_sentences))):  # Check last 3 sentences
            last_sentence = existing_sentences[-(i+1)].strip().lower()
            
            for j in range(min(3, len(new_sentences))):  # Check first 3 sentences
                first_sentence = new_sentences[j].strip().lower()
                
                # If sentences are similar enough, consider it an overlap
                if last_sentence and first_sentence and self._sentences_similar(last_sentence, first_sentence):
                    merge_point = len(existing_sentences) - i
                    new_start_index = j + 1
                    overlap_found = True
                    break
            
            if overlap_found:
                break
        
        if overlap_found:
            # Merge at the found overlap point
            merged_sentences = existing_sentences[:merge_point] + new_sentences[new_start_index:]
            return ' '.join(merged_sentences)
        else:
            # No clear overlap found, concatenate with a separator
            return f"{existing_text}\n{new_text}"
    
    def _split_into_sentences(self, text: str) -> List[str]:
        """Split text into sentences for overlap detection."""
        import re
        # Simple sentence splitting - could be improved with more sophisticated NLP
        sentences = re.split(r'[.!?]+', text)
        return [s.strip() for s in sentences if s.strip()]
    
    def _sentences_similar(self, sent1: str, sent2: str, threshold: float = 0.8) -> bool:
        """Check if two sentences are similar enough to be considered the same."""
        # Simple similarity check based on common words
        words1 = set(sent1.split())
        words2 = set(sent2.split())
        
        if not words1 or not words2:
            return False
        
        intersection = len(words1.intersection(words2))
        union = len(words1.union(words2))
        
        similarity = intersection / union if union > 0 else 0
        return similarity >= threshold
    
    def analyze_chunk_audio_properties(self, chunk_path: str) -> Dict[str, Any]:
        """
        Analyze audio properties of a chunk that might affect processing time.
        
        Args:
            chunk_path: Path to the chunk file
            
        Returns:
            Dictionary with audio analysis results
        """
        try:
            # Get detailed audio information using ffprobe
            cmd = [
                'ffprobe', '-v', 'quiet', '-print_format', 'json',
                '-show_format', '-show_streams', chunk_path
            ]
            
            result = subprocess.run(cmd, capture_output=True, check=True, timeout=_SUBPROCESS_TIMEOUT_SECONDS)
            probe_data = json.loads(decode_ffmpeg_output(result.stdout))

            audio_stream = None
            for stream in probe_data.get('streams', []):
                if stream.get('codec_type') == 'audio':
                    audio_stream = stream
                    break
            
            if not audio_stream:
                return {'error': 'No audio stream found'}
            
            format_info = probe_data.get('format', {})
            
            analysis = {
                'duration': float(format_info.get('duration', 0)),
                'size_bytes': int(format_info.get('size', 0)),
                'bitrate': int(format_info.get('bit_rate', 0)),
                'sample_rate': int(audio_stream.get('sample_rate', 0)),
                'channels': int(audio_stream.get('channels', 0)),
                'codec': audio_stream.get('codec_name', 'unknown'),
                'bits_per_sample': int(audio_stream.get('bits_per_raw_sample', 0)),
            }
            
            # Calculate some derived metrics
            if analysis['duration'] > 0:
                analysis['effective_bitrate'] = (analysis['size_bytes'] * 8) / analysis['duration']
                analysis['compression_ratio'] = analysis['bitrate'] / analysis['effective_bitrate'] if analysis['effective_bitrate'] > 0 else 0
            
            return analysis
            
        except Exception as e:
            logger.warning(f"Error analyzing chunk audio properties: {e}")
            return {'error': str(e)}
    
    def log_processing_statistics(self, chunk_results: List[Dict[str, Any]]) -> None:
        """
        Log detailed statistics about chunk processing performance.
        
        Args:
            chunk_results: List of chunk processing results with timing info
        """
        if not chunk_results:
            return
        
        logger.info("=== CHUNK PROCESSING STATISTICS ===")
        
        total_chunks = len(chunk_results)
        processing_times = []
        sizes = []
        durations = []
        
        for i, result in enumerate(chunk_results):
            processing_time = result.get('processing_time', 0)
            chunk_size = result.get('size_mb', 0)
            chunk_duration = result.get('duration', 0)
            
            processing_times.append(processing_time)
            sizes.append(chunk_size)
            durations.append(chunk_duration)
            
            # Log individual chunk stats
            rate = chunk_duration / processing_time if processing_time > 0 else 0
            logger.info(f"Chunk {i+1}: {processing_time:.1f}s processing, {chunk_size:.1f}MB, {chunk_duration:.1f}s audio (rate: {rate:.2f}x)")
        
        # Calculate summary statistics
        if processing_times:
            avg_time = sum(processing_times) / len(processing_times)
            min_time = min(processing_times)
            max_time = max(processing_times)
            
            avg_size = sum(sizes) / len(sizes)
            avg_duration = sum(durations) / len(durations)
            
            total_audio_time = sum(durations)
            total_processing_time = sum(processing_times)
            overall_rate = total_audio_time / total_processing_time if total_processing_time > 0 else 0
            
            logger.info(f"Summary: {total_chunks} chunks, {total_audio_time:.1f}s audio in {total_processing_time:.1f}s")
            logger.info(f"Average: {avg_time:.1f}s processing, {avg_size:.1f}MB, {avg_duration:.1f}s audio")
            logger.info(f"Range: {min_time:.1f}s - {max_time:.1f}s processing time")
            logger.info(f"Overall rate: {overall_rate:.2f}x realtime")
            
            # Identify performance outliers
            if max_time > avg_time * 2:
                slow_chunks = [i for i, t in enumerate(processing_times) if t > avg_time * 1.5]
                logger.warning(f"Performance outliers detected: chunks {[i+1 for i in slow_chunks]} took significantly longer")
                
                # Suggest possible causes
                logger.info("Possible causes for slow processing:")
                logger.info("- OpenAI API server load/performance variations")
                logger.info("- Network latency or connection issues")
                logger.info("- Audio content complexity (silence, noise, multiple speakers)")
                logger.info("- Temporary API rate limiting or throttling")
        
        logger.info("=== END STATISTICS ===")
    
    def get_performance_recommendations(self, chunk_results: List[Dict[str, Any]]) -> List[str]:
        """
        Generate performance recommendations based on processing results.
        
        Args:
            chunk_results: List of chunk processing results
            
        Returns:
            List of recommendation strings
        """
        recommendations = []
        
        if not chunk_results:
            return recommendations
        
        processing_times = [r.get('processing_time', 0) for r in chunk_results]
        
        if processing_times:
            avg_time = sum(processing_times) / len(processing_times)
            max_time = max(processing_times)
            
            # Check for high variance in processing times
            if max_time > avg_time * 3:
                recommendations.append("High variance in processing times detected. Consider implementing retry logic with exponential backoff.")
            
            # Check for overall slow processing
            total_audio = sum(r.get('duration', 0) for r in chunk_results)
            total_processing = sum(processing_times)
            rate = total_audio / total_processing if total_processing > 0 else 0
            
            if rate < 0.5:  # Less than 0.5x realtime
                recommendations.append("Overall processing is slow. Consider using smaller chunks or a different transcription service.")
            
            # Check for timeout issues
            if any(t > 300 for t in processing_times):  # 5+ minutes
                recommendations.append("Some chunks took over 5 minutes. Consider implementing timeout handling and chunk retry logic.")
            
            # Check chunk size optimization
            avg_size = sum(r.get('size_mb', 0) for r in chunk_results) / len(chunk_results)
            if avg_size < 10:
                recommendations.append("Chunks are relatively small. Consider increasing chunk size for better efficiency.")
            elif avg_size > 22:
                recommendations.append("Chunks are close to size limit. Consider reducing chunk size for more reliable processing.")
        
        return recommendations
    
    def cleanup_chunks(self, chunks: List[Dict[str, Any]], temp_mp3_path: str = None) -> None:
        """
        Clean up temporary chunk files and MP3 file.
        
        Args:
            chunks: List of chunk information dictionaries
            temp_mp3_path: Optional path to temporary MP3 file to clean up
        """
        for chunk in chunks:
            try:
                chunk_path = chunk.get('path')
                if chunk_path and os.path.exists(chunk_path):
                    os.remove(chunk_path)
                    logger.debug(f"Cleaned up chunk file: {chunk_path}")
            except Exception as e:
                logger.warning(f"Error cleaning up chunk {chunk.get('filename', 'unknown')}: {e}")
        
        # Clean up temporary MP3 file if provided
        if temp_mp3_path and os.path.exists(temp_mp3_path):
            try:
                os.remove(temp_mp3_path)
                logger.debug(f"Cleaned up temporary MP3 file: {temp_mp3_path}")
            except Exception as e:
                logger.warning(f"Error cleaning up temporary MP3 file: {e}")

def get_audio_duration_ffprobe(file_path: str) -> Optional[float]:
    """Get actual audio duration using ffprobe."""
    try:
        result = subprocess.run([
            'ffprobe', '-v', 'error', '-show_entries', 'format=duration',
            '-of', 'default=noprint_wrappers=1:nokey=1', file_path
        ], capture_output=True, check=True, timeout=_SUBPROCESS_TIMEOUT_SECONDS)
        return float(decode_ffmpeg_output(result.stdout).strip())
    except Exception:
        return None


def extract_speaker_samples(
    audio_path: str,
    segments: List[Dict[str, Any]],
    output_dir: str,
    min_duration: float = 1.5,  # OpenAI minimum is 1.2s, use 1.5s for safety
    max_duration: float = 9.0,  # OpenAI maximum is 10.0s, use 9.0s for safety
    max_speakers: int = 4
) -> Dict[str, str]:
    """
    Extract audio samples for each unique speaker from diarized segments.

    This is used to maintain speaker identity across chunks when processing
    long audio files with the gpt-4o-transcribe-diarize model.

    Args:
        audio_path: Path to the source audio file (should be the converted chunk MP3)
        segments: List of diarized segments with speaker, start_time, end_time
        output_dir: Directory to store extracted speaker samples
        min_duration: Minimum duration for a speaker sample (OpenAI requires 1.2-10s)
        max_duration: Maximum duration for a speaker sample
        max_speakers: Maximum number of speakers to extract (OpenAI supports up to 4)

    Returns:
        Dict mapping speaker label (e.g., "A", "B") to path of extracted audio sample
    """
    # OpenAI's actual limits
    OPENAI_MIN_DURATION = 1.2
    OPENAI_MAX_DURATION = 10.0

    # Group segments by speaker
    speaker_segments: Dict[str, List[Dict]] = {}
    for seg in segments:
        # Handle both dict and object segments
        if isinstance(seg, dict):
            speaker = seg.get('speaker', 'Unknown')
            # Use explicit None checks: a literal 0.0 start (segment at the very
            # beginning) is valid and must not be treated as missing.
            start = seg.get('start_time')
            if start is None:
                start = seg.get('start')
            end = seg.get('end_time')
            if end is None:
                end = seg.get('end')
        else:
            speaker = getattr(seg, 'speaker', 'Unknown')
            start = getattr(seg, 'start_time', None)
            if start is None:
                start = getattr(seg, 'start', None)
            end = getattr(seg, 'end_time', None)
            if end is None:
                end = getattr(seg, 'end', None)

        if speaker == 'Unknown' or start is None or end is None:
            continue

        if speaker not in speaker_segments:
            speaker_segments[speaker] = []
        speaker_segments[speaker].append({'start': start, 'end': end})

    if not speaker_segments:
        logger.warning("No valid speaker segments found for sample extraction")
        return {}

    # Sort speakers to get consistent ordering (A, B, C, D...)
    sorted_speakers = sorted(speaker_segments.keys())[:max_speakers]
    logger.info(f"Extracting samples for {len(sorted_speakers)} speakers: {sorted_speakers}")

    speaker_samples = {}

    for speaker in sorted_speakers:
        segs = speaker_segments[speaker]

        # Find the best segment for this speaker (ideally 1.5-9 seconds)
        best_segment = None
        best_duration = 0

        for seg in segs:
            duration = seg['end'] - seg['start']

            # Prefer segments in the ideal range
            if min_duration <= duration <= max_duration:
                if duration > best_duration:
                    best_segment = seg
                    best_duration = duration

        # If no segment in ideal range, try to find one we can trim
        if not best_segment:
            for seg in segs:
                duration = seg['end'] - seg['start']
                if duration >= min_duration:
                    # Trim to max_duration if needed
                    best_segment = {
                        'start': seg['start'],
                        'end': min(seg['end'], seg['start'] + max_duration)
                    }
                    best_duration = best_segment['end'] - best_segment['start']
                    break

        # Still no segment? Try combining multiple short segments
        if not best_segment and len(segs) > 1:
            # Sort by start time and try to find consecutive segments
            sorted_segs = sorted(segs, key=lambda x: x['start'])
            combined_start = sorted_segs[0]['start']
            combined_end = sorted_segs[0]['end']

            for i in range(1, len(sorted_segs)):
                # If segments are close (within 1 second), combine them
                if sorted_segs[i]['start'] - combined_end < 1.0:
                    combined_end = sorted_segs[i]['end']
                    if combined_end - combined_start >= min_duration:
                        break

            combined_duration = combined_end - combined_start
            if combined_duration >= min_duration:
                best_segment = {
                    'start': combined_start,
                    'end': min(combined_end, combined_start + max_duration)
                }
                best_duration = best_segment['end'] - best_segment['start']

        if not best_segment:
            logger.warning(f"Could not find suitable segment for speaker {speaker}")
            continue

        # Extract the audio sample using ffmpeg
        sample_filename = f"speaker_{speaker}_sample.mp3"
        sample_path = os.path.join(output_dir, sample_filename)

        try:
            cmd = [
                'ffmpeg', '-i', audio_path,
                '-ss', str(best_segment['start']),
                '-t', str(best_duration),
                '-acodec', 'libmp3lame',
                '-b:a', '128k',
                '-y',
                sample_path
            ]

            try:
                result = subprocess.run(cmd, capture_output=True, timeout=_SUBPROCESS_TIMEOUT_SECONDS)
            except subprocess.TimeoutExpired:
                logger.error(f"ffmpeg timed out extracting sample for speaker {speaker} after {_SUBPROCESS_TIMEOUT_SECONDS}s")
                continue
            if result.returncode != 0:
                logger.error(f"Failed to extract sample for speaker {speaker}: {decode_ffmpeg_output(result.stderr)}")
                continue

            if os.path.exists(sample_path) and os.path.getsize(sample_path) > 0:
                # Verify actual duration meets OpenAI requirements
                actual_duration = get_audio_duration_ffprobe(sample_path)
                if actual_duration:
                    logger.info(f"Speaker {speaker} sample: expected {best_duration:.2f}s, actual {actual_duration:.2f}s")

                    if actual_duration < OPENAI_MIN_DURATION:
                        logger.warning(f"Sample for speaker {speaker} too short ({actual_duration:.2f}s < {OPENAI_MIN_DURATION}s), skipping")
                        os.remove(sample_path)
                        continue
                    elif actual_duration > OPENAI_MAX_DURATION:
                        logger.warning(f"Sample for speaker {speaker} too long ({actual_duration:.2f}s > {OPENAI_MAX_DURATION}s), skipping")
                        os.remove(sample_path)
                        continue

                speaker_samples[speaker] = sample_path
                logger.info(f"Extracted {actual_duration:.1f}s sample for speaker {speaker} "
                           f"(from {best_segment['start']:.1f}s to {best_segment['end']:.1f}s)")
            else:
                logger.warning(f"Sample file not created for speaker {speaker}")

        except Exception as e:
            logger.error(f"Error extracting sample for speaker {speaker}: {e}")

    return speaker_samples


def samples_to_data_urls(speaker_samples: Dict[str, str]) -> Dict[str, str]:
    """
    Convert speaker sample file paths to base64-encoded data URLs.

    OpenAI's known_speaker_references requires audio samples as data URLs
    when using multipart form data.

    Args:
        speaker_samples: Dict mapping speaker label to file path

    Returns:
        Dict mapping speaker label to data URL
    """
    import base64

    data_urls = {}

    for speaker, path in speaker_samples.items():
        try:
            with open(path, 'rb') as f:
                audio_data = f.read()

            # Encode as base64 data URL
            b64_data = base64.b64encode(audio_data).decode('utf-8')
            data_url = f"data:audio/mpeg;base64,{b64_data}"
            data_urls[speaker] = data_url

            logger.debug(f"Converted speaker {speaker} sample to data URL ({len(b64_data)} bytes)")

        except Exception as e:
            logger.error(f"Error converting speaker {speaker} sample to data URL: {e}")

    return data_urls


class ChunkProcessingError(Exception):
    """Exception raised when chunk processing fails."""
    pass

class ChunkingNotSupportedError(Exception):
    """Exception raised when chunking is not supported for the current configuration."""
    pass