localcaption 0.2.0__tar.gz → 0.3.0__tar.gz

{localcaption-0.2.0 → localcaption-0.3.0}/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-16
+
+### Added
+- **Local video and audio files.** `localcaption /path/to/video.mp4` (or a
+  wav / mp3 / mkv / similar) runs the same ffmpeg + whisper.cpp path
+  without calling yt-dlp. Output names come from the input filename.
+
+### Changed
+- CLI help, `doctor`, and the README now say `<url-or-file>` instead of
+  treating this as URL-only.
+
+### Fixed
+- Architecture, pipeline, and sequence diagrams render with a white
+  background so they stay readable on GitHub dark mode.
+
 ## [0.2.0] - 2026-06-06
 
 ### Added

{localcaption-0.2.0 → localcaption-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: localcaption
-Version: 0.2.0
+Version: 0.3.0
 Summary: Fully-local video → transcript pipeline using yt-dlp, ffmpeg, and whisper.cpp. Supports YouTube, Vimeo, Twitch, and 1000+ sites. No API keys.
 Project-URL: Homepage, https://github.com/jatinkrmalik/localcaption
 Project-URL: Repository, https://github.com/jatinkrmalik/localcaption
@@ -219,6 +219,10 @@ localcaption "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
 
 # Vimeo, Twitch, Twitter/X, and 1000+ other sites work too
 localcaption "https://vimeo.com/148751763"
+
+# Local video/audio files
+localcaption /path/to/video.mp4
+localcaption ./recording.wav
 ```
 
 | flag | default | what it does |
@@ -236,15 +240,15 @@ localcaption "https://vimeo.com/148751763"
    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.
+Outputs `<videoId>.txt`, `.srt`, `.vtt`, and `.json` in the chosen directory. For local files, the output filename is derived from the input file's name.
 
-You can also invoke it as a module: `python -m localcaption <url>`.
+You can also invoke it as a module: `python -m localcaption <url-or-file>`.
 
 ### Subcommands
 
 | Subcommand | What it does |
 |---|---|
-| _(default)_ `localcaption <url>` | Transcribe a single URL. |
+| _(default)_ `localcaption <url-or-file>` | Transcribe a URL or local video/audio file. |
 | `localcaption doctor` | Read-only diagnostic: prereqs, whisper.cpp, available models. Useful before filing a bug. |
 | `localcaption doctor --fix` | Self-heal: install missing system deps, clone+build whisper.cpp, download the default model, then re-verify. Idempotent. |
 | `localcaption model list` | List every supported whisper model with size + install status. |
@@ -339,7 +343,7 @@ the subprocess hops to yt-dlp, ffmpeg, and whisper.cpp. The intermediate
 > 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
+>   -t default -b white --width 1600 --scale 2
 > ```
 
 ## Benchmarks

{localcaption-0.2.0 → localcaption-0.3.0}/README.md

@@ -164,6 +164,10 @@ localcaption "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
 
 # Vimeo, Twitch, Twitter/X, and 1000+ other sites work too
 localcaption "https://vimeo.com/148751763"
+
+# Local video/audio files
+localcaption /path/to/video.mp4
+localcaption ./recording.wav
 ```
 
 | flag | default | what it does |
@@ -181,15 +185,15 @@ localcaption "https://vimeo.com/148751763"
    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.
+Outputs `<videoId>.txt`, `.srt`, `.vtt`, and `.json` in the chosen directory. For local files, the output filename is derived from the input file's name.
 
-You can also invoke it as a module: `python -m localcaption <url>`.
+You can also invoke it as a module: `python -m localcaption <url-or-file>`.
 
 ### Subcommands
 
 | Subcommand | What it does |
 |---|---|
-| _(default)_ `localcaption <url>` | Transcribe a single URL. |
+| _(default)_ `localcaption <url-or-file>` | Transcribe a URL or local video/audio file. |
 | `localcaption doctor` | Read-only diagnostic: prereqs, whisper.cpp, available models. Useful before filing a bug. |
 | `localcaption doctor --fix` | Self-heal: install missing system deps, clone+build whisper.cpp, download the default model, then re-verify. Idempotent. |
 | `localcaption model list` | List every supported whisper model with size + install status. |
@@ -284,7 +288,7 @@ the subprocess hops to yt-dlp, ffmpeg, and whisper.cpp. The intermediate
 > 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
+>   -t default -b white --width 1600 --scale 2
 > ```
 
 ## Benchmarks

{localcaption-0.2.0 → localcaption-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "localcaption"
-version = "0.2.0"
+version = "0.3.0"
 description = "Fully-local video → transcript pipeline using yt-dlp, ffmpeg, and whisper.cpp. Supports YouTube, Vimeo, Twitch, and 1000+ sites. No API keys."
 readme = "README.md"
 requires-python = ">=3.10"

{localcaption-0.2.0 → localcaption-0.3.0}/src/localcaption/cli.py

@@ -4,8 +4,8 @@ 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
+    localcaption <url-or-file> [options]   # one-shot transcription (default)
+    localcaption doctor                    # diagnose your install
 """
 
 from __future__ import annotations
@@ -69,9 +69,12 @@ def _default_whisper_dir() -> Path:
 def _build_transcribe_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="localcaption",
-        description="Fully-local YouTube → transcript using yt-dlp + ffmpeg + whisper.cpp.",
+        description="Fully-local video → transcript using yt-dlp + ffmpeg + whisper.cpp.",
+    )
+    parser.add_argument(
+        "url",
+        help="YouTube URL, any URL yt-dlp supports, or path to a local video/audio file",
     )
-    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})",
@@ -400,7 +403,7 @@ def _cmd_doctor(argv: list[str]) -> int:
     all_ok, fix_hints, gaps = _run_doctor_diagnostics(whisper_dir)
 
     if all_ok:
-        print("\nAll checks passed. You're good to go: localcaption <url>")
+        print("\nAll checks passed. You're good to go: localcaption <url-or-file>")
         return 0
 
     if not args.fix:
@@ -422,7 +425,7 @@ def _cmd_doctor(argv: list[str]) -> int:
     print("Re-running diagnostics to verify…\n")
     all_ok_after, _, _ = _run_doctor_diagnostics(whisper_dir)
     if all_ok_after:
-        print("\nAll checks passed. You're good to go: localcaption <url>")
+        print("\nAll checks passed. You're good to go: localcaption <url-or-file>")
         return 0
     print("\nSome checks still failing — see output above.")
     return 1
@@ -579,7 +582,7 @@ def _cmd_model_download(argv: list[str]) -> int:
         return 130
 
     print(f"✅ Done. {path}")
-    print(f"   Use it with: localcaption --model {spec.name} <url>")
+    print(f"   Use it with: localcaption --model {spec.name} <url-or-file>")
     return 0
 
 
@@ -628,7 +631,7 @@ def _cmd_model_rm(argv: list[str]) -> int:
 
 def _print_top_level_help() -> None:
     print("""\
-usage: localcaption <url> [options]            transcribe a video (default)
+usage: localcaption <url-or-file> [options]    transcribe a video (default)
        localcaption doctor                     diagnose your install
        localcaption model <subcommand>         list / download / remove models
        localcaption --help                     show transcribe help

{localcaption-0.2.0 → localcaption-0.3.0}/src/localcaption/pipeline.py

@@ -25,6 +25,12 @@ class PipelineResult:
     transcripts: TranscriptionResult
 
 
+def _is_local_file(source: str) -> bool:
+    if "://" in source:
+        return False
+    return Path(source).is_file()
+
+
 def transcribe_url(
     url: str,
     *,
@@ -36,10 +42,12 @@ def transcribe_url(
 ) -> PipelineResult:
     """Run the full pipeline on *url* and return the produced artefacts.
 
+    *url* may be an actual URL or a path to a local video/audio file.
+
     Parameters
     ----------
     url:
-        Any URL `yt-dlp` can resolve.
+        Any URL `yt-dlp` can resolve, or a local file path.
     out_dir:
         Directory for the final transcript files.
     whisper_dir:
@@ -59,7 +67,9 @@ def transcribe_url(
     audio_path: Path | None = None
     wav_path: Path | None = None
     try:
-        audio_path = download_audio(url, work_dir)
+        audio_path = (
+            Path(url).resolve() if _is_local_file(url) else download_audio(url, work_dir)
+        )
         wav_path = work_dir / f"{audio_path.stem}.16k.wav"
         to_whisper_wav(audio_path, wav_path)
 

localcaption-0.3.0/tests/test_cli_transcribe.py

@@ -0,0 +1,66 @@
+"""Tests for the default transcribe subcommand and dispatcher."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from localcaption.cli import main
+
+
+class TestCliHelpText:
+    def test_transcribe_help_mentions_local_file(self, capsys) -> None:
+        with pytest.raises(SystemExit) as excinfo:
+            main(["--help"])
+        assert excinfo.value.code == 0
+        out = capsys.readouterr().out
+        assert "local video/audio file" in out
+
+    def test_top_level_help_mentions_url_or_file(self, capsys) -> None:
+        rc = main([])
+        assert rc == 2
+        out = capsys.readouterr().out
+        assert "url-or-file" in out
+
+
+class TestCliLocalFileDispatch:
+    def test_local_file_path_passed_to_pipeline(self, monkeypatch, tmp_path: Path) -> None:
+        video = tmp_path / "my_video.mp4"
+        video.write_text("fake")
+        sentinel: dict[str, str] = {}
+
+        def fake_transcribe_url(url, **kw):
+            sentinel["url"] = url
+            raise SystemExit(0)
+
+        monkeypatch.setattr("localcaption.cli.transcribe_url", fake_transcribe_url)
+        with pytest.raises(SystemExit):
+            main([str(video)])
+        assert sentinel["url"] == str(video)
+
+    def test_url_still_passed_to_pipeline(self, monkeypatch) -> None:
+        sentinel: dict[str, str] = {}
+
+        def fake_transcribe_url(url, **kw):
+            sentinel["url"] = url
+            raise SystemExit(0)
+
+        monkeypatch.setattr("localcaption.cli.transcribe_url", fake_transcribe_url)
+        with pytest.raises(SystemExit):
+            main(["https://www.youtube.com/watch?v=dQw4w9WgXcQ"])
+        assert sentinel["url"] == "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+    def test_relative_local_file_passed_to_pipeline(self, monkeypatch, tmp_path: Path) -> None:
+        video = tmp_path / "relative.mp4"
+        video.write_text("fake")
+        sentinel: dict[str, str] = {}
+
+        def fake_transcribe_url(url, **kw):
+            sentinel["url"] = url
+            raise SystemExit(0)
+
+        monkeypatch.setattr("localcaption.cli.transcribe_url", fake_transcribe_url)
+        with pytest.raises(SystemExit):
+            main(["./relative.mp4"])
+        assert sentinel["url"] == "./relative.mp4"

localcaption-0.3.0/tests/test_pipeline.py

@@ -0,0 +1,215 @@
+"""Tests for the pipeline orchestration layer."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock
+
+from localcaption.pipeline import PipelineResult, _is_local_file, transcribe_url
+
+
+class TestIsLocalFile:
+    def test_existing_file_returns_true(self, tmp_path: Path) -> None:
+        video = tmp_path / "video.mp4"
+        video.write_text("fake")
+        assert _is_local_file(str(video)) is True
+
+    def test_relative_existing_file_returns_true(self, tmp_path: Path) -> None:
+        video = tmp_path / "video.mp4"
+        video.write_text("fake")
+        import os
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            assert _is_local_file("./video.mp4") is True
+            assert _is_local_file("video.mp4") is True
+        finally:
+            os.chdir(old_cwd)
+
+    def test_url_returns_false(self) -> None:
+        assert _is_local_file("https://www.youtube.com/watch?v=dQw4w9WgXcQ") is False
+        assert _is_local_file("http://example.com/video.mp4") is False
+
+    def test_nonexistent_path_returns_false(self, tmp_path: Path) -> None:
+        assert _is_local_file(str(tmp_path / "does_not_exist.mp4")) is False
+
+    def test_file_url_returns_false(self, tmp_path: Path) -> None:
+        assert _is_local_file(f"file://{tmp_path}/video.mp4") is False
+
+
+class TestTranscribeUrlLocalFile:
+    def test_local_file_skips_download(
+        self, monkeypatch, tmp_path: Path
+    ) -> None:
+        video = tmp_path / "my_video.mp4"
+        video.write_text("fake video")
+        out_dir = tmp_path / "out"
+        whisper_dir = tmp_path / "whisper.cpp"
+
+        download_called = False
+
+        def fake_download(url, work_dir):
+            nonlocal download_called
+            download_called = True
+            return work_dir / "downloaded.mp4"
+
+        def fake_to_whisper_wav(src, dst):
+            dst.write_text("fake wav")
+            return dst
+
+        fake_transcripts = MagicMock()
+        fake_transcripts.existing.return_value = {}
+
+        def fake_transcribe(wav, model, out_base, *, whisper_dir, language):
+            return fake_transcripts
+
+        monkeypatch.setattr("localcaption.pipeline.download_audio", fake_download)
+        monkeypatch.setattr("localcaption.pipeline.to_whisper_wav", fake_to_whisper_wav)
+        monkeypatch.setattr("localcaption.pipeline.transcribe", fake_transcribe)
+
+        result = transcribe_url(
+            str(video),
+            out_dir=out_dir,
+            whisper_dir=whisper_dir,
+            model="base.en",
+            keep_intermediate=True,
+        )
+
+        assert download_called is False
+        assert isinstance(result, PipelineResult)
+        assert result.source_url == str(video)
+        assert result.audio_path == video.resolve()
+
+    def test_local_file_uses_correct_stem_for_output(
+        self, monkeypatch, tmp_path: Path
+    ) -> None:
+        video = tmp_path / "interview.mkv"
+        video.write_text("fake video")
+        out_dir = tmp_path / "out"
+        whisper_dir = tmp_path / "whisper.cpp"
+
+        captured = {}
+
+        def fake_to_whisper_wav(src, dst):
+            dst.write_text("fake wav")
+            return dst
+
+        def fake_transcribe(wav, model, out_base, *, whisper_dir, language):
+            captured["out_base"] = out_base
+            fake_transcripts = MagicMock()
+            fake_transcripts.existing.return_value = {}
+            return fake_transcripts
+
+        monkeypatch.setattr("localcaption.pipeline.to_whisper_wav", fake_to_whisper_wav)
+        monkeypatch.setattr("localcaption.pipeline.transcribe", fake_transcribe)
+
+        transcribe_url(
+            str(video),
+            out_dir=out_dir,
+            whisper_dir=whisper_dir,
+            model="base.en",
+        )
+
+        assert captured["out_base"] == out_dir / "interview"
+
+    def test_url_still_calls_download(
+        self, monkeypatch, tmp_path: Path
+    ) -> None:
+        out_dir = tmp_path / "out"
+        whisper_dir = tmp_path / "whisper.cpp"
+        work_dir = out_dir / ".work"
+        work_dir.mkdir(parents=True)
+
+        def fake_download(url, work_dir):
+            downloaded = work_dir / "yt_video.m4a"
+            downloaded.write_text("fake audio")
+            return downloaded
+
+        def fake_to_whisper_wav(src, dst):
+            dst.write_text("fake wav")
+            return dst
+
+        fake_transcripts = MagicMock()
+        fake_transcripts.existing.return_value = {}
+
+        def fake_transcribe(wav, model, out_base, *, whisper_dir, language):
+            return fake_transcripts
+
+        monkeypatch.setattr("localcaption.pipeline.download_audio", fake_download)
+        monkeypatch.setattr("localcaption.pipeline.to_whisper_wav", fake_to_whisper_wav)
+        monkeypatch.setattr("localcaption.pipeline.transcribe", fake_transcribe)
+
+        result = transcribe_url(
+            "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+            out_dir=out_dir,
+            whisper_dir=whisper_dir,
+            model="base.en",
+        )
+
+        assert isinstance(result, PipelineResult)
+        assert result.source_url == "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+    def test_keep_intermediate_preserves_local_audio_path(
+        self, monkeypatch, tmp_path: Path
+    ) -> None:
+        video = tmp_path / "podcast.mp3"
+        video.write_text("fake audio")
+        out_dir = tmp_path / "out"
+        whisper_dir = tmp_path / "whisper.cpp"
+
+        def fake_to_whisper_wav(src, dst):
+            dst.write_text("fake wav")
+            return dst
+
+        fake_transcripts = MagicMock()
+        fake_transcripts.existing.return_value = {}
+
+        def fake_transcribe(wav, model, out_base, *, whisper_dir, language):
+            return fake_transcripts
+
+        monkeypatch.setattr("localcaption.pipeline.to_whisper_wav", fake_to_whisper_wav)
+        monkeypatch.setattr("localcaption.pipeline.transcribe", fake_transcribe)
+
+        result = transcribe_url(
+            str(video),
+            out_dir=out_dir,
+            whisper_dir=whisper_dir,
+            model="base.en",
+            keep_intermediate=True,
+        )
+
+        assert result.audio_path == video.resolve()
+        assert result.wav_path is not None
+        assert result.wav_path.name == "podcast.16k.wav"
+
+    def test_no_keep_intermediate_clears_paths(
+        self, monkeypatch, tmp_path: Path
+    ) -> None:
+        video = tmp_path / "podcast.mp3"
+        video.write_text("fake audio")
+        out_dir = tmp_path / "out"
+        whisper_dir = tmp_path / "whisper.cpp"
+
+        def fake_to_whisper_wav(src, dst):
+            dst.write_text("fake wav")
+            return dst
+
+        fake_transcripts = MagicMock()
+        fake_transcripts.existing.return_value = {}
+
+        def fake_transcribe(wav, model, out_base, *, whisper_dir, language):
+            return fake_transcripts
+
+        monkeypatch.setattr("localcaption.pipeline.to_whisper_wav", fake_to_whisper_wav)
+        monkeypatch.setattr("localcaption.pipeline.transcribe", fake_transcribe)
+
+        result = transcribe_url(
+            str(video),
+            out_dir=out_dir,
+            whisper_dir=whisper_dir,
+            model="base.en",
+            keep_intermediate=False,
+        )
+
+        assert result.audio_path is None
+        assert result.wav_path is None