Metadata-Version: 2.4
Name: kavenio-youtube-transcribe
Version: 0.1.0
Summary: Turn YouTube videos into local, agent-ready transcripts.
Project-URL: Homepage, https://github.com/kaveniohq/youtube-transcribe
Project-URL: Repository, https://github.com/kaveniohq/youtube-transcribe
Project-URL: Issues, https://github.com/kaveniohq/youtube-transcribe/issues
Project-URL: Changelog, https://github.com/kaveniohq/youtube-transcribe/releases
Author: YouTube Transcribe contributors
License-Expression: MIT
License-File: LICENSE
Keywords: claude,cli,codex,transcription,whisper,youtube
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Requires-Dist: faster-whisper<2,>=1.2.1
Requires-Dist: yt-dlp[default,deno]>=2026.3.17
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: jsonschema>=4.23; extra == 'dev'
Requires-Dist: pytest-cov>=6; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Description-Content-Type: text/markdown

# YouTube Transcribe

A local-first CLI that turns a YouTube video into a clean, agent-ready
transcript.

YouTube Transcribe downloads the video's native audio with
[yt-dlp](https://github.com/yt-dlp/yt-dlp), transcribes it locally with
[faster-whisper](https://github.com/SYSTRAN/faster-whisper), and writes a
portable Markdown file. It can also preserve word-level timestamps, WebVTT
subtitles, and the original audio.

- No transcription API key or per-minute fee
- Local speech-to-text on macOS, Linux, and Windows
- Stable Markdown and versioned JSON outputs
- Optional transcript cleanup with an existing Codex CLI or Claude Code login
- Agent Skill included for Codex, Claude Code, and compatible tools

## Install

Requirements:

- Python 3.10 or newer
- Enough disk space and memory for the selected Whisper model

Install the latest stable release, its dependencies, and the Agent Skill:

```bash
curl -fsSL https://raw.githubusercontent.com/kaveniohq/youtube-transcribe/main/install.sh | bash
```

The installer creates an isolated environment, exposes the command under
`~/.local/bin`, installs the skill for Codex and Claude Code, and runs
`youtube-transcribe doctor`. If `~/.local/bin` is not on your `PATH`, it prints
the exact command to add it.

Prefer installing manually? Use
[pipx](https://pipx.pypa.io/stable/installation/):

```bash
pipx install kavenio-youtube-transcribe
youtube-transcribe install-skill
youtube-transcribe doctor
```

## Quick start

Transcribe a video:

```bash
youtube-transcribe "https://www.youtube.com/watch?v=VIDEO_ID"
```

The first run downloads the selected Whisper model. The default `base` model is
a practical speed/quality compromise.

## Usage

| What you want | Command | Result |
| --- | --- | --- |
| Create a transcript | `youtube-transcribe "URL"` | `transcript.md` |
| Choose an output location | `youtube-transcribe "URL" --output-dir ./transcripts` | One video folder inside `./transcripts` |
| Add word and segment timestamps | `youtube-transcribe "URL" --timestamps` | Markdown, versioned JSON, and WebVTT |
| Keep the downloaded audio | `youtube-transcribe "URL" --keep-audio` | Transcript plus the native WebM/M4A audio |
| Refine with Codex CLI | `youtube-transcribe "URL" --codex` | Locally transcribed, then text-edited with Codex |
| Refine with Claude Code | `youtube-transcribe "URL" --claude` | Locally transcribed, then text-edited with Claude |
| Use a faster model | `youtube-transcribe "URL" --model tiny` | Faster draft with lower accuracy |
| Use a more accurate model | `youtube-transcribe "URL" --model small` | Slower transcript with higher accuracy |
| Fix the spoken language | `youtube-transcribe "URL" --language en` | Skips language auto-detection |
| Use NVIDIA CUDA | `youtube-transcribe "URL" --device cuda` | GPU inference with supported CUDA setup |
| Use browser authentication | `youtube-transcribe "URL" --cookies-from-browser chrome` | Lets yt-dlp read the selected local browser session |
| Protect existing artifacts | `youtube-transcribe "URL" --no-overwrite` | Fails instead of replacing output files |
| Install the Agent Skill | `youtube-transcribe install-skill` | Adds the skill to Codex and Claude discovery locations |
| Check the installation | `youtube-transcribe doctor` | Dependency and update status |

Options can be combined:

```bash
youtube-transcribe "URL" \
  --output-dir ./transcripts \
  --model base \
  --timestamps \
  --codex
```

Run `youtube-transcribe --help` for the complete command reference.

## Output

Each run creates a deterministic folder named from the video title and ID:

```text
steam-machine-8cDatzBIufQ/
└── transcript.md
```

With `--timestamps`:

```text
steam-machine-8cDatzBIufQ/
├── transcript.md
├── transcript.json
└── timestamps.vtt
```

Add `--keep-audio` to retain the native audio file in the same folder.

| Artifact | Created when | Purpose |
| --- | --- | --- |
| `transcript.md` | Always | Readable transcript with source provenance |
| `transcript.json` | `--timestamps` | Versioned machine contract with raw segment and word timing |
| `timestamps.vtt` | `--timestamps` | Subtitles for players and tools that support WebVTT |
| `audio.webm` or `audio.m4a` | `--keep-audio` | Original native audio selected by yt-dlp |

The CLI writes progress to stderr and final artifact paths to stdout, which
makes it safe to use in scripts and agent workflows:

```text
[download]    YouTube audio           [████████████████████] 100%
[model]       Download Whisper base   [████████░░░░░░░░░░░░]  40%
[transcribe]  Speech to text          [██████████░░░░░░░░░░]  50%
[write]       Agent-ready artifacts
```

## Transcript format

Markdown begins with YAML-compatible provenance followed by the complete
transcript:

```markdown
---
transcript_schema: 1
title: "Example video"
source: "https://www.youtube.com/watch?v=..."
video_id: "..."
language: "en"
transcription_model: "base"
edited_by: "none"
transcript_data: null
timestamps: null
---

# Example video

Complete transcript...
```

With `--timestamps`, `transcript.json` is the canonical machine-readable
artifact. It keeps immutable raw Whisper timing separate from optionally edited
prose. The normative schema is
[`transcript-v1.schema.json`](src/youtube_transcript/schemas/transcript-v1.schema.json).

## Optional AI editing

No editor is selected by default. `--codex` and `--claude` deliberately start a
separate command-line editor process after local transcription; they may use
the allowance associated with your existing login.

The editor receives transcript text through standard input and cannot change
the raw timestamp data:

```bash
youtube-transcribe "URL" --codex --timestamps
youtube-transcribe "URL" --claude --timestamps
```

Codex runs ephemerally in a read-only sandbox without user execution rules.
Claude runs without built-in tools, MCP servers, slash commands, Chrome
integration, or session persistence. Both run from an empty temporary
directory.

## Use with AI agents

The repository includes a portable
[Agent Skill](.agents/skills/youtube-transcribe/SKILL.md) that teaches compatible
agents when to run the CLI, which options to select, and which generated file
to read.

The CLI package bundles this skill. Install it with:

```bash
youtube-transcribe install-skill
```

This works on Linux, macOS, and Windows and writes:

```text
~/.agents/skills/youtube-transcribe  # Codex and compatible agents
~/.claude/skills/youtube-transcribe  # Claude Code
```

Use `--target codex` or `--target claude` to install only one copy. Rerunning
the command safely updates an unchanged managed skill. Locally modified files
are preserved unless you explicitly pass `--force`. Run it again after
upgrading the CLI to install the bundled skill version.

Restart an already-running agent, then ask naturally:

```text
Transcribe https://www.youtube.com/watch?v=VIDEO_ID
Transcribe this video with timestamps: https://youtu.be/VIDEO_ID
Use $youtube-transcribe to turn this video into notes: https://youtu.be/VIDEO_ID
Use /youtube-transcribe to create subtitles for https://youtu.be/VIDEO_ID
```

The active agent does not need `--codex` or `--claude`; those options start a
second editor process.

## Local development

```bash
git clone https://github.com/kaveniohq/youtube-transcribe.git
cd youtube-transcribe
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest
```

On Windows PowerShell, activate the environment with:

```powershell
.venv\Scripts\Activate.ps1
```

Before submitting a change, run:

```bash
ruff check src tests
ruff format --check src tests
pytest --cov=youtube_transcript --cov-fail-under=80
python -m build
python -m twine check dist/*
```

Development references:

- [`AGENT.md`](AGENT.md) — setup, architecture, invariants, and agent-facing
  implementation guidance
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution and verification rules
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — detailed contracts, design decisions,
  and implementation evidence
- [`RELEASING.md`](RELEASING.md) — versioning and release procedure

Default tests are offline: they do not download videos or models and do not
invoke Codex or Claude.

## How it works

```text
YouTube URL
  -> yt-dlp native audio download
  -> local faster-whisper transcription
  -> optional Codex or Claude text editing
  -> atomic Markdown / JSON / WebVTT output
```

Provider-specific code stays behind small adapters. Temporary downloads are
cleaned automatically, and final artifacts are written only after the requested
pipeline succeeds.

## Current limitations

- One video per invocation; playlists and channels are not supported.
- Transcripts over 600,000 characters are not sent to an optional editor.
- Live streams, members-only videos, regional restrictions, and YouTube bot
  challenges depend on yt-dlp and may require browser cookies.
- The first transcription for a model requires a model download.

The package supplies yt-dlp's supported Deno runtime and uses faster-whisper's
PyAV decoder. A global JavaScript runtime, FFmpeg, and FFprobe are not required.

## Updates

After a successful interactive run, the CLI checks PyPI at most once every
seven days and prints a notice when a newer version is available. It never
installs updates, changes stdout, or sends transcript/source metadata.

Set `YOUTUBE_TRANSCRIBE_NO_UPDATE_CHECK=1` to disable update checks.

## Contributing

Issues and focused pull requests are welcome. Please read
[`CONTRIBUTING.md`](CONTRIBUTING.md) before making a change and include tests
for behavior changes.

## License

Licensed under the [MIT License](LICENSE).
