Metadata-Version: 2.4
Name: youtube-summariser
Version: 0.6.3
Summary: Summarize YouTube videos using AI (OpenAI, Anthropic, or OpenRouter)
Project-URL: Homepage, https://github.com/weijianzhg/youtube-summariser
Project-URL: Repository, https://github.com/weijianzhg/youtube-summariser
Project-URL: Issues, https://github.com/weijianzhg/youtube-summariser/issues
Author: Weijian Zhang
License-Expression: MIT
License-File: LICENSE
Keywords: ai,anthropic,claude,cli,gpt,openai,openrouter,summarizer,transcript,youtube
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Video
Classifier: Topic :: Text Processing :: General
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40.0
Requires-Dist: openai>=1.60.0
Requires-Dist: openrouter>=0.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pytubefix>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: youtube-transcript-api>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# YouTube Summariser

A command-line tool that summarizes YouTube videos using AI. It extracts transcripts from YouTube videos and generates structured summaries using OpenAI, Anthropic, or OpenRouter (300+ models).

## Installation

```bash
pip install youtube-summariser
```

> **Note:** `youtube-summariser` (British), `youtube-summarizer` (American), and `ys` (short alias) commands are all available.

Or install from source:

```bash
git clone https://github.com/weijianzhg/youtube-summariser
cd youtube-summariser
pip install -e .
```

## Quick Start

Run the interactive setup to configure your API keys:

```bash
youtube-summariser init
```

This guides you through:

- Selecting your default provider (Anthropic, OpenAI, or OpenRouter)
- Entering your API key (securely masked)
- Optionally configuring additional providers

## Configuration

### Option 1: Interactive Setup (Recommended)

```bash
youtube-summariser init
```

Settings are saved to a platform-appropriate location:

- **macOS/Linux**: `~/.youtube-summariser/config.yaml`
- **Windows**: `%APPDATA%\youtube-summariser\config.yaml`

Re-run `init` anytime to update your settings.

### Option 2: Environment Variables

```bash
# For Anthropic (default provider)
export ANTHROPIC_API_KEY=your_anthropic_api_key

# For OpenAI
export OPENAI_API_KEY=your_openai_api_key

# For OpenRouter (access 300+ models)
export OPENROUTER_API_KEY=your_openrouter_api_key
```

Or create a `.env` file in your working directory.

### Configuration Priority

1. Environment variables (highest priority)
2. User config file (`~/.youtube-summariser/config.yaml`)
3. Bundled defaults

### Default Provider

The default provider is **Anthropic**. You can change this via `init` or override per command using `--provider`.

## Usage

```bash
# Interactive configuration
youtube-summariser init

# Same command with the short alias
ys init

# Summarize a video (saves to auto-generated filename)
youtube-summariser "https://www.youtube.com/watch?v=VIDEO_ID"

# Specify output filename
youtube-summariser "https://youtu.be/VIDEO_ID" -o my_summary.md

# Print to terminal only (no file saved)
youtube-summariser "https://youtube.com/watch?v=VIDEO_ID" --no-save

# Use a specific provider
youtube-summariser "https://youtu.be/VIDEO_ID" --provider openai

# Use OpenRouter with access to 300+ models
youtube-summariser "https://youtu.be/VIDEO_ID" --provider openrouter
```

### Search by Title

Don't have a URL? Search for videos by title:

```bash
# Interactive selection (shows top 5 results)
youtube-summariser search "How to make mass"

# Auto-select first result
youtube-summariser search "Python tutorial" --first

# Show more results
youtube-summariser search "cooking recipes" --max-results 10
```

### Commands


| Command     | Description                                             |
| ----------- | ------------------------------------------------------- |
| `init`      | Interactive setup for API keys and preferences          |
| `summarise` | Summarize a YouTube video (also aliased as `summarize`) |
| `search`    | Search YouTube by title and summarize                   |


You can also pass a URL directly without the `summarise` subcommand for convenience.

### Options


| Flag            | Description                                                            |
| --------------- | ---------------------------------------------------------------------- |
| `-o, --output`  | Specify output filename (default: `YYYY-MM-DD__video-title-slug__video-id.md`) |
| `--no-save`     | Print summary to terminal without saving to file                       |
| `--provider`    | LLM provider to use: `openai`, `anthropic`, or `openrouter`            |
| `--no-stream`   | Disable streaming output                                               |
| `--first, -1`   | Auto-select first search result (search command only)                  |
| `--max-results` | Number of search results to display (default: 5)                       |
| `-v, --version` | Show version number                                                    |
| `-h, --help`    | Show help message                                                      |


### zsh Tip (URLs Without Quotes)

In `zsh`, unquoted YouTube URLs containing `?` are treated as glob patterns before the CLI runs.

Use one of these approaches:

```bash
# Escape ? in the URL
ys https://www.youtube.com/watch\?v=VIDEO_ID

# Or disable globbing for this command
noglob ys https://www.youtube.com/watch?v=VIDEO_ID
```

To make this convenient permanently, add to `~/.zshrc`:

```bash
ys() { noglob command ys "$@"; }
```

### Output Format

Summary files are saved as markdown (`.md`) with the following structure:

```markdown
# YouTube Video Summary

| | |
|---|---|
| **Video URL** | <https://www.youtube.com/watch?v=VIDEO_ID> |
| **Video ID** | `VIDEO_ID` |
| **Generated** | 2025-01-01 14:30:00 |
| **Model** | anthropic / claude-sonnet-4-5-20250929 |

---

## Main Topics
...

## Key Points
...

## Detailed Summary
...

## Notable Quotes
...

## Timestamps for Important Moments
...
```

## Requirements

- Python 3.10+
- An API key for OpenAI, Anthropic, or OpenRouter

## License

MIT License - see [LICENSE](LICENSE) for details.