ytfetch 1.0.0__tar.gz

ytfetch-1.0.0/.github/workflows/publish.yaml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    name: Build and upload to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tool
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

ytfetch-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+.vscode/
+ytfetch-env/
+__pycache__/
+dist/

ytfetch-1.0.0/LICENSE

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

ytfetch-1.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: ytfetch
+Version: 1.0.0
+Summary: A wrapper for yt-dlp with custom simple fetching flags
+Project-URL: Homepage, https://github.com/voidsnax/reVidx
+Author: voidsnax
+License: MIT
+License-File: LICENSE
+Keywords: converter,h264,mp3,playlist,youtubedownloader
+Requires-Python: >=3.8
+Requires-Dist: colorama
+Requires-Dist: yt-dlp>=2025.12.08
+Description-Content-Type: text/markdown
+
+# ytfetch
+
+**ytfetch** simplifies media downloading and playlist management by adding "Smart Fetching,"playlist searching, and streamlined format handling on top of the powerful [yt-dlp](https://github.com/yt-dlp/yt-dlp) engine.
+
+## ✨ Features
+
+* **Smart Fetching:** Apply limits to multiple playlists or map specific ranges in a single download.
+* **Search:** Use `-list` to display or search across single or multiple playlists contents.
+* **Direct Download:** Single flag to download in legacy `avc/h.264` and `mp3` format and audio only extraction.
+* **Video Quality:** Mention preffered video quality directly.
+* **Native Compatibility:** Can also pass through any `yt-dlp` flag.
+* **Minimal Output logs:** Clean and minimal logs.
+
+## 📋 Requirements
+
+- [Python](https://www.python.org/): 3.8 or higher.
+- [FFmpeg](https://ffmpeg.org/) and [FFprobe](https://ffmpeg.org/ffprobe.html): Should available in your system PATH.
+Download builds from [here](https://ffmpeg.org/download.html)
+
+    <details>
+    <summary>or</summary>
+
+    - On Windows:
+        ```bash
+        winget install BtbN.FFmpeg.GPL
+        ```
+        or
+        ```bash
+        winget install Gyan.FFmpeg
+        ```
+
+    - On Termux (android):
+        ```bash
+        pkg install ffmpeg
+        ```
+
+    - On Mac (using Homebrew):
+        ```bash
+        brew install ffmpeg
+        ```
+
+    - On Arch Linux:
+        ```bash
+        sudo pacman -S ffmpeg
+        ```
+
+    - On Ubuntu/Debian:
+        ```bash
+        sudo apt install ffmpeg
+        ```
+    </details>
+- [Deno](https://deno.com/): Or other JavaScript runtime/engine like [node.js](https://nodejs.org/en) or [bun](https://bun.sh/)
+
+  Check this [guide](https://github.com/yt-dlp/yt-dlp/wiki/EJS) for more info.
+
+
+## 📦 Installation
+
+### via pip
+
+```bash
+pip install ytfetch
+```
+
+### via source
+```bash
+git clone <your-repo-url>
+cd <your-repo>
+pip install -e .
+```
+
+## 🚀 Usage
+
+### General Syntax and Options
+
+```text
+usage: Usage: ytfetch [yt-dlp OPTIONS] URL ... [OPTIONS]
+
+options:
+  -h                         Show this help message and exit.
+  -help                      Show yt-dlp help message.
+  -avcmp3                    Download video in AVC (h.264) format (mp4) + extract audio
+  -q QUALITY                 Video quality (e.g., 1080, 720). Default is 1080.
+  -mp3                       Extract audio only as MP3
+  -audio                     Extract audio only
+  -fetch RANGE [RANGE ...]   Alternate for --playlist-items. Single value applies globally
+                             Multiple value must number of playlist URLs provided
+                             match number of playlist URLs provided.
+  -list [NAME]               List playlist contents. Accepts values for searching across playlist
+```
+
+*Note: Arguments are position-independent except for `-list` and `-flag` where URLs can be mentioned after it*
+
+### Examples
+
+#### Basic Downloading
+
+Download a video at the default quality (1080p)
+```bash
+ytfetch "VIDEO_URL"
+```
+Download a video in 720p
+```bash
+ytfetch "VIDEO_URL" -q 720
+```
+#### Format Conversion
+
+Download as AVC(H.264) and Mp3 in MP4 Container
+```bash
+ytfetch "VIDEO_URL" -avcmp3
+```
+Extract Audio Only in Mp3
+```bash
+ytfetch "VIDEO_URL" -mp3
+```
+#### Smart Fetching
+
+Global Limit
+```bash
+ytfetch "PLAYLIST_URL_1" "PLAYLIST_URL_2" -fetch "1-10"
+```
+Mapped Ranges
+```bash
+ytfetch "PLAYLIST_A" "PLAYLIST_B"  -fetch "1-5" "10-15"
+```
+*Note: The number of fetch arguments must match the number of URLs*
+
+#### Listing and Searching
+
+List a Playlist
+```bash
+ytfetch "PLAYLIST_URL" -list
+```
+Search through a playlist
+```bash
+ytfetch "PLAYLIST_URL" -list "remix"
+```
+Combined Fetch & Search
+```bash
+ytfetch "PLAYLIST_URL"  -fetch ":50" -list "search_word"
+```
+
+#### Passthrough Options
+
+You can append any standard yt-dlp option to your command. Both long and short flags are supported.
+
+Download via Proxy
+```bash
+ytfetch --proxy "socks5://127.0.0.1:1080" "VIDEO_URL"
+```
+Use Cookies
+```bash
+ytfetch --cookies "cookies.txt" "VIDEO_URL"
+```
+Limit Speed
+```bash
+ytfetch -r "500K" "VIDEO_URL"
+```
+
+## 🔖 License
+
+MIT License

ytfetch-1.0.0/README-pypi.md

@@ -0,0 +1,129 @@
+# ytfetch
+
+**ytfetch** simplifies media downloading and playlist management by adding "Smart Fetching,"playlist searching, and streamlined format handling on top of the powerful [yt-dlp](https://github.com/yt-dlp/yt-dlp) engine.
+
+## ✨ Features
+
+* **Smart Fetching:** Apply limits to multiple playlists or map specific ranges in a single download.
+* **Search:** Use `-list` to display or search across single or multiple playlists contents.
+* **Direct Download:** Single flag to download in legacy `avc/h.264` and `mp3` format and audio only extraction.
+* **Video Quality:** Mention preffered video quality directly.
+* **Native Compatibility:** Can also pass through any `yt-dlp` flag.
+* **Minimal Output logs:** Clean and minimal logs.
+
+## 📋 Requirements
+
+- [Python](https://www.python.org/): 3.8 or higher.
+- [FFmpeg](https://ffmpeg.org/) and [FFprobe](https://ffmpeg.org/ffprobe.html): Should available in your system PATH.
+Download builds from [here](https://ffmpeg.org/download.html)
+- [Deno](https://deno.com/): Or other JavaScript runtime/engine like [node.js](https://nodejs.org/en) or [bun](https://bun.sh/)
+
+  Check this [guide](https://github.com/yt-dlp/yt-dlp/wiki/EJS) for more info.
+
+
+## 📦 Installation
+
+### via pip
+
+```bash
+pip install ytfetch
+```
+
+### via source
+```bash
+git clone <your-repo-url>
+cd <your-repo>
+pip install -e .
+```
+
+## 🚀 Usage
+
+### General Syntax and Options
+
+```text
+usage: Usage: ytfetch [yt-dlp OPTIONS] URL ... [OPTIONS]
+
+options:
+  -h                         Show this help message and exit.
+  -help                      Show yt-dlp help message.
+  -avcmp3                    Download video in AVC (h.264) format (mp4) + extract audio
+  -q QUALITY                 Video quality (e.g., 1080, 720). Default is 1080.
+  -mp3                       Extract audio only as MP3
+  -audio                     Extract audio only
+  -fetch RANGE [RANGE ...]   Alternate for --playlist-items. Single value applies globally
+                             Multiple value must number of playlist URLs provided
+                             match number of playlist URLs provided.
+  -list [NAME]               List playlist contents. Accepts values for searching across playlist
+```
+
+*Note: Arguments are position-independent except for `-list` and `-flag` where URLs can be mentioned after it*
+
+### Examples
+
+#### Basic Downloading
+
+Download a video at the default quality (1080p)
+```bash
+ytfetch "VIDEO_URL"
+```
+Download a video in 720p
+```bash
+ytfetch "VIDEO_URL" -q 720
+```
+#### Format Conversion
+
+Download as AVC(H.264) and Mp3 in MP4 Container
+```bash
+ytfetch "VIDEO_URL" -avcmp3
+```
+Extract Audio Only in Mp3
+```bash
+ytfetch "VIDEO_URL" -mp3
+```
+#### Smart Fetching
+
+Global Limit
+```bash
+ytfetch "PLAYLIST_URL_1" "PLAYLIST_URL_2" -fetch "1-10"
+```
+Mapped Ranges
+```bash
+ytfetch "PLAYLIST_A" "PLAYLIST_B"  -fetch "1-5" "10-15"
+```
+*Note: The number of fetch arguments must match the number of URLs*
+
+#### Listing and Searching
+
+List a Playlist
+```bash
+ytfetch "PLAYLIST_URL" -list
+```
+Search through a playlist
+```bash
+ytfetch "PLAYLIST_URL" -list "remix"
+```
+Combined Fetch & Search
+```bash
+ytfetch "PLAYLIST_URL"  -fetch ":50" -list "search_word"
+```
+
+#### Passthrough Options
+
+You can append any standard yt-dlp option to your command. Both long and short flags are supported.
+
+Download via Proxy
+```bash
+ytfetch --proxy "socks5://127.0.0.1:1080" "VIDEO_URL"
+```
+Use Cookies
+```bash
+ytfetch --cookies "cookies.txt" "VIDEO_URL"
+```
+Limit Speed
+```bash
+ytfetch -r "500K" "VIDEO_URL"
+```
+
+## 🔖 License
+
+MIT License

ytfetch-1.0.0/README.md

@@ -0,0 +1,162 @@
+# ytfetch
+
+**ytfetch** simplifies media downloading and playlist management by adding "Smart Fetching,"playlist searching, and streamlined format handling on top of the powerful [yt-dlp](https://github.com/yt-dlp/yt-dlp) engine.
+
+## ✨ Features
+
+* **Smart Fetching:** Apply limits to multiple playlists or map specific ranges in a single download.
+* **Search:** Use `-list` to display or search across single or multiple playlists contents.
+* **Direct Download:** Single flag to download in legacy `avc/h.264` and `mp3` format and audio only extraction.
+* **Video Quality:** Mention preffered video quality directly.
+* **Native Compatibility:** Can also pass through any `yt-dlp` flag.
+* **Minimal Output logs:** Clean and minimal logs.
+
+## 📋 Requirements
+
+- [Python](https://www.python.org/): 3.8 or higher.
+- [FFmpeg](https://ffmpeg.org/) and [FFprobe](https://ffmpeg.org/ffprobe.html): Should available in your system PATH.
+Download builds from [here](https://ffmpeg.org/download.html)
+
+    <details>
+    <summary>or</summary>
+
+    - On Windows:
+        ```bash
+        winget install BtbN.FFmpeg.GPL
+        ```
+        or
+        ```bash
+        winget install Gyan.FFmpeg
+        ```
+
+    - On Termux (android):
+        ```bash
+        pkg install ffmpeg
+        ```
+
+    - On Mac (using Homebrew):
+        ```bash
+        brew install ffmpeg
+        ```
+
+    - On Arch Linux:
+        ```bash
+        sudo pacman -S ffmpeg
+        ```
+
+    - On Ubuntu/Debian:
+        ```bash
+        sudo apt install ffmpeg
+        ```
+    </details>
+- [Deno](https://deno.com/): Or other JavaScript runtime/engine like [node.js](https://nodejs.org/en) or [bun](https://bun.sh/)
+
+  Check this [guide](https://github.com/yt-dlp/yt-dlp/wiki/EJS) for more info.
+
+
+## 📦 Installation
+
+### via pip
+
+```bash
+pip install ytfetch
+```
+
+### via source
+```bash
+git clone <your-repo-url>
+cd <your-repo>
+pip install -e .
+```
+
+## 🚀 Usage
+
+### General Syntax and Options
+
+```text
+usage: Usage: ytfetch [yt-dlp OPTIONS] URL ... [OPTIONS]
+
+options:
+  -h                         Show this help message and exit.
+  -help                      Show yt-dlp help message.
+  -avcmp3                    Download video in AVC (h.264) format (mp4) + extract audio
+  -q QUALITY                 Video quality (e.g., 1080, 720). Default is 1080.
+  -mp3                       Extract audio only as MP3
+  -audio                     Extract audio only
+  -fetch RANGE [RANGE ...]   Alternate for --playlist-items. Single value applies globally
+                             Multiple value must number of playlist URLs provided
+                             match number of playlist URLs provided.
+  -list [NAME]               List playlist contents. Accepts values for searching across playlist
+```
+
+*Note: Arguments are position-independent except for `-list` and `-flag` where URLs can be mentioned after it*
+
+### Examples
+
+#### Basic Downloading
+
+Download a video at the default quality (1080p)
+```bash
+ytfetch "VIDEO_URL"
+```
+Download a video in 720p
+```bash
+ytfetch "VIDEO_URL" -q 720
+```
+#### Format Conversion
+
+Download as AVC(H.264) and Mp3 in MP4 Container
+```bash
+ytfetch "VIDEO_URL" -avcmp3
+```
+Extract Audio Only in Mp3
+```bash
+ytfetch "VIDEO_URL" -mp3
+```
+#### Smart Fetching
+
+Global Limit
+```bash
+ytfetch "PLAYLIST_URL_1" "PLAYLIST_URL_2" -fetch "1-10"
+```
+Mapped Ranges
+```bash
+ytfetch "PLAYLIST_A" "PLAYLIST_B"  -fetch "1-5" "10-15"
+```
+*Note: The number of fetch arguments must match the number of URLs*
+
+#### Listing and Searching
+
+List a Playlist
+```bash
+ytfetch "PLAYLIST_URL" -list
+```
+Search through a playlist
+```bash
+ytfetch "PLAYLIST_URL" -list "remix"
+```
+Combined Fetch & Search
+```bash
+ytfetch "PLAYLIST_URL"  -fetch ":50" -list "search_word"
+```
+
+#### Passthrough Options
+
+You can append any standard yt-dlp option to your command. Both long and short flags are supported.
+
+Download via Proxy
+```bash
+ytfetch --proxy "socks5://127.0.0.1:1080" "VIDEO_URL"
+```
+Use Cookies
+```bash
+ytfetch --cookies "cookies.txt" "VIDEO_URL"
+```
+Limit Speed
+```bash
+ytfetch -r "500K" "VIDEO_URL"
+```
+
+## 🔖 License
+
+MIT License

ytfetch-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ytfetch"
+version = "1.0.0"
+description = "A wrapper for yt-dlp with custom simple fetching flags"
+authors = [
+    { name = "voidsnax" }
+]
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = [
+    "yt-dlp>=2025.12.08",
+    "colorama"
+]
+
+keywords = ["youtubedownloader", "converter", "h264", "mp3", "playlist"]
+
+[project.urls]
+Homepage = "https://github.com/voidsnax/reVidx"
+
+[project.scripts]
+ytfetch = "ytfetch.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ytfetch"]

ytfetch-1.0.0/src/ytfetch/cli.py

@@ -0,0 +1,247 @@
+import argparse
+import sys
+import yt_dlp # type: ignore
+from colorama import Fore, Style # type: ignore
+import subprocess
+from .utils import (
+    validate_fetch_ranges,
+    ErrorOnlyLogger,
+    AlignedHelpFormatter,
+    print_error,
+    parse_passthrough_args
+    )
+
+# --- Custom Logger ---
+class YTFetchLogger:
+    def debug(self, msg):
+        message = [
+            "Downloading playlist:", "Downloading item", "Resuming",
+            "Destination:", "already been downloaded",  "Finished downloading"
+        ]
+        clean_msg = msg.replace("[download] ", "")
+
+        if any(phrase in msg for phrase in message):
+            print(clean_msg)
+
+        if "Merging formats" in msg:
+            print(msg.replace("[Merger] ", ""))
+
+    def info(self, msg):
+        pass
+
+    def warning(self, msg):
+        if "Some web client https formats have been skipped" in msg:
+            return
+        print(f"{msg}")
+
+    def error(self, msg):
+        print(f"{msg}")
+
+
+# --- Custom Progress Hook ---
+def progress_hook(d):
+    if d['status'] == 'downloading':
+        percent = d.get('_percent_str', '0.0%')
+        total = d.get('_total_bytes_str', d.get('_total_bytes_estimate_str', 'N/A'))
+        speed = d.get('_speed_str', 'N/A')
+        status = f"{percent} of {total} at {speed}"
+        print(f"\r{status}", end="")
+        sys.stdout.flush()
+    elif d['status'] == 'finished':
+        print()
+
+# --- Argument Parsing ---
+def parse_arguments():
+    parser = argparse.ArgumentParser(
+        usage = "ytfetch [yt-dlp OPTIONS] URL ... [OPTIONS]",
+        description="ytfetch: yt-dlp wrapper with flexible args.",
+        epilog = "type ytftech -help for yt-dlp options \n"
+        "Doc & issues: https://github.com/voidsnax/ytFetch",
+        formatter_class=AlignedHelpFormatter,
+        add_help=False,
+        allow_abbrev=False
+    )
+    parser.add_argument('-h',action='help',
+                        help='Show this help message and exit.')
+    parser.add_argument('-help',action="store_const",const="default",
+                        help='Show yt-dlp help message.')
+
+    parser.add_argument("-avcmp3", action="store_true",
+                        help="Download video in AVC (h.264) format (mp4) + extract audio")
+    parser.add_argument("-q", metavar="QUALITY",default="1080",
+                        help="Video quality (e.g., 1080, 720). Default is 1080.")
+    parser.add_argument("-mp3", action="store_true",
+                        help="Extract audio only as MP3")
+    parser.add_argument("-audio", action="store_true",
+                        help="Extract audio only (bestaudio)")
+    parser.add_argument("-fetch", metavar="RANGE",nargs="+",
+                        help="Alternate for --playlist-items. Single value applies globally\n"
+                        "Multiple values must match number of playlist URLs provided")
+    parser.add_argument("-list", metavar="NAME",nargs="?",const="default",
+                        help="List playlist contents. Accepts values for searching across playlist")
+
+    args, unknown_args = parser.parse_known_args()
+    return args, unknown_args
+
+def get_urls_from_args(args_list):
+    return [a for a in args_list if a.startswith("http")]
+
+def get_format_selector(args):
+    height = args.q.rstrip("p")
+
+    if args.mp3 or args.audio:
+        return "bestaudio"
+
+    if args.avcmp3:
+        return f"bestvideo[vcodec^=avc1][height<={height}]+bestaudio/best[vcodec^=avc1][height<={height}]"
+    return f"bestvideo[height<={height}]+bestaudio/best[height<={height}]"
+
+
+def process_urls(custom_args, raw_ytdlp_args):
+    urls = get_urls_from_args(raw_ytdlp_args)
+    if custom_args.help:
+        yt_dlp.options.create_parser().print_help() # type: ignore
+        sys.exit()
+    if custom_args.list and custom_args.list.startswith('http'):
+        print_error(f"Provided URL link as argument for -list\nUse -list after URL")
+        sys.exit(1)
+    if custom_args.fetch and any(item.startswith("http") for item in custom_args.fetch):
+        print_error(f"Provided a URL link after -fetch\nUse -fetch after URL")
+        sys.exit(1)
+    if not urls:
+        print_error(f"Error: No URLs provided.")
+        sys.exit(1)
+
+    passthrough_opts = parse_passthrough_args(raw_ytdlp_args)
+
+    ydl_opts = {
+        'outtmpl': '%(title)s.%(ext)s',
+        'logger': YTFetchLogger(),
+        'progress_hooks': [progress_hook],
+    }
+
+    ydl_opts.update(passthrough_opts)
+
+    # --- Mode: List ---
+    if custom_args.list:
+        base_cmd = [
+            "yt-dlp",
+            "--flat-playlist",
+            "--print", "%(playlist_index)s - %(title)s"
+        ]
+
+        passthrough_args = [arg for arg in raw_ytdlp_args if arg not in urls]
+        base_cmd.extend(passthrough_args)
+        command = []
+
+        ydl_opts['extract_flat'] = 'in_playlist'
+        ydl_opts['logger'] = ErrorOnlyLogger()
+
+        search_mode = False
+
+        fetch_ranges = custom_args.fetch
+        if fetch_ranges:
+            if len(fetch_ranges) >1:
+                validate_fetch_ranges(fetch_ranges,urls)
+                for fetch_range in fetch_ranges:
+                    command.append(base_cmd + [ "--playlist-items", fetch_range])
+            else:
+                command.append(base_cmd + ["--playlist-items", fetch_ranges[0]])
+        else:
+            command.append(base_cmd)
+
+        # make sure command is a list of list
+        if len(command) == 1 and len(urls) > 1:
+            command = [cmd.copy() for cmd in [command[0]] * len(urls)]
+
+        # print(command)
+
+        if custom_args.list != 'default':
+            search_mode = True
+            list_val = custom_args.list
+            search_pattern = list_val.lower()
+        for url, cmd in zip(urls, command):
+            # currently for title fetching this is more reliable
+            with yt_dlp.YoutubeDL(ydl_opts) as ydl:  #type: ignore
+                try:
+                    info = ydl.extract_info(url, download=False) # type: ignore
+                    if 'entries' not in info:
+                        print(f"Single Video: {info.get('title')}")
+                    else:
+                        title = f"▶ Playlist: {info.get('title')}"
+                        print(f"▶ Playlist: {Fore.CYAN}{info.get('title')}{Style.RESET_ALL}")
+                        print(f"{"-" * len(title)}")
+                except Exception as e:
+                    print(f"Error getting {url} title: {e}")
+            try:
+                cmd.append(url)
+                # print(cmd)
+                result = subprocess.run(cmd, capture_output=True, text=True)
+                found_match = False
+                for line in result.stdout.splitlines():
+                    idx, title = line.split(" - ", 1)
+                    video = f"{Fore.YELLOW}{idx}{Style.RESET_ALL} - {title}"
+                    if search_mode:
+                        if search_pattern in line.lower():
+                            found_match = True
+                            print(video)
+                    else:
+                        print(video)
+                if not found_match and search_mode:
+                    print(f"No match found for {Fore.YELLOW}{search_pattern}{Style.RESET_ALL}")
+            except Exception as e:
+                print_error(f"Error listing {url}: {e}")
+
+        # stops further execution
+        return
+
+    ydl_opts['format'] = get_format_selector(custom_args)
+
+    if custom_args.mp3:
+        ydl_opts['postprocessors'] = [{
+            'key': 'FFmpegExtractAudio',
+            'preferredcodec': 'mp3',
+            'preferredquality': '192',
+        }]
+
+    if custom_args.avcmp3 and not custom_args.mp3:
+        ydl_opts['merge_output_format'] = 'mp4'
+        ydl_opts['postprocessor_args'] = {
+            'ffmpeg': ['-c:v', 'copy', '-c:a', 'libmp3lame', '-b:a', '192k']
+        }
+
+    # --- Mode: Download ---
+    def run_download(url, playlist_items=None):
+        opts = ydl_opts.copy()
+        if playlist_items:
+            opts['playlist_items'] = playlist_items
+        with yt_dlp.YoutubeDL(opts) as ydl:  #type:ignore
+            try:
+                ydl.download([url])
+            except Exception as e:
+                # print(f"Download error for {url}: {e}")
+                pass
+
+    fetch_ranges = custom_args.fetch
+    if fetch_ranges:
+        if len(fetch_ranges) == 1:
+            for url in urls:
+                run_download(url, fetch_ranges[0])
+        else:
+            validate_fetch_ranges(fetch_ranges,urls)
+            for url, rng in zip(urls, fetch_ranges):
+                run_download(url, rng)
+    else:
+        for url in urls:
+            run_download(url)
+
+def main():
+    try:
+        custom_args, ytdlp_args = parse_arguments()
+        process_urls(custom_args, ytdlp_args)
+    except KeyboardInterrupt:
+        print(f"\n\n{Fore.YELLOW}Process aborted by user.{Style.RESET_ALL}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

ytfetch-1.0.0/src/ytfetch/utils.py

@@ -0,0 +1,64 @@
+import sys
+import argparse
+import yt_dlp
+from colorama import Fore, init # type: ignore
+
+init(autoreset=True)
+
+def validate_fetch_ranges(fetch_ranges, urls):
+    if len(fetch_ranges) != len(urls):
+        print_error(f"Error: Provided {len(fetch_ranges)} fetch ranges for {len(urls)} URLs.")
+        sys.exit(1)
+
+class ErrorOnlyLogger:
+    def debug(self, msg): pass
+    def info(self, msg): pass
+    def warning(self, msg): pass
+    def error(self, msg): print(msg)
+
+class AlignedHelpFormatter(argparse.HelpFormatter):
+    def __init__(self, *args, **kwargs):
+        kwargs['max_help_position'] = 35  # default is 24
+        super().__init__(*args, **kwargs)
+    def _fill_text(self, text, width, indent):
+        # Preserve newlines in Description and Epilog
+        # splitlines(keepends=True) ensures not losing of double newlines
+        return ''.join(indent + line for line in text.splitlines(keepends=True))
+
+    def _split_lines(self, text, width):
+        # Preserve newlines in help
+        return text.splitlines()
+
+
+def print_error(msg):
+    print(f"{Fore.RED}{msg}")
+
+def parse_passthrough_args(args_list):
+    """
+    Parses unknown arguments using yt-dlp's internal parser.
+    Returns a dictionary containing ONLY the options explicitly passed by the user.
+    """
+    filtered_args = [a for a in args_list if not a.startswith("http")]
+    if not filtered_args:
+        return {}
+
+    parser = yt_dlp.options.create_parser() # type: ignore
+
+    parsed, _ = parser.parse_known_args(filtered_args)
+
+    opts = vars(parsed) # convert to dict
+
+    # Filter out defaults to return ONLY user-provided args
+    # create a baseline parser to see what the defaults are
+    base_parser = yt_dlp.options.create_parser() # type: ignore
+    base_parsed, _ = base_parser.parse_args([])
+    base_opts = vars(base_parsed)
+
+    # Build dictionary of only changed items
+    final_opts = {}
+    for key, value in opts.items():
+        # Only keep the option if the user changed it from the default
+        if base_opts[key] != value:
+            final_opts[key] = value
+
+    return final_opts