ytfetch 2.0.0__tar.gz → 3.0.0__tar.gz

ytfetch-3.0.0/PKG-INFO

@@ -0,0 +1,347 @@
+Metadata-Version: 2.5
+Name: ytfetch
+Version: 3.0.0
+Summary: A wrapper for yt-dlp with some flexible args
+Project-URL: Homepage, https://github.com/voidsnax/ytFetch
+Author: voidsnax
+License: MIT
+License-File: LICENSE
+Keywords: converter,downloader,h264,mp3,playlist,youtubedownloader
+Requires-Python: >=3.11
+Requires-Dist: colorama
+Requires-Dist: yt-dlp[curl-cffi,default]
+Description-Content-Type: text/markdown
+
+# ytFetch
+
+**ytfetch** simplifies media downloading and playlist management by adding playlist searching, and streamlined format handling on top of [yt-dlp](https://github.com/yt-dlp/yt-dlp) engine.
+
+## ✨ Features
+
+- **Search:** Use `-list` to display or search across one or more playlists.
+- **Direct Download:** Download video in AVC/H.264 with MP3 audio, or extract audio only.
+- **Video Quality:** Set the preferred video quality directly.
+- **Native Compatibility:** Can also pass through any `yt-dlp` flag.
+- **Minimal logs:** Clean and minimal logs.
+- **Auto-Update:** Automatically checks for updates to ytfetch and its dependencies when enabled.
+
+## 📋 Requirements
+
+- [Python](https://www.python.org/): 3.11 or higher.
+- [uv](https://docs.astral.sh/uv/getting-started/installation/): recommended, optional.
+- [FFmpeg](https://ffmpeg.org/) and [FFprobe](https://ffmpeg.org/ffprobe.html): Must be available in your system PATH.
+  Download builds from [here](https://ffmpeg.org/download.html).
+  <details>
+    <summary>or using your system's package manager</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
+      ```
+  </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.
+  Also check [yt-dlp dependency](https://github.com/yt-dlp/yt-dlp#dependencies) for optional dependencies.
+
+  <details>
+    <summary>On Termux</summary>
+
+    Install uv or Deno with the `pkg` package manager:
+
+    ```bash
+    pkg install uv
+    ```
+
+    ```bash
+    pkg install deno
+    ```
+  </details>
+
+## 📦 Installation
+
+### via uv (Recommended)
+
+```bash
+uv tool install ytfetch
+```
+
+### via pip
+
+```bash
+pip install ytfetch
+```
+
+Auto-update is intended for uv tool installations. If enabled while running a
+pip installation, it still runs `uv tool upgrade ytfetch`; that updates a
+uv-managed installation, if present, rather than the pip-installed copy.
+
+## 🔄 Auto-Update
+
+When enabled, auto-update runs `uv tool upgrade ytfetch`. This upgrades the
+uv-managed ytfetch tool and its dependencies, including yt-dlp. Set the
+`YTFETCH_UPDATE` environment variable to select the update channel:
+
+| Value           | Channel                      | Check frequency |
+| --------------- | ---------------------------- | --------------- |
+| `nightly`       | yt-dlp nightly (pre-release) | once per day    |
+| `stable`        | yt-dlp stable                | once per week   |
+| unset / invalid | disabled                     | –               |
+
+### Setting `YTFETCH_UPDATE`
+
+Set the value to `nightly` for daily checks or `stable` for weekly checks.
+Changes to startup files or Windows user variables take effect in new terminal
+sessions unless you also set the variable in the current session.
+
+**Bash (Linux/macOS)** — append the setting to `~/.bashrc` so it persists
+across sessions, then load it into the current session:
+
+```bash
+printf '\nexport YTFETCH_UPDATE=nightly\n' >> ~/.bashrc
+source ~/.bashrc
+```
+
+If your login shell does not load `~/.bashrc`, add the line to the startup file
+it does load, such as `~/.profile`. On macOS, the default shell is usually zsh;
+for zsh, use `~/.zshrc` instead:
+
+```zsh
+printf '\nexport YTFETCH_UPDATE=nightly\n' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Run the append command only once. To change or remove the setting later, edit
+the corresponding startup file.
+
+**Fish** — set a persistent, exported variable:
+
+```fish
+set -Ux YTFETCH_UPDATE nightly
+```
+
+Use `stable` instead of `nightly` to select the stable update channel.
+
+**Windows PowerShell** — set the variable for your Windows user account:
+
+```powershell
+[Environment]::SetEnvironmentVariable("YTFETCH_UPDATE", "nightly", "User")
+```
+
+This applies to newly opened terminals. To set it in the current PowerShell
+session too, run:
+
+```powershell
+$env:YTFETCH_UPDATE = "nightly"
+```
+
+**Windows Environment Variables settings** — to set it manually:
+
+1. Open Start and search for **Edit environment variables for your account**.
+2. Under **User variables**, choose **New...**, or select `YTFETCH_UPDATE` and
+   choose **Edit...** if it already exists.
+3. Set the variable name to `YTFETCH_UPDATE` and its value to `nightly` or
+   `stable`, then confirm the dialogs.
+4. Open a new terminal for the change to take effect.
+
+To check the value, use `echo "$YTFETCH_UPDATE"` in bash/zsh,
+`echo $YTFETCH_UPDATE` in fish, or `$env:YTFETCH_UPDATE` in PowerShell.
+
+Notes:
+
+- If an update fails, the next retry happens after **1 hour** instead of the
+  normal interval.
+- To disable persistently in bash/zsh, remove the export line from the startup
+  file; run `unset YTFETCH_UPDATE` to disable it in the current session.
+- In fish, use `set -eU YTFETCH_UPDATE` to remove the persistent universal
+  variable. To disable updates only in the current session, use
+  `set -gx YTFETCH_UPDATE ""`.
+- In Windows, remove the User variable; to disable it in the current
+  PowerShell session, run `Remove-Item Env:YTFETCH_UPDATE`.
+
+### Switching from nightly to stable
+
+`uv tool upgrade` never downgrades. If a nightly build is installed and you
+switch to `stable`, yt-dlp will stay on the nightly until a **newer** stable
+release appears — then stable takes over automatically.
+
+To switch immediately, force-reinstall:
+
+```bash
+uv tool install --reinstall ytfetch
+```
+
+## 🚀 Usage
+
+### General Syntax and Options
+
+```text
+usage: ytfetch [OPTIONS] [yt-dlp OPTIONS] URL ...
+
+options:
+  -h                         Show this help message and exit
+  --help                     Show yt-dlp help message and exit
+  -avcmp3                    Download video in AVC (h.264) & audio in mp3 format
+  -q QUALITY                 Video quality (e.g., 1080, 720). Default will pick best video
+  -mp3                       Extract audio only as MP3
+  -audio                     Extract audio only (bestaudio)
+  -list [NAME]               List playlist contents. Accepts values for searching across playlist
+
+output template aliases:
+  -o autonumber/num   -> playlist-numbered naming
+  -o music/song       -> title + artist naming
+  -o default          -> default ytdlp naming
+```
+
+### Examples
+
+#### Downloading
+
+Download a video at the best quality:
+
+```bash
+ytfetch "VIDEO_URL"
+```
+
+Download a video in 1080p:
+
+```bash
+ytfetch -q 1080 "VIDEO_URL"
+```
+
+List the available formats for a video:
+
+```bash
+ytfetch -F "VIDEO_URL"
+```
+
+Download a video as AVC/H.264 with MP3 audio in an MP4 container:
+
+```bash
+ytfetch -avcmp3 "VIDEO_URL"
+```
+
+#### Audio
+
+Extract audio only (best available audio):
+
+```bash
+ytfetch -audio "VIDEO_URL"
+```
+
+Extract audio as MP3:
+
+```bash
+ytfetch -mp3 "VIDEO_URL"
+```
+
+#### Listing and searching playlists
+
+List a playlist:
+
+```bash
+ytfetch -list "PLAYLIST_URL"
+```
+
+List only entries 10 through 50:
+
+```bash
+ytfetch -I "10:50" -list "PLAYLIST_URL"
+```
+
+List in reverse order:
+
+```bash
+ytfetch -I "30:20:-1" -list "PLAYLIST_URL"
+```
+
+Search a playlist by title (case-insensitive):
+
+```bash
+ytfetch -list "remix" "PLAYLIST_URL"
+```
+
+#### Downloading part of a playlist
+
+Download only items 10 through 50:
+
+```bash
+ytfetch -I "10:50" "PLAYLIST_URL"
+```
+
+Download from item 30 backwards to 20 in reverse order:
+
+```bash
+ytfetch -I "30:20:-1" "PLAYLIST_URL"
+```
+
+#### Output templates and paths
+
+Use the playlist-numbered naming scheme:
+
+```bash
+ytfetch -o num "PLAYLIST_URL"
+```
+
+Use the music scheme (title + artist):
+
+```bash
+ytfetch -o music "VIDEO_URL"
+```
+
+Use the default naming scheme of yt-dlp:
+
+```bash
+ytfetch -o default "VIDEO_URL"
+```
+
+Download songs with thumbnail and metadata embedded, using the music template:
+
+```bash
+ytfetch -o music --embed-thumbnail --embed-metadata "VIDEO_URL"
+```
+
+Use a download archive to skip already-downloaded items:
+
+```bash
+ytfetch --embed-thumbnail --embed-metadata --download-archive archive.txt -o music "PLAYLIST_URL"
+```
+Save to a custom directory:
+
+```bash
+ytfetch "VIDEO_URL" --paths "~/Downloads"
+```
+
+#### Downloading a specific time range
+
+Download only a portion of the video:
+
+```bash
+ytfetch --download-sections "*0:30-2:00"  "VIDEO_URL"
+```
+
+#### Rate limiting
+
+Sleep between downloads to avoid rate limits:
+
+```bash
+ytfetch --sleep-interval 5 --max-sleep-interval 15 "PLAYLIST_URL"
+```
+
+_and so on..._
+
+## 🔖 License
+
+MIT License

ytfetch-3.0.0/README.md

@@ -0,0 +1,333 @@
+# ytFetch
+
+**ytfetch** simplifies media downloading and playlist management by adding playlist searching, and streamlined format handling on top of [yt-dlp](https://github.com/yt-dlp/yt-dlp) engine.
+
+## ✨ Features
+
+- **Search:** Use `-list` to display or search across one or more playlists.
+- **Direct Download:** Download video in AVC/H.264 with MP3 audio, or extract audio only.
+- **Video Quality:** Set the preferred video quality directly.
+- **Native Compatibility:** Can also pass through any `yt-dlp` flag.
+- **Minimal logs:** Clean and minimal logs.
+- **Auto-Update:** Automatically checks for updates to ytfetch and its dependencies when enabled.
+
+## 📋 Requirements
+
+- [Python](https://www.python.org/): 3.11 or higher.
+- [uv](https://docs.astral.sh/uv/getting-started/installation/): recommended, optional.
+- [FFmpeg](https://ffmpeg.org/) and [FFprobe](https://ffmpeg.org/ffprobe.html): Must be available in your system PATH.
+  Download builds from [here](https://ffmpeg.org/download.html).
+  <details>
+    <summary>or using your system's package manager</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
+      ```
+  </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.
+  Also check [yt-dlp dependency](https://github.com/yt-dlp/yt-dlp#dependencies) for optional dependencies.
+
+  <details>
+    <summary>On Termux</summary>
+
+    Install uv or Deno with the `pkg` package manager:
+
+    ```bash
+    pkg install uv
+    ```
+
+    ```bash
+    pkg install deno
+    ```
+  </details>
+
+## 📦 Installation
+
+### via uv (Recommended)
+
+```bash
+uv tool install ytfetch
+```
+
+### via pip
+
+```bash
+pip install ytfetch
+```
+
+Auto-update is intended for uv tool installations. If enabled while running a
+pip installation, it still runs `uv tool upgrade ytfetch`; that updates a
+uv-managed installation, if present, rather than the pip-installed copy.
+
+## 🔄 Auto-Update
+
+When enabled, auto-update runs `uv tool upgrade ytfetch`. This upgrades the
+uv-managed ytfetch tool and its dependencies, including yt-dlp. Set the
+`YTFETCH_UPDATE` environment variable to select the update channel:
+
+| Value           | Channel                      | Check frequency |
+| --------------- | ---------------------------- | --------------- |
+| `nightly`       | yt-dlp nightly (pre-release) | once per day    |
+| `stable`        | yt-dlp stable                | once per week   |
+| unset / invalid | disabled                     | –               |
+
+### Setting `YTFETCH_UPDATE`
+
+Set the value to `nightly` for daily checks or `stable` for weekly checks.
+Changes to startup files or Windows user variables take effect in new terminal
+sessions unless you also set the variable in the current session.
+
+**Bash (Linux/macOS)** — append the setting to `~/.bashrc` so it persists
+across sessions, then load it into the current session:
+
+```bash
+printf '\nexport YTFETCH_UPDATE=nightly\n' >> ~/.bashrc
+source ~/.bashrc
+```
+
+If your login shell does not load `~/.bashrc`, add the line to the startup file
+it does load, such as `~/.profile`. On macOS, the default shell is usually zsh;
+for zsh, use `~/.zshrc` instead:
+
+```zsh
+printf '\nexport YTFETCH_UPDATE=nightly\n' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Run the append command only once. To change or remove the setting later, edit
+the corresponding startup file.
+
+**Fish** — set a persistent, exported variable:
+
+```fish
+set -Ux YTFETCH_UPDATE nightly
+```
+
+Use `stable` instead of `nightly` to select the stable update channel.
+
+**Windows PowerShell** — set the variable for your Windows user account:
+
+```powershell
+[Environment]::SetEnvironmentVariable("YTFETCH_UPDATE", "nightly", "User")
+```
+
+This applies to newly opened terminals. To set it in the current PowerShell
+session too, run:
+
+```powershell
+$env:YTFETCH_UPDATE = "nightly"
+```
+
+**Windows Environment Variables settings** — to set it manually:
+
+1. Open Start and search for **Edit environment variables for your account**.
+2. Under **User variables**, choose **New...**, or select `YTFETCH_UPDATE` and
+   choose **Edit...** if it already exists.
+3. Set the variable name to `YTFETCH_UPDATE` and its value to `nightly` or
+   `stable`, then confirm the dialogs.
+4. Open a new terminal for the change to take effect.
+
+To check the value, use `echo "$YTFETCH_UPDATE"` in bash/zsh,
+`echo $YTFETCH_UPDATE` in fish, or `$env:YTFETCH_UPDATE` in PowerShell.
+
+Notes:
+
+- If an update fails, the next retry happens after **1 hour** instead of the
+  normal interval.
+- To disable persistently in bash/zsh, remove the export line from the startup
+  file; run `unset YTFETCH_UPDATE` to disable it in the current session.
+- In fish, use `set -eU YTFETCH_UPDATE` to remove the persistent universal
+  variable. To disable updates only in the current session, use
+  `set -gx YTFETCH_UPDATE ""`.
+- In Windows, remove the User variable; to disable it in the current
+  PowerShell session, run `Remove-Item Env:YTFETCH_UPDATE`.
+
+### Switching from nightly to stable
+
+`uv tool upgrade` never downgrades. If a nightly build is installed and you
+switch to `stable`, yt-dlp will stay on the nightly until a **newer** stable
+release appears — then stable takes over automatically.
+
+To switch immediately, force-reinstall:
+
+```bash
+uv tool install --reinstall ytfetch
+```
+
+## 🚀 Usage
+
+### General Syntax and Options
+
+```text
+usage: ytfetch [OPTIONS] [yt-dlp OPTIONS] URL ...
+
+options:
+  -h                         Show this help message and exit
+  --help                     Show yt-dlp help message and exit
+  -avcmp3                    Download video in AVC (h.264) & audio in mp3 format
+  -q QUALITY                 Video quality (e.g., 1080, 720). Default will pick best video
+  -mp3                       Extract audio only as MP3
+  -audio                     Extract audio only (bestaudio)
+  -list [NAME]               List playlist contents. Accepts values for searching across playlist
+
+output template aliases:
+  -o autonumber/num   -> playlist-numbered naming
+  -o music/song       -> title + artist naming
+  -o default          -> default ytdlp naming
+```
+
+### Examples
+
+#### Downloading
+
+Download a video at the best quality:
+
+```bash
+ytfetch "VIDEO_URL"
+```
+
+Download a video in 1080p:
+
+```bash
+ytfetch -q 1080 "VIDEO_URL"
+```
+
+List the available formats for a video:
+
+```bash
+ytfetch -F "VIDEO_URL"
+```
+
+Download a video as AVC/H.264 with MP3 audio in an MP4 container:
+
+```bash
+ytfetch -avcmp3 "VIDEO_URL"
+```
+
+#### Audio
+
+Extract audio only (best available audio):
+
+```bash
+ytfetch -audio "VIDEO_URL"
+```
+
+Extract audio as MP3:
+
+```bash
+ytfetch -mp3 "VIDEO_URL"
+```
+
+#### Listing and searching playlists
+
+List a playlist:
+
+```bash
+ytfetch -list "PLAYLIST_URL"
+```
+
+List only entries 10 through 50:
+
+```bash
+ytfetch -I "10:50" -list "PLAYLIST_URL"
+```
+
+List in reverse order:
+
+```bash
+ytfetch -I "30:20:-1" -list "PLAYLIST_URL"
+```
+
+Search a playlist by title (case-insensitive):
+
+```bash
+ytfetch -list "remix" "PLAYLIST_URL"
+```
+
+#### Downloading part of a playlist
+
+Download only items 10 through 50:
+
+```bash
+ytfetch -I "10:50" "PLAYLIST_URL"
+```
+
+Download from item 30 backwards to 20 in reverse order:
+
+```bash
+ytfetch -I "30:20:-1" "PLAYLIST_URL"
+```
+
+#### Output templates and paths
+
+Use the playlist-numbered naming scheme:
+
+```bash
+ytfetch -o num "PLAYLIST_URL"
+```
+
+Use the music scheme (title + artist):
+
+```bash
+ytfetch -o music "VIDEO_URL"
+```
+
+Use the default naming scheme of yt-dlp:
+
+```bash
+ytfetch -o default "VIDEO_URL"
+```
+
+Download songs with thumbnail and metadata embedded, using the music template:
+
+```bash
+ytfetch -o music --embed-thumbnail --embed-metadata "VIDEO_URL"
+```
+
+Use a download archive to skip already-downloaded items:
+
+```bash
+ytfetch --embed-thumbnail --embed-metadata --download-archive archive.txt -o music "PLAYLIST_URL"
+```
+Save to a custom directory:
+
+```bash
+ytfetch "VIDEO_URL" --paths "~/Downloads"
+```
+
+#### Downloading a specific time range
+
+Download only a portion of the video:
+
+```bash
+ytfetch --download-sections "*0:30-2:00"  "VIDEO_URL"
+```
+
+#### Rate limiting
+
+Sleep between downloads to avoid rate limits:
+
+```bash
+ytfetch --sleep-interval 5 --max-sleep-interval 15 "PLAYLIST_URL"
+```
+
+_and so on..._
+
+## 🔖 License
+
+MIT License

{ytfetch-2.0.0 → ytfetch-3.0.0}/pyproject.toml

@@ -4,20 +4,20 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ytfetch"
-version = "2.0.0"
-description = "A wrapper for yt-dlp with custom simple fetching flags"
+version = "3.0.0"
+description = "A wrapper for yt-dlp with some flexible args"
 authors = [
     { name = "voidsnax" }
 ]
 readme = "README.md"
 license = { text = "MIT" }
-requires-python = ">=3.8"
+requires-python = ">=3.11"
 dependencies = [
     "yt-dlp[default,curl-cffi]",
     "colorama"
 ]
 
-keywords = ["youtubedownloader", "converter", "h264", "mp3", "playlist"]
+keywords = ["downloader", "youtubedownloader", "converter", "h264", "mp3", "playlist"]
 
 [project.urls]
 Homepage = "https://github.com/voidsnax/ytFetch"