youtube-to-mp3 [WIP]

Project is still a work in progress. (3-15-2026)

I started refactoring it because this was a prior project that I revamped. If built, it may fail as a forewarning. Life's been crazy for me so haven't returned in awhile. I plan on shifting from using bash logic to doing more in Python syntax.

youtube-to-mp3 downloads audio tracks from YouTube videos, then tags them with user-provided artist and title metadata.

Setup is quick! Set an environment variable YTMP3_OUTPUT_DIR, build the Docker image, and you're ready to start downloading audio from YouTube.

Tech stack

youtube-to-mp3 is open source and is fully containerized!

It uses some great open source software:

• 🐳 Docker
• yt-dlp: Download YouTube video/audio tracks
• ffmpeg: Convert to MP3
• mutagen: Set artist, album and title tags

How does it work?

When you run ytmp3.sh, here's what happens:

1. A Docker container starts up, the directory at $YTMP3_OUTPUT_DIR is mounted as a volume or requests you to input the output directory if not already entered prior.

2. You are prompted for the YouTube URL and the track metadata

3. yt-dlp downloads the best available audio track

4. ffmpeg converts the file to MP3 format

5. mutagen tags the file with the metadata you provided

6. The audio file is moved to the output directory

7. The container is stopped and removed

Quick start

1. Clone this repo

git clone https://github.com/fr0st-chill/youtube-to-mp3.git && cd youtube-to-mp3

2. Build the Docker image

make build

3. In your .bashrc/.zshrc:

• Set YTMP3_OUTPUT_DIR to the directory where you want the audio file to be output
• (Optional) Add the repo to your PATH to be able to run it from anywhere with the command ytmp3

4. Run ytmp3, which will prompt you for the URL of the video and the artist and song metadata. Feel free to examine the script before running to verify authenticity as this app runs through shell scripting.

bash ytmp3

~ $ ytmp3
URL: https://www.youtube.com/watch?v=DY-7adE4EVM
Artist: Parcels
Title: Live at Reeperbahn Festival (2018)

Setting up local discovery in music apps

Most apps look for local audio files in user-specified directories. If you set YTMP3_OUTPUT_DIR to a directory that you want your app to auto-discover from, here's how to get your app configured to look in that directory.