Metadata-Version: 2.5
Name: yt-dlp-tui
Version: 0.1.2
Summary: A Textual client for an independently updateable yt-dlp engine.
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: textual>=3.0
Description-Content-Type: text/markdown

# yt-dlp TUI

[中文文档](README.zh-CN.md)

[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![Textual](https://img.shields.io/badge/TUI-Textual-5C2D91)](https://textual.textualize.io/)

A terminal user interface for `yt-dlp` built with [Textual](https://textual.textualize.io/). It provides format inspection, playlist item selection, download progress, persistent history, resumable interrupted downloads, and independently managed `yt-dlp` and FFmpeg binaries.

> This project is not affiliated with yt-dlp. Please use it only for content you are permitted to download.

## Screenshots

### Start a download

![Start page with URL input, output directory, format list, and sidebar navigation](https://raw.githubusercontent.com/z4none/yt-dlp-tui/main/assets/screenshots/main.png)

### Inspect a playlist

![Playlist inspect view with selectable items and queue controls](https://raw.githubusercontent.com/z4none/yt-dlp-tui/main/assets/screenshots/playlist.png)

### Track downloads

![Downloading page with task progress, speed, ETA, and raw yt-dlp output](https://raw.githubusercontent.com/z4none/yt-dlp-tui/main/assets/screenshots/downloading.png)

### Configure the download engine

![Settings page with download directory, proxy, yt-dlp, and FFmpeg controls](https://raw.githubusercontent.com/z4none/yt-dlp-tui/main/assets/screenshots/settings.png)

## Features

- Inspect video and playlist URLs before downloading.
- Select playlist items before queueing them, while single videos still use format selection.
- Choose from available yt-dlp format IDs.
- Automatically add the best available audio stream to video-only formats and merge with FFmpeg.
- Show active downloads with a text progress bar, speed, ETA, and live yt-dlp output.
- Persist completed, failed, and interrupted tasks in per-user JSON history.
- Resume interrupted tasks with yt-dlp's `--continue` support.
- Open a completed file, reveal it in the system file manager, or copy its path.
- Install and update yt-dlp independently from the TUI application.
- Install FFmpeg from GitHub on Windows.
- Use an optional HTTP(S) proxy for engine installation, update checks, metadata extraction, and downloads.

## Requirements

- Python 3.11 or newer
- [uv](https://docs.astral.sh/uv/) for development or local installation
- Windows is the primary supported platform at present. FFmpeg auto-install currently targets Windows x64.

## Installation

### Run with uvx (recommended)

Run the latest published version without installing it permanently:

```powershell
uvx yt-dlp-tui
```

### From PyPI

```powershell
pip install yt-dlp-tui
yt-dlp-tui
```

### From source

```powershell
git clone https://github.com/z4none/yt-dlp-tui.git
cd yt-dlp-tui
uv sync --all-groups
uv run yt-dlp-tui
```

## Quick start

1. Open **Settings** from the sidebar.
2. Set the default download directory and, if needed, an HTTP(S) proxy.
3. Install yt-dlp from GitHub. The app checks the selected `stable` or `nightly` channel in the background and offers an update when one is available.
4. Install FFmpeg from GitHub to merge separate video and audio streams automatically.
5. Open **Start**, paste a URL, inspect formats, select one, and begin downloading.

## Notes on downloads

- A video-only format requires FFmpeg to merge it with audio. The app automatically selects `FORMAT_ID+bestaudio/best` when appropriate.
- The **Downloading** page includes raw yt-dlp output. Task logs are also written to the application's per-user data directory.
- Interrupted downloads are marked as failed after restart, but can be resumed from **Completed**.

## Development

```powershell
uv sync --all-groups
uv run ruff check .
uv run pytest -q
uv run yt-dlp-tui
```

## Build and publish

```powershell
uv build
uv publish --publish-url https://upload.pypi.org/legacy/
```

Use a PyPI API token through `UV_PUBLISH_TOKEN`; never commit publishing credentials.

## License

Distributed under the [MIT License](LICENSE).
