Metadata-Version: 2.4
Name: vidsmith
Version: 1.0.0rc1
Summary: A production-grade, zero-config YouTube media downloader for your terminal.
Project-URL: Homepage, https://github.com/Nagamanikanta2331/VidSmith
Project-URL: Repository, https://github.com/Nagamanikanta2331/VidSmith
Project-URL: Issues, https://github.com/Nagamanikanta2331/VidSmith/issues
Project-URL: Changelog, https://github.com/Nagamanikanta2331/VidSmith/blob/main/CHANGELOG.md
Author-email: Naga Manikanta Nandyala <nagamanikantanandyala@outlook.com>
License-Expression: MIT
License-File: LICENSE
Keywords: audio,cli,download,ffmpeg,subtitles,video,youtube,yt-dlp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: curl-cffi>=0.7.0
Requires-Dist: imageio-ffmpeg>=0.6.0
Requires-Dist: mutagen>=1.47.0
Requires-Dist: rich>=13.7.0
Requires-Dist: webvtt-py>=0.4.6
Requires-Dist: yt-dlp>=2024.1.0
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: tui
Requires-Dist: textual>=0.61.0; extra == 'tui'
Requires-Dist: typer>=0.12.0; extra == 'tui'
Description-Content-Type: text/markdown

# VidSmith

> **🤖 Built by AI — Idea by the Owner**
> This entire project — all source code, tests, UI, and documentation — was developed by an AI coding assistant (Claude). The original idea, product direction, and ownership belong to the repository owner, [Naga Manikanta Nandyala](https://github.com/Nagamanikanta2331).

**A production-grade, zero-config YouTube media downloader for your terminal.**

VidSmith wraps the full power of [yt-dlp](https://github.com/yt-dlp/yt-dlp)
in a polished interactive CLI: paste a URL, press **1**, and get the best
possible file — same stream selection as the official yt-dlp CLI, with
subtitles, chapters, metadata, and cover art embedded automatically.

```text
__     ___     _ ____            _ _   _
\ \   / (_) __| / ___| _ __ ___ (_) |_| |__
 \ \ / /| |/ _` \___ \| '_ ` _ \| | __| '_ \
  \ V / | | (_| |___) | | | | | | | |_| | | |
   \_/  |_|\__,_|____/|_| |_| |_|_|\__|_| |_|
```

[![CI](https://github.com/Nagamanikanta2331/VidSmith/actions/workflows/ci.yml/badge.svg)](https://github.com/Nagamanikanta2331/VidSmith/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/vidsmith)](https://pypi.org/project/vidsmith/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## Features

- ⭐ **Best Download** — one keypress, zero configuration. Selects the exact
  VP9+Opus streams (`313+251/308+251/303+251/302+251`) and merges to MKV
  without transcoding.
- 🎯 **Custom wizards** — quality, container (MP4/MKV/WebM), subtitles, audio
  format, playlists — all through guided multi-step prompts.
- 🎵 **Audio mode** — MP3, M4A, FLAC, Opus, WAV with metadata and cover art.
- 📝 **Transcripts** — download captions and convert to TXT, Markdown, or JSON.
- 💬 **Professional subtitle handling** — many languages at once; failures
  (e.g. HTTP 429) are reported per-language, never fatal.
- 🖼️ **Honest thumbnail embedding** — tells you exactly what each container
  supports instead of failing silently.
- 📊 **Rich progress + summary** — live speed/ETA, then a full report:
  resolution, FPS, HDR, codecs, bitrates, file size, subtitle outcome.
- 🩺 **`vidsmith doctor`** — one command to diagnose your environment.
- ⏯️ **Resume support** — interrupted downloads continue from `.part` files.

### Screenshot

```text
╭──────────────────── ✅ Best Download Complete ────────────────────╮
│                                                                   │
│   Video Name       Survive 30 Days Chained To A Stranger…         │
│   Channel          MrBeast                                        │
│   Container        MKV                                            │
│   Resolution       1920x1080          FPS  30 fps                 │
│   Video Codec      vp9                Video Bitrate  1490 kbps    │
│   Audio Codec      opus               Audio Bitrate  128 kbps     │
│   File Size        406.2 MB           Download Time  2m 43s       │
│                                                                   │
│   ✓ Metadata Embedded                                             │
│   ✓ Thumbnail Embedded                                            │
│      Supported by MKV container                                   │
│   ✓ Resume Supported                                              │
│                                                                   │
│   Primary Subtitle       English                                  │
│   Other Subtitles        23 languages                             │
│   Subtitles Downloaded   24                                       │
╰───────────────────────────────────────────────────────────────────╯
```

---

## Installation

Install directly from GitHub (recommended until the first PyPI release):

```bash
pip install git+https://github.com/Nagamanikanta2331/VidSmith.git
```

Or clone and install from source:

```bash
git clone https://github.com/Nagamanikanta2331/VidSmith.git
cd VidSmith
pip install -e .
```

> **Note**: `pip install vidsmith` will work once the first release is published
> to PyPI. Until then, use one of the commands above.

### Prerequisites
- **Python 3.12+**
- **yt-dlp**: Installed automatically for you when you run the installation command above. No manual installation is required!

### Recommended System Tools
While VidSmith comes with fallbacks, installing these system tools ensures maximum performance and compatibility:

**1. FFmpeg (for media conversion and muxing)**
If not found, VidSmith uses a bundled fallback (`imageio-ffmpeg`), but a native installation is faster and more robust.
- **Windows:** `winget install ffmpeg` (or download from [gyan.dev](https://www.gyan.dev/ffmpeg/builds/))
- **macOS:** `brew install ffmpeg`
- **Linux:** `sudo apt install ffmpeg` (Ubuntu/Debian)

**2. Node.js or Deno (for complex YouTube extractions)**
YouTube occasionally requires executing JavaScript to extract certain video formats.
- **Windows/macOS/Linux:** Download from [Node.js](https://nodejs.org/) or install Deno via `iwr https://deno.land/install.ps1 -useb | iex` (Windows) / `curl -fsSL https://deno.land/install.sh | sh` (macOS/Linux).

Verify your environment:

```bash
vidsmith doctor
```

---

## Quick Start

```bash
vidsmith
```

1. Paste a YouTube URL (video, Shorts, or playlist) and press **Enter**.
2. VidSmith analyses it and shows a menu — option **1** is always
   **⭐ Best Download**.
3. Press **1** + Enter. Done.

A live progress bar tracks the download; a summary panel reports exactly what
you got.

---

## Commands

| Command | Purpose |
|---------|---------|
| `vidsmith` | Launch the interactive app |
| `vidsmith doctor` | Diagnose environment (tools, network, YouTube access) |
| `vidsmith doctor --no-network` | Same, skipping connectivity checks |
| `vidsmith --version` | Print the version |

---

## Modes

### ⭐ Recommended (Best Download)

Zero configuration. Automatically:

| What | How |
|------|-----|
| Video | VP9 preference chain: `313+251/308+251/303+251/302+251`, then `bestvideo+bestaudio` |
| Audio | Best available track (e.g. Opus 128k) |
| Container | MKV — holds any codec, subtitles, chapters, and cover art |
| Subtitles | Manual + auto captions downloaded and embedded |
| Metadata | Title, channel, date, description embedded |
| Chapters | Embedded when the video has them |
| Thumbnail | Embedded as MKV attachment (always visible) |

### Custom video

Guided wizard: output directory → quality (Best/4K/2K/1080p/720p/480p/360p) →
container (MP4/MKV/WebM) → subtitles → confirm.

> Choosing MP4 restricts streams to MP4-compatible codecs for maximum device
> compatibility. Choose MKV for maximum quality.

### Audio

Wizard: format (MP3/M4A/FLAC/Opus/WAV) → bitrate → thumbnail → metadata.

### Transcript

Downloads captions and converts to clean TXT, Markdown, or JSON — with optional
timestamps.

### Subtitles / Thumbnail only

Direct menu actions save subtitle files or the best thumbnail without
downloading media.

---

## Configuration

VidSmith is deliberately zero-config for the common case. Power users can
tune the provider via the `YouTubeProvider(config=...)` API:

| Key | Default | Purpose |
|-----|---------|---------|
| `download_retries` | `3` | Full-download retry attempts |
| `subtitle_sleep_interval` | `1` | Seconds between subtitle requests (429 protection) |
| `ffmpeg_location` | auto | Explicit FFmpeg path |
| `metadata_cache_size` | `16` | Analyzed-URL cache entries |

Persistent user settings (config file) are on the roadmap.

---

## Dependencies

| Package | Role |
|---------|------|
| `yt-dlp` | Extraction and downloading |
| `rich` | Terminal UI |
| `curl_cffi` | Browser impersonation (reduces YouTube rate limiting) |
| `mutagen` | Visible MP4/M4A cover-art atoms |
| `webvtt-py` | Transcript parsing |
| `imageio-ffmpeg` | Bundled FFmpeg fallback |

Optional (auto-detected, recommended):

- **Deno** or **Node.js** — JS runtime for full YouTube format parity
- **AtomicParsley** — alternative MP4 cover-art writer

---

## Troubleshooting

**Run `vidsmith doctor` first.** It diagnoses nearly every common problem.

| Symptom | Cause & fix |
|---------|-------------|
| "Impersonation … not available" | `pip install curl_cffi` |
| Thumbnail invisible in Windows Explorer (MP4/M4A) | `pip install mutagen` — or use MKV. Windows Explorer ignores ffmpeg's `attached_pic`; VLC/MediaInfo show it. |
| HTTP 429 on subtitles | YouTube rate limiting. VidSmith throttles and continues; failed languages are listed in the summary. Retry later for missing ones. |
| "Some formats may be missing" | Install [Deno](https://deno.com) (or Node.js). |
| Download smaller than other tools | Modern codecs such as VP9 give the same quality in half the size of H.264. Compare resolution/codec, not bytes. |
| Interrupted download | Rerun the same download — it resumes from `.part`. |

## FAQ

**Why MKV by default?**
It's the only mainstream container that holds any codec plus subtitles,
chapters, and cover art without re-encoding — and it's what
`yt-dlp --merge-output-format mkv` produces. Choose MP4 in the custom wizard if
a device requires it.

**Is quality identical to yt-dlp?**
Best Download intentionally prefers VP9+Opus before falling back to yt-dlp's
generic bestvideo+bestaudio selector. Custom MKV downloads still use the normal
yt-dlp-style best selector.

**Does it re-encode?**
No. Streams are merged, never transcoded (except explicit audio-format
conversion in Audio mode).

**Playlists?**
Yes — Best Download and the custom wizard both support playlists with
per-item progress and failure reporting.

---

## Roadmap

- Persistent settings file (`~/.config/vidsmith/`)
- Subtitle/thumbnail embedding options in the custom wizard
- Non-interactive one-shot mode (`vidsmith <url> --best`)
- Textual full-screen TUI
- Additional providers behind the existing `Provider` ABC

---

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup,
quality gates, and PR guidelines. Please note the
[Code of Conduct](CODE_OF_CONDUCT.md).

```bash
pip install -e ".[dev]"
pre-commit install
pytest
```

## License

[MIT](LICENSE) © Naga Manikanta Nandyala

---

*VidSmith is an independent project built on yt-dlp. Download only content
you are authorized to access.*
