fiatcode/site
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

blog: building a self-hosted music library

Browse source
This commit is contained in:
fiatcode 2026-03-18 16:26:37 +07:00
parent fb67572fda
commit 26d7d217dc
No known key found for this signature in database
GPG key ID: A09C05FF07C009B5
2 changed files with 310 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

309
src/content/blog/building-my-own-self-hosted-music-library.md Normal file
View file

@ -0,0 +1,309 @@
---
title: "Building My Own Self-Hosted Music Library"
description: "From format wars to streaming anywhere, on my own terms"
date: 2026-03-18T16:18:00+07:00
draft: false
tags:
- linux
- self-hosting
- music
- open-source
---
There's a specific kind of dissatisfaction that comes with streaming services. The music is there, the app is polished, but none of it is really _yours_. The moment you stop paying, it disappears. The algorithm decides what comes next. Your listening history is someone else's data.
I had a collection of digital audio files sitting around and I wanted to stream them to my phone from anywhere. Not through Spotify. Not through YouTube Music. Just my files, my server, my player.
So I built the whole pipeline from scratch — format conversion, cover art, playlists, and a self-hosted music server. This post covers all of it.
---
### Why Opus?
Before writing a single line of code, I had to settle the format question.
The short answer: **FLAC** for archival, **Opus** for everyday listening.
FLAC is lossless and open source — the master copy that doesn't throw away any information. Opus is a modern lossy codec that beats MP3 and AAC at equivalent bitrates. At 160kbps, Opus is considered perceptually transparent — meaning in blind listening tests, people can't reliably tell it apart from lossless. I verified this myself using [Spek](https://spek.cc/) to compare spectrograms side-by-side.
The high-frequency rolloff above ~20kHz is visible on the spectrogram, but it's inaudible. No amount of bitrate will make a lossy file match a lossless one on a graph — that's the nature of lossy compression. The point is that 160k Opus sounds identical in practice, and the files are a fraction of the size.
---
### Opus vs OGG — A Quick Detour
These two are often confused, and I ran into this confusion head-first while writing the conversion scripts.
**Opus** is the audio _codec_ — the algorithm that compresses the audio data. **OGG** is a _container format_ — the file wrapper that holds the audio, metadata, and optionally cover art.
The `.opus` extension uses a strict Opus container that only supports audio streams. No embedded images. The `.ogg` extension is more flexible and can carry Opus audio alongside cover art — but FFmpeg's OGG muxer doesn't actually support writing embedded images either. After a lot of trial and error, I gave up on embedded art entirely and went with the standard approach:
- `.opus` files for audio
- `cover.jpg` in each album or single directory
This is actually cleaner anyway. Navidrome picks up folder-level cover art natively, and it works everywhere without container compatibility headaches.
---
### Directory Structure
Each release gets its own directory, whether it's an album, an EP, or a single:
```
Music/
Artist Name/
Album Name/
01 - Track Title.opus
02 - Track Title.opus
cover.jpg
Album Name.m3u
```
Singles follow the same pattern — their own folder, their own `cover.jpg`. No flat dumps. No shared cover art across multiple releases.
---
### The Conversion Pipeline
I wrote two scripts: a Python script that handles the actual conversion and cover art extraction, and a Fish shell function that wraps it for batch use.
#### `flac2opus.py`
The Python script does three things: converts FLAC to Opus using FFmpeg, extracts the embedded cover art from the FLAC file, and saves it as `cover.jpg` in the output directory. It skips cover extraction if a `cover.jpg` already exists, so running it twice on the same directory is safe.
```python
#!/usr/bin/env python3
"""Convert FLAC to Opus with folder-based cover art."""
import sys
import subprocess
from pathlib import Path
def convert(input_path: Path, output_path: Path, bitrate: str = "160k"):
from mutagen.flac import FLAC
flac = FLAC(input_path)
pictures = flac.pictures
subprocess.run([
"ffmpeg", "-i", str(input_path),
"-map", "0:a",
"-c:a", "libopus",
"-b:a", bitrate,
"-y", str(output_path)
], check=True)
if pictures:
import io
from PIL import Image
cover_path = output_path.parent / "cover.jpg"
if not cover_path.exists():
img = Image.open(io.BytesIO(pictures[0].data)).convert("RGB")
w, h = img.size
if w > h:
left = (w - h) // 2
img = img.crop((left, 0, left + h, h))
img.save(cover_path, format="JPEG", quality=90)
print(f" Cover art saved ({img.width}x{img.height})")
else:
print(f" cover.jpg already exists, skipping")
else:
print(f" No cover art found")
if __name__ == "__main__":
if len(sys.argv) < 3:
print("Usage: flac2opus.py <input.flac> <output.opus> [bitrate]")
sys.exit(1)
input_path = Path(sys.argv[1])
output_path = Path(sys.argv[2])
bitrate = sys.argv[3] if len(sys.argv) > 3 else "160k"
convert(input_path, output_path, bitrate)
```
The center-crop on wide images handles YouTube Music thumbnails — they come in as landscape JPEGs, so the script crops them to a square before saving.
Full source: [`scripts/flac2opus.py`](https://codeberg.org/fiatcode/fish/src/branch/main/scripts/flac2opus.py)
#### `flac2opus` Fish function
The Fish function wraps the Python script and adds batch processing, skip detection, and M3U playlist handling per directory. It uses [`uv run --with`](https://docs.astral.sh/uv/guides/scripts/#running-a-script-with-dependencies) to pull in `mutagen` and `pillow` inline — no virtualenv, no manual dependency installation needed. `uv` handles it on the first run and caches it after that.
```fish
function flac2opus --description "Batch convert FLAC to Opus"
set bitrate "160k"
set dir "."
set script ~/.config/fish/scripts/flac2opus.py
for arg in $argv
switch $arg
case '-b' '--bitrate'
set bitrate $argv[(math (contains -i -- $arg $argv) + 1)]
case '*.flac'
set out (string replace -r '\.flac$' '.opus' $arg)
if uv run --with mutagen --with pillow $script $arg $out $bitrate
_flac2opus_handle_m3u (dirname $arg)
end
return
case '*'
set dir $arg
end
end
set files (find $dir -name "*.flac")
set total (count $files)
set current 0
set converted_dirs
for file in $files
set current (math $current + 1)
set out (string replace -r '\.flac$' '.opus' $file)
if test -f $out
echo "[$current/$total] Skipping (already exists): $file"
continue
end
echo "[$current/$total] Converting: $file"
if uv run --with mutagen --with pillow $script $file $out $bitrate
set file_dir (dirname $file)
if not contains $file_dir $converted_dirs
set -a converted_dirs $file_dir
end
end
end
for d in $converted_dirs
_flac2opus_handle_m3u $d
end
echo "Done."
end
function _flac2opus_handle_m3u --description "Create or update M3U playlist in a directory"
set d $argv[1]
set dirname (basename $d)
set existing_m3u (find $d -maxdepth 1 -name "*.m3u" 2>/dev/null | head -1)
if test -n "$existing_m3u"
set new_m3u "$d/$dirname.m3u"
if test "$existing_m3u" != "$new_m3u"
mv $existing_m3u $new_m3u
echo " Renamed M3U: "(basename $existing_m3u)" → $dirname.m3u"
end
sed -i 's/\.flac/.opus/g' $new_m3u
echo " Updated M3U: $dirname.m3u"
else
set opus_files (find $d -maxdepth 1 -name "*.opus" | sort)
if test (count $opus_files) -gt 0
set m3u_path "$d/$dirname.m3u"
echo "#EXTM3U" > $m3u_path
for f in $opus_files
echo (basename $f) >> $m3u_path
end
echo " Created M3U: $dirname.m3u"
end
end
end
```
Full source: [`functions/flac2opus.fish`](https://codeberg.org/fiatcode/fish/src/branch/main/functions/flac2opus.fish)
The M3U logic handles two cases: if a playlist already exists (possibly with a mismatched name or `.flac` references), it renames it to match the directory name and rewrites the extensions. If none exists, it creates one from the converted files.
#### Usage
```fish
flac2opus # convert all FLAC in current directory
flac2opus ~/Music # specific directory
flac2opus song.flac # single file
flac2opus ~/Music -b 192k # custom bitrate
```
After converting, remove the original FLAC files:
```fish
find . -name "*.flac" -print -delete
```
---
### Downloading from YouTube Music
I also wrote `ytm2opus` — a Fish function that downloads from YouTube Music and converts to Opus in one step, using `yt-dlp` under the hood.
It downloads at the highest available source quality (up to 262kbps Opus with premium), converts via `flac2opus.py` (same script, same `uv` inline dependencies), creates a named output directory automatically, saves `cover.jpg`, and generates an M3U playlist. The source is always FLAC — download first at best quality, then re-encode. Never transcode from an already-lossy source.
It uses the `bgutil-ytdlp-pot-provider` plugin for YouTube Music premium quality, and requires a cookies file exported from your browser. Setup instructions are in the script header.
Full source: [`functions/ytm2opus.fish`](https://codeberg.org/fiatcode/fish/src/branch/main/functions/ytm2opus.fish)
```fish
ytm2opus 'https://music.youtube.com/watch?v=...' # single track
ytm2opus 'https://music.youtube.com/playlist?list=...' # album or playlist
ytm2opus -g 'Reggae' 'https://...' # with genre tag
```
---
### Self-Hosting with Navidrome
[Navidrome](https://www.navidrome.org/) is a lightweight, open source music server that implements the Subsonic API. It runs comfortably on a modest VPS, has a clean web UI, and the Subsonic API means a wide choice of Android clients. I use [Musly](https://musly.devid.ink/) on Android.
I run it on my Netcup VPS behind Traefik v3:
```yaml
services:
navidrome:
image: deluan/navidrome:latest
restart: unless-stopped
volumes:
- ./data:/data
- ./music:/music:ro
environment:
ND_MUSICFOLDER: /music
ND_DATAFOLDER: /data
ND_LOGLEVEL: info
ND_SCANSCHEDULE: 1h
ND_SESSIONTIMEOUT: 24h
labels:
- "traefik.enable=true"
- "traefik.http.routers.navidrome.rule=Host(`music.dhemasnurjaya.com`)"
- "traefik.http.routers.navidrome.entrypoints=websecure"
- "traefik.http.routers.navidrome.tls.certresolver=letsencrypt"
- "traefik.http.services.navidrome.loadbalancer.server.port=4533"
networks:
- traefik-proxy
networks:
traefik-proxy:
external: true
```
Upload your music with rsync:
```bash
rsync -avz --progress ~/Music/ user@your-vps:/path/to/navidrome/music/
```
On first run Navidrome will prompt you to create an admin account, then scan the music folder automatically.
---
### The Full Pipeline
Put it all together and it looks like this:
1. Rip or download FLAC (lossless master)
2. Run `flac2opus` — converts to Opus 160k, extracts `cover.jpg`, generates M3U
3. Delete original FLAC files
4. `rsync` to VPS
5. Navidrome picks it up on the next scan
It's not the simplest setup. But it's fully open source, self-hosted, and mine. No subscriptions, no tracking, no algorithm deciding what comes next.
That's the whole point.