Download audio from YouTube by searching with human-readable titles, then convert the best audio stream to MP3 with metadata and thumbnails.

This repo originally shipped as a Python 2 + youtube-dl + Google Data API script. That version is not viable anymore:

• it does not parse on Python 3
• it hardcodes personal file paths
• it requires a Google API key for a task that yt-dlp can already handle
• the dependency stack is stale enough to break on a current machine

The current version replaces that with a Python 3 implementation built on yt-dlp.

• reads a newline-delimited titles file such as titles.txt
• searches YouTube for the first result matching each title
• downloads the best available audio
• converts the result to MP3
• embeds metadata and thumbnails
• records successful video IDs in a download archive
• writes failed titles to an errors file

There are two entry points:

• list2mp3_seq.py for sequential execution
• list2mp3_mp.py for parallel execution

• Python 3.10+
• ffmpeg available on PATH

Install Python dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Install FFmpeg if needed:

sudo apt update
sudo apt install -y ffmpeg

Sequential:

python3 list2mp3_seq.py \
  --titles-file titles.txt \
  --download-dir downloads

Parallel:

python3 list2mp3_mp.py \
  --titles-file titles.txt \
  --download-dir downloads \
  --jobs 8

Dry run to resolve matches without downloading:

python3 list2mp3_mp.py --dry-run

Both entry points support:

• --titles-file
• --download-dir
• --errors-file
• --archive-file
• --dry-run

The parallel version also accepts:

• --jobs

The original "multiprocess" version was not actually production-grade parallel download code. It relied on:

• a global YouTube API client
• stale Python 2 exception handling
• a shared archive file without safe coordination

The current implementation uses a worker pool while coordinating duplicate video IDs in-memory for the current run. That avoids multiple workers downloading the same resolved video at once and appends archive entries only after successful downloads.

Use one query per line:

Ed Sheeran - Happier [Official Audio]
Daft Punk - Something About Us
Radiohead - No Surprises

More specific titles usually produce better first-result matches.

By default the scripts use:

• titles.txt
• downloads/
• errors.txt
• archive.txt

archive.txt stores entries in a yt-dlp-compatible style:

youtube 8TpcBDJZsJA

dir2list.py scans directories non-recursively and converts local video filenames into a titles file:

python3 dir2list.py ~/Videos ~/MoreVideos --output titles.txt

Downloading copyrighted content may violate the law, platform rules, or license terms depending on your jurisdiction and the content involved. Use the tool only where you have the right to access, download, and convert the media.