audio2sub 0.1.0__py3-none-any.whl

audio2sub/__init__.py

@@ -0,0 +1,113 @@
+"""Audio2Sub package: convert media to subtitles."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Callable, Iterable, List, Optional
+from dataclasses import dataclass
+
+import pysrt
+
+__all__ = ["__version__", "transcribe", "segments_to_srt", "Segment", "Usage"]
+__title__ = "audio2sub"
+__description__ = "Transcribe media files to SRT subtitles."
+__url__ = "https://github.com/Xavier-Lam/audio2sub"
+__version__ = "0.1.0"
+__author__ = "Xavier-Lam"
+__author_email__ = "xavierlam7@hotmail.com"
+
+
+ReporterCallback = Callable[[str, dict], None]
+
+
+@dataclass
+class Segment:
+    index: int
+    start: float
+    end: float
+    text: str = ""
+    audio: Optional[Path] = None
+
+
+from .audio import convert_media_to_wav, cut_wav_segment  # noqa: E402
+from .transcribers.base import Base, Usage  # noqa: E402
+from .vad import SileroVAD  # noqa: E402
+
+
+def transcribe(
+    input_media: str | Path,
+    transcriber: Base,
+    lang: Optional[str] = None,
+    reporter: Optional[ReporterCallback] = None,
+    stats: Optional[Usage | dict] = None,
+    opts: Optional[dict] = None,
+) -> List[Segment]:
+    """Convert media to segments using Silero VAD and batch transcription."""
+
+    input_media = Path(input_media)
+    if not input_media.exists():
+        raise FileNotFoundError(f"Input media not found: {input_media}")
+
+    _output = lambda message: reporter and reporter("status", message=message)
+    _progress = lambda name, current, total, **payload: reporter and reporter(
+        "progress",
+        name=name,
+        current=current,
+        total=total,
+        **payload,
+    )
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        wav_path = Path(tmpdir) / "audio.wav"
+        _output("Converting audio...")
+        convert_media_to_wav(input_media, wav_path)
+
+        vad = SileroVAD(sample_rate=16_000)
+        _output("Running voice activity detection (VAD)...")
+        segments = vad.detect_segments(wav_path)
+        if not segments:
+            raise RuntimeError("No speech detected by Silero VAD")
+        total_segments = len(segments)
+        _output((f"Detected {total_segments} speech segment(s)."))
+        _output("Cutting audio into clips...")
+
+        # Attach indices and extract audio clips for each segment
+        for idx, seg in enumerate(segments, start=1):
+            seg.index = idx
+            seg_path = Path(tmpdir) / f"segment_{idx}.wav"
+            cut_wav_segment(wav_path, seg.start, seg.end, seg_path)
+            seg.audio = seg_path
+
+        _output("Starting transcription...")
+        _progress("transcription", 0, total_segments, unit="seg")
+
+        # Batch transcribe for potential backend optimizations (generator)
+        transcribed_segments: List[Segment] = []
+        completed = 0
+        for seg in transcriber.batch_transcribe(
+            segments, lang=lang, stats=stats, **(opts or {})
+        ):
+            if seg.text.strip():
+                transcribed_segments.append(seg)
+            completed += 1
+            _progress("transcription", completed, total_segments, unit="seg")
+
+        if len(transcribed_segments) == 0:
+            raise RuntimeError("Transcription produced no subtitle lines.")
+
+        _output("Transcription completed.")
+        return transcribed_segments
+
+
+def segments_to_srt(segments: Iterable[Segment]) -> pysrt.SubRipFile:
+    srt = pysrt.SubRipFile()
+    for seg in segments:
+        item = pysrt.SubRipItem(
+            index=seg.index,
+            start=pysrt.SubRipTime(seconds=seg.start),
+            end=pysrt.SubRipTime(seconds=seg.end),
+            text=seg.text,
+        )
+        srt.append(item)
+    return srt

audio2sub/audio.py

@@ -0,0 +1,50 @@
+from pathlib import Path
+
+import ffmpeg
+
+
+def convert_media_to_wav(
+    input_path: str | Path,
+    output_path: str | Path,
+    sample_rate: int = 16_000,
+    channels: int = 1,
+    overwrite: bool = True,
+):
+    """Convert any media file to a WAV"""
+
+    input_path = Path(input_path)
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if not input_path.exists():
+        raise FileNotFoundError(f"Input file does not exist: {input_path}")
+
+    stream = ffmpeg.input(str(input_path)).output(
+        str(output_path),
+        ac=channels,
+        ar=sample_rate,
+        format="wav",
+    )
+    if overwrite:
+        stream = stream.overwrite_output()
+    else:
+        stream = stream.global_args("-n")
+    stream.run(quiet=True)
+
+
+def cut_wav_segment(
+    input_wav: str | Path,
+    start: float,
+    end: float,
+    output_path: str | Path,
+):
+    """Cut a WAV segment using ffmpeg"""
+
+    input_wav = Path(input_wav)
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    stream = ffmpeg.input(str(input_wav), ss=start, to=end).output(
+        str(output_path), acodec="copy"
+    )
+    stream.overwrite_output().run(quiet=True)

audio2sub/cli.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import argparse
+import inspect
+from pathlib import Path
+import warnings
+from typing import Dict, Type
+
+import torch
+from tqdm.auto import tqdm
+
+from . import __version__, segments_to_srt, transcribe, transcribers
+from .transcribers import Base
+
+
+def _available_transcribers() -> Dict[str, Type[Base]]:
+    return {
+        obj.name: obj
+        for _, obj in inspect.getmembers(transcribers, inspect.isclass)
+        if issubclass(obj, Base) and not inspect.isabstract(obj)
+    }
+
+
+def _build_backend_parser(choices: list[str]) -> argparse.ArgumentParser:
+    default = "faster_whisper"
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument(
+        "-t",
+        "--transcriber",
+        choices=choices,
+        default=default,
+        help=f"Transcription backend to use (default: {default})",
+    )
+    return parser
+
+
+def build_parser(
+    available: Dict[str, Type[Base]], args=None
+) -> argparse.ArgumentParser:
+    backend_parser = _build_backend_parser(choices=sorted(available.keys()))
+    backend_args, _remaining = backend_parser.parse_known_args(args)
+
+    parser = argparse.ArgumentParser(
+        prog="audio2sub",
+        description=(
+            "Convert media files to SRT subtitles using FFmpeg, Silero VAD, "
+            "and transcription backends."
+        ),
+        parents=[backend_parser],
+    )
+
+    parser.add_argument("input", help="Path to input media file (audio or video)")
+    parser.add_argument(
+        "-o",
+        "--output",
+        required=True,
+        help="Output SRT file path",
+    )
+    parser.add_argument(
+        "--lang",
+        default=None,
+        help=(
+            "Language code (e.g., en, es, fr). If omitted, backend may default to en. "
+            "See https://github.com/openai/whisper/blob/main/whisper/tokenizer.py for "
+            "a list of available languages."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    available[backend_args.transcriber].contribute_to_cli(parser)
+    return parser
+
+
+def main() -> int:
+    if not torch.cuda.is_available():
+        warnings.warn(
+            "CUDA is not available; performance may be degraded significantly. "
+            "For more information, please refer to the README.md of the project."
+        )
+
+    available = _available_transcribers()
+    parser = build_parser(available)
+    args = parser.parse_args()
+    backend = args.transcriber
+
+    input_media = Path(args.input)
+    output_srt = Path(args.output)
+
+    bars: dict[str, tqdm] = {}
+
+    def reporter(kind: str, **payload):
+        if kind == "status":
+            print(payload.get("message", ""))
+        if kind == "progress":
+            name = payload.pop("name")
+            current = payload.pop("current", 0)
+            total = payload.pop("total", 0)
+
+            bar = bars.get(name)
+            if bar is None:
+                bar = tqdm(
+                    total=total,
+                    desc=name.capitalize(),
+                    leave=True,
+                    **payload,
+                )
+                bars[name] = bar
+            bar.n = current
+            bar.refresh()
+            if current >= total:
+                bar.close()
+                bars.pop(name, None)
+
+    stats = {}
+    transcriber_cls = available[backend]
+    transcriber = transcriber_cls.from_cli_args(args)
+    batch_opts = transcriber_cls.opts_from_cli(args)
+
+    segments = transcribe(
+        input_media,
+        transcriber,
+        lang=args.lang,
+        reporter=reporter,
+        stats=stats,
+        opts=batch_opts,
+    )
+    segments_to_srt(segments).save(str(output_srt))
+
+    print("Stats:")
+    for k, v in stats.items():
+        print(f"  {k}: {v}")
+    print(f"SRT written to {output_srt}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

audio2sub/transcribers/__init__.py

@@ -0,0 +1,22 @@
+from .base import (
+    AIAPITranscriber,
+    Base,
+    MissingDependencyException,
+    Usage,
+)
+from .whisper import Whisper
+from .faster_whisper import FasterWhisper
+from .gemini import Gemini
+from audio2sub import Segment
+
+
+__all__ = [
+    "Base",
+    "AIAPITranscriber",
+    "Whisper",
+    "FasterWhisper",
+    "Gemini",
+    "MissingDependencyException",
+    "Segment",
+    "Usage",
+]

audio2sub/transcribers/base.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import json
+import os
+from abc import ABC, abstractmethod
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Optional, Tuple
+
+from audio2sub import Segment
+
+
+@dataclass
+class Usage:
+    tokens_in: int = 0
+    tokens_out: int = 0
+
+    def export(self, stats: Optional[dict]) -> None:
+        if stats is None:
+            return
+        stats["tokens_in"] = self.tokens_in
+        stats["tokens_out"] = self.tokens_out
+
+
+class Base(ABC):
+    """Base class for transcription backends."""
+
+    name: str = "base"
+
+    @classmethod
+    def contribute_to_cli(cls, parser: argparse.ArgumentParser) -> None:
+        """Hook for CLI option registration."""
+
+    @classmethod
+    def from_cli_args(cls, args: argparse.Namespace) -> "Base":
+        """Instantiate transcriber from CLI args."""
+        return cls()  # pragma: no cover - overridden when needed
+
+    @classmethod
+    def opts_from_cli(cls, args: argparse.Namespace) -> dict:
+        """Extract transcriber-specific options from CLI args."""
+        return {}
+
+    @abstractmethod
+    def transcribe(
+        self,
+        audio_path: str,
+        lang: Optional[str] = None,
+        stats: Optional[dict] = None,
+    ) -> str:
+        """Transcribe a single audio segment and return text."""
+        raise NotImplementedError
+
+    def batch_transcribe(
+        self,
+        segments: List[Segment],
+        lang: Optional[str] = None,
+        stats: Optional[dict] = None,
+    ) -> Iterable[Segment]:
+        """Transcribe a list of segments. Yields updated segments."""
+        for seg in segments:
+            if seg.audio is None:
+                raise FileNotFoundError("Segment has no audio path set")
+            text = self.transcribe(str(seg.audio), lang=lang, stats=stats)
+            seg.text = text
+            yield seg
+
+
+class AIAPITranscriber(Base, ABC):
+    """Base class for AI API transcribers"""
+
+    base_prompt: str = (
+        "You will receive multiple audio clips. Return a JSON array of objects "
+        "with `index` and `text` fields in the same order. Transcribe each "
+        "clip verbatim (no paraphrasing). Omit non-speech clips or return "
+        "empty text."
+    )
+
+    default_model: str = ""
+    default_chunk: int = 20
+
+    api_key_env_var: Optional[str] = None
+
+    def __init__(self, model="", api_key=None) -> None:
+        self.model = model or self.default_model
+        self.api_key = api_key
+
+    @classmethod
+    def contribute_to_cli(cls, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--model",
+            default=cls.default_model or None,
+            help=(
+                "Model name to use"
+                + (f" (default: {cls.default_model})" if cls.default_model else "")
+            ),
+        )
+        parser.add_argument(
+            "--api-key",
+            dest="api_key",
+            required=False,
+            help=(
+                f"API key (optional; env {cls.api_key_env_var or 'API key env var'} "
+                "is used if not provided)"
+            ),
+        )
+
+        # Add batch transcription options
+        parser.add_argument(
+            "--chunk",
+            type=int,
+            default=cls.default_chunk,
+            help=("Number of clips per API request " f"(default: {cls.default_chunk})"),
+        )
+        parser.add_argument(
+            "--outline",
+            dest="outline",
+            required=False,
+            help=("Context outline to guide transcription"),
+        )
+        parser.add_argument(
+            "--prompt",
+            dest="prompt",
+            required=False,
+            help=("Additional system prompt/instructions"),
+        )
+
+    @classmethod
+    def from_cli_args(cls, args: argparse.Namespace) -> "AIAPITranscriber":
+        return cls(model=args.model, api_key=args.api_key)
+
+    @classmethod
+    def opts_from_cli(cls, args: argparse.Namespace) -> dict:
+        return {
+            "chunk": args.chunk,
+            "outline": args.outline,
+            "prompt": args.prompt,
+        }
+
+    def transcribe(
+        self, audio_path: str, lang: Optional[str] = None, stats: Optional[dict] = None
+    ) -> str:
+        segments_iter = self.batch_transcribe(
+            [Segment(index=1, start=0, end=0, audio=Path(audio_path))],
+            lang=lang,
+            stats=stats,
+        )
+        segments = list(segments_iter)
+        return segments[0].text if segments else ""
+
+    def batch_transcribe(
+        self,
+        segments: List[Segment],
+        lang: Optional[str] = None,
+        stats: Optional[dict] = None,
+        chunk: Optional[int] = None,
+        outline: Optional[str] = None,
+        prompt: Optional[str] = None,
+    ) -> Iterable[Segment]:
+        """Transcribe segments with shared chunking, prompt, and stats."""
+
+        chunk_size = chunk if chunk and chunk > 0 else self.default_chunk
+        prompt_cfg = self._build_prompt(lang=lang, outline=outline, prompt=prompt)
+        client = self._ensure_client()
+        usage_tracker = Usage()
+
+        for batch in self._iter_chunks(segments, chunk_size):
+            raw_text, usage = self._request_transcription(client, batch, prompt_cfg)
+            self._parse_response_text(raw_text, batch)
+            if usage:
+                usage_tracker.tokens_in += usage.tokens_in
+                usage_tracker.tokens_out += usage.tokens_out
+                usage_tracker.export(stats)
+            for seg in batch:
+                yield seg
+
+    def _ensure_client(self):
+        if getattr(self, "_client", None):
+            return self._client
+        self._client = self._create_client()
+        return self._client
+
+    @abstractmethod
+    def _create_client(self):
+        """Instantiate the API client."""
+
+    @abstractmethod
+    def _request_transcription(
+        self,
+        client,
+        batch: List[Segment],
+        prompt: List[str],
+    ) -> Tuple[str, Optional[Usage]]:
+        """Call the provider and return (raw_text_response, Usage)."""
+
+    def _iter_chunks(self, items: List[Segment], size: int) -> Iterable[List[Segment]]:
+        if size <= 0:
+            size = len(items)
+        for i in range(0, len(items), size):
+            yield items[i : i + size]
+
+    def _build_prompt(
+        self,
+        lang: Optional[str],
+        outline: Optional[str],
+        prompt: Optional[str],
+    ) -> List[str]:
+        prompt_text = self.base_prompt
+        if lang:
+            prompt_text += (
+                " Primary language is "
+                f"{lang}, but audio may include other languages."
+            )
+        prompt_text += (
+            " Each object's `text` must be the transcription of that specific "
+            "clip, with no labels or formatting. Respond as plain JSON text "
+            "only; do not include markdown or code fences such as ``` or "
+            "other wrappers."
+        )
+        prompt_text += (
+            '\nRespond with JSON array of objects: [{"index": <clip '
+            'index>, "text": <transcription>}, ...].'
+        )
+
+        system_prompts = [prompt_text]
+        if outline:
+            system_prompts.append(
+                "Outline to guide transcription (context only). *Use the outline "
+                "only to make minor corrections to what you hear in the audio "
+                "(for example: fix homophones, obvious mis-hearings, or minor "
+                "punctuation). Do NOT use the outline or any external knowledge "
+                "to create or add words that are not present in the audio*:\n" + outline
+            )
+        if prompt:
+            system_prompts.append("Additional instructions:\n" + prompt)
+
+        # Return raw list of system prompts (was PromptConfig.system_prompts)
+        return system_prompts
+
+    def _parse_response_text(self, raw_text: str, batch: List[Segment]) -> None:
+        raw_text = raw_text.strip()
+        parsed: List[dict] = json.loads(raw_text)
+
+        by_index = {
+            entry.get("index"): entry
+            for entry in parsed
+            if isinstance(entry, dict) and "index" in entry
+        }
+
+        for idx, seg in enumerate(batch):
+            entry = by_index.get(seg.index)
+            if entry:
+                seg.text = entry.get("text", "").strip()
+
+    def _segments_to_audio_bytes(
+        self, batch: List[Segment]
+    ) -> List[Tuple[Segment, bytes]]:
+        payloads: List[Tuple[Segment, bytes]] = []
+        for seg in batch:
+            if seg.audio is None:
+                raise FileNotFoundError("Segment has no audio path set")
+            audio_path = Path(seg.audio)
+            if not audio_path.exists():
+                raise FileNotFoundError(f"Audio not found: {audio_path}")
+            payloads.append((seg, audio_path.read_bytes()))
+        return payloads
+
+    def _resolve_api_key(self) -> str:
+        api_key = self.api_key
+        if not api_key and self.api_key_env_var:
+            api_key = os.getenv(self.api_key_env_var)
+        if not api_key:
+            env_hint = self.api_key_env_var or "API key"
+            raise RuntimeError(f"{env_hint} is required for {self.name} transcriber.")
+        return api_key
+
+
+class MissingDependencyException(RuntimeError):
+    def __init__(self, transcriber) -> None:
+        name = transcriber.name
+        msg = (
+            f"Transcriber '{name}' is not installed. Install with `pip install "
+            f"audio2sub[{name}]`."
+        )
+        super().__init__(msg)

audio2sub/transcribers/faster_whisper.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Optional
+
+from .base import Base, MissingDependencyException
+
+
+class FasterWhisper(Base):
+    """Transcriber using faster-whisper (ctranslate2 backend)."""
+
+    name = "faster_whisper"
+
+    def __init__(self, model_name: str = "turbo") -> None:
+        self.model_name = model_name
+        self._model = None
+
+    @classmethod
+    def contribute_to_cli(cls, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--model",
+            default="turbo",
+            help="Faster-Whisper model name (default: turbo)",
+        )
+
+    @classmethod
+    def from_cli_args(cls, args: argparse.Namespace) -> "FasterWhisper":
+        return cls(model_name=args.model)
+
+    def transcribe(
+        self,
+        audio_path: str,
+        lang: Optional[str] = None,
+        stats: Optional[dict] = None,
+    ) -> str:
+        model = self._ensure_model()
+
+        audio_path = Path(audio_path)
+        if not audio_path.exists():
+            raise FileNotFoundError(f"Audio not found: {audio_path}")
+
+        segments, _info = model.transcribe(
+            str(audio_path),
+            language=lang,
+        )
+
+        return " ".join(seg.text.strip() for seg in segments).strip()
+
+    def _ensure_model(self):  # pragma: no cover - exercised in integration
+        if self._model is not None:
+            return self._model
+        try:
+            import torch
+            from faster_whisper import WhisperModel
+        except ImportError as exc:
+            raise MissingDependencyException(self) from exc
+
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        compute_type = "float16" if device == "cuda" else "int8"
+
+        self._model = WhisperModel(
+            self.model_name, device=device, compute_type=compute_type
+        )
+        return self._model

audio2sub/transcribers/gemini.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from audio2sub import Segment
+from .base import AIAPITranscriber, MissingDependencyException, Usage
+
+
+class Gemini(AIAPITranscriber):
+    """Transcriber using Gemini API (google-genai)."""
+
+    name = "gemini"
+    default_model = "gemini-2.5-flash"
+    api_key_env_var = "GEMINI_API_KEY"
+
+    def _create_client(self):
+        try:
+            from google import genai
+        except ImportError as exc:
+            raise MissingDependencyException(self) from exc
+
+        api_key = self._resolve_api_key()
+        return genai.Client(api_key=api_key)
+
+    def _request_transcription(
+        self,
+        client,
+        batch: List[Segment],
+        prompt: List[str],
+    ) -> Tuple[str, Optional[Usage]]:
+        parts = [{"text": "\n\n".join(prompt)}]
+        parts.extend(self._build_parts(batch=batch))
+        contents = [{"role": "user", "parts": parts}]
+
+        response = client.models.generate_content(
+            model=self.model,
+            contents=contents,
+        )
+        raw_text = response.text.strip() if hasattr(response, "text") else ""
+
+        usage = Usage(
+            tokens_in=getattr(response.usage_metadata, "prompt_token_count", 0),
+            tokens_out=getattr(response.usage_metadata, "candidates_token_count", 0),
+        )
+        return raw_text, usage
+
+    def _build_parts(self, batch: List[Segment]) -> List[dict]:
+        parts: List[dict] = []
+        for seg, audio_bytes in self._segments_to_audio_bytes(batch):
+            parts.append({"text": f"Clip {seg.index}"})
+            parts.append(
+                {"inline_data": {"mime_type": "audio/wav", "data": audio_bytes}}
+            )
+
+        return parts

audio2sub/transcribers/whisper.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Optional
+
+from .base import Base, MissingDependencyException
+
+
+class Whisper(Base):
+    """Whisper-based transcriber (openai/whisper) for single audio segments."""
+
+    name = "whisper"
+
+    def __init__(self, model_name: str = "turbo") -> None:
+        self.model_name = model_name
+        self._model = None
+
+    @classmethod
+    def contribute_to_cli(cls, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--model",
+            default="turbo",
+            help="Whisper model name (default: turbo)",
+        )
+
+    @classmethod
+    def from_cli_args(cls, args: argparse.Namespace) -> "Whisper":
+        return cls(args.model)
+
+    def transcribe(
+        self,
+        audio_path: str,
+        lang: Optional[str] = None,
+        stats: Optional[dict] = None,
+    ) -> str:
+        model, whisper = self._ensure_model()
+
+        audio_path = Path(audio_path)
+        if not audio_path.exists():
+            raise FileNotFoundError(f"Audio not found: {audio_path}")
+
+        audio = whisper.load_audio(str(audio_path))
+        result = model.transcribe(
+            audio,
+            language=lang or "en",
+            task="transcribe",
+            fp16=model.device.type == "cuda",
+        )
+        text = result.get("text", "")
+        return str(text).strip()
+
+    def _ensure_model(self):
+        try:
+            import torch
+            import whisper
+        except ImportError as exc:
+            raise MissingDependencyException(self) from exc
+
+        if self._model is not None:
+            return self._model, whisper
+
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        self._model = whisper.load_model(self.model_name, device=device)
+        return self._model, whisper

audio2sub/vad.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+import ffmpeg
+import numpy as np
+import torch
+
+from audio2sub import Segment
+
+
+class SileroVAD:
+    """Thin wrapper around snakers4/silero-vad for speech timestamp detection."""
+
+    def __init__(
+        self,
+        threshold: float = 0.5,
+        min_silence_duration: float = 0.5,
+        window_size_samples: int = 512,
+        sample_rate: int = 16_000,
+    ) -> None:
+        self.threshold = threshold
+        self.min_silence_duration = min_silence_duration
+        self.window_size_samples = window_size_samples
+        self.sample_rate = sample_rate
+
+    def detect_segments(self, wav_path: str | Path) -> List[Segment]:
+        try:
+            model, utils = torch.hub.load(
+                repo_or_dir="snakers4/silero-vad",
+                model="silero_vad",
+                force_reload=False,
+                onnx=False,
+                trust_repo=True,
+            )
+            get_speech_timestamps = utils[0]
+        except Exception as exc:
+            raise RuntimeError(f"Failed to load silero-vad: {exc}") from exc
+
+        # Read WAV via ffmpeg pipe (float32 mono at target sample rate)
+        process = (
+            ffmpeg.input(str(wav_path))
+            .output(
+                "pipe:",
+                format="f32le",
+                ac=1,
+                ar=self.sample_rate,
+            )
+            .run(capture_stdout=True, capture_stderr=True)
+        )
+        audio_bytes, stderr = process
+
+        wav_np = np.frombuffer(audio_bytes, dtype=np.float32).copy()
+        if wav_np.size == 0:
+            raise RuntimeError("No audio data decoded from WAV.")
+        wav = torch.from_numpy(wav_np)
+
+        timestamps = get_speech_timestamps(
+            wav,
+            model,
+            sampling_rate=self.sample_rate,
+            threshold=self.threshold,
+            min_silence_duration_ms=int(self.min_silence_duration * 1000),
+            window_size_samples=self.window_size_samples,
+        )
+
+        segments: List[Segment] = []
+        for idx, ts in enumerate(timestamps, start=1):
+            start = ts.get("start", 0) / self.sample_rate
+            end = ts.get("end", 0) / self.sample_rate
+            if end > start:
+                segments.append(Segment(index=idx, start=start, end=end))
+        return segments

audio2sub-0.1.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: audio2sub
+Version: 0.1.0
+Summary: Transcribe media files to SRT subtitles.
+Home-page: https://github.com/Xavier-Lam/audio2sub
+Author: Xavier-Lam
+Author-email: xavierlam7@hotmail.com
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.1.0
+Requires-Dist: torchaudio>=2.1.0
+Requires-Dist: ffmpeg-python>=0.2.0
+Requires-Dist: pysrt>=1.1.2
+Requires-Dist: tqdm
+Requires-Dist: onnxruntime<2,>=1.14
+Requires-Dist: numpy
+Provides-Extra: faster-whisper
+Requires-Dist: faster-whisper>=1.0.1; extra == "faster-whisper"
+Provides-Extra: whisper
+Requires-Dist: openai-whisper>=20231117; extra == "whisper"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == "gemini"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: openai-whisper>=20231117; extra == "dev"
+Requires-Dist: faster-whisper>=1.0.1; extra == "dev"
+Requires-Dist: google-genai>=1.0.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: openai-whisper>=20231117; extra == "all"
+Requires-Dist: faster-whisper>=1.0.1; extra == "all"
+Requires-Dist: google-genai>=1.0.0; extra == "all"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Audio2Sub
+
+**Audio2Sub** is a command-line tool that automatically transcribes audio from video or audio files and generates subtitles in the `.srt` format. It uses FFmpeg for media handling, [Silero VAD](https://github.com/snakers4/silero-vad) for precise voice activity detection, and supports multiple transcription backends to convert speech to text.
+
+## Installation
+
+Before installing, you must have [FFmpeg](https://ffmpeg.org/download.html) installed and available in your system's PATH.
+
+You can install Audio2Sub using `pip`. The default installation includes the `faster_whisper` backend.
+
+```bash
+pip install audio2sub[faster_whisper]
+```
+
+To install with a different backend, see the table in the [Backends](#Backends) section below.
+
+## Usage
+### Basic Example
+
+```bash
+audio2sub my_video.mp4 -o my_video.srt --lang en
+```
+
+This command will transcribe the audio from `my_video.mp4` into English and save the subtitles to `my_video.srt`.
+
+**Notes:**
+*   **First-Time Use**: The first time you run the program, it will download the necessary transcription models. This may take some time and require significant disk space.
+*   **CUDA**: Performance significantly degraded without CUDA when using whisper-based local models. The program will raise a warning if CUDA is not available when it starts. If your system has a compatible GPU, install the [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit-archive) first. If you are sure CUDA has been installed correctly and still get the warning, you may need to [reinstall a compatible PyTorch version manually](https://pytorch.org/get-started/locally/). The reinstallation of PyTorch may break other dependencies if you choose a different version than what you currently have. In this case, you may need to reinstall those according to the warnings shown.
+
+### Using a Different Transcriber
+
+Use the `-t` or `--transcriber` flag to select a different backend.
+
+```bash
+audio2sub my_audio.wav -o my_audio.srt --lang en -t whisper --model medium
+```
+
+Each transcriber has its own options. To see them, use `--help` with the transcriber specified.
+
+```bash
+audio2sub -t faster_whisper --help
+```
+
+## Backends
+
+Audio2Sub supports the following transcription backends.
+
+| Backend Name      | Description |
+| --- | --- |
+| `faster_whisper` | A faster reimplementation of Whisper using CTranslate2. See [Faster Whisper](https://github.com/guillaumekln/faster-whisper). This is the default backend. |
+| `whisper`        | The original speech recognition model by OpenAI. See [OpenAI Whisper](https://github.com/openai/whisper). |
+| `gemini`         | Google's Gemini model via their API. Requires a `GEMINI_API_KEY` environment variable or `--gemini-api-key` argument.|
+
+You should use `pip install audio2sub[<backend>]` to install the desired backend support and use the corresponding transcriber with the `-t` flag.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on the GitHub repository.

audio2sub-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+audio2sub/__init__.py,sha256=vtNHWilMeUJh8aMQqeWqIq_hWNr4TJ_kawfdz2XSxrQ,3661
+audio2sub/audio.py,sha256=WsSJNqT62Q-7aq4JwD4bpNRlTMjNKcAMr451sOo82tY,1226
+audio2sub/cli.py,sha256=rh2QxNfqKsXtsuhmZpJIyYxMrOYnoT8bq9eU93tegQQ,3930
+audio2sub/vad.py,sha256=0s710xcdupOvGcLMtadUcB_86oKeK4z9Klh5CR_mZqs,2360
+audio2sub/transcribers/__init__.py,sha256=NnwNvg_RXXXNcSctcHSDKMRFbZ0-uW_ABiWX2YJKyiw,389
+audio2sub/transcribers/base.py,sha256=-uwK7xfJ_i9yEPg9g3bD8XXiPnpGhajSGhWmSobThZE,9508
+audio2sub/transcribers/faster_whisper.py,sha256=Dc5KXsmZbdrS71r3KBQH_ExOYYXY4NqEu8ZKGqigKuQ,1898
+audio2sub/transcribers/gemini.py,sha256=-67zkMnhB4ruxWCLspVY4JVXWZgkcNL72RpVRruELno,1741
+audio2sub/transcribers/whisper.py,sha256=2iQP6kqqL1CzkZeSfcIGYyutT8DyWSurY-IO3NRCVBk,1840
+audio2sub-0.1.0.dist-info/licenses/LICENSE,sha256=NoqtIpP2SxhnVDs1RxKe2oLL5QdcHxyg5Ytzvenh5w0,1076
+audio2sub-0.1.0.dist-info/METADATA,sha256=cQsgoEjP-wmjPS5vcGUlNg9rEoLk2WjJ0qOZvdKD_6c,5013
+audio2sub-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+audio2sub-0.1.0.dist-info/entry_points.txt,sha256=8dJOZbTc4JrkIXJbWauaCqoZeASo76z6jTWC_kFPpvU,49
+audio2sub-0.1.0.dist-info/top_level.txt,sha256=LAGOkV7oCPKbeFHyx_U0tM5_vj7X3BiG_FbrizXM1JI,10
+audio2sub-0.1.0.dist-info/RECORD,,

audio2sub-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

audio2sub-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+audio2sub = audio2sub.cli:main

audio2sub-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Xavier-Lam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

audio2sub-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+audio2sub