localcaption 0.1.0__py3-none-any.whl

localcaption/__init__.py

@@ -0,0 +1,14 @@
+"""localcaption — fully-local YouTube → transcript pipeline.
+
+A thin orchestrator over yt-dlp, ffmpeg, and whisper.cpp. No API keys,
+nothing leaves your machine.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("localcaption")
+except PackageNotFoundError:  # editable install before metadata is generated
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

localcaption/__main__.py

@@ -0,0 +1,10 @@
+"""Allow `python -m localcaption ...` invocation."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

localcaption/_logging.py

@@ -0,0 +1,26 @@
+"""Tiny logging shim so every module logs in the same style without pulling
+in a heavyweight logging config. Honors `NO_COLOR` and non-tty stdout.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_ENABLE_COLOR = sys.stdout.isatty() and "NO_COLOR" not in os.environ
+
+
+def _wrap(code: str, msg: str) -> str:
+    return f"\033[{code}m{msg}\033[0m" if _ENABLE_COLOR else msg
+
+
+def info(msg: str) -> None:
+    print(f"{_wrap('1;34', '[localcaption]')} {msg}", flush=True)
+
+
+def warn(msg: str) -> None:
+    print(f"{_wrap('1;33', '[warning    ]')} {msg}", file=sys.stderr, flush=True)
+
+
+def error(msg: str) -> None:
+    print(f"{_wrap('1;31', '[error      ]')} {msg}", file=sys.stderr, flush=True)

localcaption/audio.py

@@ -0,0 +1,48 @@
+"""Stage 2: re-encode arbitrary audio to 16 kHz mono PCM WAV.
+
+whisper.cpp expects exactly that format, so this stage is a hard requirement
+even when the source is already a `.wav` (sample rate / channel count may
+not match).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from . import _logging as log
+from .errors import AudioConversionError, DependencyError
+
+WHISPER_SAMPLE_RATE = 16_000
+WHISPER_CHANNELS = 1
+
+
+def to_whisper_wav(src: Path, dst: Path) -> Path:
+    """Convert *src* to a 16 kHz mono PCM WAV at *dst* and return *dst*."""
+    if shutil.which("ffmpeg") is None:
+        raise DependencyError(
+            "Required tool 'ffmpeg' was not found on PATH. "
+            "On macOS: brew install ffmpeg"
+        )
+
+    cmd = [
+        "ffmpeg", "-y", "-loglevel", "error",
+        "-i", str(src),
+        "-ac", str(WHISPER_CHANNELS),
+        "-ar", str(WHISPER_SAMPLE_RATE),
+        "-vn",                       # drop any video stream
+        "-c:a", "pcm_s16le",         # signed 16-bit little-endian PCM
+        str(dst),
+    ]
+    log.info(f"ffmpeg: re-encoding to {WHISPER_SAMPLE_RATE} Hz mono WAV")
+    try:
+        subprocess.run(cmd, check=True)
+    except subprocess.CalledProcessError as exc:
+        raise AudioConversionError(
+            f"ffmpeg failed (exit {exc.returncode}) while converting {src}"
+        ) from exc
+
+    if not dst.is_file():
+        raise AudioConversionError(f"ffmpeg ran but {dst} was not created")
+    return dst

localcaption/cli.py

@@ -0,0 +1,260 @@
+"""Command-line entry point.
+
+Exposed as the ``localcaption`` console script via ``pyproject.toml``.
+
+Two invocation styles are supported:
+
+    localcaption <url> [options]      # one-shot transcription (default)
+    localcaption doctor               # diagnose your install
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from . import __version__
+from . import _logging as log
+from .errors import LocalCaptionError
+from .pipeline import transcribe_url
+from .whisper import DEFAULT_MODEL, WhisperPaths
+
+# Subcommands recognised by the dispatcher. Anything else is treated as a URL
+# and routed to the implicit "transcribe" command for backwards compatibility.
+SUBCOMMANDS = frozenset({"doctor", "transcribe"})
+
+
+# --- whisper.cpp directory resolution ------------------------------------
+
+def _xdg_data_home() -> Path:
+    """Return $XDG_DATA_HOME or its conventional fallback (~/.local/share)."""
+    env = os.environ.get("XDG_DATA_HOME")
+    return Path(env).expanduser() if env else Path.home() / ".local" / "share"
+
+
+def _candidate_whisper_dirs() -> list[Path]:
+    """Where to look for the whisper.cpp checkout, in priority order.
+
+    1. ``$LOCALCAPTION_WHISPER_DIR`` if set (explicit override).
+    2. ``./whisper.cpp`` if running from a dev checkout.
+    3. ``$XDG_DATA_HOME/localcaption/whisper.cpp`` (where ``install.sh`` puts it).
+    """
+    candidates: list[Path] = []
+    env = os.environ.get("LOCALCAPTION_WHISPER_DIR")
+    if env:
+        candidates.append(Path(env).expanduser())
+    candidates.append(Path.cwd() / "whisper.cpp")
+    candidates.append(_xdg_data_home() / "localcaption" / "whisper.cpp")
+    return candidates
+
+
+def _default_whisper_dir() -> Path:
+    """Pick the first existing whisper.cpp directory, or the last candidate.
+
+    The "last candidate" fallback ensures error messages point users at the
+    canonical install location rather than the dev-only ``./whisper.cpp``.
+    """
+    candidates = _candidate_whisper_dirs()
+    for c in candidates:
+        if c.is_dir():
+            return c
+    return candidates[-1]
+
+
+# --- transcribe (default) subcommand -------------------------------------
+
+def _build_transcribe_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="localcaption",
+        description="Fully-local YouTube → transcript using yt-dlp + ffmpeg + whisper.cpp.",
+    )
+    parser.add_argument("url", help="YouTube URL (or any URL yt-dlp supports)")
+    parser.add_argument(
+        "-m", "--model", default=DEFAULT_MODEL,
+        help=f"whisper model name (default: {DEFAULT_MODEL})",
+    )
+    parser.add_argument(
+        "-o", "--out", type=Path, default=Path.cwd() / "transcripts",
+        help="output directory for transcript files (default: ./transcripts)",
+    )
+    parser.add_argument(
+        "-l", "--language", default="auto",
+        help="ISO language code, or 'auto' (default: auto)",
+    )
+    parser.add_argument(
+        "--whisper-dir", type=Path, default=None,
+        help="path to a built whisper.cpp checkout "
+             "(default: $LOCALCAPTION_WHISPER_DIR, ./whisper.cpp, "
+             "or ~/.local/share/localcaption/whisper.cpp)",
+    )
+    parser.add_argument(
+        "--keep-audio", action="store_true",
+        help="keep the downloaded audio and intermediate WAV under <out>/.work/",
+    )
+    parser.add_argument(
+        "--no-print", action="store_true",
+        help="do not echo the transcript to stdout when finished",
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def _cmd_transcribe(argv: list[str]) -> int:
+    args = _build_transcribe_parser().parse_args(argv)
+    whisper_dir = args.whisper_dir or _default_whisper_dir()
+
+    try:
+        result = transcribe_url(
+            args.url,
+            out_dir=args.out,
+            whisper_dir=whisper_dir,
+            model=args.model,
+            language=args.language,
+            keep_intermediate=args.keep_audio,
+        )
+    except LocalCaptionError as exc:
+        log.error(str(exc))
+        return 1
+
+    log.info("transcript files:")
+    for kind, path in result.transcripts.existing().items():
+        print(f"  {kind:>4}: {path}")
+
+    if not args.no_print:
+        txt = result.transcripts.txt
+        if txt.exists():
+            print("\n" + "─" * 30 + " transcript " + "─" * 30)
+            print(txt.read_text(encoding="utf-8", errors="replace"))
+
+    return 0
+
+
+# --- doctor subcommand ---------------------------------------------------
+
+def _check(label: str, ok: bool, detail: str = "") -> bool:
+    """Print a diagnostic line. Returns ``ok`` for chaining into a final exit code."""
+    mark = "✅" if ok else "❌"
+    suffix = f"  ({detail})" if detail else ""
+    print(f"  {mark} {label}{suffix}")
+    return ok
+
+
+def _cmd_doctor(argv: list[str]) -> int:
+    """Diagnose a localcaption install: prereqs, whisper.cpp, models."""
+    parser = argparse.ArgumentParser(
+        prog="localcaption doctor",
+        description="Diagnose a localcaption install: external tools, "
+                    "whisper.cpp build, available models.",
+    )
+    parser.add_argument(
+        "--whisper-dir", type=Path, default=None,
+        help="check this whisper.cpp directory (default: auto-detect)",
+    )
+    args = parser.parse_args(argv)
+
+    print(f"localcaption {__version__}\n")
+
+    all_ok = True
+
+    print("System tools:")
+    all_ok &= _check("python", True, sys.version.split()[0])
+    ff = shutil.which("ffmpeg")
+    all_ok &= _check("ffmpeg", ff is not None, ff or "missing — `brew install ffmpeg`")
+    git = shutil.which("git")
+    all_ok &= _check("git", git is not None, git or "missing")
+
+    print("\nPython dependencies:")
+    try:
+        import yt_dlp  # noqa: F401
+        from yt_dlp.version import __version__ as ytdlp_ver
+        all_ok &= _check("yt-dlp", True, ytdlp_ver)
+    except ImportError:
+        all_ok &= _check("yt-dlp", False, "missing — `pip install yt-dlp`")
+
+    print("\nwhisper.cpp:")
+    whisper_dir = args.whisper_dir or _default_whisper_dir()
+    print(f"  searching: {whisper_dir}")
+    if whisper_dir.is_dir():
+        _check("directory exists", True, str(whisper_dir))
+        paths = WhisperPaths(whisper_dir)
+        try:
+            binary = paths.find_binary()
+            all_ok &= _check("binary built", True, str(binary))
+        except LocalCaptionError as exc:
+            all_ok &= _check("binary built", False, str(exc).splitlines()[0])
+
+        models_dir = paths.models_dir
+        if models_dir.is_dir():
+            available = sorted(p.name for p in models_dir.glob("ggml-*.bin"))
+            if available:
+                _check("models present", True, ", ".join(available))
+            else:
+                all_ok &= _check(
+                    "models present", False,
+                    f"no ggml-*.bin in {models_dir} — "
+                    f"`bash {models_dir}/download-ggml-model.sh base.en`",
+                )
+        else:
+            all_ok &= _check("models directory", False, str(models_dir))
+    else:
+        all_ok &= _check(
+            "directory exists", False,
+            "run install.sh or set --whisper-dir / $LOCALCAPTION_WHISPER_DIR",
+        )
+
+    print("\nLookup paths searched:")
+    for c in _candidate_whisper_dirs():
+        marker = "✓" if c.is_dir() else "·"
+        print(f"  {marker} {c}")
+
+    print()
+    if all_ok:
+        print("All checks passed. You're good to go: localcaption <url>")
+        return 0
+    else:
+        print("Some checks failed. See messages above.")
+        return 1
+
+
+# --- top-level dispatcher -------------------------------------------------
+
+def _print_top_level_help() -> None:
+    print("""\
+usage: localcaption <url> [options]            transcribe a video (default)
+       localcaption doctor                     diagnose your install
+       localcaption --help                     show transcribe help
+       localcaption --version                  print version
+
+Run `localcaption <subcommand> --help` for details on each.""")
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    # Bare invocation → top-level help (exit non-zero, like most CLIs do).
+    if not argv:
+        _print_top_level_help()
+        return 2
+
+    head = argv[0]
+
+    # Allow `localcaption help` as a friendly alias for the top-level help.
+    if head in {"help", "--help-all"}:
+        _print_top_level_help()
+        return 0
+
+    # Explicit subcommands.
+    if head == "doctor":
+        return _cmd_doctor(argv[1:])
+    if head == "transcribe":
+        return _cmd_transcribe(argv[1:])
+
+    # Anything else (URL, --help, --version, …) goes to the default transcribe.
+    return _cmd_transcribe(argv)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

localcaption/download.py

@@ -0,0 +1,79 @@
+"""Stage 1: download the best available audio stream with yt-dlp.
+
+We use yt-dlp's Python API rather than the CLI so we can deterministically
+discover the resulting filename via :py:meth:`YoutubeDL.prepare_filename`.
+This avoids the fragility of parsing ``--print after_move:filepath`` output
+across yt-dlp versions.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import _logging as log
+from .errors import DependencyError, DownloadError
+
+# YouTube periodically blocks specific player clients. The mobile clients
+# tend to be the most stable for audio-only retrieval. Order matters: yt-dlp
+# tries them left-to-right.
+DEFAULT_PLAYER_CLIENTS: tuple[str, ...] = ("android", "ios", "web")
+
+
+def download_audio(
+    url: str,
+    work_dir: Path,
+    *,
+    player_clients: tuple[str, ...] = DEFAULT_PLAYER_CLIENTS,
+) -> Path:
+    """Download the best audio stream for *url* into *work_dir*.
+
+    Returns the path to the downloaded file. Raises :class:`DownloadError`
+    if yt-dlp fails to produce a usable file.
+    """
+    try:
+        from yt_dlp import YoutubeDL
+    except ImportError as exc:
+        raise DependencyError(
+            "Python package 'yt-dlp' is not installed. "
+            "Install with: pip install -e .[dev]   (or)   pip install yt-dlp"
+        ) from exc
+
+    ydl_opts: dict[str, Any] = {
+        "format": "bestaudio/best",
+        "outtmpl": str(work_dir / "%(id)s.%(ext)s"),
+        "noplaylist": True,
+        "quiet": False,
+        "no_warnings": True,
+        "restrictfilenames": True,
+        "overwrites": True,
+        "retries": 5,
+        "fragment_retries": 5,
+        "extractor_args": {"youtube": {"player_client": list(player_clients)}},
+    }
+
+    log.info(f"yt-dlp: downloading bestaudio for {url}")
+    try:
+        with YoutubeDL(ydl_opts) as ydl:
+            info = ydl.extract_info(url, download=True)
+            # Playlists nest one level deeper. We disabled them above, but be
+            # defensive in case the URL is e.g. a single video inside a list.
+            if "entries" in info and info["entries"]:
+                info = info["entries"][0]
+            audio_path = Path(ydl.prepare_filename(info))
+    except Exception as exc:  # yt-dlp raises a zoo of exception types
+        raise DownloadError(f"yt-dlp failed: {exc}") from exc
+
+    # If a post-processor changed the extension, fall back to scanning by id.
+    if not audio_path.is_file():
+        matches = sorted(work_dir.glob(f"{info.get('id', '*')}.*"))
+        if matches:
+            audio_path = matches[0]
+
+    if not audio_path.is_file():
+        raise DownloadError(
+            f"yt-dlp finished but no audio file was found near {audio_path}"
+        )
+
+    log.info(f"downloaded audio: {audio_path.name}")
+    return audio_path

localcaption/errors.py

@@ -0,0 +1,27 @@
+"""Custom exceptions for localcaption.
+
+Defining a small hierarchy makes it easy for callers (and tests) to catch
+a specific failure mode rather than scraping error strings.
+"""
+
+from __future__ import annotations
+
+
+class LocalCaptionError(Exception):
+    """Base class for all localcaption errors."""
+
+
+class DependencyError(LocalCaptionError):
+    """A required external tool or model is missing."""
+
+
+class DownloadError(LocalCaptionError):
+    """yt-dlp failed to fetch the requested media."""
+
+
+class AudioConversionError(LocalCaptionError):
+    """ffmpeg failed to produce the expected WAV file."""
+
+
+class TranscriptionError(LocalCaptionError):
+    """whisper.cpp failed to produce a transcript."""

localcaption/pipeline.py

@@ -0,0 +1,82 @@
+"""High-level orchestration: URL → transcript artefacts.
+
+This module is the public Python API. The CLI is a thin wrapper around
+:func:`transcribe_url`.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import _logging as log
+from .audio import to_whisper_wav
+from .download import download_audio
+from .whisper import DEFAULT_MODEL, TranscriptionResult, transcribe
+
+
+@dataclass(frozen=True)
+class PipelineResult:
+    """Aggregated result of one URL → transcript run."""
+    source_url: str
+    audio_path: Path | None
+    wav_path: Path | None
+    transcripts: TranscriptionResult
+
+
+def transcribe_url(
+    url: str,
+    *,
+    out_dir: Path,
+    whisper_dir: Path,
+    model: str = DEFAULT_MODEL,
+    language: str = "auto",
+    keep_intermediate: bool = False,
+) -> PipelineResult:
+    """Run the full pipeline on *url* and return the produced artefacts.
+
+    Parameters
+    ----------
+    url:
+        Any URL `yt-dlp` can resolve.
+    out_dir:
+        Directory for the final transcript files.
+    whisper_dir:
+        Path to the whisper.cpp checkout (built and with a ggml model present).
+    model:
+        whisper.cpp model name (e.g. ``base.en``, ``small.en``, ``large-v3``).
+    language:
+        ISO language code or ``"auto"`` to let whisper detect it.
+    keep_intermediate:
+        If True, leave the downloaded audio + 16 kHz WAV in ``out_dir/.work``.
+    """
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    work_dir = out_dir / ".work"
+    work_dir.mkdir(parents=True, exist_ok=True)
+
+    audio_path: Path | None = None
+    wav_path: Path | None = None
+    try:
+        audio_path = download_audio(url, work_dir)
+        wav_path = work_dir / f"{audio_path.stem}.16k.wav"
+        to_whisper_wav(audio_path, wav_path)
+
+        out_base = out_dir / audio_path.stem
+        transcripts = transcribe(
+            wav_path, model, out_base, whisper_dir=whisper_dir, language=language
+        )
+    finally:
+        if not keep_intermediate:
+            shutil.rmtree(work_dir, ignore_errors=True)
+            audio_path = None
+            wav_path = None
+
+    log.info("done")
+    return PipelineResult(
+        source_url=url,
+        audio_path=audio_path,
+        wav_path=wav_path,
+        transcripts=transcripts,
+    )

localcaption/whisper.py

@@ -0,0 +1,103 @@
+"""Stage 3: run whisper.cpp against a 16 kHz mono WAV.
+
+The whisper.cpp checkout is treated as an external dependency installed by
+``scripts/setup.sh``. We auto-detect the binary because the project moved
+its executable around historically (``main`` → ``build/bin/main`` →
+``build/bin/whisper-cli``).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import _logging as log
+from .errors import DependencyError, TranscriptionError
+
+DEFAULT_MODEL = "base.en"
+SUPPORTED_OUTPUT_FORMATS = ("txt", "srt", "vtt", "json")
+
+
+@dataclass(frozen=True)
+class WhisperPaths:
+    """Locations of an installed whisper.cpp checkout."""
+    root: Path
+
+    @property
+    def models_dir(self) -> Path:
+        return self.root / "models"
+
+    def model_file(self, model_name: str) -> Path:
+        return self.models_dir / f"ggml-{model_name}.bin"
+
+    def find_binary(self) -> Path:
+        candidates = [
+            self.root / "build" / "bin" / "whisper-cli",
+            self.root / "build" / "bin" / "main",
+            self.root / "main",
+        ]
+        for c in candidates:
+            if c.is_file() and os.access(c, os.X_OK):
+                return c
+        raise DependencyError(
+            f"whisper.cpp binary not found under {self.root}. "
+            "Run scripts/setup.sh to build it."
+        )
+
+
+@dataclass(frozen=True)
+class TranscriptionResult:
+    """Paths to the artefacts emitted by whisper.cpp."""
+    txt: Path
+    srt: Path
+    vtt: Path
+    json: Path
+
+    def existing(self) -> dict[str, Path]:
+        """Return only the outputs that actually exist on disk."""
+        return {k: v for k, v in vars(self).items() if isinstance(v, Path) and v.exists()}
+
+
+def transcribe(
+    wav: Path,
+    model: str,
+    out_basename: Path,
+    *,
+    whisper_dir: Path,
+    language: str = "auto",
+) -> TranscriptionResult:
+    """Run whisper.cpp on *wav* and emit transcripts at *out_basename*.{txt,srt,vtt,json}."""
+    paths = WhisperPaths(whisper_dir)
+    binary = paths.find_binary()
+    model_path = paths.model_file(model)
+    if not model_path.is_file():
+        raise DependencyError(
+            f"Model file missing: {model_path}\n"
+            f"Download it with: bash {paths.models_dir}/download-ggml-model.sh {model}"
+        )
+
+    out_basename.parent.mkdir(parents=True, exist_ok=True)
+    cmd = [
+        str(binary),
+        "-m", str(model_path),
+        "-f", str(wav),
+        "-of", str(out_basename),
+        "-otxt", "-osrt", "-ovtt", "-oj",
+        "-l", language,
+    ]
+    log.info(f"whisper.cpp: model={model} language={language}")
+    try:
+        subprocess.run(cmd, check=True)
+    except subprocess.CalledProcessError as exc:
+        raise TranscriptionError(
+            f"whisper.cpp failed (exit {exc.returncode}) on {wav}"
+        ) from exc
+
+    return TranscriptionResult(
+        txt=out_basename.with_suffix(".txt"),
+        srt=out_basename.with_suffix(".srt"),
+        vtt=out_basename.with_suffix(".vtt"),
+        json=out_basename.with_suffix(".json"),
+    )

localcaption-0.1.0.dist-info/METADATA

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: localcaption
+Version: 0.1.0
+Summary: Fully-local YouTube → transcript pipeline using yt-dlp, ffmpeg, and whisper.cpp. No API keys.
+Project-URL: Homepage, https://github.com/jatinkrmalik/localcaption
+Project-URL: Repository, https://github.com/jatinkrmalik/localcaption
+Project-URL: Issues, https://github.com/jatinkrmalik/localcaption/issues
+Project-URL: Changelog, https://github.com/jatinkrmalik/localcaption/blob/main/CHANGELOG.md
+Author: Jatin Kumar Malik
+License: MIT License
+        
+        Copyright (c) 2026 Jatin Kumar Malik
+        
+        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.
+License-File: LICENSE
+Keywords: captions,local,speech-to-text,subtitles,transcription,whisper,whisper.cpp,youtube,yt-dlp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: yt-dlp>=2025.10.14
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# localcaption
+
+> Paste a YouTube URL, get a transcript. **Fully local, no API keys.**
+
+<!-- Package & versioning -->
+[![PyPI version](https://img.shields.io/pypi/v/localcaption?logo=pypi&logoColor=white&color=%233775A9)](https://pypi.org/project/localcaption/)
+[![Python versions](https://img.shields.io/pypi/pyversions/localcaption?logo=python&logoColor=white)](https://pypi.org/project/localcaption/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/localcaption?logo=pypi&logoColor=white&label=downloads%2Fmo&color=%23306998)](https://pypistats.org/packages/localcaption)
+[![License: MIT](https://img.shields.io/github/license/jatinkrmalik/localcaption?color=yellow)](LICENSE)
+
+<!-- Build & code quality -->
+[![CI](https://github.com/jatinkrmalik/localcaption/actions/workflows/ci.yml/badge.svg)](https://github.com/jatinkrmalik/localcaption/actions/workflows/ci.yml)
+[![Release](https://github.com/jatinkrmalik/localcaption/actions/workflows/release.yml/badge.svg)](https://github.com/jatinkrmalik/localcaption/actions/workflows/release.yml)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+
+<!-- Repo activity & community -->
+[![GitHub release](https://img.shields.io/github/v/release/jatinkrmalik/localcaption?include_prereleases&label=latest%20release&logo=github)](https://github.com/jatinkrmalik/localcaption/releases)
+[![GitHub stars](https://img.shields.io/github/stars/jatinkrmalik/localcaption?style=flat&logo=github)](https://github.com/jatinkrmalik/localcaption/stargazers)
+[![Open issues](https://img.shields.io/github/issues/jatinkrmalik/localcaption?logo=github)](https://github.com/jatinkrmalik/localcaption/issues)
+[![Last commit](https://img.shields.io/github/last-commit/jatinkrmalik/localcaption?logo=github)](https://github.com/jatinkrmalik/localcaption/commits/main)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+`localcaption` is a tiny orchestrator over three battle-tested tools:
+
+| Stage | Tool |
+|---|---|
+| Download bestaudio | [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) |
+| Re-encode to 16 kHz mono WAV | [`ffmpeg`](https://ffmpeg.org/) |
+| Transcribe locally | [`whisper.cpp`](https://github.com/ggerganov/whisper.cpp) |
+
+Nothing is uploaded to a third-party service. No OpenAI / Google / DeepL keys
+required. Runs happily on a laptop.
+
+![Pipeline overview](docs/diagrams/pipeline.png)
+
+## Install
+
+### Prerequisites
+
+- Python 3.10+
+- `git`, `ffmpeg`, `cmake` on your `$PATH`
+  (macOS: `brew install ffmpeg cmake`)
+
+### Quick install (recommended for end users)
+
+One command. Installs `localcaption` system-wide via [pipx](https://pipx.pypa.io)
+and bootstraps `whisper.cpp` + a default model. After this you can run
+`localcaption <url>` from any directory.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/localcaption/main/scripts/install.sh | bash
+```
+
+What it does:
+
+1. Verifies prerequisites (`python3`, `git`, `ffmpeg`, `cmake`) and installs `pipx` + `cmake` if missing (via `brew` or `apt`).
+2. `pipx install localcaption` — isolated venv, console script on `$PATH`.
+3. Clones & builds `whisper.cpp` into `~/.local/share/localcaption/whisper.cpp/` (XDG-compliant).
+4. Downloads the default `base.en` ggml model.
+
+Override the default model with `WHISPER_MODEL=small.en bash install.sh`.
+
+After install, verify everything is wired up:
+
+```bash
+localcaption doctor
+```
+
+Sample output:
+
+```
+localcaption 0.1.0
+
+System tools:
+  ✅ python  (3.12.3)
+  ✅ ffmpeg  (/opt/homebrew/bin/ffmpeg)
+  ✅ git     (/opt/homebrew/bin/git)
+
+Python dependencies:
+  ✅ yt-dlp  (2025.10.14)
+
+whisper.cpp:
+  searching: /Users/you/.local/share/localcaption/whisper.cpp
+  ✅ directory exists
+  ✅ binary built  (.../build/bin/whisper-cli)
+  ✅ models present  (ggml-base.en.bin)
+
+All checks passed. You're good to go: localcaption <url>
+```
+
+### Dev install (contributors)
+
+If you're hacking on `localcaption` itself, install editable from a clone:
+
+```bash
+git clone https://github.com/jatinkrmalik/localcaption
+cd localcaption
+./scripts/setup.sh           # creates .venv, pip install -e .[dev], clones+builds whisper.cpp HERE
+source .venv/bin/activate
+pytest                        # 14 tests, all should pass
+```
+
+The dev setup keeps `whisper.cpp/` inside the repo (so you can poke at it),
+and editable-installs the package so source edits take effect immediately.
+
+## Usage
+
+### CLI
+
+```bash
+localcaption "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+```
+
+| flag | default | what it does |
+|---|---|---|
+| `-m`, `--model` | `base.en` | whisper model name (`tiny.en`, `base.en`, `small.en`, `medium.en`, `large-v3`, …) |
+| `-o`, `--out` | `./transcripts` | output directory |
+| `-l`, `--language` | `auto` | ISO language code, or `auto` to let whisper detect it |
+| `--whisper-dir` | auto-detect¹ | path to a built whisper.cpp checkout |
+| `--keep-audio` | off | keep the downloaded audio + intermediate WAV in `<out>/.work/` |
+| `--no-print` | off | don't echo the transcript to stdout |
+
+¹ `--whisper-dir` resolution order:
+   1. The explicit flag value, if given.
+   2. `$LOCALCAPTION_WHISPER_DIR` env var.
+   3. `./whisper.cpp` (dev checkout).
+   4. `~/.local/share/localcaption/whisper.cpp` (where `install.sh` puts it).
+
+Outputs `<videoId>.txt`, `.srt`, `.vtt`, and `.json` in the chosen directory.
+
+You can also invoke it as a module: `python -m localcaption <url>`.
+
+### Subcommands
+
+| Subcommand | What it does |
+|---|---|
+| _(default)_ `localcaption <url>` | Transcribe a single URL. |
+| `localcaption doctor` | Diagnose your install: prereqs, whisper.cpp, available models. Useful before filing a bug. |
+
+### Python API
+
+```python
+from pathlib import Path
+from localcaption.pipeline import transcribe_url
+
+result = transcribe_url(
+    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+    out_dir=Path("transcripts"),
+    whisper_dir=Path("whisper.cpp"),
+    model="base.en",
+)
+print(result.transcripts.txt.read_text())
+```
+
+## Architecture
+
+`localcaption` is intentionally tiny: an orchestrator (`pipeline.py`) drives
+three single-responsibility stages, each wrapping one external tool. The
+modules are split this way so that a contributor can swap, say, `whisper.cpp`
+for `faster-whisper` without touching `download.py` or `audio.py`.
+
+### Module map
+
+![Module architecture](docs/diagrams/architecture.png)
+
+| Layer | Files | Responsibility |
+|---|---|---|
+| Entry points | `cli.py`, `__main__.py` | argparse, exit codes, stdout formatting |
+| Orchestration | `pipeline.py` | public Python API: `transcribe_url(...)` |
+| Pipeline stages | `download.py`, `audio.py`, `whisper.py` | one external tool each |
+| Support | `errors.py`, `_logging.py` | exception hierarchy, tiny logger |
+
+### Runtime sequence
+
+End-to-end call flow for a single `localcaption <url>` invocation, including
+the subprocess hops to yt-dlp, ffmpeg, and whisper.cpp. The intermediate
+`.work/` directory is cleaned up at the end unless `--keep-audio` is passed.
+
+![Sequence diagram](docs/diagrams/sequence.png)
+
+> Diagrams live in [`docs/diagrams/`](docs/diagrams) as Mermaid `.mmd` source
+> files alongside the rendered PNGs. Regenerate with:
+> ```bash
+> mmdc -i docs/diagrams/<name>.mmd -o docs/diagrams/<name>.png \
+>   -t default -b transparent --width 1600 --scale 2
+> ```
+
+## Benchmarks
+
+Wall-clock times for the **complete** pipeline (yt-dlp download → ffmpeg
+re-encode → whisper.cpp transcription), measured with the default `base.en`
+model. Numbers will vary with your network speed and CPU/GPU; treat them as
+order-of-magnitude reference, not a competitive benchmark.
+
+| Video | Length | Wall-clock | Speed vs. realtime | Hardware |
+|---|---|---|---|---|
+| [TED-Ed — *How does your immune system work?*](https://www.youtube.com/watch?v=PSRJfaAYkW4) | 5:23   | **7.5 s**  | ~43× | MacBook Pro M4 Pro, 48 GB |
+| [3Blue1Brown — *But what is a Neural Network?*](https://www.youtube.com/watch?v=aircAruvnKk) | 18:40  | **19.3 s** | ~58× | MacBook Pro M4 Pro, 48 GB |
+| [Hasan Minhaj × Neil deGrasse Tyson — *Why AI is Overrated*](https://www.youtube.com/watch?v=BYizgB2FcAQ) | 54:17 | **49.8 s** | ~65× | MacBook Pro M4 Pro, 48 GB |
+
+<details>
+<summary>Reproduce</summary>
+
+```bash
+# Apple Silicon, macOS, whisper.cpp built with Metal,
+# model: ggml-base.en, language: auto, no other heavy processes.
+
+time localcaption --no-print -o /tmp/lc-bench-1 \
+  "https://www.youtube.com/watch?v=PSRJfaAYkW4"
+
+time localcaption --no-print -o /tmp/lc-bench-2 \
+  "https://www.youtube.com/watch?v=aircAruvnKk"
+
+time localcaption --no-print -o /tmp/lc-bench-3 \
+  "https://www.youtube.com/watch?v=BYizgB2FcAQ"
+```
+
+If you'd like to contribute numbers from a different machine (Linux + CUDA,
+Windows + WSL, x86 macOS, etc.), open a PR adding a row above with your
+hardware in the **Hardware** column.
+</details>
+
+## Notes
+
+- Bigger models = better quality but slower. `base.en` is a good default;
+  try `small.en` if you have the patience and `tiny.en` for instant results.
+- Apple Silicon: whisper.cpp's CMake build uses Metal automatically — you'll
+  see `ggml_metal_init` in the logs.
+- The pipeline accepts any URL `yt-dlp` supports (Vimeo, Twitch VODs, podcast
+  pages, etc.), not just YouTube.
+- If you hit `HTTP 403 Forbidden`, your `yt-dlp` is probably stale —
+  `pip install -U yt-dlp` usually fixes it.
+
+## Roadmap
+
+The roadmap lives on GitHub Issues so it's easy to track, comment on, and
+contribute to:
+
+👉 **[Open roadmap items](https://github.com/jatinkrmalik/localcaption/issues?q=is%3Aissue+is%3Aopen+label%3Aroadmap)**
+
+A snapshot of what's planned (click through for full descriptions, acceptance
+criteria, and discussion):
+
+| # | Item | Labels |
+|---|---|---|
+| [#1](https://github.com/jatinkrmalik/localcaption/issues/1) | Switch default model from `base.en` to `small.en` | `good first issue` |
+| [#2](https://github.com/jatinkrmalik/localcaption/issues/2) | Batch mode (`--batch urls.txt`) | `enhancement` |
+| [#3](https://github.com/jatinkrmalik/localcaption/issues/3) | Local auto-summary via Ollama (`--summary`) | `enhancement` |
+| [#4](https://github.com/jatinkrmalik/localcaption/issues/4) | Speaker diarization with pyannote.audio (`--diarize`) | `stretch`, `help wanted` |
+| [#5](https://github.com/jatinkrmalik/localcaption/issues/5) | YouTube chapters & grep-able search index | `enhancement` |
+| [#6](https://github.com/jatinkrmalik/localcaption/issues/6) | Pluggable transcription backends (faster-whisper / MLX) | `help wanted` |
+
+**Have an idea?** Open a
+[feature request](https://github.com/jatinkrmalik/localcaption/issues/new/choose) —
+or jump into [Discussions](https://github.com/jatinkrmalik/localcaption/discussions)
+if you want to chat about it first.
+
+## Related projects
+
+`localcaption` deliberately stays tiny. If you want more, check out:
+
+- [`whishper`](https://github.com/pluja/whishper) — full web UI for local
+  transcription with translation and editing.
+- [`transcribe-anything`](https://github.com/zackees/transcribe-anything) —
+  multi-backend, Mac-arm optimised, supports URLs.
+- [`WhisperX`](https://github.com/m-bain/whisperX) — word-level timestamps and
+  diarisation on top of openai-whisper.
+
+## Contributing
+
+Pull requests welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). By
+participating you agree to abide by our
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](LICENSE).

localcaption-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+localcaption/__init__.py,sha256=r7bgowkiemdii0CjS_TnmuvtRVOUZVlGuCaV2UP4UrQ,417
+localcaption/__main__.py,sha256=cI9jrT1b-BbZZMWCFWiPml5-lnwdsgWv5sFmQZv4VoA,173
+localcaption/_logging.py,sha256=2IYAGOfquaHEPlc8n7x7NwAg4b6SXyeqCu6BeJd2cmw,706
+localcaption/audio.py,sha256=ScJ9C7MNRc4ZsoY0ewNfGzJqHfz18iBh5n_tA0DcrmI,1516
+localcaption/cli.py,sha256=rkIZ_KLoE9M-9aQ_7qTsSBG5r8FskgZN8dKdmFHzo6Y,8913
+localcaption/download.py,sha256=zNjnFrIdjx-XNWbwHqS0pbOD68Cm4VAB8Oqyxv4Gh_E,2804
+localcaption/errors.py,sha256=lJzKNibtJix7xEElG36sJf4eu7Iv6guUXTCm8o6F5Qg,706
+localcaption/pipeline.py,sha256=DDr04_491PA7xZ_KIvYMbpALRngo3WnYvThC_ZQYVLA,2343
+localcaption/whisper.py,sha256=o9KndumkoqA3nptZdatJTxTyb7nxq2ZtEXfbHwswgKY,3092
+localcaption-0.1.0.dist-info/METADATA,sha256=j-8-273AGHGsqpfUk6LY5KG9MLeP0BRg-JYhUG6AhoU,14375
+localcaption-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+localcaption-0.1.0.dist-info/entry_points.txt,sha256=YR6Ov5vPTQoCzmZabO0HaKu7xFhiPNolbWlC6fsGpuk,55
+localcaption-0.1.0.dist-info/licenses/LICENSE,sha256=RyJWmox6YO3j9-J-ssABfzdeVNhKuuTklun4g9iwakk,1074
+localcaption-0.1.0.dist-info/RECORD,,

localcaption-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

localcaption-0.1.0.dist-info/entry_points.txt

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

localcaption-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jatin Kumar Malik
+
+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.