fm-dlp 2.3.3__tar.gz

fm_dlp-2.3.3/LICENSE

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

fm_dlp-2.3.3/PKG-INFO

@@ -0,0 +1,436 @@
+Metadata-Version: 2.4
+Name: fm-dlp
+Version: 2.3.3
+Summary: fm-dlp is a CLI tool for searching YouTube/YTMusic and downloading audio/video from 1000+ platforms
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cyclopts
+Requires-Dist: yt-dlp
+Requires-Dist: ytmusicapi
+Requires-Dist: mutagen
+Dynamic: license-file
+
+# fm-dlp is a CLI tool for searching YouTube/YTMusic and downloading audio/video from 1000+ platforms
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)]()
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-261230?logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/)
+
+Download and tag high-quality music and video from YouTube, YouTube Music, and 1000+ sites — all from your terminal.
+
+## ✨ Features
+
+- **Multi-platform Search** — YouTube, YouTube Music
+- **Search by Type** — Tracks or albums
+- **Parallel Downloads** — Async support for multiple URLs
+- **1000+ Supported Sites** — Any site yt-dlp supports (YouTube, SoundCloud, Bandcamp, etc.)
+- **Audio Formats** — MP3, AAC, FLAC, M4A, Opus, Vorbis, WAV with configurable bitrate
+- **Video Formats** — MP4, MKV, WebM, MOV, AVI, FLV with automatic audio codec selection
+- **Metadata Embedding** — Title, artist, album tags + thumbnail (audio only)
+- **Proxy Support** — HTTP, HTTPS, SOCKS4, SOCKS5, SOCKS5h for all requests (download supports all protocols; search via yt-music requires HTTP/HTTPS)
+- **Cookie Support** — Browser cookies for restricted content
+- **Self-updating** — Built-in update mechanism via Git
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.10+ & FFmpeg & Git
+
+### Installation
+
+#### 1. Clone Repository
+
+```bash
+git clone https://github.com/Fkernel653/fm-dlp.git && cd fm-dlp
+```
+
+#### 2. Install Dependencies
+
+**uv** (recommended)
+```bash
+uv sync
+```
+
+**pip**
+```bash
+pip install .
+```
+
+**Poetry**
+```bash
+poetry install
+```
+
+**PDM**
+```bash
+pdm install
+```
+
+### Usage
+```bash
+# Set download directory (required first)
+python fm-dlp.py config ~/Music
+
+# Search for tracks
+python fm-dlp.py search "artist name" --limit 5 --platform yt-music
+
+# Search for albums
+python fm-dlp.py search "album name" --platform yt-music --type album
+
+# Download audio
+python fm-dlp.py download "https://youtu.be/..." --codec mp3 --kbps 320
+
+# Download video
+python fm-dlp.py download "https://youtu.be/..." --codec mp4
+```
+
+## 📋 Commands
+
+### `search` — Find music
+```bash
+python fm-dlp.py search <query> [--limit 10] [--platform {yt-video|yt-music}] [--type {track|album}] [--proxy URL]
+```
+| Option | Values | Default | Description |
+|--------|--------|---------|-------------|
+| `--platform` | `yt-video`, `yt-music` | `yt-music` | Search platform |
+| `--type` | `track`, `album` | `track` | Content type to search |
+| `--limit` | 1–∞ | 10 | Number of results |
+| `--proxy` | URL | — | Proxy for requests |
+
+### `download` — Download audio or video
+```bash
+python fm-dlp.py download <urls> [--codec CODEC] [--kbps 256] [--quiet False] [--max-concurrent 5] [--cookies browser] [--proxy URL]
+```
+| Option | Values | Default |
+|--------|--------|---------|
+| `--codec` | **Audio:** `mp3`, `aac`, `flac`, `m4a`, `opus`, `vorbis`, `wav`<br>**Video:** `mp4`, `mkv`, `webm`, `mov`, `avi`, `flv` | `m4a` (macOS) / `opus` |
+| `--kbps` | 64–320 (audio only) | 256 |
+| `--quiet` | True/False (flag) | False |
+| `--max-concurrent` | 1–∞ | 5 |
+| `--cookies` | chrome, firefox, edge, etc. | — |
+| `--proxy` | http://, socks5:// | — |
+
+### Supported Proxies
+
+fm-dlp supports the following proxy protocols:
+
+| Protocol | Download | Search (yt-video) | Search (yt-music) |
+|----------|:--------:|:-----------------:|:-----------------:|
+| `http://` | ✅ | ✅ | ✅ |
+| `https://` | ✅ | ✅ | ✅ |
+| `socks4://` | ✅ | ✅ | ❌ |
+| `socks5://` | ✅ | ✅ | ❌ |
+| `socks5h://` | ✅ | ✅ | ❌ |
+
+> **Note:** `socks5h://` performs DNS resolution through the proxy (remote DNS), while `socks5://` resolves DNS locally. Use `socks5h://` for better privacy with Tor.
+
+**Examples:**
+```bash
+# HTTP proxy
+python fm-dlp.py download "URL" --proxy http://user:pass@proxy.example.com:8080
+
+# SOCKS5 (Tor)
+python fm-dlp.py download "URL" --proxy socks5://127.0.0.1:9050
+
+# SOCKS5h with remote DNS (recommended for Tor)
+python fm-dlp.py download "URL" --proxy socks5h://127.0.0.1:9050
+
+# SOCKS5 for video search
+python fm-dlp.py search "query" --platform yt-video --proxy socks5://127.0.0.1:9050
+```
+
+**Video container audio codec mapping:**
+
+| Video Container | Audio Codec | Typical Use |
+|-----------------|-------------|-------------|
+| `mp4` | `m4a` (AAC) | Universal compatibility |
+| `mkv` | `opus` | High quality, modern |
+| `webm` | `opus` | Web, streaming |
+| `mov` | `m4a` (AAC) | Apple ecosystem |
+| `avi` | `mp3` | Legacy hardware |
+| `flv` | `aac` | Legacy web |
+
+### `config` — Set or view download path
+```bash
+python fm-dlp.py config <path>   # Set directory
+python fm-dlp.py config          # View current setting
+```
+
+### `update` — Update the tool
+```bash
+python fm-dlp.py update          # Pull latest version via Git
+```
+Requires Git to be installed and the project to be a clone of the repository.
+
+## 📁 Project Structure
+```
+fm-dlp/
+├── fm-dlp.py               # CLI entry point (cyclopts App)
+├── config.json             # Persistent download path storage
+├── pyproject.toml          # Project metadata & dependencies
+├── README.md               # Project documentation
+└── modules/
+    ├── __init__.py          # Package initializer
+    ├── commands/
+    │   ├── __init__.py
+    │   ├── search.py       # YouTube & YT Music search (tracks & albums)
+    │   └── download.py     # Async audio/video download engine (yt-dlp)
+    └── utils/
+        ├── __init__.py
+        ├── configer.py     # JSON config manager (read/write)
+        ├── validator.py    # Input validation (URLs, codecs, proxies, bitrate)
+        │                   # + system dependency checks (ffmpeg, git, yt-dlp)
+        ├── update.py       # Self-update via Git (fetch + hard reset)
+        └── colors.py       # Terminal ANSI color constants
+```
+
+## 🔧 Requirements
+
+| Dependency | Purpose |
+|------------|---------|
+| `yt-dlp` | YouTube extraction & download |
+| `mutagen` | Audio metadata tagging |
+| `ytmusicapi` | YouTube Music API |
+| `cyclopts` | CLI framework |
+| **FFmpeg** | Audio/video conversion (system) |
+| **Git** | Self-update mechanism (system) |
+
+## 📖 Examples
+
+### Search Examples
+```bash
+# Search for tracks on YouTube Music
+python fm-dlp.py search "Sewerslvt" --limit 10 --platform yt-music
+
+# Search for albums on YouTube Music
+python fm-dlp.py search "usedcvnt" --platform yt-music --type album
+
+# Search for videos on YouTube
+python fm-dlp.py search "breakcore mix" --platform yt-video --limit 5
+
+# Search with proxy
+python fm-dlp.py search "tokyona" --proxy socks5://127.0.0.1:9050
+```
+
+### Download Examples
+
+**Audio:**
+```bash
+# Basic audio download
+python fm-dlp.py download "https://youtu.be/..." --codec flac
+
+# Multiple URLs with custom quality
+python fm-dlp.py download "URL1 URL2 URL3" --codec mp3 --kbps 320
+
+# Lossless download
+python fm-dlp.py download "URL" --codec wav
+```
+
+**Video:**
+```bash
+# Download as MP4
+python fm-dlp.py download "https://youtu.be/..." --codec mp4
+
+# Download as MKV with Opus audio
+python fm-dlp.py download "https://youtu.be/..." --codec mkv
+
+# Download as MOV for Apple devices
+python fm-dlp.py download "https://youtu.be/..." --codec mov
+```
+
+**Advanced:**
+```bash
+# Age-restricted content with cookies
+python fm-dlp.py download "URL" --cookies firefox
+
+# Anonymous download via Tor
+python fm-dlp.py download "URL" --proxy socks5://127.0.0.1:9050
+
+# Quiet mode with increased parallelism
+python fm-dlp.py download "URL1 URL2 URL3 URL4 URL5" --quiet --max-concurrent 10
+```
+
+### Maintenance
+```bash
+# Update to latest version
+python fm-dlp.py update
+```
+
+### Complete Workflow
+```bash
+# 1. Set download location
+python fm-dlp.py config ~/Music
+
+# 2. Search for an album
+python fm-dlp.py search "we had good times together, don't forget that" --limit 1 --type album
+
+# 3. Download audio from album
+python fm-dlp.py download "https://music.youtube.com/playlist?list=OLAK5uy_muvgxae_oLSvDyo0q_zp0JrkBS73nkLMM" --codec flac
+
+# 4. Search and download a video
+python fm-dlp.py search "goreshit" --platform yt-video
+python fm-dlp.py download "https://youtu.be/gnubBJ6dP4g" --codec mkv
+```
+
+## ❓ FAQ
+
+### Why does fm-dlp exist when yt-dlp already downloads audio and video?
+
+Think of fm-dlp as a **purpose-built stereo system**, while yt-dlp is a universal
+multimedia Swiss Army knife. Yes, yt-dlp can extract audio, embed metadata,
+and download video, but it takes a long string of flags to get there:
+
+```bash
+# Audio with yt-dlp
+yt-dlp -f bestaudio --extract-audio --audio-format mp3 --audio-quality 320k \
+  --embed-metadata --embed-thumbnail -o "~/Music/%(title)s.%(ext)s" "URL"
+
+# Video with yt-dlp
+yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best" --merge-output-format mp4 \
+  -o "~/Videos/%(title)s.%(ext)s" "URL"
+```
+
+fm-dlp wraps all that into a clean, music-focused workflow:
+- **Search** with human-readable, formatted output — no scraping IDs from text dumps
+- **Download audio or video** with a single option — no memorising flag combinations
+- **Cleaner tags** — when used with `search` results, artist and title come from
+  structured music metadata rather than raw video descriptions with channel suffixes
+- **Automatic format selection** — video containers automatically pick the best compatible audio codec
+
+### Why does macOS default to M4A while other platforms default to Opus?
+
+The defaults are chosen to match the **native music player experience** on each
+operating system:
+
+| Platform | Default | Reasoning |
+|----------|---------|-----------|
+| **macOS / iOS** | `m4a` (AAC) | Apple's entire ecosystem — Finder, Music.app, QuickTime, GarageBand — treats M4A/AAC as the first-class audio format. Album artwork, tagging, and playback are seamless. |
+| **Linux / Windows** | `opus` | Opus offers superior perceptual quality at equivalent bitrates. It's the codec modern Android devices, desktop players (VLC, foobar2000, audacious), and browsers use natively. |
+
+You can always override the default with `--codec mp3` (universal, legacy
+hardware), `--codec flac` (lossless archival), or any other supported format.
+
+### What video formats are supported and how do they work?
+
+fm-dlp supports six video containers: `mp4`, `mkv`, `webm`, `mov`, `avi`, and `flv`.
+When you choose a video format, fm-dlp automatically:
+1. Downloads the best available video stream
+2. Selects the optimal audio codec for that container (see mapping table above)
+3. Merges them together using FFmpeg
+
+For example, `--codec mkv` downloads VP9 video + Opus audio and packs them into an MKV container,
+while `--codec mp4` prefers H.264 video + AAC audio for maximum device compatibility.
+
+### Why is metadata embedding only available for audio?
+
+Metadata embedding (title, artist, album, thumbnail) works only with audio codecs
+(`mp3`, `aac`, `flac`, `m4a`, `opus`, `vorbis`, `wav`) using the `mutagen` library.
+Video containers don't get automatic metadata tagging — this keeps the download
+fast and avoids potential issues with video metadata standards.
+
+### How does the update command work?
+
+`fm-dlp update` runs `git pull` inside the project directory. This means:
+- You must have **Git installed** and accessible from the terminal
+- The project must be a **Git clone** (not a downloaded ZIP)
+- It pulls the latest commits from the remote repository
+- No version checking or rollback — it's intentionally simple and transparent
+
+### Why write this in Python instead of something faster?
+
+The initial version was a personal script that solved a daily annoyance: finding
+and tagging high-quality music without fighting CLI flags. Python allowed rapid
+iteration and immediate real-world use.
+
+Most of the actual "work" is performed by highly optimised native code:
+`yt-dlp` for networking, `ffmpeg` (C/ASM) for transcoding. The Python layer
+orchestrates these tools and handles metadata logic in **milliseconds** — the
+network download and ffmpeg encoding dominate execution time regardless of the
+language.
+
+### Does this break YouTube's Terms of Service?
+
+fm-dlp is an educational tool that demonstrates how public APIs and
+open-source software can be combined. You are responsible for ensuring your
+usage complies with the platform's Terms of Service and your local copyright
+laws. Please support artists you enjoy.
+
+## 🐛 Troubleshooting
+
+### Configuration
+| Issue | Solution |
+|-------|----------|
+| **Config file not found** | Run `fm-dlp config /your/download/path` first |
+| **"Invalid path" error** | Ensure the directory exists and is writable |
+| **Config reset after update** | `config.json` is preserved across updates — no action needed |
+
+### Dependencies
+| Issue | Solution |
+|-------|----------|
+| **"FFmpeg is not installed"** | Install FFmpeg and verify: `ffmpeg -version`<br>• macOS: `brew install ffmpeg`<br>• Linux: `sudo apt install ffmpeg`<br>• Windows: `winget install ffmpeg` |
+| **"Git is not installed"** | Required only for `update` command: `git --version` |
+
+### Search Issues
+| Issue | Solution |
+|-------|----------|
+| **Album search returns no results** | Try different `--platform` (`yt-video` vs `yt-music`) or `--type` (`album` vs `track`) |
+| **Too few results** | Increase limit: `--limit 20` |
+| **Wrong content type** | Music search defaults to `track`. Use `--type album` for albums |
+
+### Download Issues
+| Issue | Solution |
+|-------|----------|
+| **Age-restricted video** | Use browser cookies: `--cookies chrome` (or `firefox`, `edge`, `brave`) |
+| **Network blocked / 403 error** | Use a proxy: `--proxy socks5://127.0.0.1:9050` |
+| **Slow downloads** | Increase concurrent downloads: `--max-concurrent 10` |
+| **Audio codec error in video** | Video containers auto-select compatible audio. Use `mp4` or `mkv` for best compatibility |
+| **Video format not supported** | Supported containers: `mp4`, `mkv`, `webm`, `mov`, `avi`, `flv` |
+| **WAV has no metadata** | WAV doesn't support embedded tags. Use `flac` or `m4a` instead |
+| **Codec not available** | yt-dlp selects best available. Try `opus` (best quality) or `mp3` (compatibility) |
+
+### Update Issues
+| Issue | Solution |
+|-------|----------|
+| **"Not a git repository"** | `update` only works if installed via `git clone`. ZIP downloads must be updated manually |
+| **Update fails** | Check internet connection. Force update: `git -C /path/to/fm-dlp fetch origin && git -C /path/to/fm-dlp reset --hard origin/main` |
+
+### Proxy
+| Issue | Solution |
+|-------|----------|
+| **"Invalid proxy URL"** | Format: `protocol://host:port`<br>• HTTP: `http://127.0.0.1:8080`<br>• SOCKS5: `socks5://127.0.0.1:9050` |
+| **Proxy not working with yt-music** | yt-music only supports `http://` and `https://` proxies |
+
+---
+
+### Still stuck?
+Run with verbose output to see detailed errors:
+```bash
+fm-dlp download "URL" --no-quiet
+```
+
+Check yt-dlp version compatibility:
+```bash
+yt-dlp --version
+```
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) file.
+
+## 🙏 Acknowledgments
+
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — YouTube extraction & download engine
+- [ytmusicapi](https://github.com/sigma67/ytmusicapi) — YouTube Music API wrapper
+- [mutagen](https://github.com/quodlibet/mutagen) — Audio metadata tagging
+- [cyclopts](https://github.com/BrianPugh/cyclopts) — Modern CLI framework
+
+## ⚠️ Disclaimer
+
+For educational purposes only. Users are responsible for complying with platform Terms of Service and applicable copyright laws.
+
+---
+
+**Author:** [Fkernel653](https://github.com/Fkernel653)
+**Repository:** [github.com/Fkernel653/fm-dlp](https://github.com/Fkernel653/fm-dlp)