PlaylistForge

PlaylistForge is a Rust command-line and interactive application for downloading a single YouTube video or an entire playlist as MP3 or MP4.

yt-dlp
→ isolated temporary file
→ MP3 conversion or MP4 merge/remux with FFmpeg
→ validation
→ final file

CUDA is not used or required. No NVIDIA GPU is needed. Downloads and conversions use yt-dlp, FFmpeg, and the CPU.

Confirmed features

• Single videos and playlists.
• MP3 output at 128k, 192k, 256k, or 320k.
• MP4 output at up to 480p, 720p, 1080p, 1440p, 2160p, or the best available quality.
• Configurable output directory and sanitized filenames containing the video ID and requested quality.
• Exact resume/skip behavior by video ID, output format, and requested quality.
• Bounded retries, concurrent fragments, and a bounded playlist worker pool.
• auto, safe, balanced, and fast performance profiles with manual overrides.
• Local yt-dlp, FFmpeg, and Deno discovery next to the application, followed by PATH lookup.
• Interactive mode without arguments and CLI mode with arguments.
• Compact progress UI by default, with --verbose / --logs verbose for complete subprocess logs.
• TTY-aware rendering and optional output-folder opening with --open-output.

Automatic configuration uses only the number of logical CPUs. It does not benchmark the network or disk and does not inspect the GPU. Limits are 1–8 jobs, 1–8 fragments per download, 1–16 FFmpeg threads, and 0–10 extra retries. Manual overrides take precedence over the selected profile.

Platform status

Platform	Status
Windows x86_64	Validated locally
Linux x86_64	Build script and CI prepared; not validated locally
macOS x86_64	Build script and CI prepared; not validated locally
macOS Apple Silicon	Native CI and packaging prepared; not validated locally
Linux aarch64	Not supported

A future successful CI job validates the build on that runner, not every possible machine.

Getting started

Official portable packages include yt-dlp, ffmpeg, ffprobe, and a compatible Deno runtime. Deno improves yt-dlp's handling of YouTube JavaScript challenges. A Cargo-built binary can run without Deno, but extraction may be less reliable and some formats may be unavailable.

Windows interactive mode:

.\auto_download_ytb_playlist.exe

Linux and macOS interactive mode:

chmod +x auto_download_ytb_playlist yt-dlp ffmpeg ffprobe deno
./auto_download_ytb_playlist

CLI example:

.\auto_download_ytb_playlist.exe --format mp3 --quality 320k --output downloads --performance auto --jobs 3 --concurrent-fragments 4 --ffmpeg-threads 1 --retries 3 "URL"

CLI options

• --format mp3|mp4
• --quality 128k|192k|256k|320k for MP3, or 480p|720p|1080p|1440p|2160p|best for MP4
• --output PATH
• --performance auto|safe|balanced|fast
• --jobs 1..8
• --concurrent-fragments 1..8
• --ffmpeg-threads 1..16 — MP3 encoding only
• --retries 0..10 — extra attempts after the first
• --use-system-certs — use the system certificate store while keeping TLS verification enabled
• --logs compact|verbose / --verbose — select the console presentation
• --no-color — disable ANSI colors and live redraw
• --open-output — open the output folder after the run
• --help

Typical output paths:

Title [video-id] [320k].mp3
Title [video-id] [1080p].mp4
Playlist title [playlist-id]/01 - Title [video-id] [320k].mp3

The MP4 suffix describes the requested quality; the actual available resolution may be lower.

Installing portable archives

• Windows: extract the ZIP and run the executable from the extracted directory.
• Linux: extract the .tar.gz, grant execute permissions, and review the ldd dependency report from the packaging job.
• macOS: extract the archive and grant execute permissions. The binaries are currently unsigned and not notarized. If you trust the archive, use the one-time approval offered by Gatekeeper. Do not disable Gatekeeper globally.

Building and packaging

The application has no external Rust crate dependencies. Build it with stable Rust and Cargo:

cargo build --release

Actual downloads require yt-dlp and FFmpeg. Portable packages are produced by:

scripts/build-portable.ps1
scripts/build-portable-linux.sh
scripts/build-portable-macos.sh

The scripts record tool versions and SHA-256 hashes. Linux packaging inspects file and ldd. macOS FFmpeg currently comes from Homebrew: its exact version is recorded, but the process is not fully reproducible.

Troubleshooting

• yt-dlp or FFmpeg is missing: place the tools next to PlaylistForge or add them to PATH; these two tools are required.
• Deno is missing: PlaylistForge continues with a warning. Add Deno 2.3.0 or newer next to the executable or to PATH for more reliable YouTube extraction. Official packages already include it.
• SSL errors: try --use-system-certs with a correctly configured local certificate store. TLS verification is never disabled.
• HTTP 403: reduce the performance profile, job count, or fragment count, and update yt-dlp.
• Private or unavailable video: yt-dlp must have the required access. PlaylistForge does not bypass restrictions.
• Existing files: a non-empty file with the same video ID, format, and requested-quality label is skipped.
• macOS Gatekeeper: use one-time approval for a trusted archive; never disable protection globally.
• Linux dependencies: review the packaging job's ldd output.
• JavaScript runtime warnings: official packages bundle Deno and pass its absolute path to every network yt-dlp command. Source builds may provide Deno 2.3.0 or newer; otherwise PlaylistForge continues in reduced-reliability mode.

Legal notice and licenses

Only download content you are authorized to use, and comply with the applicable service terms and copyright laws. PlaylistForge is not presented as a way to bypass access controls or technical protections.

PlaylistForge is licensed under the MIT License. Third-party notices for yt-dlp and the packaged FFmpeg build are stored in portable/licenses/. Packaging refuses to create a redistributable archive if the matching FFmpeg license cannot be found.