snagvid 0.1.0__tar.gz

snagvid-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waqas
+
+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.

snagvid-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: snagvid
+Version: 0.1.0
+Summary: Download videos from YouTube, X/Twitter, Instagram, Facebook, or almost any website straight from your terminal.
+Author: Waqas
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/WaqasAhmad313/snagvid
+Project-URL: Repository, https://github.com/WaqasAhmad313/snagvid
+Project-URL: Issues, https://github.com/WaqasAhmad313/snagvid/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp>=2024.1.1
+Requires-Dist: click>=8.1
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.0
+Dynamic: license-file
+
+# snagvid (`vdl`)
+
+Download videos from YouTube, X/Twitter, Instagram, Facebook, or almost any website — straight from your terminal, no browser extensions, no sketchy websites.
+
+[![PyPI version](https://img.shields.io/pypi/v/snagvid.svg)](https://pypi.org/project/snagvid/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+![demo](docs/demo.gif)
+
+## Features
+
+- 🧙 **Interactive CLI Wizard**: Simply type `vdl` to get guided prompts for URL, resolution, and output folder.
+- 📊 **Smart Resolution & Size Detection**: Shows available resolutions with accurate combined video + audio download size estimates.
+- 🎵 **Audio Extraction**: Easily extract high-quality audio tracks (e.g. MP3) directly.
+- 🎨 **Clean Live Progress**: Real-time progress display with speed, ETA, and spinner animations powered by `rich`.
+- 🌐 **1800+ Supported Sites**: Powered by `yt-dlp` for unmatched platform compatibility.
+- ⚡ **Scripting Ready**: Pass URLs and flags directly (`vdl "<url>" -q 720p`) for automation.
+- 🛡️ **Long Title Protection**: Automatic title truncation and ID tagging to prevent filesystem errors on long post captions.
+
+## Prerequisites
+
+- **Python**: 3.9 or higher
+- **FFmpeg**: Required for stream merging and audio extraction.
+  - **Linux**: `sudo apt install ffmpeg` / `sudo pacman -S ffmpeg`
+  - **macOS**: `brew install ffmpeg`
+
+## Installation
+
+```bash
+pip install snagvid
+# or with pipx for isolated global installation:
+pipx install snagvid
+```
+
+### Local Development Install
+
+```bash
+git clone https://github.com/WaqasAhmad313/snagvid.git
+cd snagvid
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+Run `vdl` with no arguments to start the interactive wizard:
+
+```bash
+vdl
+```
+
+### Direct / Scripted Usage
+
+Pass arguments directly to bypass the interactive prompts:
+
+```bash
+# Direct download best quality
+vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+# Download audio-only (MP3)
+vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio
+
+# Download specific quality to custom directory
+vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q 720p -o ~/Videos
+```
+
+### Configuration (`~/.vdlrc`)
+
+You can save your default preferences in `~/.vdlrc` (INI format):
+
+```ini
+[defaults]
+output       = ~/Videos
+quality      = 1080p
+audio_format = mp3
+retries      = 5
+```
+
+## Supported Sites
+
+`vdl` inherits complete extractor support from `yt-dlp`, covering 1800+ websites including YouTube, X/Twitter, Instagram, Facebook, TikTok, Twitch, Reddit, Vimeo, and SoundCloud.
+
+For a full list of supported extractors, see the [yt-dlp supported sites documentation](https://github.com/yt-dlp/yt-dlp/blob/master/supported_sites.md).
+
+## Responsible Use
+
+This tool is intended for downloading content you own, have explicit permission to use, or that is otherwise legally accessible to you — e.g. personal backups, offline access to your own posts, content licensed for reuse. Respect the terms of service of the platform you're downloading from and applicable copyright law. The maintainers are not responsible for misuse.
+
+## Contributing
+
+Contributions are welcome!
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.

snagvid-0.1.0/README.md

@@ -0,0 +1,105 @@
+# snagvid (`vdl`)
+
+Download videos from YouTube, X/Twitter, Instagram, Facebook, or almost any website — straight from your terminal, no browser extensions, no sketchy websites.
+
+[![PyPI version](https://img.shields.io/pypi/v/snagvid.svg)](https://pypi.org/project/snagvid/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+![demo](docs/demo.gif)
+
+## Features
+
+- 🧙 **Interactive CLI Wizard**: Simply type `vdl` to get guided prompts for URL, resolution, and output folder.
+- 📊 **Smart Resolution & Size Detection**: Shows available resolutions with accurate combined video + audio download size estimates.
+- 🎵 **Audio Extraction**: Easily extract high-quality audio tracks (e.g. MP3) directly.
+- 🎨 **Clean Live Progress**: Real-time progress display with speed, ETA, and spinner animations powered by `rich`.
+- 🌐 **1800+ Supported Sites**: Powered by `yt-dlp` for unmatched platform compatibility.
+- ⚡ **Scripting Ready**: Pass URLs and flags directly (`vdl "<url>" -q 720p`) for automation.
+- 🛡️ **Long Title Protection**: Automatic title truncation and ID tagging to prevent filesystem errors on long post captions.
+
+## Prerequisites
+
+- **Python**: 3.9 or higher
+- **FFmpeg**: Required for stream merging and audio extraction.
+  - **Linux**: `sudo apt install ffmpeg` / `sudo pacman -S ffmpeg`
+  - **macOS**: `brew install ffmpeg`
+
+## Installation
+
+```bash
+pip install snagvid
+# or with pipx for isolated global installation:
+pipx install snagvid
+```
+
+### Local Development Install
+
+```bash
+git clone https://github.com/WaqasAhmad313/snagvid.git
+cd snagvid
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+Run `vdl` with no arguments to start the interactive wizard:
+
+```bash
+vdl
+```
+
+### Direct / Scripted Usage
+
+Pass arguments directly to bypass the interactive prompts:
+
+```bash
+# Direct download best quality
+vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+# Download audio-only (MP3)
+vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio
+
+# Download specific quality to custom directory
+vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q 720p -o ~/Videos
+```
+
+### Configuration (`~/.vdlrc`)
+
+You can save your default preferences in `~/.vdlrc` (INI format):
+
+```ini
+[defaults]
+output       = ~/Videos
+quality      = 1080p
+audio_format = mp3
+retries      = 5
+```
+
+## Supported Sites
+
+`vdl` inherits complete extractor support from `yt-dlp`, covering 1800+ websites including YouTube, X/Twitter, Instagram, Facebook, TikTok, Twitch, Reddit, Vimeo, and SoundCloud.
+
+For a full list of supported extractors, see the [yt-dlp supported sites documentation](https://github.com/yt-dlp/yt-dlp/blob/master/supported_sites.md).
+
+## Responsible Use
+
+This tool is intended for downloading content you own, have explicit permission to use, or that is otherwise legally accessible to you — e.g. personal backups, offline access to your own posts, content licensed for reuse. Respect the terms of service of the platform you're downloading from and applicable copyright law. The maintainers are not responsible for misuse.
+
+## Contributing
+
+Contributions are welcome!
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.

snagvid-0.1.0/downloader/__init__.py

@@ -0,0 +1,5 @@
+"""
+snagvid — a yt-dlp wrapper with a clean CLI.
+"""
+
+__version__ = "0.1.0"

snagvid-0.1.0/downloader/cli.py

@@ -0,0 +1,307 @@
+import sys
+from pathlib import Path
+
+import click
+import questionary
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .core import download, download_batch, download_from_file, QUALITY_PRESETS, extract_formats
+from .utils import is_valid_url, list_formats, load_config, RichDownloadProgress
+
+console = Console(highlight=False)
+
+
+# ── vdl-cmd group ─────────────────────────────────────────────────────────────
+
+@click.group(invoke_without_command=True, context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "-V", "--version")
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """vdl -- download videos from YouTube, Twitter/X, and 1800+ other sites."""
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+# ── Shared helpers ─────────────────────────────────────────────────────────────
+
+def _common_options(func):
+    func = click.option("--output",       "-o", default=None, metavar="DIR",   help="Output directory.")(func)
+    func = click.option("--quality",      "-q", default=None, metavar="PRESET", help=f"Quality preset: {', '.join(QUALITY_PRESETS)} or raw yt-dlp selector.")(func)
+    func = click.option("--audio",        "-a", is_flag=True, default=False,   help="Extract audio only.")(func)
+    func = click.option("--audio-format",        default=None, metavar="CODEC", help="Audio codec (mp3, m4a, opus). Default: mp3.")(func)
+    func = click.option("--playlist",     "-p", is_flag=True, default=False,   help="Download entire playlist.")(func)
+    func = click.option("--retries",      "-r", default=None, type=int, metavar="N", help="Retry count on network errors. Default: 3.")(func)
+    func = click.option("--verbose",      "-v", is_flag=True, default=False,   help="Show full error details on failure.")(func)
+    return func
+
+
+def _resolve_opts(cfg, output, quality, audio, audio_format, playlist, retries):
+    return dict(
+        output_dir   = output       or cfg.get("output", "downloads"),
+        quality      = quality      or cfg.get("quality", "best"),
+        audio_only   = audio,
+        audio_format = audio_format or cfg.get("audio_format", "mp3"),
+        playlist     = playlist,
+        retries      = retries if retries is not None else int(cfg.get("retries", 3)),
+    )
+
+
+def _short_error(exc: Exception) -> str:
+    """Return only the first meaningful line of a yt-dlp error message."""
+    msg = str(exc).strip().removeprefix("ERROR: ")
+    return msg.splitlines()[0] if msg else type(exc).__name__
+
+
+def _run_download(url: str, opts: dict, verbose: bool = False) -> None:
+    """
+    Core download routine shared by wizard and flag-based paths.
+    Uses RichDownloadProgress for a polished progress display.
+    Prints ✓ Done on success, ✗ Failed on error.
+    """
+    with RichDownloadProgress() as dp:
+        try:
+            download(
+                url,
+                **opts,
+                hook=dp.progress_hook,
+                postprocessor_hook=dp.postprocessor_hook,
+            )
+        except Exception as exc:
+            console.print(f"\n[bold red]✗ Failed:[/bold red] {_short_error(exc)}")
+            if verbose:
+                console.print_exception(show_locals=False)
+            raise   # caller does sys.exit(1)
+
+    # Progress context has stopped; print the Done message outside it
+    if dp.final_path:
+        final = Path(dp.final_path).resolve()
+        # %(title).80s pads with spaces — strip for display only (file on disk is fine)
+        display_name = final.name.strip()
+        console.print(
+            f"\n[bold green]✓ Done[/bold green] — saved to "
+            f"[cyan]{display_name}[/cyan]"
+        )
+        console.print(f"  [dim]{final}[/dim]")
+    else:
+        console.print("\n[bold green]✓ Done[/bold green]")
+
+
+# ── Interactive wizard ─────────────────────────────────────────────────────────
+
+def _fmt_size(n_bytes) -> str:
+    """Format bytes as ~XMB or ~XKB."""
+    if n_bytes is None:
+        return "?"
+    if n_bytes >= 1_048_576:
+        return f"~{n_bytes / 1_048_576:.0f}MB"
+    return f"~{n_bytes / 1024:.0f}KB"
+
+
+def _build_format_choices(formats: list, duration: float | None = None) -> list:
+    """
+    Build a sorted questionary Choice list from yt-dlp format dicts.
+    - Video formats sorted by height descending, deduplicated by height.
+    - 'Audio only (mp3)' always last.
+    - Choice value: (yt-dlp format selector string, audio_only bool)
+
+    Size = video stream estimate + best audio stream estimate (realistic total).
+    """
+    def _stream_bytes(f: dict) -> float | None:
+        b = f.get("filesize") or f.get("filesize_approx")
+        if b:
+            return float(b)
+        tbr = f.get("tbr")
+        if tbr and duration:
+            return tbr * 1000 / 8 * duration
+        return None
+
+    best_audio_bytes: float | None = None
+    for f in formats:
+        if f.get("vcodec", "none") in ("none", None) and f.get("acodec", "none") not in ("none", None):
+            ab = _stream_bytes(f)
+            if ab and (best_audio_bytes is None or ab > best_audio_bytes):
+                best_audio_bytes = ab
+
+    by_height: dict[int, dict] = {}
+    for f in formats:
+        vcodec = f.get("vcodec", "none")
+        height = f.get("height")
+        if vcodec and vcodec != "none" and height:
+            existing = by_height.get(height)
+            if existing is None or (f.get("tbr") or 0) > (existing.get("tbr") or 0):
+                by_height[height] = f
+
+    choices = []
+    for height in sorted(by_height, reverse=True):
+        f        = by_height[height]
+        ext      = f.get("ext", "mp4")
+        vbytes   = _stream_bytes(f)
+        total    = (vbytes + best_audio_bytes) if (vbytes and best_audio_bytes) else vbytes
+        size_str = _fmt_size(total)
+        label    = f"{height}p  ({ext}, {size_str})"
+        selector = f"bestvideo[height<={height}]+bestaudio/best[height<={height}]"
+        choices.append(questionary.Choice(label, value=(selector, False)))
+
+    choices.append(questionary.Choice("Audio only (mp3)", value=("bestaudio/best", True)))
+    return choices
+
+
+def _print_download_summary(url: str, mode_label: str, out_dir: str) -> None:
+    """Print a rich-formatted summary box before download starts."""
+    console.print()
+    console.rule("[bold]Video Downloader[/bold]")
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="dim", justify="right")
+    grid.add_column()
+    grid.add_row("URL",    f"[cyan]{url}[/cyan]")
+    grid.add_row("Format", mode_label)
+    grid.add_row("Folder", str(Path(out_dir).expanduser().resolve()))
+    console.print(grid)
+    console.print()
+
+
+def _run_wizard(cfg: dict) -> dict | None:
+    """
+    Launch the interactive download wizard.
+    Returns a dict of download kwargs, or None if the user aborted.
+    """
+    # ── Step 1: URL ──────────────────────────────────────────────────────────
+    url = questionary.text("Paste the video URL:").ask()
+    if not url or not url.strip():
+        return None
+    url = url.strip()
+
+    # ── Step 2: Format list ──────────────────────────────────────────────────
+    console.print("  [dim]Fetching available formats…[/dim]")
+    formats, duration = extract_formats(url)
+
+    if formats:
+        choices = _build_format_choices(formats, duration)
+        selection = questionary.select("Choose quality:", choices=choices).ask()
+        if selection is None:
+            return None
+        quality_selector, audio_only = selection
+    else:
+        console.print("  [dim](Format list unavailable — using simplified menu)[/dim]")
+        mode = questionary.select(
+            "Download as:",
+            choices=["Video (best quality)", "Audio only (mp3)"],
+        ).ask()
+        if mode is None:
+            return None
+        audio_only       = mode.startswith("Audio")
+        quality_selector = "bestaudio/best" if audio_only else "best"
+
+    # ── Step 3: Output folder ────────────────────────────────────────────────
+    default_out = cfg.get("output", "downloads")
+    out_dir = questionary.path(
+        "Save to folder:", default=default_out, only_directories=True
+    ).ask()
+    if out_dir is None:
+        return None
+    out_dir = out_dir.strip() or default_out
+
+    # ── Step 4: Rich summary before download ─────────────────────────────────
+    mode_label = "Audio only (mp3)" if audio_only else f"Video  ({quality_selector})"
+    _print_download_summary(url, mode_label, out_dir)
+
+    return dict(
+        url          = url,
+        output_dir   = str(Path(out_dir).expanduser()),
+        quality      = quality_selector,
+        audio_only   = audio_only,
+        audio_format = cfg.get("audio_format", "mp3"),
+        retries      = int(cfg.get("retries", 3)),
+        playlist     = False,
+    )
+
+
+# ── vdl-cmd subcommands ────────────────────────────────────────────────────────
+
+@cli.command("get")
+@click.argument("url")
+@_common_options
+def cmd_get(url, output, quality, audio, audio_format, playlist, retries, verbose):
+    """Download a single video or audio track."""
+    if not is_valid_url(url):
+        console.print(f"[bold red]Error:[/bold red] '{url}' does not look like a valid URL.")
+        sys.exit(1)
+    cfg  = load_config()
+    opts = _resolve_opts(cfg, output, quality, audio, audio_format, playlist, retries)
+    _print_download_summary(url, "Audio only (mp3)" if audio else f"Video ({opts['quality']})", opts["output_dir"])
+    try:
+        _run_download(url, opts, verbose=verbose)
+    except Exception:
+        sys.exit(1)
+
+
+@cli.command("batch")
+@click.argument("urlfile", type=click.Path(exists=True, dir_okay=False))
+@_common_options
+def cmd_batch(urlfile, output, quality, audio, audio_format, playlist, retries, verbose):
+    """Download all URLs listed in URLFILE (one per line)."""
+    cfg  = load_config()
+    opts = _resolve_opts(cfg, output, quality, audio, audio_format, playlist, retries)
+    console.print(f"[bold]Batch downloading from:[/bold] {urlfile}")
+    try:
+        download_from_file(urlfile, **opts)
+    except Exception as exc:
+        console.print(f"[bold red]✗ Failed:[/bold red] {_short_error(exc)}")
+        if verbose:
+            console.print_exception(show_locals=False)
+        sys.exit(1)
+
+
+@cli.command("formats")
+@click.argument("url")
+def cmd_formats(url):
+    """List all available formats for URL (like yt-dlp -F)."""
+    if not is_valid_url(url):
+        console.print(f"[bold red]Error:[/bold red] '{url}' does not look like a valid URL.")
+        sys.exit(1)
+    list_formats(url)
+
+
+# ── vdl <url>  (top-level shortcut — no URL → interactive wizard) ─────────────
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "-V", "--version")
+@click.argument("url", required=False, default=None)
+@_common_options
+def main(url, output, quality, audio, audio_format, playlist, retries, verbose):
+    """Download a video from any supported site.
+
+    \b
+    Run WITHOUT a URL to launch the interactive wizard:
+      vdl
+
+    Run WITH a URL (and optional flags) for scripting:
+      vdl "https://youtu.be/..." -q 720p -o ~/Videos
+    """
+    cfg = load_config()
+
+    # ── Interactive wizard (no URL supplied) ──────────────────────────────────
+    if url is None:
+        wizard_result = _run_wizard(cfg)
+        if wizard_result is None:
+            console.print("[dim]Aborted.[/dim]")
+            sys.exit(0)
+        _url = wizard_result.pop("url")
+        try:
+            _run_download(_url, wizard_result, verbose=verbose)
+        except Exception:
+            sys.exit(1)
+        return
+
+    # ── Flag-based mode (URL supplied) — unchanged for scripting ─────────────
+    if not is_valid_url(url):
+        console.print(f"[bold red]Error:[/bold red] '{url}' does not look like a valid URL.")
+        sys.exit(1)
+    opts = _resolve_opts(cfg, output, quality, audio, audio_format, playlist, retries)
+    _print_download_summary(url, "Audio only (mp3)" if audio else f"Video ({opts['quality']})", opts["output_dir"])
+    try:
+        _run_download(url, opts, verbose=verbose)
+    except Exception:
+        sys.exit(1)

snagvid-0.1.0/downloader/core.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import Callable, List, Optional
+
+import yt_dlp
+
+from .utils import progress_hook
+
+
+def _detect_js_runtimes() -> dict:
+    """
+    Return a yt-dlp ``js_runtimes`` dict of ``{runtime_name: config_dict}``
+    for whatever JS engines are available on this machine.
+    Supported names: node, deno, bun, quickjs  (checked in priority order).
+    """
+    runtimes: dict = {}
+    for name in ("node", "bun", "deno", "quickjs"):
+        path = shutil.which(name)
+        if path:
+            runtimes[name] = {}   # empty config = use discovered binary
+    return runtimes
+
+
+QUALITY_PRESETS: dict[str, str] = {
+    "best":   "bestvideo+bestaudio/best",
+    "1080p":  "bestvideo[height<=1080]+bestaudio/best",
+    "720p":   "bestvideo[height<=720]+bestaudio/best",
+    "480p":   "bestvideo[height<=480]+bestaudio/best",
+    "360p":   "bestvideo[height<=360]+bestaudio/best",
+    "worst":  "worstvideo+worstaudio/worst",
+    "audio":  "bestaudio/best",
+}
+
+
+def _resolve_format(quality: str, audio_only: bool) -> str:
+    if audio_only:
+        return QUALITY_PRESETS["audio"]
+    return QUALITY_PRESETS.get(quality, quality)
+
+
+def extract_formats(url: str) -> tuple[list[dict], float | None]:
+    """
+    Run yt-dlp in info-only mode (no download) and return
+    ``(formats, duration_seconds)`` for *url*.
+
+    ``formats`` is the raw list of yt-dlp format dicts.
+    ``duration`` is the video length in seconds (None if unknown).
+
+    Returns ``([], None)`` if extraction fails or the site does not expose
+    a structured format list.  Callers must always handle the empty-list path.
+    """
+    js_runtimes = _detect_js_runtimes()
+    ydl_opts: dict = {
+        "quiet":             True,
+        "no_warnings":       True,
+        "remote_components": ["ejs:github"],
+    }
+    if js_runtimes:
+        ydl_opts["js_runtimes"] = js_runtimes
+    try:
+        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+            info = ydl.extract_info(url, download=False)
+            if not info:
+                return [], None
+            return info.get("formats", []), info.get("duration")
+    except Exception:
+        return [], None
+
+
+def download(
+    url: str,
+    output_dir: str = "downloads",
+    audio_only: bool = False,
+    audio_format: str = "mp3",
+    quality: str = "best",
+    playlist: bool = False,
+    retries: int = 3,
+    extra_opts: Optional[dict] = None,
+    hook: Optional[Callable] = None,
+    postprocessor_hook: Optional[Callable] = None,
+) -> None:
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+
+    fmt = _resolve_format(quality, audio_only)
+
+    # Auto-detect a JS runtime (node/deno) so yt-dlp can handle YouTube
+    js_runtimes = _detect_js_runtimes()
+
+    ydl_opts: dict = {
+        # Truncate title to 80 chars and append the video ID to avoid collisions.
+        # Facebook/Instagram use the post caption as the title (no separate short
+        # title field), so captions can be 100–300+ chars and include multi-byte
+        # Unicode — easily blowing past the 255-byte filename limit (ENAMETOOLONG /
+        # OSError errno 36).  The ID suffix keeps filenames unique even when two
+        # videos share the first 80 characters of their caption.
+        "outtmpl":            os.path.join(output_dir, "%(title).80s [%(id)s].%(ext)s"),
+        # Belt-and-suspenders: hard-cap the final on-disk filename at 150 bytes
+        # regardless of template expansion (yt-dlp trims the title portion first).
+        "trim_file_name":     150,
+        "format":             fmt,
+        "noplaylist":         not playlist,
+        "continuedl":         True,
+        "retries":            retries,
+        "fragment_retries":   retries,
+        "progress_hooks":     [hook or progress_hook],
+        # Silence yt-dlp's own console output — our rich hooks own the display.
+        "quiet":              True,
+        "no_warnings":        True,
+        "noprogress":         True,
+        # Allow yt-dlp to fetch the EJS challenge solver from GitHub.
+        # This resolves YouTube signature & n-challenge obfuscation warnings.
+        "remote_components":  ["ejs:github"],
+    }
+
+    if js_runtimes:
+        ydl_opts["js_runtimes"] = js_runtimes
+
+    if postprocessor_hook:
+        ydl_opts["postprocessor_hooks"] = [postprocessor_hook]
+
+    if audio_only:
+        ydl_opts["postprocessors"] = [
+            {
+                "key":            "FFmpegExtractAudio",
+                "preferredcodec": audio_format,
+            }
+        ]
+    else:
+        ydl_opts["merge_output_format"] = "mp4"
+
+    if extra_opts:
+        ydl_opts.update(extra_opts)
+
+    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+        ydl.download([url])
+
+
+def download_batch(urls: List[str], **kwargs) -> None:
+    total = len(urls)
+    for idx, url in enumerate(urls, start=1):
+        print(f"\n[{idx}/{total}] {url}")
+        try:
+            download(url, **kwargs)
+        except yt_dlp.utils.DownloadError as exc:
+            print(f"  Failed: {exc}")
+
+
+def download_from_file(filepath: str, **kwargs) -> None:
+    path = Path(filepath)
+    if not path.exists():
+        raise FileNotFoundError(f"URL file not found: {filepath}")
+
+    urls = [
+        line.strip()
+        for line in path.read_text().splitlines()
+        if line.strip() and not line.strip().startswith("#")
+    ]
+
+    if not urls:
+        print("No URLs found in file.")
+        return
+
+    download_batch(urls, **kwargs)

snagvid-0.1.0/downloader/utils.py

@@ -0,0 +1,300 @@
+"""
+utils.py — helpers for progress display, URL validation, format listing.
+"""
+
+import re
+import os
+import sys
+import configparser
+import yt_dlp
+from pathlib import Path
+
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    Progress,
+    ProgressColumn,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    Task,
+)
+from rich.text import Text
+
+
+# ── Legacy plain-text hook (used by test_manual.py and batch mode) ────────────
+
+def progress_hook(d: dict) -> None:
+    """Plain-text yt-dlp progress callback (fallback for non-rich contexts)."""
+    status = d.get("status")
+
+    if status == "downloading":
+        percent    = d.get("_percent_str", "?%").strip()
+        speed      = d.get("_speed_str", "?/s").strip()
+        eta        = d.get("_eta_str", "?s").strip()
+        downloaded = d.get("_downloaded_bytes_str", "").strip()
+        total      = d.get("_total_bytes_str", "") or d.get("_total_bytes_estimate_str", "")
+        total      = total.strip()
+        size_info  = f"{downloaded}/{total}" if total else downloaded
+        sys.stdout.write(f"\r  {percent:>6}  {size_info}  @ {speed}  ETA {eta}   ")
+        sys.stdout.flush()
+
+    elif status == "finished":
+        sys.stdout.write("\n  Done. Post-processing...\n")
+        sys.stdout.flush()
+
+    elif status == "error":
+        sys.stdout.write("\n  Download error.\n")
+        sys.stdout.flush()
+
+
+# ── Rich progress columns ─────────────────────────────────────────────────────
+
+class _ConditionalPercentColumn(TaskProgressColumn):
+    """Percentage column — hidden for indeterminate tasks (total is None)."""
+    def render(self, task: Task) -> Text:  # type: ignore[override]
+        if task.total is None:
+            return Text("")
+        return super().render(task)
+
+
+class _ConditionalSpeedColumn(ProgressColumn):
+    """Speed column — hidden for indeterminate tasks; uses yt-dlp's string."""
+    def render(self, task: Task) -> Text:
+        if task.total is None:
+            return Text("")
+        speed = (task.fields.get("speed") or "").strip()
+        if not speed or "Unknown" in speed:
+            return Text("")
+        return Text(speed, style="bold green")
+
+
+class _ConditionalEtaColumn(ProgressColumn):
+    """ETA column — hidden for indeterminate tasks; uses yt-dlp's string."""
+    def render(self, task: Task) -> Text:
+        if task.total is None:
+            return Text("")
+        eta = (task.fields.get("eta") or "").strip()
+        if not eta or "Unknown" in eta:
+            return Text("")
+        return Text(f"ETA {eta}", style="yellow")
+
+
+# ── Rich download progress context manager ────────────────────────────────────
+
+class RichDownloadProgress:
+    """
+    Context manager that renders a clean Rich progress display for yt-dlp.
+
+    Provides two callbacks to pass into ``core.download()``:
+      - ``.progress_hook``       — replaces the plain-text progress_hook
+      - ``.postprocessor_hook``  — tracks ffmpeg merge / audio-extraction stages
+
+    After the ``with`` block exits, read ``.final_path`` for the absolute path
+    of the saved file (updated by postprocessor_hook so it reflects the final
+    converted file, e.g. the ``.mp3`` not the intermediate ``.webm``).
+
+    Visual layout per task::
+
+        ⠋ Downloading…   ━━━━━━━━━━━━━━━━━━━━  57%  •  3.2MB/s  ETA 0:00:03
+        ⠋ Merging video and audio…  ━━━━━╸━━━━  (pulsing, no %)
+
+    DASH downloads (separate video + audio streams) produce two download bars
+    that each reach 100%; the postprocessor bar is then removed before the
+    Progress stops so the final printed state is clean.
+    """
+
+    def __init__(self) -> None:
+        self.final_path: str | None = None
+        self._task_id: int | None = None
+        self._pp_task_id: int | None = None
+
+        self._progress = Progress(
+            SpinnerColumn(finished_text="[green]✓[/green]"),
+            TextColumn("[bold]{task.description}"),
+            BarColumn(bar_width=38, style="cyan", complete_style="bright_cyan"),
+            _ConditionalPercentColumn(),
+            TextColumn("[dim]•[/dim]"),
+            _ConditionalSpeedColumn(),
+            _ConditionalEtaColumn(),
+            transient=False,
+            console=Console(stderr=False, highlight=False),
+        )
+
+    def __enter__(self) -> "RichDownloadProgress":
+        self._progress.start()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self._progress.stop()
+
+    # ── yt-dlp callbacks ──────────────────────────────────────────────────────
+
+    def progress_hook(self, d: dict) -> None:
+        """yt-dlp progress_hook — updates the download bar.
+
+        Stream labelling:
+          - If the stream has a real video codec (vcodec != 'none') → "Downloading video…"
+          - Otherwise (audio-only DASH stream)                       → "Downloading audio…"
+          - If vcodec info is unavailable (direct-link sites)        → "Downloading…"
+
+        The label is set once when the task is created and preserved on every
+        subsequent update tick (we never pass `description=` during updates).
+        """
+        status = d.get("status")
+
+        if status == "downloading":
+            total      = d.get("total_bytes") or d.get("total_bytes_estimate")
+            downloaded = float(d.get("downloaded_bytes", 0))
+            speed      = (d.get("_speed_str") or "").strip()
+            eta        = (d.get("_eta_str") or "").strip()
+
+            if self._task_id is None:
+                # Determine stream type from info_dict on the FIRST call for this stream
+                info   = d.get("info_dict") or {}
+                vcodec = info.get("vcodec", "")
+                if vcodec and vcodec != "none":
+                    label = "Downloading video…"
+                elif vcodec == "none":
+                    label = "Downloading audio…"
+                else:
+                    label = "Downloading…"          # fallback for sites with muxed streams
+
+                self._task_id    = self._progress.add_task(
+                    label,
+                    total=float(total) if total else 100.0,
+                    speed=speed,
+                    eta=eta,
+                )
+            else:
+                # Update progress only — do NOT pass description so the label is preserved
+                kw: dict = dict(completed=downloaded, speed=speed, eta=eta)
+                if total:
+                    kw["total"] = float(total)
+                self._progress.update(self._task_id, **kw)
+
+        elif status == "finished":
+            if self._task_id is not None:
+                task = self._progress.tasks[self._task_id]
+                self._progress.update(
+                    self._task_id,
+                    completed=task.total or 100.0,
+                    speed="",
+                    eta="",
+                )
+            # Reset so the next DASH stream gets its own fresh bar
+            self._task_id = None
+
+            # Tentative final path — may be overwritten by postprocessor_hook
+            info = d.get("info_dict", {})
+            path = info.get("filepath") or info.get("filename") or d.get("filename", "")
+            if path:
+                self.final_path = path
+
+    def postprocessor_hook(self, d: dict) -> None:
+        """yt-dlp postprocessor_hook — single spinner task for ffmpeg stages.
+
+        yt-dlp fires 'started'/'finished' multiple times for the same logical
+        postprocessor (e.g. ExtractAudio fires twice internally).  We guard with
+        ``if self._pp_task_id is None`` so only ONE task is ever created per
+        download, no matter how many started events arrive.
+
+        Lifecycle:
+          started (first call)  → create spinner task (total=None, animates)
+          started (duplicates)  → no-op (task already exists)
+          finished (any call)   → mark task complete (total=1) → ✓ checkmark
+                                  capture final filepath
+          MoveFiles finished    → update final_path, task already ✓ so no change
+        """
+        status  = d.get("status")
+        pp_name = d.get("postprocessor", "")
+
+        if status == "started":
+            # Determine label from the first meaningful postprocessor we see
+            if "ExtractAudio" in pp_name:
+                label = "Converting to mp3…"
+            elif "Merger" in pp_name:
+                label = "Merging video and audio…"
+            else:
+                return  # ignore MoveFiles, metadata writers, etc.
+
+            # ONLY create the task once — guard against duplicate 'started' events
+            if self._pp_task_id is None:
+                # total=None → Rich renders pulsing indeterminate bar + spinning icon
+                self._pp_task_id = self._progress.add_task(
+                    label,
+                    total=None,
+                    speed="",
+                    eta="",
+                )
+
+        elif status == "finished":
+            if self._pp_task_id is not None:
+                # Mark complete → SpinnerColumn renders the green ✓ checkmark
+                self._progress.update(
+                    self._pp_task_id,
+                    total=1,
+                    completed=1,
+                    speed="",
+                    eta="",
+                )
+                # Remove the task so the final printed state only shows the ✓ rows
+                # from the download phase (keeps the output clean)
+                self._progress.remove_task(self._pp_task_id)
+                self._pp_task_id = None
+
+            # Overwrite with the TRUE final path (e.g. .mp3 after audio extraction,
+            # final location after MoveFiles)
+            info = d.get("info_dict", {})
+            path = info.get("filepath") or info.get("filename") or ""
+            if path:
+                self.final_path = path
+
+
+# ── URL validation ────────────────────────────────────────────────────────────
+
+_URL_RE = re.compile(
+    r"^(https?://)?"
+    r"([a-zA-Z0-9\-]+\.)+[a-zA-Z]{2,}"
+    r"(/[^\s]*)?$",
+    re.IGNORECASE,
+)
+
+
+def is_valid_url(url: str) -> bool:
+    """Return True if *url* looks like a plausible HTTP(S) URL."""
+    return bool(_URL_RE.match(url.strip()))
+
+
+# ── Format listing ────────────────────────────────────────────────────────────
+
+def list_formats(url: str) -> None:
+    """Print all available formats for *url*, mimicking ``yt-dlp -F``."""
+    ydl_opts = {
+        "listformats": True,
+        "quiet": False,
+        "no_warnings": False,
+    }
+    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+        ydl.download([url])
+
+
+# ── Config loader ─────────────────────────────────────────────────────────────
+
+_CONFIG_PATH = Path.home() / ".vdlrc"
+
+
+def load_config() -> dict:
+    """
+    Load ``~/.vdlrc`` (INI format, ``[defaults]`` section).
+    Returns a plain dict; missing keys are absent.
+    """
+    cfg = configparser.ConfigParser()
+    if _CONFIG_PATH.exists():
+        cfg.read(_CONFIG_PATH)
+
+    defaults: dict = {}
+    if cfg.has_section("defaults"):
+        for key, val in cfg.items("defaults"):
+            defaults[key] = os.path.expanduser(val)
+    return defaults

snagvid-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "snagvid"
+version = "0.1.0"
+description = "Download videos from YouTube, X/Twitter, Instagram, Facebook, or almost any website straight from your terminal."
+readme = "README.md"
+authors = [
+    { name = "Waqas" }
+]
+license = "MIT"
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = [
+    "yt-dlp>=2024.1.1",
+    "click>=8.1",
+    "questionary>=2.0",
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/WaqasAhmad313/snagvid"
+Repository = "https://github.com/WaqasAhmad313/snagvid"
+Issues = "https://github.com/WaqasAhmad313/snagvid/issues"
+
+[project.scripts]
+vdl = "downloader.cli:main"
+vdl-cmd = "downloader.cli:cli"
+
+[tool.setuptools.packages.find]
+include = ["downloader*"]

snagvid-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

snagvid-0.1.0/snagvid.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: snagvid
+Version: 0.1.0
+Summary: Download videos from YouTube, X/Twitter, Instagram, Facebook, or almost any website straight from your terminal.
+Author: Waqas
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/WaqasAhmad313/snagvid
+Project-URL: Repository, https://github.com/WaqasAhmad313/snagvid
+Project-URL: Issues, https://github.com/WaqasAhmad313/snagvid/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp>=2024.1.1
+Requires-Dist: click>=8.1
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.0
+Dynamic: license-file
+
+# snagvid (`vdl`)
+
+Download videos from YouTube, X/Twitter, Instagram, Facebook, or almost any website — straight from your terminal, no browser extensions, no sketchy websites.
+
+[![PyPI version](https://img.shields.io/pypi/v/snagvid.svg)](https://pypi.org/project/snagvid/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+![demo](docs/demo.gif)
+
+## Features
+
+- 🧙 **Interactive CLI Wizard**: Simply type `vdl` to get guided prompts for URL, resolution, and output folder.
+- 📊 **Smart Resolution & Size Detection**: Shows available resolutions with accurate combined video + audio download size estimates.
+- 🎵 **Audio Extraction**: Easily extract high-quality audio tracks (e.g. MP3) directly.
+- 🎨 **Clean Live Progress**: Real-time progress display with speed, ETA, and spinner animations powered by `rich`.
+- 🌐 **1800+ Supported Sites**: Powered by `yt-dlp` for unmatched platform compatibility.
+- ⚡ **Scripting Ready**: Pass URLs and flags directly (`vdl "<url>" -q 720p`) for automation.
+- 🛡️ **Long Title Protection**: Automatic title truncation and ID tagging to prevent filesystem errors on long post captions.
+
+## Prerequisites
+
+- **Python**: 3.9 or higher
+- **FFmpeg**: Required for stream merging and audio extraction.
+  - **Linux**: `sudo apt install ffmpeg` / `sudo pacman -S ffmpeg`
+  - **macOS**: `brew install ffmpeg`
+
+## Installation
+
+```bash
+pip install snagvid
+# or with pipx for isolated global installation:
+pipx install snagvid
+```
+
+### Local Development Install
+
+```bash
+git clone https://github.com/WaqasAhmad313/snagvid.git
+cd snagvid
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+Run `vdl` with no arguments to start the interactive wizard:
+
+```bash
+vdl
+```
+
+### Direct / Scripted Usage
+
+Pass arguments directly to bypass the interactive prompts:
+
+```bash
+# Direct download best quality
+vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+# Download audio-only (MP3)
+vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio
+
+# Download specific quality to custom directory
+vdl "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q 720p -o ~/Videos
+```
+
+### Configuration (`~/.vdlrc`)
+
+You can save your default preferences in `~/.vdlrc` (INI format):
+
+```ini
+[defaults]
+output       = ~/Videos
+quality      = 1080p
+audio_format = mp3
+retries      = 5
+```
+
+## Supported Sites
+
+`vdl` inherits complete extractor support from `yt-dlp`, covering 1800+ websites including YouTube, X/Twitter, Instagram, Facebook, TikTok, Twitch, Reddit, Vimeo, and SoundCloud.
+
+For a full list of supported extractors, see the [yt-dlp supported sites documentation](https://github.com/yt-dlp/yt-dlp/blob/master/supported_sites.md).
+
+## Responsible Use
+
+This tool is intended for downloading content you own, have explicit permission to use, or that is otherwise legally accessible to you — e.g. personal backups, offline access to your own posts, content licensed for reuse. Respect the terms of service of the platform you're downloading from and applicable copyright law. The maintainers are not responsible for misuse.
+
+## Contributing
+
+Contributions are welcome!
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.

snagvid-0.1.0/snagvid.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+downloader/__init__.py
+downloader/cli.py
+downloader/core.py
+downloader/utils.py
+snagvid.egg-info/PKG-INFO
+snagvid.egg-info/SOURCES.txt
+snagvid.egg-info/dependency_links.txt
+snagvid.egg-info/entry_points.txt
+snagvid.egg-info/requires.txt
+snagvid.egg-info/top_level.txt

snagvid-0.1.0/snagvid.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

snagvid-0.1.0/snagvid.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+vdl = downloader.cli:main
+vdl-cmd = downloader.cli:cli

snagvid-0.1.0/snagvid.egg-info/requires.txt

@@ -0,0 +1,4 @@
+yt-dlp>=2024.1.1
+click>=8.1
+questionary>=2.0
+rich>=13.0

snagvid-0.1.0/snagvid.egg-info/top_level.txt

@@ -0,0 +1 @@
+downloader