Metadata-Version: 2.4
Name: ytdl-archiver
Version: 0.2.8
Summary: Modern Python CLI for archiving YouTube playlists with media-server metadata support
Keywords: youtube,archive,yt-dlp,media-server,cli
Author: Ben Chitty
Author-email: Ben Chitty <htmlgxn@pm.me>
License-Expression: Unlicense
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Requires-Dist: yt-dlp>=2026.2.4
Requires-Dist: yt-dlp-ejs>=0.4.0
Requires-Dist: toml>=0.10.2,<0.11.0
Requires-Dist: structlog>=24.2.0,<25.0.0
Requires-Dist: tenacity>=9.0.0,<10.0.0
Requires-Dist: click>=8.1.7,<9.0.0
Requires-Dist: pathvalidate>=3.0.0,<4.0.0
Requires-Dist: tqdm>=4.66.0,<5.0.0
Requires-Dist: colorama>=0.4.6,<0.5.0
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/htmlgxn/ytdl-archiver
Project-URL: Repository, https://github.com/htmlgxn/ytdl-archiver
Description-Content-Type: text/markdown

# ytdl-archiver

<p align="center">
  <img src="assets/logo.png" alt="ytdl-archiver" width="600">
</p>

Modern Python CLI for archiving YouTube playlists with media-server-friendly sidecar files.

## Dependencies
- Python 3.14+
- [`uv`](https://docs.astral.sh/uv/)
- FFmpeg on `PATH`
- (Recommended) External JavaScript runtime (`deno` or `Node.js`) for full yt-dlp extraction compatibility
- (Recommended) Firefox recommended for cookie extraction
- (Optional) Rust for setup TUI

## Install
Install with uv (recommended):
```bash
uv tool install ytdl-archiver
```

Or with pip:
```bash
pip install ytdl-archiver
```

From source (development):
```bash
git clone https://github.com/htmlgxn/ytdl-archiver.git
cd ytdl-archiver
uv sync
```

## Quick Start

### 1. Run first-time setup
```bash
ytdl-archiver archive
```

If `~/.config/ytdl-archiver/config.toml` is missing, setup runs automatically on non-help commands and generates:
- `~/.config/ytdl-archiver/config.toml`
- `~/.config/ytdl-archiver/playlists.toml`

You can also run setup directly:
```bash
ytdl-archiver init
```

### 2. Define playlists
Edit `~/.config/ytdl-archiver/playlists.toml`:

```toml
[[playlists]]
id = "UUxxxxxxxxxxxxxxxxxxxxxx"
path = "Music/Example Channel"
name = "Example Music Channel"

[playlists.download]
format = "bestaudio"
write_subtitles = false
write_thumbnail = true
```

Notes:
- `[[playlists]]` entries are loaded from the `playlists` array.
- If both `playlists.toml` and `playlists.json` exist in the config directory, TOML is preferred.
- Playlist download overrides accept canonical snake_case keys and yt-dlp-style aliases (for example `write_subtitles` and `writesubtitles`).

### 3. Run archive
```bash
ytdl-archiver archive
```

## Core Commands
```bash
ytdl-archiver --help
ytdl-archiver archive --help
ytdl-archiver convert-playlists --help
ytdl-archiver init --help
```

## Documentation
- Docs index: `docs/index.md`
- CLI reference: `docs/cli.md`
- Configuration reference: `docs/configuration.md`
- Development/contributing: `docs/development.md`
- Migration notes: `MIGRATION.md`
- Terminal output modes: `docs/terminal-output.md`