Baladio

In French, baladeur is a noun that means a personal stereo, portable music player, or walkman. Baladio is a combination for "baladeur" and "audio". Pronounciation: bah-LAH-dee-oh.

A self-hosted, privacy-first local music player with a glassmorphism UI, spatial audio, and listening analytics.

Features · Getting Started · Screenshots · Keyboard Shortcuts · License

---

Features

• Local-first — plays audio files directly from your machine. No accounts, no streaming, no tracking.
• OS Media Controls — full Media Session API integration for hardware media keys, lock screen playback controls, and native OS overlay metadata (title, artist, cover art).
• Spatial 8D Audio — HRTF-based binaural panning using the Web Audio API. Rotation continues even when the browser tab is in the background (pre-scheduled via AudioContext automation).
• Reverb & Deep effects — convolution reverb with synthetic impulse response + pitch-shifted bass boost.
• Effect Config panel — live-tune 8D speed, reverb wet/dry, and reverb tail.
• Playback speed — 0.5× to 2× with a dedicated speed input that can also accept mouse scroll.
• Listening analytics — home dashboard with top song, top artist, hottest playlist, plays today, artists explored, and day streak. Songs are counted after 20 seconds of playback. History stored server-side in data/history.json.
• Recently Played — horizontal scroll strip on the home page.
• Download with effects — exports the song with the current effect chain applied (8D, reverb, speed) as an mp3 file using OfflineAudioContext.
• Cover art — reads embedded ID3 tags for MP3s, extracts the first frame of MP4s via ffmpeg, automatically fetches high-res artwork from the iTunes API if missing, and supports custom uploaded covers.
• Metadata editing — edit title/artist per song; writes to ID3 tags for MP3s.
• File rename — renames the audio file on disk to {Artist} - {Title}.ext from metadata.
• App Settings Dashboard — centralized configuration for auto-play persistence, UI layouts, cover art priorities, and analytics management.
• Auto-Play Persistence — optionally resume playback automatically when launching the application.
• Synced Lyrics — real-time synchronized lyrics fetched silently in the background via LRCLIB. Displays a scrolling karaoke-style lyrics panel in the fullscreen view. Local .lrc files in the songs directory are prioritised over online lookups.
• Notification Centre — in-app notification system for background events.

Getting Started

1. Clone the repository

git clone https://github.com/rxdwan/baladio.git
cd Baladio

2. Install dependencies

npm install

3. Add your music

Create a songs/ folder one level above Baladio/ and drop your .mp3, .mp4, .flac, .wav, or .ogg files inside:

your-folder/
├── songs/               ← your audio files go here
│   ├── song1.mp3
│   └── song2.flac
└── Baladio/             ← this repo
    ├── covers/          ← auto-created on first run
    ├── data/            ← auto-created on first run
    ├── public/
    ├── server.js
    └── package.json

4. Start the server

node server.js

or

npm start

Then open http://localhost:3000 in your browser.

Optional: Auto-start on login

Windows

Use the included .start-server.vbs script — it launches the server silently with no console window.

Place a shortcut to .start-server.vbs in your Windows Startup folder (Win + R → shell:startup) to auto-start on login.

Use .stop-server.bat to stop the server, and .view_logs.bat to watch live logs.

Linux

Use the included shell scripts:

# Make scripts executable (one-time)
chmod +x start-server.sh stop-server.sh view-logs.sh

# Start the server in the background
./start-server.sh

# Stop the server
./stop-server.sh

# Watch live logs
./view-logs.sh

To auto-start on login, create a systemd user service:

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/baladio.service <<EOF
[Unit]
Description=Baladio Music Server
After=network.target

[Service]
Type=forking
WorkingDirectory=/path/to/music_player
ExecStart=/path/to/music_player/start-server.sh
ExecStop=/path/to/music_player/stop-server.sh
Restart=on-failure

[Install]
WantedBy=default.target
EOF

systemctl --user enable baladio
systemctl --user start baladio

macOS

The same shell scripts work on macOS. To auto-start on login, create a LaunchAgent:

mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/io.baladio.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>          <string>io.baladio</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/node</string>
    <string>/path/to/music_player/server.js</string>
  </array>
  <key>WorkingDirectory</key> <string>/path/to/music_player</string>
  <key>RunAtLoad</key>        <true/>
  <key>KeepAlive</key>        <true/>
  <key>StandardOutPath</key>  <string>/path/to/music_player/logs/server.log</string>
  <key>StandardErrorPath</key><string>/path/to/music_player/logs/server.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/io.baladio.plist

---

Screenshots

Home page
Home Page Light	Home Page Dark
Explore page
Explore Page Light	Explore Page Dark
Playlist page
Playlist Page Light	Playlist Page Light

---

An example playlist

Fullscreen (same for light/dark theme)

---

Keyboard Shortcuts

Discovery Page to download songs, manage cover art, lyrics etc

Notification Centre

Settings Page

Key	Action
Space	Play / Pause
F	Toggle fullscreen
M	Mute / Unmute
Esc	Back
→	Move 5 seconds ahead
←	Move 5 seconds behind
Shift + →	Next track
Shift + ←	Previous track

---

Project Structure

Baladio/
├── covers/
│   ├── songs/           song cover images ({uuid}.jpg)
│   ├── playlists/       playlist cover images ({id}.jpg)
│   └── default_song_cover.jpg
├── data/
│   ├── metadata.json    custom title/artist metadata and filename mappings
│   ├── playlists.json   user created playlists
│   └── history.json     server-side play history
├── public/
│   ├── app.js           all frontend logic
│   ├── index.html       app shell
│   ├── style.css        all styles
│   └── icons.js         SVG icon library
└── server.js            Express API server

---

Acknowledgements

Built with:

• Express.js — Node.js web framework
• music-metadata — audio tag parsing
• node-id3 — MP3 ID3 tag writing
• fluent-ffmpeg — MP4 thumbnail extraction
• better-sqlite3 — local SQLite database for notifications & lyrics cache
• LRCLIB — free, open-source synced lyrics API
• Web Audio API — 8D spatial audio, reverb, and offline rendering

---

License