feat: add chunked ASR for long audio with env-configurable chunk duration

- Integrate chunking into LocalAI client to avoid GPU OOM on long audio.
- Split long files into overlapping chunks; transcribe each chunk; merge segments with corrected timestamps.
- Auto-enable chunking when audio duration > LOCALAI_MAX_SINGLE_REQUEST_DURATION (default 300s).
- Add env variables:
    LOCALAI_CHUNK_DURATION (default 180)
    LOCALAI_CHUNK_OVERLAP (default 2)
    LOCALAI_MAX_SINGLE_REQUEST_DURATION (default 300)
- Add unit and integration tests for chunking logic.
- Confirmed working end-to-end with vibevoice-cpp-asr on 88-minute file.

scraibe/audio.py

@@ -7,13 +7,21 @@ Simplified audio processor for ScrAIbe.
 Previously this used torch and pyannote-style processing. In the LocalAI-backed
 version, we primarily pass files to the API, but we keep a lightweight helper
 for backward compatibility.
+
+Now also includes utilities for chunking long audio into smaller segments
+to avoid GPU memory limits when using vibevoice-cpp on LocalAI.
 """
 
+import json
+import os
+import tempfile
 from subprocess import CalledProcessError, run
 import numpy as np
 
 SAMPLE_RATE = 16000
 NORMALIZATION_FACTOR = 32768.0
+DEFAULT_CHUNK_DURATION = 180.0  # seconds
+DEFAULT_CHUNK_OVERLAP = 2.0    # seconds
 
 
 class AudioProcessor:
@@ -106,3 +114,109 @@ class AudioProcessor:
 
     def __repr__(self) -> str:
         return f"AudioProcessor(waveform_len={len(self.waveform)}, sr={self.sr})"
+
+
+def get_audio_duration(file_path: str) -> float:
+    """
+    Get the duration of an audio file in seconds using ffprobe.
+
+    Args:
+        file_path: Path to the audio file.
+
+    Returns:
+        Duration in seconds as a float.
+
+    Raises:
+        RuntimeError: If ffprobe fails.
+    """
+    cmd = [
+        "ffprobe",
+        "-v", "error",
+        "-show_entries", "format=duration",
+        "-of", "json",
+        file_path,
+    ]
+    try:
+        result = run(cmd, capture_output=True, text=True, check=True)
+        data = json.loads(result.stdout)
+        return float(data["format"]["duration"])
+    except (CalledProcessError, json.JSONDecodeError, KeyError) as e:
+        raise RuntimeError(f"Failed to get audio duration for {file_path}: {e}")
+
+
+def split_audio_into_chunks(
+    input_path: str,
+    max_duration: float = DEFAULT_CHUNK_DURATION,
+    overlap: float = DEFAULT_CHUNK_OVERLAP,
+    output_format: str = "wav",
+    sample_rate: int = 24000,
+) -> list:
+    """
+    Split a long audio file into overlapping chunks using ffmpeg.
+
+    Args:
+        input_path: Path to the input audio file.
+        max_duration: Maximum duration of each chunk in seconds.
+        overlap: Overlap duration in seconds between consecutive chunks.
+        output_format: Output format (e.g., 'wav').
+        sample_rate: Sample rate for output chunks.
+
+    Returns:
+        List of dicts:
+            [{"path": "chunk.wav", "start": 0.0, "end": 180.0}, ...]
+        Files must be cleaned up by the caller.
+    """
+    duration = get_audio_duration(input_path)
+
+    # If file is shorter than max_duration, no need to split
+    if duration <= max_duration:
+        return [{"path": input_path, "start": 0.0, "end": duration}]
+
+    chunks = []
+    start = 0.0
+    chunk_id = 0
+
+    while start < duration:
+        chunk_end = min(start + max_duration, duration)
+        chunk_duration = chunk_end - start
+
+        tmp = tempfile.NamedTemporaryFile(
+            delete=False,
+            suffix=f".{output_format}",
+            prefix="scraibe_chunk_",
+        )
+        chunk_path = tmp.name
+        tmp.close()
+
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-nostdin",
+            "-ss", str(start),
+            "-i", input_path,
+            "-t", str(chunk_duration),
+            "-ar", str(sample_rate),
+            "-ac", "1",
+            "-c:a", "pcm_s16le",
+            chunk_path,
+        ]
+        try:
+            run(cmd, capture_output=True, check=True)
+        except CalledProcessError as e:
+            # Clean up on error
+            if os.path.exists(chunk_path):
+                os.remove(chunk_path)
+            raise RuntimeError(
+                f"Failed to create audio chunk {chunk_id} for {input_path}: {e.stderr.decode()}"
+            )
+
+        chunks.append({
+            "path": chunk_path,
+            "start": start,
+            "end": chunk_end,
+        })
+
+        start += max_duration - overlap
+        chunk_id += 1
+
+    return chunks

scraibe/localai_client.py

@@ -9,11 +9,21 @@ It replaces the previous local Whisper + Pyannote pipeline by sending
 audio files to the /v1/audio/diarization endpoint and mapping the
 response into the same Transcript format used by the UI.
 
+For long audio files, it can chunk the input to avoid GPU OOM errors.
+
 Environment Variables:
     LOCALAI_API_URL: (required) Base URL of the LocalAI server
                      (e.g., http://localhost:8080)
     LOCALAI_API_KEY: (optional) API key, if configured
     LOCALAI_MODEL:   (optional) Model name to use (default: vibevoice-diarize)
+
+    Chunking / long audio (all optional):
+    LOCALAI_CHUNK_DURATION:               Max duration of each chunk in seconds
+                                           (default: 180.0)
+    LOCALAI_CHUNK_OVERLAP:                Overlap between consecutive chunks in seconds
+                                           (default: 2.0)
+    LOCALAI_MAX_SINGLE_REQUEST_DURATION:  If audio duration exceeds this, chunking
+                                           is enabled automatically (default: 300.0)
 """
 
 import os
@@ -24,6 +34,8 @@ from typing import Dict, List, Any, Optional
 
 import httpx
 
+from .audio import get_audio_duration, split_audio_into_chunks
+
 logger = logging.getLogger("scraibe.localai_client")
 
 
@@ -41,8 +53,14 @@ class LocalAIClient:
       - Upload audio file as multipart/form-data.
       - Parse diarization + transcription response (verbose_json).
       - Map response into the same structure expected by Scraibe's Transcript.
+      - For long audio: chunk, transcribe each chunk, merge results.
     """
 
+    # Default thresholds for chunking long audio to avoid GPU OOM.
+    # These can be overridden via environment or at call time.
+    DEFAULT_CHUNK_DURATION = 180.0  # seconds
+    DEFAULT_CHUNK_OVERLAP = 2.0    # seconds
+
     def __init__(
         self,
         api_url: Optional[str] = None,
@@ -82,6 +100,55 @@ class LocalAIClient:
             follow_redirects=True,
         )
 
+    @staticmethod
+    def _env_float(var: str, default: float) -> float:
+        """
+        Read a float from environment with a fallback default.
+        """
+        val = (os.getenv(var) or "").strip()
+        if val == "":
+            return default
+        try:
+            return float(val)
+        except ValueError:
+            logger.warning(
+                "Invalid value for %s: %s; using default %s", var, val, default
+            )
+            return default
+
+    def _effective_chunk_duration(self, provided: Optional[float]) -> float:
+        """
+        Resolve chunk_duration using this precedence:
+          1) provided argument
+          2) LOCALAI_CHUNK_DURATION env
+          3) class default
+        """
+        if provided is not None:
+            return provided
+        return self._env_float("LOCALAI_CHUNK_DURATION", self.DEFAULT_CHUNK_DURATION)
+
+    def _effective_chunk_overlap(self, provided: Optional[float]) -> float:
+        """
+        Resolve chunk_overlap:
+          1) provided argument
+          2) LOCALAI_CHUNK_OVERLAP env
+          3) class default
+        """
+        if provided is not None:
+            return provided
+        return self._env_float("LOCALAI_CHUNK_OVERLAP", self.DEFAULT_CHUNK_OVERLAP)
+
+    def _effective_max_single_request_duration(self, provided: Optional[float]) -> float:
+        """
+        Resolve max_single_request_duration:
+          1) provided argument
+          2) LOCALAI_MAX_SINGLE_REQUEST_DURATION env
+          3) default 300.0
+        """
+        if provided is not None:
+            return provided
+        return self._env_float("LOCALAI_MAX_SINGLE_REQUEST_DURATION", 300.0)
+
     def close(self):
         """Close the underlying HTTP client."""
         self._client.close()
@@ -107,6 +174,10 @@ class LocalAIClient:
         include_text: Optional[bool] = None,
         verbose: bool = False,
         return_raw: bool = False,
+        use_chunking: Optional[bool] = None,
+        chunk_duration: Optional[float] = None,
+        chunk_overlap: Optional[float] = None,
+        max_single_request_duration: Optional[float] = None,
         **_ignored,
     ) -> Dict[str, Any]:
         """
@@ -114,6 +185,8 @@ class LocalAIClient:
         - A normalized dict with segments, speakers, transcripts.
         - Optionally, the raw verbose_json response (for JSON export).
 
+        For long audio, it can automatically chunk the file to avoid GPU OOM.
+
         Args:
             audio_path: Path to the audio file.
             language: Language hint, forwarded if set.
@@ -129,6 +202,93 @@ class LocalAIClient:
                           Defaults to True.
             verbose: If True, prints progress messages.
             return_raw: If True, also return the raw API response in 'raw_result'.
+            use_chunking: Whether to enable chunking for long audio.
+                          If None, enabled automatically based on duration.
+            chunk_duration: Max duration per chunk in seconds.
+                            Falls back to LOCALAI_CHUNK_DURATION env, then 180.0.
+            chunk_overlap: Overlap between chunks in seconds.
+                           Falls back to LOCALAI_CHUNK_OVERLAP env, then 2.0.
+            max_single_request_duration: If audio duration exceeds this, chunking
+                                         is enabled (unless explicitly disabled).
+                                         Falls back to LOCALAI_MAX_SINGLE_REQUEST_DURATION
+                                         env, then 300.0.
+        """
+        if verbose:
+            print("Starting diarization and transcription via LocalAI.")
+
+        logger.info("diarize_and_transcribe requested for: %s", audio_path)
+
+        # Resolve chunking parameters with environment support
+        chunk_duration = self._effective_chunk_duration(chunk_duration)
+        chunk_overlap = self._effective_chunk_overlap(chunk_overlap)
+        max_single = self._effective_max_single_request_duration(max_single_request_duration)
+
+        if use_chunking is None:
+            try:
+                duration = get_audio_duration(audio_path)
+            except RuntimeError:
+                duration = None
+
+            use_chunking = (duration is not None and duration > max_single)
+            logger.info(
+                "Auto-chunking decision: duration=%s, threshold=%s, use_chunking=%s",
+                duration,
+                max_single,
+                use_chunking,
+            )
+
+        if use_chunking:
+            return self._diarize_and_transcribe_chunked(
+                audio_path=audio_path,
+                language=language,
+                num_speakers=num_speakers,
+                min_speakers=min_speakers,
+                max_speakers=max_speakers,
+                clustering_threshold=clustering_threshold,
+                min_duration_on=min_duration_on,
+                min_duration_off=min_duration_off,
+                response_format=response_format,
+                include_text=include_text,
+                verbose=verbose,
+                return_raw=return_raw,
+                chunk_duration=chunk_duration,
+                chunk_overlap=chunk_overlap,
+            )
+
+        # Single-request path (existing behavior)
+        return self._diarize_and_transcribe_single(
+            audio_path=audio_path,
+            language=language,
+            num_speakers=num_speakers,
+            min_speakers=min_speakers,
+            max_speakers=max_speakers,
+            clustering_threshold=clustering_threshold,
+            min_duration_on=min_duration_on,
+            min_duration_off=min_duration_off,
+            response_format=response_format,
+            include_text=include_text,
+            verbose=verbose,
+            return_raw=return_raw,
+        )
+
+    def _diarize_and_transcribe_single(
+        self,
+        audio_path: str,
+        *,
+        language: Optional[str] = None,
+        num_speakers: Optional[int] = None,
+        min_speakers: Optional[int] = None,
+        max_speakers: Optional[int] = None,
+        clustering_threshold: Optional[float] = None,
+        min_duration_on: Optional[float] = None,
+        min_duration_off: Optional[float] = None,
+        response_format: Optional[str] = None,
+        include_text: Optional[bool] = None,
+        verbose: bool = False,
+        return_raw: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Internal: single-request diarization and transcription.
         """
         if verbose:
             print("Starting diarization and transcription via LocalAI.")
@@ -214,6 +374,153 @@ class LocalAIClient:
 
         return parsed
 
+    def _diarize_and_transcribe_chunked(
+        self,
+        audio_path: str,
+        *,
+        language: Optional[str] = None,
+        num_speakers: Optional[int] = None,
+        min_speakers: Optional[int] = None,
+        max_speakers: Optional[int] = None,
+        clustering_threshold: Optional[float] = None,
+        min_duration_on: Optional[float] = None,
+        min_duration_off: Optional[float] = None,
+        response_format: Optional[str] = None,
+        include_text: Optional[bool] = None,
+        verbose: bool = False,
+        return_raw: bool = False,
+        chunk_duration: float = DEFAULT_CHUNK_DURATION,
+        chunk_overlap: float = DEFAULT_CHUNK_OVERLAP,
+    ) -> Dict[str, Any]:
+        """
+        Internal: chunked diarization and transcription for long audio.
+
+        - Splits audio into overlapping chunks.
+        - Transcribes each chunk via /v1/audio/diarization.
+        - Merges segments with adjusted timestamps.
+        """
+        if verbose:
+            print("Audio is long; splitting into chunks to avoid GPU memory issues.")
+
+        logger.info(
+            "Chunked transcription: chunk_duration=%s, overlap=%s",
+            chunk_duration,
+            chunk_overlap,
+        )
+
+        chunks = split_audio_into_chunks(
+            input_path=audio_path,
+            max_duration=chunk_duration,
+            overlap=chunk_overlap,
+        )
+
+        if len(chunks) == 1:
+            # No actual split needed; fall back to single-request path
+            return self._diarize_and_transcribe_single(
+                audio_path=chunks[0]["path"],
+                language=language,
+                num_speakers=num_speakers,
+                min_speakers=min_speakers,
+                max_speakers=max_speakers,
+                clustering_threshold=clustering_threshold,
+                min_duration_on=min_duration_on,
+                min_duration_off=min_duration_off,
+                response_format=response_format,
+                include_text=include_text,
+                verbose=verbose,
+                return_raw=return_raw,
+            )
+
+        all_segments: List[List[float]] = []
+        all_speakers: List[str] = []
+        all_transcripts: List[str] = []
+        raw_results: List[Dict[str, Any]] = []
+        temp_files = [c["path"] for c in chunks]
+
+        try:
+            for i, chunk_info in enumerate(chunks):
+                chunk_path = chunk_info["path"]
+                chunk_start = chunk_info["start"]
+
+                if verbose:
+                    print(
+                        f"Transcribing chunk {i+1}/{len(chunks)} "
+                        f"(start={chunk_start:.1f}s)"
+                    )
+
+                logger.info(
+                    "Transcribing chunk %d/%d, start=%.1f", i + 1, len(chunks), chunk_start
+                )
+
+                # Use single-request logic for each chunk
+                chunk_result = self._diarize_and_transcribe_single(
+                    audio_path=chunk_path,
+                    language=language,
+                    num_speakers=num_speakers,
+                    min_speakers=min_speakers,
+                    max_speakers=max_speakers,
+                    clustering_threshold=clustering_threshold,
+                    min_duration_on=min_duration_on,
+                    min_duration_off=min_duration_off,
+                    response_format=response_format,
+                    include_text=include_text,
+                    verbose=False,
+                    return_raw=return_raw,
+                )
+
+                segs = chunk_result.get("segments", [])
+                spks = chunk_result.get("speakers", [])
+                txts = chunk_result.get("transcripts", [])
+                raw = chunk_result.get("raw_result")
+
+                # Adjust timestamps to global timeline
+                adjusted_segs = []
+                for seg, sp, txt in zip(segs, spks, txts):
+                    start = float(seg[0]) + chunk_start
+                    end = float(seg[1]) + chunk_start
+                    adjusted_segs.append([start, end])
+                    all_speakers.append(sp)
+                    all_transcripts.append(txt)
+                all_segments.extend(adjusted_segs)
+
+                if return_raw and raw is not None:
+                    raw_results.append(raw)
+
+        finally:
+            # Clean up temporary chunk files
+            for path in temp_files:
+                if path and os.path.exists(path) and path != audio_path:
+                    try:
+                        os.remove(path)
+                    except Exception as e:
+                        logger.warning("Failed to remove chunk file %s: %s", path, e)
+
+        # Sort segments by start time
+        combined = list(zip(all_segments, all_speakers, all_transcripts))
+        combined.sort(key=lambda x: x[0][0])
+        all_segments = [x[0] for x in combined]
+        all_speakers = [x[1] for x in combined]
+        all_transcripts = [x[2] for x in combined]
+
+        if verbose:
+            print(
+                f"Chunked transcription complete. Total segments: {len(all_segments)}"
+            )
+
+        result = {
+            "segments": all_segments,
+            "speakers": all_speakers,
+            "transcripts": all_transcripts,
+        }
+
+        if return_raw and raw_results:
+            result["raw_result"] = {
+                "chunked": True,
+                "chunks": raw_results,
+            }
+
+        return result
+
     def _parse_diarization_response(self, result: Dict[str, Any]) -> Dict[str, Any]:
         """
         Convert LocalAI verbose_json response into the internal format used by Scraibe: