hearsay 0.1.0__tar.gz

hearsay-0.1.0/LICENSE

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

hearsay-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: hearsay
+Version: 0.1.0
+Summary: crawl4ai for video & audio — turn any YouTube video, podcast episode, or local recording into clean, timestamped, LLM-ready markdown
+Author: Mudassar Awan
+Author-email: Mudassar Awan <mudassar.awan@snapdev.ai>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: faster-whisper>=1.2.1
+Requires-Dist: feedparser>=6.0.12
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: typer>=0.26.7
+Requires-Dist: youtube-transcript-api>=1.2.4
+Requires-Dist: yt-dlp>=2026.6.9
+Requires-Dist: mcp>=1.2 ; extra == 'mcp'
+Requires-Python: >=3.11
+Provides-Extra: mcp
+Description-Content-Type: text/markdown
+
+# hearsay
+
+> **crawl4ai for video & audio.** One command turns any YouTube video, podcast
+> episode, or local recording into clean, timestamped, chunked, LLM-ready
+> markdown — for RAG pipelines and AI agents.
+
+[![CI](https://github.com/mudassar531/hearsay/actions/workflows/ci.yml/badge.svg)](https://github.com/mudassar531/hearsay/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+![hearsay in action](demo/demo.gif)
+
+## Why
+
+Getting a transcript into your RAG pipeline usually means gluing together
+`yt-dlp`, Whisper, and a pile of timestamp-wrangling scripts — and you still end
+up with one line per caption fragment or an undifferentiated wall of text.
+hearsay does the whole thing in one command and gives you back markdown a human
+*and* a model can read: readable paragraphs, real timestamps, chapter headings,
+and an optional JSON sidecar with a stable schema.
+
+## Install
+
+```bash
+uv tool install hearsay          # recommended
+# or
+pipx install hearsay
+# transcription + MCP server support:
+uv tool install "hearsay[mcp]"
+```
+
+> **Pre-release:** hearsay isn't on PyPI yet. Until the first release, install
+> from a checkout:
+>
+> ```bash
+> git clone https://github.com/mudassar531/hearsay
+> cd hearsay
+> uv tool install .               # puts `hearsay` on your PATH
+> # or, for development:  uv sync && uv run hearsay --help
+> ```
+
+**System requirement:** [ffmpeg](#requirements) on your PATH.
+
+## 30-second quickstart
+
+```bash
+# YouTube → markdown via captions (fast — no download)
+hearsay "https://www.youtube.com/watch?v=VIDEO_ID"
+
+# Local audio/video → markdown via local Whisper (runs on CPU)
+hearsay talk.mp3
+
+# Force Whisper on a YouTube URL, pick a model, also emit JSON
+hearsay "https://youtu.be/VIDEO_ID" --transcribe --model small --json
+
+# Music/song? Add --no-vad so the lyrics aren't filtered out as "non-speech"
+hearsay "https://youtu.be/SONG_ID" --no-vad
+
+# A podcast feed or YouTube playlist: list, then ingest a selection
+hearsay "https://example.com/feed.xml"
+hearsay "https://example.com/feed.xml" --all --limit 3 --output-dir ./out
+```
+
+No captions on a video? hearsay falls back to local Whisper automatically.
+
+## What you get
+
+```markdown
+---
+title: "You Would Be a Terrible Leader"
+source: "https://www.youtube.com/watch?v=rStL7niR7gs"
+channel: "CGP Grey"
+duration: "00:18:13"
+ingested: "2026-06-13T10:00:00Z"
+method: "captions"
+language: "en"
+---
+
+# You Would Be a Terrible Leader
+
+## [00:00:00 – 00:05:21]
+
+**[00:00:00]** Do you want to rule? Do you see the problems in your country and
+know how to fix them? If only you had the power to do so. Well. You've come to
+the right place. But, before we begin this lesson in political power, ask
+yourself, why don't rulers see as clearly as you...
+```
+
+Pass `--json` for a sidecar matching the [`Transcript` schema](docs/schema.json):
+metadata plus `chunks[]`, each with `start_s`, `end_s`, `section`, and `text` —
+ready to embed.
+
+## How it compares
+
+| | **hearsay** | DIY `yt-dlp` + Whisper | markitdown / docling |
+| --- | --- | --- | --- |
+| Input | video & **audio** | video & audio (you wire it) | documents (pdf/docx/pptx) |
+| One command | ✅ | ❌ multi-step plumbing | ✅ (for docs) |
+| Captions-first (no download) | ✅ | ✗ usually re-transcribes | n/a |
+| Timestamps + paragraph grouping | ✅ readable | ✗ raw segments | n/a |
+| Chapters → sections | ✅ | ✗ manual | n/a |
+| Podcasts · playlists · batch | ✅ | ✗ manual | ✗ |
+| JSON sidecar for RAG | ✅ stable schema | ✗ manual | varies |
+| MCP server for agents | ✅ | ✗ | varies |
+
+hearsay does **media**; document tools like
+[markitdown](https://github.com/microsoft/markitdown) and
+[docling](https://github.com/docling-project/docling) do **documents**. Use both.
+
+## Give your agent ears
+
+hearsay ships an [MCP](https://modelcontextprotocol.io) server so AI agents can
+ingest media themselves. It exposes two tools — `ingest_url(url, transcribe?, lang?)`
+and `ingest_file(path)` — that each return clean, timestamped markdown.
+
+```bash
+uv tool install "hearsay[mcp]"
+hearsay mcp                      # stdio MCP server (Ctrl-C to stop)
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add hearsay -- hearsay mcp
+```
+
+or add to `.mcp.json` (project) / `~/.claude.json` (user):
+
+```json
+{
+  "mcpServers": {
+    "hearsay": {
+      "type": "stdio",
+      "command": "hearsay",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Claude Desktop** — add to `claude_desktop_config.json` (Settings → Developer →
+Edit Config; macOS: `~/Library/Application Support/Claude/`, Windows:
+`%APPDATA%\Claude\`):
+
+```json
+{
+  "mcpServers": {
+    "hearsay": {
+      "type": "stdio",
+      "command": "hearsay",
+      "args": ["mcp"],
+      "env": {
+        "HEARSAY_MODEL": "small"
+      }
+    }
+  }
+}
+```
+
+If `hearsay` is not on the host's PATH, use the absolute path (`which hearsay`),
+or `"command": "python"`, `"args": ["-m", "hearsay", "mcp"]`.
+
+Server configuration (env vars, since MCP tool signatures are fixed):
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `HEARSAY_MODEL` | `small` | Whisper model size (`tiny`…`large-v3`) |
+| `HEARSAY_LANG` | _(unset)_ | Default language: English captions, else Whisper auto-detect |
+| `HEARSAY_VAD` | `1` | Voice-activity filter; set `0` for music/songs |
+
+> **Speech vs. music:** hearsay is tuned for spoken audio (podcasts, talks,
+> interviews, meetings), where transcription is accurate. For music, pass
+> `--no-vad` so the vocals aren't discarded — but expect a rough, approximate
+> lyric transcript, since Whisper is a speech model, not a lyrics transcriber.
+
+## CLI reference
+
+```text
+hearsay <SOURCE> [options]      SOURCE = YouTube video/playlist URL, podcast RSS, or local file
+
+  -o, --output PATH    Output file for a single source (default ./<id>.md)
+  --output-dir PATH    Output directory for batch (playlist/feed) ingestion (default ./hearsay-out)
+  --lang CODE          Language: captions default to English; transcription auto-detects
+  --transcribe         Force local Whisper even when captions exist
+  --model SIZE         Whisper model: tiny | base | small | medium | large-v3 (default small)
+  --no-vad             Disable voice-activity filtering (use for music/songs)
+  --json               Also write a .json sidecar (Transcript schema)
+  --latest             Batch: ingest only the most recent item
+  --episode N          Batch: ingest only item N (1-indexed)
+  --all [--limit N]    Batch: ingest all items (optionally capped)
+  --version            Show version
+
+hearsay mcp            Run the MCP stdio server
+```
+
+## Requirements
+
+- **Python 3.11+**
+- **ffmpeg** on your PATH. hearsay decodes most audio/video directly
+  (faster-whisper bundles its own decoder), but ffmpeg is the safe baseline and
+  is used for some yt-dlp format merges.
+
+| OS | Install ffmpeg |
+| --- | --- |
+| macOS (Homebrew) | `brew install ffmpeg` |
+| Debian / Ubuntu | `sudo apt install ffmpeg` |
+| Fedora | `sudo dnf install ffmpeg` |
+| Arch | `sudo pacman -S ffmpeg` |
+| Windows (winget) | `winget install Gyan.FFmpeg` |
+| Windows (Chocolatey) | `choco install ffmpeg` |
+
+The first transcription downloads the chosen Whisper model once (tens of MB to
+~1.5 GB), then caches it for offline use.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[good first issues](docs/good-first-issues.md). hearsay does one thing well —
+media → great markdown — and aims to keep doing exactly that.
+
+## License
+
+[MIT](LICENSE)

hearsay-0.1.0/README.md

@@ -0,0 +1,223 @@
+# hearsay
+
+> **crawl4ai for video & audio.** One command turns any YouTube video, podcast
+> episode, or local recording into clean, timestamped, chunked, LLM-ready
+> markdown — for RAG pipelines and AI agents.
+
+[![CI](https://github.com/mudassar531/hearsay/actions/workflows/ci.yml/badge.svg)](https://github.com/mudassar531/hearsay/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+![hearsay in action](demo/demo.gif)
+
+## Why
+
+Getting a transcript into your RAG pipeline usually means gluing together
+`yt-dlp`, Whisper, and a pile of timestamp-wrangling scripts — and you still end
+up with one line per caption fragment or an undifferentiated wall of text.
+hearsay does the whole thing in one command and gives you back markdown a human
+*and* a model can read: readable paragraphs, real timestamps, chapter headings,
+and an optional JSON sidecar with a stable schema.
+
+## Install
+
+```bash
+uv tool install hearsay          # recommended
+# or
+pipx install hearsay
+# transcription + MCP server support:
+uv tool install "hearsay[mcp]"
+```
+
+> **Pre-release:** hearsay isn't on PyPI yet. Until the first release, install
+> from a checkout:
+>
+> ```bash
+> git clone https://github.com/mudassar531/hearsay
+> cd hearsay
+> uv tool install .               # puts `hearsay` on your PATH
+> # or, for development:  uv sync && uv run hearsay --help
+> ```
+
+**System requirement:** [ffmpeg](#requirements) on your PATH.
+
+## 30-second quickstart
+
+```bash
+# YouTube → markdown via captions (fast — no download)
+hearsay "https://www.youtube.com/watch?v=VIDEO_ID"
+
+# Local audio/video → markdown via local Whisper (runs on CPU)
+hearsay talk.mp3
+
+# Force Whisper on a YouTube URL, pick a model, also emit JSON
+hearsay "https://youtu.be/VIDEO_ID" --transcribe --model small --json
+
+# Music/song? Add --no-vad so the lyrics aren't filtered out as "non-speech"
+hearsay "https://youtu.be/SONG_ID" --no-vad
+
+# A podcast feed or YouTube playlist: list, then ingest a selection
+hearsay "https://example.com/feed.xml"
+hearsay "https://example.com/feed.xml" --all --limit 3 --output-dir ./out
+```
+
+No captions on a video? hearsay falls back to local Whisper automatically.
+
+## What you get
+
+```markdown
+---
+title: "You Would Be a Terrible Leader"
+source: "https://www.youtube.com/watch?v=rStL7niR7gs"
+channel: "CGP Grey"
+duration: "00:18:13"
+ingested: "2026-06-13T10:00:00Z"
+method: "captions"
+language: "en"
+---
+
+# You Would Be a Terrible Leader
+
+## [00:00:00 – 00:05:21]
+
+**[00:00:00]** Do you want to rule? Do you see the problems in your country and
+know how to fix them? If only you had the power to do so. Well. You've come to
+the right place. But, before we begin this lesson in political power, ask
+yourself, why don't rulers see as clearly as you...
+```
+
+Pass `--json` for a sidecar matching the [`Transcript` schema](docs/schema.json):
+metadata plus `chunks[]`, each with `start_s`, `end_s`, `section`, and `text` —
+ready to embed.
+
+## How it compares
+
+| | **hearsay** | DIY `yt-dlp` + Whisper | markitdown / docling |
+| --- | --- | --- | --- |
+| Input | video & **audio** | video & audio (you wire it) | documents (pdf/docx/pptx) |
+| One command | ✅ | ❌ multi-step plumbing | ✅ (for docs) |
+| Captions-first (no download) | ✅ | ✗ usually re-transcribes | n/a |
+| Timestamps + paragraph grouping | ✅ readable | ✗ raw segments | n/a |
+| Chapters → sections | ✅ | ✗ manual | n/a |
+| Podcasts · playlists · batch | ✅ | ✗ manual | ✗ |
+| JSON sidecar for RAG | ✅ stable schema | ✗ manual | varies |
+| MCP server for agents | ✅ | ✗ | varies |
+
+hearsay does **media**; document tools like
+[markitdown](https://github.com/microsoft/markitdown) and
+[docling](https://github.com/docling-project/docling) do **documents**. Use both.
+
+## Give your agent ears
+
+hearsay ships an [MCP](https://modelcontextprotocol.io) server so AI agents can
+ingest media themselves. It exposes two tools — `ingest_url(url, transcribe?, lang?)`
+and `ingest_file(path)` — that each return clean, timestamped markdown.
+
+```bash
+uv tool install "hearsay[mcp]"
+hearsay mcp                      # stdio MCP server (Ctrl-C to stop)
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add hearsay -- hearsay mcp
+```
+
+or add to `.mcp.json` (project) / `~/.claude.json` (user):
+
+```json
+{
+  "mcpServers": {
+    "hearsay": {
+      "type": "stdio",
+      "command": "hearsay",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Claude Desktop** — add to `claude_desktop_config.json` (Settings → Developer →
+Edit Config; macOS: `~/Library/Application Support/Claude/`, Windows:
+`%APPDATA%\Claude\`):
+
+```json
+{
+  "mcpServers": {
+    "hearsay": {
+      "type": "stdio",
+      "command": "hearsay",
+      "args": ["mcp"],
+      "env": {
+        "HEARSAY_MODEL": "small"
+      }
+    }
+  }
+}
+```
+
+If `hearsay` is not on the host's PATH, use the absolute path (`which hearsay`),
+or `"command": "python"`, `"args": ["-m", "hearsay", "mcp"]`.
+
+Server configuration (env vars, since MCP tool signatures are fixed):
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `HEARSAY_MODEL` | `small` | Whisper model size (`tiny`…`large-v3`) |
+| `HEARSAY_LANG` | _(unset)_ | Default language: English captions, else Whisper auto-detect |
+| `HEARSAY_VAD` | `1` | Voice-activity filter; set `0` for music/songs |
+
+> **Speech vs. music:** hearsay is tuned for spoken audio (podcasts, talks,
+> interviews, meetings), where transcription is accurate. For music, pass
+> `--no-vad` so the vocals aren't discarded — but expect a rough, approximate
+> lyric transcript, since Whisper is a speech model, not a lyrics transcriber.
+
+## CLI reference
+
+```text
+hearsay <SOURCE> [options]      SOURCE = YouTube video/playlist URL, podcast RSS, or local file
+
+  -o, --output PATH    Output file for a single source (default ./<id>.md)
+  --output-dir PATH    Output directory for batch (playlist/feed) ingestion (default ./hearsay-out)
+  --lang CODE          Language: captions default to English; transcription auto-detects
+  --transcribe         Force local Whisper even when captions exist
+  --model SIZE         Whisper model: tiny | base | small | medium | large-v3 (default small)
+  --no-vad             Disable voice-activity filtering (use for music/songs)
+  --json               Also write a .json sidecar (Transcript schema)
+  --latest             Batch: ingest only the most recent item
+  --episode N          Batch: ingest only item N (1-indexed)
+  --all [--limit N]    Batch: ingest all items (optionally capped)
+  --version            Show version
+
+hearsay mcp            Run the MCP stdio server
+```
+
+## Requirements
+
+- **Python 3.11+**
+- **ffmpeg** on your PATH. hearsay decodes most audio/video directly
+  (faster-whisper bundles its own decoder), but ffmpeg is the safe baseline and
+  is used for some yt-dlp format merges.
+
+| OS | Install ffmpeg |
+| --- | --- |
+| macOS (Homebrew) | `brew install ffmpeg` |
+| Debian / Ubuntu | `sudo apt install ffmpeg` |
+| Fedora | `sudo dnf install ffmpeg` |
+| Arch | `sudo pacman -S ffmpeg` |
+| Windows (winget) | `winget install Gyan.FFmpeg` |
+| Windows (Chocolatey) | `choco install ffmpeg` |
+
+The first transcription downloads the chosen Whisper model once (tens of MB to
+~1.5 GB), then caches it for offline use.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[good first issues](docs/good-first-issues.md). hearsay does one thing well —
+media → great markdown — and aims to keep doing exactly that.
+
+## License
+
+[MIT](LICENSE)

hearsay-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "hearsay"
+version = "0.1.0"
+description = "crawl4ai for video & audio — turn any YouTube video, podcast episode, or local recording into clean, timestamped, LLM-ready markdown"
+readme = "README.md"
+authors = [
+    { name = "Mudassar Awan", email = "mudassar.awan@snapdev.ai" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+    "faster-whisper>=1.2.1",
+    "feedparser>=6.0.12",
+    "pydantic>=2.13.4",
+    "typer>=0.26.7",
+    "youtube-transcript-api>=1.2.4",
+    "yt-dlp>=2026.6.9",
+]
+
+[project.scripts]
+hearsay = "hearsay.cli:app"
+
+[project.optional-dependencies]
+mcp = [
+    "mcp>=1.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mcp>=1.2",
+    "mypy>=2.1.0",
+    "pytest>=9.0.3",
+    "ruff>=0.15.17",
+]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# These characters are intentional typography: the en dash appears in
+# time-span section titles, and the curly quotes are matched literally in
+# the grouping module's punctuation regexes (transcripts contain them).
+allowed-confusables = ["–", "“", "”", "‘", "’"]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # bugbear
+    "C4",  # comprehensions
+    "SIM", # simplify
+    "RUF", # ruff-specific
+]
+
+[tool.mypy]
+files = ["src", "tests"]
+python_version = "3.11"
+check_untyped_defs = true
+warn_unused_ignores = true
+# Lenient policy: no strict mode; untyped third-party deps get scoped
+# [[tool.mypy.overrides]] entries instead of a global ignore_missing_imports,
+# so first-party import typos still fail.
+
+[[tool.mypy.overrides]]
+# These third-party deps ship no type stubs or py.typed marker.
+module = ["faster_whisper.*", "feedparser.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

hearsay-0.1.0/src/hearsay/__init__.py

@@ -0,0 +1,12 @@
+"""hearsay — crawl4ai for video & audio.
+
+Turn any YouTube video, podcast episode, or local recording into clean,
+timestamped, LLM-ready markdown.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hearsay")
+except PackageNotFoundError:  # pragma: no cover - source tree without an install
+    __version__ = "0.0.0.dev0"

hearsay-0.1.0/src/hearsay/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m hearsay`` (used by MCP server configs and tests)."""
+
+from hearsay.cli import app
+
+if __name__ == "__main__":
+    app()