yt-aug 0.1.0__tar.gz

yt_aug-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: yt-aug
+Version: 0.1.0
+Summary: YouTube Music Manager CLI
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.25.0
+Requires-Dist: yt-dlp>=2026.3.17
+Requires-Dist: yt-dlp-ejs>=0.8.0
+
+# yt-aug — YouTube Augment
+
+Download audio from YouTube videos and playlists — from the command line.
+
+## Install
+
+```bash
+pip install yt-aug
+```
+
+Requires Python 3.13+.
+
+## System Requirements
+
+yt-aug uses `yt-dlp` under the hood, which needs the following installed on your machine:
+
+| Binary | Purpose | Windows | macOS | Linux |
+|--------|---------|---------|-------|-------|
+| `ffmpeg` | Audio extraction/conversion | `winget install ffmpeg` | `brew install ffmpeg` | `sudo apt install ffmpeg` |
+| `deno` or `node` (≥ 20) | JS runtime for YouTube challenge solving | `winget install deno` | `brew install deno` | `curl -fsSL https://deno.land/install.sh \| sh` |
+
+## Usage
+
+### `download <url>`
+
+Downloads audio from a YouTube video or playlist. Extracts best available audio and converts to m4a at 192kbps via FFmpeg.
+
+```bash
+ytaug download "https://youtube.com/watch?v=..." -o ~/Music
+ytaug download "https://youtube.com/playlist?list=PL..." -o ~/Music
+ytaug download "https://music.youtube.com/playlist?list=PL..."
+```
+
+Before downloading, ytaug will:
+1. Check for a JS runtime and ffmpeg
+2. Fetch the URL metadata (title, type, track count for playlists)
+3. Ask for confirmation
+
+For playlists, files are organized into a subfolder named after the playlist.
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--output` | `-o` | Output directory (default: current directory) |
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run unit tests only
+uv run pytest tests/unit
+
+# Run integration tests only (requires JS runtime + ffmpeg + network)
+uv run pytest tests/integration -m integration
+```
+
+## Architecture
+
+```
+src/ytaug/
+├── main.py         Typer CLI entry point (orchestration + user I/O)
+├── download.py     yt-dlp wrapper (system checks, URL validation, metadata, downloads)
+└── exceptions.py   YTAugError hierarchy
+```
+
+- `main.py` handles all CLI interaction (prompts, messages, exits)
+- `download.py` is pure logic with no console output
+- All library functions raise `YTAugError` subclasses on operational failure

yt_aug-0.1.0/README.md

@@ -0,0 +1,72 @@
+# yt-aug — YouTube Augment
+
+Download audio from YouTube videos and playlists — from the command line.
+
+## Install
+
+```bash
+pip install yt-aug
+```
+
+Requires Python 3.13+.
+
+## System Requirements
+
+yt-aug uses `yt-dlp` under the hood, which needs the following installed on your machine:
+
+| Binary | Purpose | Windows | macOS | Linux |
+|--------|---------|---------|-------|-------|
+| `ffmpeg` | Audio extraction/conversion | `winget install ffmpeg` | `brew install ffmpeg` | `sudo apt install ffmpeg` |
+| `deno` or `node` (≥ 20) | JS runtime for YouTube challenge solving | `winget install deno` | `brew install deno` | `curl -fsSL https://deno.land/install.sh \| sh` |
+
+## Usage
+
+### `download <url>`
+
+Downloads audio from a YouTube video or playlist. Extracts best available audio and converts to m4a at 192kbps via FFmpeg.
+
+```bash
+ytaug download "https://youtube.com/watch?v=..." -o ~/Music
+ytaug download "https://youtube.com/playlist?list=PL..." -o ~/Music
+ytaug download "https://music.youtube.com/playlist?list=PL..."
+```
+
+Before downloading, ytaug will:
+1. Check for a JS runtime and ffmpeg
+2. Fetch the URL metadata (title, type, track count for playlists)
+3. Ask for confirmation
+
+For playlists, files are organized into a subfolder named after the playlist.
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--output` | `-o` | Output directory (default: current directory) |
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run unit tests only
+uv run pytest tests/unit
+
+# Run integration tests only (requires JS runtime + ffmpeg + network)
+uv run pytest tests/integration -m integration
+```
+
+## Architecture
+
+```
+src/ytaug/
+├── main.py         Typer CLI entry point (orchestration + user I/O)
+├── download.py     yt-dlp wrapper (system checks, URL validation, metadata, downloads)
+└── exceptions.py   YTAugError hierarchy
+```
+
+- `main.py` handles all CLI interaction (prompts, messages, exits)
+- `download.py` is pure logic with no console output
+- All library functions raise `YTAugError` subclasses on operational failure

yt_aug-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "yt-aug"
+version = "0.1.0"
+description = "YouTube Music Manager CLI"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "typer>=0.25.0",
+    "yt-dlp>=2026.3.17",
+    "yt-dlp-ejs>=0.8.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-mock>=3.15.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+  "unit: Quick logic tests that require zero external tools.",
+  "integration: Real runtime environment or platform binary execution tests.",
+  "local_only: Tests that should only be run on local machine."
+]
+
+[project.scripts]
+ytaug = "ytaug.main:app"

yt_aug-0.1.0/setup.cfg

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

yt_aug-0.1.0/src/yt_aug.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: yt-aug
+Version: 0.1.0
+Summary: YouTube Music Manager CLI
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.25.0
+Requires-Dist: yt-dlp>=2026.3.17
+Requires-Dist: yt-dlp-ejs>=0.8.0
+
+# yt-aug — YouTube Augment
+
+Download audio from YouTube videos and playlists — from the command line.
+
+## Install
+
+```bash
+pip install yt-aug
+```
+
+Requires Python 3.13+.
+
+## System Requirements
+
+yt-aug uses `yt-dlp` under the hood, which needs the following installed on your machine:
+
+| Binary | Purpose | Windows | macOS | Linux |
+|--------|---------|---------|-------|-------|
+| `ffmpeg` | Audio extraction/conversion | `winget install ffmpeg` | `brew install ffmpeg` | `sudo apt install ffmpeg` |
+| `deno` or `node` (≥ 20) | JS runtime for YouTube challenge solving | `winget install deno` | `brew install deno` | `curl -fsSL https://deno.land/install.sh \| sh` |
+
+## Usage
+
+### `download <url>`
+
+Downloads audio from a YouTube video or playlist. Extracts best available audio and converts to m4a at 192kbps via FFmpeg.
+
+```bash
+ytaug download "https://youtube.com/watch?v=..." -o ~/Music
+ytaug download "https://youtube.com/playlist?list=PL..." -o ~/Music
+ytaug download "https://music.youtube.com/playlist?list=PL..."
+```
+
+Before downloading, ytaug will:
+1. Check for a JS runtime and ffmpeg
+2. Fetch the URL metadata (title, type, track count for playlists)
+3. Ask for confirmation
+
+For playlists, files are organized into a subfolder named after the playlist.
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--output` | `-o` | Output directory (default: current directory) |
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run unit tests only
+uv run pytest tests/unit
+
+# Run integration tests only (requires JS runtime + ffmpeg + network)
+uv run pytest tests/integration -m integration
+```
+
+## Architecture
+
+```
+src/ytaug/
+├── main.py         Typer CLI entry point (orchestration + user I/O)
+├── download.py     yt-dlp wrapper (system checks, URL validation, metadata, downloads)
+└── exceptions.py   YTAugError hierarchy
+```
+
+- `main.py` handles all CLI interaction (prompts, messages, exits)
+- `download.py` is pure logic with no console output
+- All library functions raise `YTAugError` subclasses on operational failure

yt_aug-0.1.0/src/yt_aug.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/yt_aug.egg-info/PKG-INFO
+src/yt_aug.egg-info/SOURCES.txt
+src/yt_aug.egg-info/dependency_links.txt
+src/yt_aug.egg-info/entry_points.txt
+src/yt_aug.egg-info/requires.txt
+src/yt_aug.egg-info/top_level.txt
+src/ytaug/__init__.py
+src/ytaug/download.py
+src/ytaug/exceptions.py
+src/ytaug/main.py

yt_aug-0.1.0/src/yt_aug.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

yt_aug-0.1.0/src/yt_aug.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ytaug = ytaug.main:app

yt_aug-0.1.0/src/yt_aug.egg-info/requires.txt

@@ -0,0 +1,3 @@
+typer>=0.25.0
+yt-dlp>=2026.3.17
+yt-dlp-ejs>=0.8.0

yt_aug-0.1.0/src/yt_aug.egg-info/top_level.txt

@@ -0,0 +1 @@
+ytaug

yt_aug-0.1.0/src/ytaug/download.py

@@ -0,0 +1,177 @@
+import shutil
+import platform
+import yt_dlp
+import urllib
+from pathlib import Path
+from ytaug.exceptions import YTAugError
+
+# TODO: handle playlist does not exist:"https://www.youtube.com/playlist?list=PLwivhteH3vK_S0yV2w3gCh_zM-2S_3N-Z"
+# TODO: handle no internet connection error
+# TODO: handle private video/playlist error
+# TODO: raise custom error for only expected errors
+
+
+def has_ffmpeg() -> bool:
+    return shutil.which("ffmpeg") is not None
+
+
+def get_ffmpeg_install_instructions() -> str:
+    os_name = platform.system()
+    instructions = {
+        "Windows": "winget install ffmpeg \nor check their website: https://ffmpeg.org",
+        "Darwin": "brew install ffmpeg \nor check their website: https://ffmpeg.org",
+        "Linux": "sudo apt install ffmpeg (Debian/Ubuntu) \nor sudo dnf install ffmpeg (Fedora) \nor check their website: https://ffmpeg.org",
+    }
+    return instructions.get(
+        os_name, "check their website for download instructions \nhttps://ffmpeg.org"
+    )
+
+
+def has_js_runtime() -> bool:
+    """
+    Checks for available JS runtimes in order of preference.
+
+    Returns:
+        True if at least one runtime is available, False otherwise.
+    """
+    for runtime in ("deno", "node"):
+        full_path = shutil.which(runtime)
+        if full_path:
+            return True
+    return False
+
+
+def get_ytdlp_js_runtime_config() -> dict:
+    """
+    Returns a yt-dlp js_runtimes config dict with all found JS runtimes.
+
+    Returns:
+        dict in js_runtimes format, e.g. {"deno": {"path": "/usr/bin/deno"}}.
+        Empty dict if no runtime found.
+    """
+    config = {}
+    for runtime in ("deno", "node"):
+        path = shutil.which(runtime)
+        if path:
+            config[runtime] = {"path": path}
+    return config
+
+
+def get_js_runtime_install_instructions() -> str:
+    os_name = platform.system()
+    instructions = {
+        "Windows": "winget install deno  OR  winget install OpenJS.NodeJS \nor check their website: \nhttps://deno.com OR https://nodejs.org",
+        "Darwin": "brew install deno  OR  brew install node \nor check their website: \nhttps://deno.com OR https://nodejs.org",
+        "Linux": "curl -fsSL https://deno.land/install.sh | sh  OR  See https://nodejs.org/en/download/package-manager \nor check their website: \nhttps://deno.com OR https://nodejs.org",
+    }
+    return instructions.get(
+        os_name,
+        "check their website for download instructions \nhttps://deno.com OR  See https://nodejs.org",
+    )
+
+
+def is_youtube_url(url: str | None) -> bool:
+    if not url:
+        return False
+
+    try:
+        parsed = urllib.parse.urlparse(url)
+    except Exception:
+        return False
+
+    domain = parsed.netloc or parsed.path.split("/")[0]
+    domain = domain.lower()
+    domain = domain.removeprefix("www.")
+
+    return domain in ("youtube.com", "m.youtube.com", "music.youtube.com", "youtu.be")
+
+
+def get_url_info_ytdlp(url: str, js_runtime_config: dict) -> dict:
+    """
+    runtime: {"path": full_path}}
+    """
+
+    # dummy logger class to pass yt_dlp's logger so that it doesnt log anything to terminal
+    class _NullLogger:
+        def debug(self, msg):
+            pass
+
+        def info(self, msg):
+            pass
+
+        def warning(self, msg):
+            pass
+
+        def error(self, msg):
+            pass
+
+    ydl_opts = {
+        "quiet": True,
+        "no_warnings": True,
+        "extract_flat": True,
+        "js_runtimes": js_runtime_config,
+        "logger": _NullLogger(),
+    }
+
+    try:
+        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+            info = ydl.extract_info(url, download=False)
+
+    except yt_dlp.utils.DownloadError as e:
+        if "Error 400" in str(e):
+            raise YTAugError("Provided video/playlist URL does not exist on youtube")
+
+        # if its not Error 400:
+        raise Exception("Unexpected error in get_url_info_ytdlp") from e
+
+    url_info = {
+        "type": info.get("_type"),
+        "title": info.get("title"),
+        "id": info.get("id"),
+    }
+    if (url_info.get("type")) == "playlist":
+        url_info["video_count"] = info.get("playlist_count")
+
+    return url_info
+
+
+def download_url_ytdlp(
+    url: str, target_path: Path, is_playlist: bool, js_runtime_config: dict
+) -> None:
+    ydl_opts = {
+        # "quiet": True,
+        "format": "bestaudio/best",
+        "outtmpl": str(target_path / "%(title)s.%(ext)s"),
+        "js_runtimes": js_runtime_config,
+        "postprocessors": [
+            {
+                "key": "FFmpegExtractAudio",
+                "preferredcodec": "m4a",
+                "preferredquality": "192",
+            }
+        ],
+    }
+    if is_playlist:
+        ydl_opts["outtmpl"] = str(
+            target_path / "%(playlist_title)s" / "%(title)s.%(ext)s"
+        )
+
+    try:
+        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+            ydl.download([url])
+    except Exception as e:
+        raise Exception("Unexpected error in download_url_ytdlp") from e
+
+
+if __name__ == "__main__":
+    ydl_opts = {
+        "quiet": True,
+        "no_warnings": True,
+        "extract_flat": True,
+        "js_runtimes": get_ytdlp_js_runtime_config,
+    }
+    url = None
+
+    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+        info = ydl.extract_info(url, download=False)
+        print(info)

yt_aug-0.1.0/src/ytaug/exceptions.py

@@ -0,0 +1,6 @@
+class YTAugError(Exception):
+    """Base exception for all ytaug errors."""
+
+
+class SystemRequirementError(YTAugError):
+    """Missing system dependencies (ffmpeg, JS runtime)."""

yt_aug-0.1.0/src/ytaug/main.py

@@ -0,0 +1,86 @@
+import typer
+import traceback
+from typing import Annotated
+from pathlib import Path
+
+from ytaug.download import (
+    has_ffmpeg,
+    get_ffmpeg_install_instructions,
+    has_js_runtime,
+    get_js_runtime_install_instructions,
+    get_ytdlp_js_runtime_config,
+    get_url_info_ytdlp,
+    download_url_ytdlp,
+    is_youtube_url,
+)
+from ytaug.exceptions import YTAugError
+
+# TODO: save unhandled exceptions in log
+# TODO: print traceback of all errors except custom errors
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.command(help="Download audio from a YouTube playlist as m4a (192kbps)")
+def download(
+    url: Annotated[str, typer.Argument(help="YouTube video or playlist URL")],
+    output: Annotated[
+        Path,
+        typer.Option("--output", "-o", help="Output directory for downloaded files"),
+    ] = Path.cwd(),
+):
+    # check ffmpeg, js runtime and valid youtbe url
+    if not has_js_runtime():
+        typer.echo(
+            "A JavaScript runtime (deno or node) is required but not found on your system."
+        )
+        typer.echo(get_js_runtime_install_instructions())
+        raise typer.Exit(1)
+
+    if not has_ffmpeg():
+        typer.echo("ffmpeg is required but not found on your system.")
+        typer.echo(get_ffmpeg_install_instructions())
+        raise typer.Exit(1)
+
+    if not is_youtube_url(url):
+        typer.echo("Provided URL is not a valid youtube domain's URL")
+        raise typer.Exit(1)
+
+    try:
+        # confirm info of video/playlist and download location
+        info = get_url_info_ytdlp(
+            url=url, js_runtime_config=get_ytdlp_js_runtime_config()
+        )
+
+        if info["type"] == "playlist":
+            dest = Path(output, info["title"])
+            confirm = typer.confirm(
+                f'Download playlist: "{info["title"]}" ({info["video_count"]} tracks) → {dest}'
+            )
+        else:
+            confirm = typer.confirm(f'Download video: "{info["title"]}" → {output}')
+        if not confirm:
+            typer.echo("Download cancelled.")
+            raise typer.Exit(0)
+
+        # download the files
+
+        download_url_ytdlp(
+            url=url,
+            target_path=output,
+            is_playlist=info["type"] == "playlist",
+            js_runtime_config=get_ytdlp_js_runtime_config(),
+        )
+        typer.echo("Download complete.")
+
+    except typer.Exit:
+        raise
+    except YTAugError as e:
+        typer.echo(f"App error: {e}")
+    except Exception as e:
+        typer.echo(traceback.print_exception(e))
+        typer.echo(f"Uncaught Exception: {e}")
+
+
+if __name__ == "__main__":
+    app()