vidsmith 1.0.0rc1__tar.gz

vidsmith-1.0.0rc1/.gitignore

@@ -0,0 +1,85 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+downloads/
+out/
+tmp/
+*.egg-info/
+*.egg
+wheels/
+.installed.cfg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+.env
+.env.*
+
+# Test / coverage / caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+
+# Editors / IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# AI assistant local state
+.claude/
+
+# OS noise
+.DS_Store
+Thumbs.db
+
+# VidSmith output artifacts (downloaded media should never be committed)
+*.mp4
+*.mkv
+*.webm
+*.m4a
+*.mp3
+*.opus
+*.flac
+*.wav
+*.vtt
+*.srt
+*.webp
+*.part
+*.ytdl
+*.jpg
+*.jpeg
+*.png
+
+# VidSmith logs (vidsmith.log and rotations)
+*.log
+
+# Local debug / scratch dumps (never committed)
+out2/
+rick.json
+test_dump.json
+yt_dlp_output.json
+thumb_test_opts.json
+ydl_init.txt
+ytdlp_help.txt
+scratch/
+test_*/
+thumb_test/
+regression/
+*.txt

vidsmith-1.0.0rc1/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [Unreleased]
+
+### Changed
+- **Project renamed: MediaForge → VidSmith.** The previous name collided with an existing PyPI package. The distribution, import package (`vidsmith`), and terminal command (`vidsmith`) are all renamed; the on-screen logo and product name are rebranded. Functionality and behavior are unchanged.
+- Settings are now stored under the `VidSmith` config directory. Existing settings from a previous MediaForge install are automatically copied over on first launch — no reconfiguration needed.
+- Debug logs now write to `vidsmith.log` in the `VidSmith` config directory.
+- Repository moved to [Nagamanikanta2331/VidSmith](https://github.com/Nagamanikanta2331/VidSmith); all project links updated.
+
+### Fixed
+- Fixed an intermittent `UnicodeDecodeError` (`'charmap' codec can't decode byte …`) on Windows during post-download validation. Subprocess output from ffmpeg/ffprobe was being decoded with the legacy ANSI codepage (cp1252) instead of UTF-8, crashing the reader thread when video metadata contained non-ASCII characters (e.g. Hindi titles, fullwidth `｜`, emoji). All captured-output subprocess calls now decode as UTF-8 with `errors="replace"`.
+
+## [1.0.0-rc1] - 2026-07-15
+
+VidSmith has reached its first Release Candidate! This release finalizes the core architectural refactoring and prepares the project for broader real-world testing.
+
+### Added
+- **Validation Pipeline**: Hardened the post-download validation architecture with an immutable `ValidationContext` and single-pass FFprobe inspection.
+- **Windows Compatibility QA**: Introduced deterministic regression dataset generation via FFmpeg to systematically test Windows Explorer compatibility.
+- **Documentation**: Added `WINDOWS_COMPATIBILITY.md`, `QA_CHECKLIST.md`, and `RELEASE_CHECKLIST.md` for standardized manual QA testing prior to releases.
+
+### Changed
+- **Audio Output & Validation**: Decoupled thumbnail generation and metadata tagging to support dynamic, safe embedding for `MP3`, `M4A`, and `FLAC` with full graceful degradation when codecs are missing.
+- **Cleanup Routine**: Strengthened cleanup workflows (`test_cleanup_e2e`) to ensure temporary files (`.part`, `.webp`, `.vtt`) are accurately purged without jeopardizing the final embedded payload.
+- **Subtitle and Transcript Pipelines**: Standardized subtitle download logic to perfectly integrate into the main yt-dlp job structure, guaranteeing consistent retry handling and format fallback.
+- **Transcript UX**: Improved the transcript extraction workflow to gracefully notify the user and restart the wizard if a selected language is unavailable, preventing abrupt exits.
+- **Documentation**: Updated `README.md` with explicit, platform-specific installation instructions for FFmpeg and Node.js/Deno, and clarified that `yt-dlp` is automatically installed.
+
+### Fixed
+- Fixed issues where ffmpeg crashes would improperly halt the entire validation pipeline instead of degrading gracefully.
+- Removed duplicate artifacts and simplified execution paths across `YouTubeProvider`.
+- Suppressed duplicate metadata injection processes.
+- Fixed a critical `TypeError` string/int comparison bug in Best Download and Custom Video formats filtering.
+
+VidSmith is now feature-complete for its 1.0.0 milestone. Future updates in the RC phase will focus solely on packaging, bug fixes, and optimization.

vidsmith-1.0.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naga Manikanta Nandyala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vidsmith-1.0.0rc1/PKG-INFO

@@ -0,0 +1,327 @@
+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.*