audio2sub 0.1.0__tar.gz

audio2sub-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,58 @@
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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",
+]