videoxplainer 0.3.3__tar.gz

videoxplainer-0.3.3/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,12 @@
+---
+name: Bug report
+about: Something failed or looks wrong
+---
+
+**Command you ran**
+
+**What you expected / what happened** (paste the error text)
+
+**`videoxplainer doctor` output**
+
+**Video type** (chaptered? auto-captions or uploaded? language? Shorts/live?)

videoxplainer-0.3.3/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.11", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -q
+      - run: python -m videoxplainer --version
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - name: smoke-test the built wheel
+        run: |
+          python -m pip install dist/*.whl
+          videoxplainer doctor

videoxplainer-0.3.3/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: publish
+# One-time setup: on pypi.org add a "trusted publisher" for this repo + workflow
+# (project name, owner, repo, workflow "publish.yml", environment "pypi").
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

videoxplainer-0.3.3/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.videoxplainer/
+finalize.py
+run_checks.ps1
+check-results.txt

videoxplainer-0.3.3/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## 0.3.3
+- Requires Python 3.11 or newer. Current yt-dlp needs 3.11+, and older Pythons would be stuck on a frozen, outdated yt-dlp that YouTube changes will break.
+- README: corrected the language-support note (real vs synthetic test data).
+
+## 0.3.2
+- Cleaner auto-detected section headings (no contractions or conversational filler).
+- `check` prints full error messages (including the list of available caption languages).
+
+## 0.3.1
+- New: `fetch --no-chapters` ignores YouTube's chapters and detects topics from the text.
+- `check` also benchmarks topic auto-detection against a video's real chapters (information only).
+
+## 0.3.0
+- New: `videoxplainer install-skill` installs the Claude Code skill in one command (`--dir`, `--force`, `--print`).
+- New: local transcript files (`.srt .vtt .json3 .txt .md`) work with `fetch`, `verify` and `check`; plain text without timestamps gets estimated ones.
+- New: `vxp` is a short alias for the `videoxplainer` command.
+- `--lang` is now strict: you never silently get another language or a machine translation; the error lists what is available. The library re-fetches when you ask for a different language than the one stored.
+- Library upgrades itself automatically (new column), no action needed.
+- Topic auto-detection only cuts at significant shifts, so long topics aren't split in pieces and a uniform talk stays whole.
+
+## 0.2.2
+- Fix: section detection, passage ranking and `verify` only understood Latin letters, so Hindi/Tamil/other non-Latin captions were handled poorly. Now Unicode-aware.
+- Token estimates are conservative for non-Latin scripts, so budgets aren't overshot.
+- New: `videoxplainer check <url>...` self-tests the pipeline on real videos.
+- `videoxplainer doctor` warns when yt-dlp is more than 90 days old.
+- CI also builds the package and smoke-tests the installed command.
+
+## 0.2.1
+- Fix: condensed briefs no longer include meaningless fragments; a section with nothing worth quoting is dropped instead of padded.
+
+## 0.2.0
+- Chapter-aware condensing: every YouTube chapter (or auto-detected topic) gets a share of the token budget.
+- Views: `--view chapters|excerpts|raw`. Modes: `--mode text|summary|actions`.
+- Library now stores chapter markers (older libraries upgrade automatically; use `--refresh` once per video).
+
+## 0.1.1
+- Fix: tiny fragments selected on small budgets; timeline coverage kept on small budgets.
+
+## 0.1.0
+- First release: token-budgeted briefs, `verify` (quote check), local full-text search, Windows/macOS/Linux CI.

videoxplainer-0.3.3/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+Small, focused PRs are welcome.
+
+```bash
+git clone https://github.com/narayan-govindaraj/videoXplainer && cd videoXplainer
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+- Tests must not touch the network (see `tests/test_fetch_cli.py` for the fake yt-dlp pattern).
+- Keep dependencies at zero beyond yt-dlp; that is a feature.
+- Bug reports: include the output of `videoxplainer doctor` and the exact command. For caption-download failures, say whether you used cookies.

videoxplainer-0.3.3/LICENSE

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

videoxplainer-0.3.3/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.5
+Name: videoxplainer
+Version: 0.3.3
+Summary: Turn YouTube videos into token-budgeted, evidence-checked action briefs for LLMs.
+Project-URL: Homepage, https://github.com/narayan-govindaraj/videoXplainer
+Project-URL: Issues, https://github.com/narayan-govindaraj/videoXplainer/issues
+Project-URL: Changelog, https://github.com/narayan-govindaraj/videoXplainer/blob/main/CHANGELOG.md
+Author: Narayan Govindaraj
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chapters,claude,llm,mcp,summary,token,transcript,youtube,yt-dlp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.11
+Requires-Dist: yt-dlp>=2025.1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/narayan-govindaraj/videoXplainer/main/docs/brand/logo-lockup-dark.png">
+    <img src="https://raw.githubusercontent.com/narayan-govindaraj/videoXplainer/main/docs/brand/logo-lockup-light.png" alt="VideoXplainer" width="440">
+  </picture>
+</p>
+
+**Your AI reads 4k tokens instead of 18k, and every claim comes with a quote you can check.**
+
+[![ci](https://github.com/narayan-govindaraj/videoXplainer/actions/workflows/ci.yml/badge.svg)](https://github.com/narayan-govindaraj/videoXplainer/actions)
+![license: MIT](https://img.shields.io/badge/license-MIT-blue)
+![python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+
+Most "YouTube summarizer" tools paste the whole transcript into your chat. That burns your context window, and nothing stops the model from inventing points the video never made.
+
+videoxplainer sits between the video and your assistant (Claude Code, Claude Desktop, any agent that can run a command):
+
+- **Condenses by chapter, to a token budget you choose.** Every chapter keeps a share, so the end of the video isn't dropped.
+- **Makes claims checkable.** Ask for actions *with verbatim quotes*, then `videoxplainer verify` confirms each quote really appears in the video, and where.
+- **Needs no API key and no LLM of its own.** Your assistant does the reading; videoxplainer does the plumbing. One `pipx install`, no Node, no compiler.
+
+![VideoXplainer demo: a 1-hour talk condensed to 4,000 tokens across 21 chapters, then every quote checked](https://raw.githubusercontent.com/narayan-govindaraj/videoXplainer/main/docs/demo.gif)
+
+## See it work
+
+The animation above wraps motion graphics around this real run on a public 1-hour talk (59:48). Transcript passages are elided, and the assistant reply and claim cards in the animation are illustrative examples:
+
+```text
+$ videoxplainer fetch zjkBMFhNj_g --budget 4000 --mode summary
+
+# [1hr Talk] Intro to Large Language Models
+Andrej Karpathy | 59:48 | en (auto-captions)
+sections: 21 (YouTube chapters)
+note: condensed to ~3994 of ~17957 tokens (extractive, spread across sections)
+---
+## [00:20] LLM Inference
+[00:29] ...
+## [25:43] LLM Scaling Laws
+[25:44] ...
+## [46:14] Jailbreaks
+[46:33] ...
+---
+TASK: for each "##" heading above write 1-2 sentences on its main point ...
+```
+
+About 17.9k tokens become about 4k, spread over all 21 chapters. Your assistant reads that and writes the chapter-by-chapter summary. No chapters on the video? videoxplainer detects topic shifts from the text instead.
+
+Then check the model's work (illustrative output):
+
+```text
+$ videoxplainer verify VIDEO_ID claims.json
+{ "checked": 3, "supported": 2, "weak": 0, "unsupported": 1,
+  "items": [
+    { "index": 0, "status": "supported",   "matched_at": "01:05", "link": "https://youtu.be/VIDEO_ID?t=65" },
+    { "index": 1, "status": "supported",   "matched_at": "02:10", "link": "https://youtu.be/VIDEO_ID?t=130" },
+    { "index": 2, "status": "unsupported" } ] }
+```
+
+Unsupported means the quote the model cited isn't in the video: drop or fix that point.
+
+## How it compares
+
+| | **videoxplainer** | [youtube-summarize](https://pypi.org/project/youtube-summarize/) (MCP) | [didntwatch](https://github.com/ewro/didntwatch) | [fabric](https://github.com/danielmiessler/fabric) | [martino-summarize](https://pypi.org/project/martino-summarize/) |
+|---|---|---|---|---|---|
+| Needs an LLM API key | **No** | No | No | Yes | Yes (bring your own) |
+| You set a token budget | **Yes** | - | - | - | Yes (optional LLM prefilter) |
+| Chapter-aware condensing | **Yes** | metadata only | - | - | - |
+| Checks the model's quotes against the video | **Yes** | - | - | - | - |
+| Windows install documented | Yes | Yes | no (Linux/macOS) | Yes | Yes |
+| Sources beyond YouTube | local subtitle/transcript files | - | - | articles, files, audio/video files | **11+** |
+| Speech-to-text fallback | - (roadmap) | - | - | Yes (OpenAI API) | **Whisper** |
+| Runtime | Python 3.11+ | Python 3.13+, uv | Claude Code skill | Go binary | Python or Docker |
+
+`-` means I found nothing in the README or code (I read each project's repository in November 2026). Found a mistake? Please open an issue.
+
+Notes on the table:
+- The closest thing to a token budget elsewhere is martino-summarize's optional prefilter (default: keep 35% of each chunk, scored by an LLM). fabric's `--maxTokens` and martino's `max-tokens` cap the *output*, not what your assistant has to read.
+- didntwatch tells the model to stay grounded in the transcript (a prompt rule); nothing checks it afterwards. martino's "Fact Checker" prompt checks claims against outside sources, not quotes against the video.
+
+Pick **martino-summarize** if you want a full self-hosted pipeline that calls its own LLM and covers many platforms. Pick **fabric** if you live in prompt "patterns". Pick **videoxplainer** if you want your own assistant to do the reading with the fewest tokens and verifiable claims.
+
+## Install
+
+```bash
+pipx install videoxplainer
+videoxplainer doctor              # checks your setup (`vxp` is a short alias for the same command)
+```
+
+Windows: `py -m pip install videoxplainer`, then run it as `py -m videoxplainer ...` if `videoxplainer` isn't on your PATH.
+Until the first PyPI release: `pipx install git+https://github.com/narayan-govindaraj/videoXplainer`.
+
+With Claude Code, run `videoxplainer install-skill` (it writes one file, `~/.claude/skills/videoxplainer/SKILL.md`, and tells you where), restart Claude Code, then paste a video link. Other agents: `videoxplainer install-skill --print` shows the instructions to paste into theirs. Claude Desktop needs an MCP server, which is on the roadmap.
+
+## Use
+
+Choose **what you see** with `--view`, and **what the assistant should do** with `--mode`:
+
+| `--view` | You get |
+|---|---|
+| `chapters` (default) | condensed passages grouped under chapter / topic headings |
+| `excerpts` | condensed key passages only, flat |
+| `raw` | captions exactly as downloaded, unfiltered |
+
+| `--mode` | Task appended for the assistant |
+|---|---|
+| `text` (default) | none, just the content |
+| `summary` | a summary (one per chapter in the chapters view) |
+| `actions` | evidence-backed actions, checkable with `videoxplainer verify` |
+
+```bash
+videoxplainer fetch "https://youtu.be/VIDEO_ID" --view chapters --mode summary --budget 4000
+videoxplainer fetch VIDEO_ID --mode actions       # then: videoxplainer verify VIDEO_ID claims.json
+videoxplainer fetch VIDEO_ID --view raw           # everything, untouched
+videoxplainer search "pricing advice"             # across everything you've fetched
+videoxplainer fetch weekly-sync.vtt --mode summary  # a meeting or podcast transcript on disk
+```
+
+**Your own transcripts.** Point `fetch` (and `verify`, `check`) at a `.srt`, `.vtt`, `.json3`, `.txt` or `.md` file: meeting exports, podcast transcripts, subtitles you downloaded. Text files with leading timestamps (`[00:12:30] ...`) keep them; files with none get timestamps estimated from word count, and the output says so. Nothing leaves your machine.
+
+`--full` gives the complete cleaned transcript with no limit. `--refresh` re-downloads (once per video fetched before v0.2, to pick up chapter markers).
+
+Something off on a video? Run `videoxplainer check <url>`: it tests the whole pipeline on that video (budget respected, every section represented, quotes verifiable) and its output makes a great bug report.
+
+If YouTube asks you to prove you're not a bot: `--cookies-from-browser firefox` (Chrome/Edge cookie import is unreliable on Windows) or `--cookies-file cookies.txt`.
+
+## Limits, honestly
+
+- Online sources: YouTube only for now, and the video needs captions (no speech-to-text yet). Local files must already be text.
+- Condensing is extractive and lossy by design. Use `--full` or `--view raw` when every word matters.
+- Auto-detected sections are a heuristic. YouTube's own chapters are used whenever they exist. On two real talks with known chapters, detection from the text alone put 6 of 11 cuts within a minute of a real chapter start and recovered 7 of 25 real chapter starts; its headings are keyword lists (summary mode asks your assistant to rename them). Run `videoxplainer check <url>` to see how it does on your video.
+- `verify` proves a quote exists in the video. It can't tell you the advice is good.
+- Token counts are conservative estimates (about 4 characters per token for Latin text, heavier for other scripts).
+- Tested on real English, Bengali, Arabic and Bulgarian captions, and on synthetic Hindi and Tamil text. Chinese, Japanese and Thai aren't word-segmented, so section detection and quote matching may be weaker there.
+- YouTube changes things; if caption downloads break, update yt-dlp first (`pip install -U yt-dlp`).
+- Use it for your own research and respect creators' rights and YouTube's terms.
+
+## Roadmap
+
+- [x] v0.1 budgeted briefs, `verify`, local search
+- [x] v0.2 chapter-aware condensing, three views, summary mode
+- [x] v0.3 `install-skill`, local transcript files
+- [ ] v0.4 `videoxplainer channel <url> --since 7d` digests, MCP server (Claude Desktop, Cursor)
+- [ ] v0.5 ask your library with receipts, cross-video agreements/disagreements, optional free local speech-to-text (faster-whisper), more platforms via yt-dlp
+
+## Credits and license
+
+MIT. Built on [yt-dlp](https://github.com/yt-dlp/yt-dlp) (Unlicense) for caption retrieval. Developed with AI assistance (Claude).

videoxplainer-0.3.3/README.md

@@ -0,0 +1,147 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/narayan-govindaraj/videoXplainer/main/docs/brand/logo-lockup-dark.png">
+    <img src="https://raw.githubusercontent.com/narayan-govindaraj/videoXplainer/main/docs/brand/logo-lockup-light.png" alt="VideoXplainer" width="440">
+  </picture>
+</p>
+
+**Your AI reads 4k tokens instead of 18k, and every claim comes with a quote you can check.**
+
+[![ci](https://github.com/narayan-govindaraj/videoXplainer/actions/workflows/ci.yml/badge.svg)](https://github.com/narayan-govindaraj/videoXplainer/actions)
+![license: MIT](https://img.shields.io/badge/license-MIT-blue)
+![python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+
+Most "YouTube summarizer" tools paste the whole transcript into your chat. That burns your context window, and nothing stops the model from inventing points the video never made.
+
+videoxplainer sits between the video and your assistant (Claude Code, Claude Desktop, any agent that can run a command):
+
+- **Condenses by chapter, to a token budget you choose.** Every chapter keeps a share, so the end of the video isn't dropped.
+- **Makes claims checkable.** Ask for actions *with verbatim quotes*, then `videoxplainer verify` confirms each quote really appears in the video, and where.
+- **Needs no API key and no LLM of its own.** Your assistant does the reading; videoxplainer does the plumbing. One `pipx install`, no Node, no compiler.
+
+![VideoXplainer demo: a 1-hour talk condensed to 4,000 tokens across 21 chapters, then every quote checked](https://raw.githubusercontent.com/narayan-govindaraj/videoXplainer/main/docs/demo.gif)
+
+## See it work
+
+The animation above wraps motion graphics around this real run on a public 1-hour talk (59:48). Transcript passages are elided, and the assistant reply and claim cards in the animation are illustrative examples:
+
+```text
+$ videoxplainer fetch zjkBMFhNj_g --budget 4000 --mode summary
+
+# [1hr Talk] Intro to Large Language Models
+Andrej Karpathy | 59:48 | en (auto-captions)
+sections: 21 (YouTube chapters)
+note: condensed to ~3994 of ~17957 tokens (extractive, spread across sections)
+---
+## [00:20] LLM Inference
+[00:29] ...
+## [25:43] LLM Scaling Laws
+[25:44] ...
+## [46:14] Jailbreaks
+[46:33] ...
+---
+TASK: for each "##" heading above write 1-2 sentences on its main point ...
+```
+
+About 17.9k tokens become about 4k, spread over all 21 chapters. Your assistant reads that and writes the chapter-by-chapter summary. No chapters on the video? videoxplainer detects topic shifts from the text instead.
+
+Then check the model's work (illustrative output):
+
+```text
+$ videoxplainer verify VIDEO_ID claims.json
+{ "checked": 3, "supported": 2, "weak": 0, "unsupported": 1,
+  "items": [
+    { "index": 0, "status": "supported",   "matched_at": "01:05", "link": "https://youtu.be/VIDEO_ID?t=65" },
+    { "index": 1, "status": "supported",   "matched_at": "02:10", "link": "https://youtu.be/VIDEO_ID?t=130" },
+    { "index": 2, "status": "unsupported" } ] }
+```
+
+Unsupported means the quote the model cited isn't in the video: drop or fix that point.
+
+## How it compares
+
+| | **videoxplainer** | [youtube-summarize](https://pypi.org/project/youtube-summarize/) (MCP) | [didntwatch](https://github.com/ewro/didntwatch) | [fabric](https://github.com/danielmiessler/fabric) | [martino-summarize](https://pypi.org/project/martino-summarize/) |
+|---|---|---|---|---|---|
+| Needs an LLM API key | **No** | No | No | Yes | Yes (bring your own) |
+| You set a token budget | **Yes** | - | - | - | Yes (optional LLM prefilter) |
+| Chapter-aware condensing | **Yes** | metadata only | - | - | - |
+| Checks the model's quotes against the video | **Yes** | - | - | - | - |
+| Windows install documented | Yes | Yes | no (Linux/macOS) | Yes | Yes |
+| Sources beyond YouTube | local subtitle/transcript files | - | - | articles, files, audio/video files | **11+** |
+| Speech-to-text fallback | - (roadmap) | - | - | Yes (OpenAI API) | **Whisper** |
+| Runtime | Python 3.11+ | Python 3.13+, uv | Claude Code skill | Go binary | Python or Docker |
+
+`-` means I found nothing in the README or code (I read each project's repository in November 2026). Found a mistake? Please open an issue.
+
+Notes on the table:
+- The closest thing to a token budget elsewhere is martino-summarize's optional prefilter (default: keep 35% of each chunk, scored by an LLM). fabric's `--maxTokens` and martino's `max-tokens` cap the *output*, not what your assistant has to read.
+- didntwatch tells the model to stay grounded in the transcript (a prompt rule); nothing checks it afterwards. martino's "Fact Checker" prompt checks claims against outside sources, not quotes against the video.
+
+Pick **martino-summarize** if you want a full self-hosted pipeline that calls its own LLM and covers many platforms. Pick **fabric** if you live in prompt "patterns". Pick **videoxplainer** if you want your own assistant to do the reading with the fewest tokens and verifiable claims.
+
+## Install
+
+```bash
+pipx install videoxplainer
+videoxplainer doctor              # checks your setup (`vxp` is a short alias for the same command)
+```
+
+Windows: `py -m pip install videoxplainer`, then run it as `py -m videoxplainer ...` if `videoxplainer` isn't on your PATH.
+Until the first PyPI release: `pipx install git+https://github.com/narayan-govindaraj/videoXplainer`.
+
+With Claude Code, run `videoxplainer install-skill` (it writes one file, `~/.claude/skills/videoxplainer/SKILL.md`, and tells you where), restart Claude Code, then paste a video link. Other agents: `videoxplainer install-skill --print` shows the instructions to paste into theirs. Claude Desktop needs an MCP server, which is on the roadmap.
+
+## Use
+
+Choose **what you see** with `--view`, and **what the assistant should do** with `--mode`:
+
+| `--view` | You get |
+|---|---|
+| `chapters` (default) | condensed passages grouped under chapter / topic headings |
+| `excerpts` | condensed key passages only, flat |
+| `raw` | captions exactly as downloaded, unfiltered |
+
+| `--mode` | Task appended for the assistant |
+|---|---|
+| `text` (default) | none, just the content |
+| `summary` | a summary (one per chapter in the chapters view) |
+| `actions` | evidence-backed actions, checkable with `videoxplainer verify` |
+
+```bash
+videoxplainer fetch "https://youtu.be/VIDEO_ID" --view chapters --mode summary --budget 4000
+videoxplainer fetch VIDEO_ID --mode actions       # then: videoxplainer verify VIDEO_ID claims.json
+videoxplainer fetch VIDEO_ID --view raw           # everything, untouched
+videoxplainer search "pricing advice"             # across everything you've fetched
+videoxplainer fetch weekly-sync.vtt --mode summary  # a meeting or podcast transcript on disk
+```
+
+**Your own transcripts.** Point `fetch` (and `verify`, `check`) at a `.srt`, `.vtt`, `.json3`, `.txt` or `.md` file: meeting exports, podcast transcripts, subtitles you downloaded. Text files with leading timestamps (`[00:12:30] ...`) keep them; files with none get timestamps estimated from word count, and the output says so. Nothing leaves your machine.
+
+`--full` gives the complete cleaned transcript with no limit. `--refresh` re-downloads (once per video fetched before v0.2, to pick up chapter markers).
+
+Something off on a video? Run `videoxplainer check <url>`: it tests the whole pipeline on that video (budget respected, every section represented, quotes verifiable) and its output makes a great bug report.
+
+If YouTube asks you to prove you're not a bot: `--cookies-from-browser firefox` (Chrome/Edge cookie import is unreliable on Windows) or `--cookies-file cookies.txt`.
+
+## Limits, honestly
+
+- Online sources: YouTube only for now, and the video needs captions (no speech-to-text yet). Local files must already be text.
+- Condensing is extractive and lossy by design. Use `--full` or `--view raw` when every word matters.
+- Auto-detected sections are a heuristic. YouTube's own chapters are used whenever they exist. On two real talks with known chapters, detection from the text alone put 6 of 11 cuts within a minute of a real chapter start and recovered 7 of 25 real chapter starts; its headings are keyword lists (summary mode asks your assistant to rename them). Run `videoxplainer check <url>` to see how it does on your video.
+- `verify` proves a quote exists in the video. It can't tell you the advice is good.
+- Token counts are conservative estimates (about 4 characters per token for Latin text, heavier for other scripts).
+- Tested on real English, Bengali, Arabic and Bulgarian captions, and on synthetic Hindi and Tamil text. Chinese, Japanese and Thai aren't word-segmented, so section detection and quote matching may be weaker there.
+- YouTube changes things; if caption downloads break, update yt-dlp first (`pip install -U yt-dlp`).
+- Use it for your own research and respect creators' rights and YouTube's terms.
+
+## Roadmap
+
+- [x] v0.1 budgeted briefs, `verify`, local search
+- [x] v0.2 chapter-aware condensing, three views, summary mode
+- [x] v0.3 `install-skill`, local transcript files
+- [ ] v0.4 `videoxplainer channel <url> --since 7d` digests, MCP server (Claude Desktop, Cursor)
+- [ ] v0.5 ask your library with receipts, cross-video agreements/disagreements, optional free local speech-to-text (faster-whisper), more platforms via yt-dlp
+
+## Credits and license
+
+MIT. Built on [yt-dlp](https://github.com/yt-dlp/yt-dlp) (Unlicense) for caption retrieval. Developed with AI assistance (Claude).

videoxplainer-0.3.3/SECURITY.md

@@ -0,0 +1,8 @@
+# Security
+
+videoxplainer runs locally. It sends no telemetry and has no server. Network access is yt-dlp talking to YouTube.
+
+- Browser cookies are read only if you pass `--cookies-from-browser` / `--cookies-file`, and are handed to yt-dlp, never stored by videoxplainer.
+- Fetched captions are cached in a local SQLite file (`videoxplainer doctor` prints the path).
+
+Report vulnerabilities privately via GitHub "Report a vulnerability" on this repository's Security tab.

videoxplainer-0.3.3/docs/brand/logo-icon.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#7C3AED"/>
+      <stop offset="1" stop-color="#FF4D8D"/>
+    </linearGradient>
+    <radialGradient id="shine" cx="0.25" cy="0.2" r="0.7">
+      <stop offset="0" stop-color="#FFFFFF" stop-opacity="0.28"/>
+      <stop offset="1" stop-color="#FFFFFF" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <rect width="1024" height="1024" rx="232" fill="url(#bg)"/>
+  <rect width="1024" height="1024" rx="232" fill="url(#shine)"/>
+  <g stroke="#FFFFFF" stroke-width="150" stroke-linecap="round" fill="none">
+    <line x1="270" y1="270" x2="754" y2="754"/>
+    <line x1="754" y1="270" x2="270" y2="754"/>
+  </g>
+  <g stroke-linejoin="round" stroke-width="44">
+    <polygon points="402,300 402,724 758,512" fill="#1B0F3C" stroke="#1B0F3C" transform="translate(512 512) scale(1.0) translate(-512 -512)"/>
+    <polygon points="428,350 428,674 700,512" fill="#C6F432" stroke="#C6F432"/>
+  </g>
+</svg>

videoxplainer-0.3.3/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "videoxplainer"
+version = "0.3.3"
+description = "Turn YouTube videos into token-budgeted, evidence-checked action briefs for LLMs."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Narayan Govindaraj" }]
+keywords = ["youtube", "transcript", "summary", "llm", "claude", "mcp", "token", "yt-dlp", "chapters"]
+requires-python = ">=3.11"
+dependencies = ["yt-dlp>=2025.1.1"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Multimedia :: Video",
+  "Programming Language :: Python :: 3",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+videoxplainer = "videoxplainer.cli:main"
+vxp = "videoxplainer.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/videoxplainer"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[project.urls]
+Homepage = "https://github.com/narayan-govindaraj/videoXplainer"
+Issues = "https://github.com/narayan-govindaraj/videoXplainer/issues"
+Changelog = "https://github.com/narayan-govindaraj/videoXplainer/blob/main/CHANGELOG.md"

videoxplainer-0.3.3/src/videoxplainer/__init__.py

@@ -0,0 +1,3 @@
+"""videoxplainer - token-budgeted, evidence-checked action briefs from videos."""
+
+__version__ = "0.3.3"

videoxplainer-0.3.3/src/videoxplainer/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())