localcaption 0.1.0__tar.gz

localcaption-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+name: 🐛 Bug report
+description: Something is broken or doesn't behave as documented.
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report!
+        Please run `pip install -U yt-dlp` and try again first — the vast
+        majority of "YouTube broke it" issues are upstream extractor regressions.
+
+  - type: input
+    id: command
+    attributes:
+      label: Exact command you ran
+      placeholder: localcaption "https://www.youtube.com/watch?v=..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: error
+    attributes:
+      label: Full output (including stack trace)
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: localcaption-version
+    attributes:
+      label: localcaption version
+      description: Output of `localcaption --version`
+    validations:
+      required: true
+
+  - type: input
+    id: ytdlp-version
+    attributes:
+      label: yt-dlp version
+      description: Output of `yt-dlp --version`
+    validations:
+      required: true
+
+  - type: input
+    id: env
+    attributes:
+      label: OS / Python version
+      placeholder: "macOS 14.5 / Python 3.12.3"
+    validations:
+      required: true
+
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `localcaption doctor`
+      description: Paste the full output. This catches 90% of "it doesn't work" causes.
+      render: shell
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else?
+      description: Logs, screenshots, model used, etc.

localcaption-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Discussion / question
+    url: https://github.com/jatinkrmalik/localcaption/discussions
+    about: Ask a question or share what you're building.
+  - name: 🔒 Security report
+    url: https://github.com/jatinkrmalik/localcaption/security/advisories/new
+    about: Report a security vulnerability privately.

localcaption-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: ✨ Feature request
+description: Suggest an idea for localcaption.
+labels: ["enhancement", "triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: A clear and concise description of the use case.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would you like this to work? CLI flag? Python API? Config?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you've considered
+
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      options:
+        - label: This stays within the project's "thin local orchestrator" scope (no cloud APIs, no GUIs).
+          required: true

localcaption-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## What changed
+
+<!-- A short description of the change. Link any related issues with `Closes #123`. -->
+
+## Why
+
+<!-- The motivation. What problem does this solve for users / contributors? -->
+
+## How
+
+<!-- Brief implementation notes. Anything reviewers should pay attention to. -->
+
+## Checklist
+
+- [ ] Tests added or updated.
+- [ ] `pytest` passes locally.
+- [ ] `ruff check src tests` passes.
+- [ ] `CHANGELOG.md` updated under `## [Unreleased]` (for user-visible changes).
+- [ ] Public APIs have docstrings.
+- [ ] No new external dependencies (or, if added, justified above).

localcaption-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }} on ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Run tests
+        run: pytest -q
+
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Upload artefacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

localcaption-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,144 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+# Cancel any in-flight release for the same tag (e.g. if someone re-pushes).
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false   # never abort a real release in flight
+
+env:
+  PYTHON_VERSION: '3.12'
+
+jobs:
+  # ─────────────────────────────────────────────────────────────────────
+  # 1. Build sdist + wheel, validate metadata, sanity-check version.
+  # ─────────────────────────────────────────────────────────────────────
+  build:
+    name: Build & validate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.tag.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Extract version from git tag
+        id: tag
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Tag version: $VERSION"
+
+      - name: Verify pyproject.toml version matches tag
+        run: |
+          PKG_VERSION=$(python -c "import tomllib,sys; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG_VERSION="${{ steps.tag.outputs.version }}"
+          echo "pyproject.toml version: $PKG_VERSION"
+          echo "git tag version:        $TAG_VERSION"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::pyproject.toml version ($PKG_VERSION) does not match git tag ($TAG_VERSION)."
+            echo "::error::Bump pyproject.toml or re-tag, then push."
+            exit 1
+          fi
+
+      - name: Build sdist + wheel
+        run: |
+          python -m build
+          ls -la dist/
+
+      - name: Validate distributions
+        run: twine check --strict dist/*
+
+      - name: Upload artefacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  # ─────────────────────────────────────────────────────────────────────
+  # 2. Publish to PyPI via Trusted Publishing (OIDC, no API token).
+  # ─────────────────────────────────────────────────────────────────────
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/localcaption/
+    permissions:
+      id-token: write   # required for Trusted Publishing (OIDC)
+    steps:
+      - name: Download dist artefacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # ─────────────────────────────────────────────────────────────────────
+  # 3. Create the GitHub Release with auto-generated notes + dist files.
+  #    Runs in parallel with publish-pypi (no dependency between them).
+  # ─────────────────────────────────────────────────────────────────────
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # required to create a release
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download dist artefacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref_name, 'alpha') || contains(github.ref_name, 'beta') || contains(github.ref_name, 'rc') }}
+          body: |
+            ## Install
+
+            ### One-line install (recommended)
+            ```bash
+            curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/localcaption/${{ github.ref_name }}/scripts/install.sh | bash
+            ```
+
+            ### From PyPI
+            ```bash
+            pipx install localcaption
+            ```
+
+            ---
+            See [CHANGELOG.md](https://github.com/jatinkrmalik/localcaption/blob/${{ github.ref_name }}/CHANGELOG.md)
+            for the full list of changes.

localcaption-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+
+# Project-specific
+whisper.cpp/
+transcripts/
+transcripts_*/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp

localcaption-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- `scripts/install.sh` — one-line end-user installer that uses `pipx` for an
+  isolated install and bootstraps `whisper.cpp` + a default model into
+  `~/.local/share/localcaption/whisper.cpp` (XDG-compliant). After install,
+  `localcaption` is callable from any directory.
+- New `localcaption doctor` subcommand that diagnoses prerequisites,
+  whisper.cpp build, and available models. Used by the bug-report template.
+- The CLI now searches a third location for whisper.cpp:
+  `$XDG_DATA_HOME/localcaption/whisper.cpp` (after the explicit flag, env var,
+  and `./whisper.cpp` dev path).
+
+### Changed
+- `localcaption` invoked with no arguments now prints top-level help and
+  exits with code 2 (was: argparse error). Existing `localcaption <url>`
+  usage is unchanged.
+
+## [0.1.0] - 2026-04-21
+
+### Added
+- Initial public release as `localcaption`.
+- Modular package layout: `download` (yt-dlp), `audio` (ffmpeg), `whisper`
+  (whisper.cpp), orchestrated by `pipeline.transcribe_url`.
+- `localcaption` console script and `python -m localcaption` entry point.
+- One-shot `scripts/setup.sh` that builds whisper.cpp and downloads a model.
+- MIT license, contributor docs, security policy, GitHub Actions CI.

localcaption-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behaviour that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologising to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Unacceptable behaviour includes:
+
+- The use of sexualised language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others’ private information without explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be
+reported to the project maintainers via a private GitHub Security Advisory or
+the contact listed in `SECURITY.md`. All complaints will be reviewed and
+investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

localcaption-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to localcaption
+
+Thanks for considering a contribution! This project is intentionally small —
+the goal is to stay a thin, dependable orchestrator over `yt-dlp`, `ffmpeg`,
+and `whisper.cpp`. PRs that keep that surface tidy are very welcome.
+
+## Quick start
+
+```bash
+git clone https://github.com/jatinkrmalik/localcaption
+cd localcaption
+./scripts/setup.sh                  # builds whisper.cpp, sets up venv
+source .venv/bin/activate
+pip install -e .[dev]               # if not already done by setup.sh
+pytest                              # run the test suite
+ruff check src tests                # lint
+```
+
+## Project layout
+
+```
+src/localcaption/
+├── __init__.py
+├── __main__.py        # python -m localcaption
+├── _logging.py        # tiny stdout logger (no logging-module config)
+├── audio.py           # ffmpeg → 16 kHz mono WAV (stage 2)
+├── cli.py             # argparse entry point (the `localcaption` script)
+├── download.py        # yt-dlp Python API wrapper (stage 1)
+├── errors.py          # exception hierarchy
+├── pipeline.py        # public Python API: transcribe_url(...)
+└── whisper.py         # whisper.cpp invocation (stage 3)
+scripts/
+└── setup.sh           # bootstraps whisper.cpp + venv + model
+tests/                 # pytest suite
+```
+
+Each pipeline stage is its own module so you can swap one out (e.g. replace
+the `whisper.cpp` backend with `faster-whisper`) without touching the others.
+
+## Pull request checklist
+
+- [ ] `pytest` passes.
+- [ ] `ruff check src tests` passes (the CI runs both).
+- [ ] New behaviour is covered by a test.
+- [ ] User-visible changes are noted in `CHANGELOG.md` under `## [Unreleased]`.
+- [ ] Public APIs have docstrings.
+
+## Reporting bugs
+
+Please include:
+
+- The exact command you ran.
+- The output of `localcaption --version` and `yt-dlp --version`.
+- Your OS + Python version (`python --version`).
+- Whether `whisper.cpp` was built with CMake or `make`.
+
+For YouTube-side issues (HTTP 4xx, "Sign in to confirm…"), try
+`pip install -U yt-dlp` first — those are usually upstream extractor breakage,
+not bugs in this project.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
+By participating you agree to abide by its terms.

localcaption-0.1.0/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.