BeoRadio Scrobbler 🎵

Problem Statement

When Spotify released Wrapped for the first time, I was beaten in minutes listened to music by far by my friends.

But, I was actually listening to music on the radio all day long.

That left me wondering: How do I track my music listening record besides Spotify? I liked the idea of analyzing my listening behaviour, but I had heard of scrobblers and never felt the urge to connect to Last.fm.

Every year since, when a new Wrapped is published, I have to think again about my "problem".

Timeline 🗓️

timeline
    title Project Development Journey
    
    section Initial Idea
        Spotify Wrapped Released : Idea born
                                  : Get radio tracks to Spotify?
                                  : Run songs on headless system?
                                  : ...what a waste of energy 💡
    
    section December 2025
        Dec 23rd : Lying in bed googling stuff
                 : Wrapped haunting me again
                 : Musical age: 66 years
                 : Behind friends in minutes
                 : Losing street credibility 😢
        
        Dec 24th : Starting tests on Christmas Eve
                 : Working better than expected! 🎄
                 : API understood
                 : Getting artist and title info
                 : First scrobble with pylast
                 : All work done by pylast library
        
        Dec 25th : Kids playing with new toys
                 : Scrobbling works! 🎁
                 : Minor flaws fixed
                 : Exception handling added
                 : Local work complete
                 : Next: Docker, then Unraid
        
        Dec 26th-30th : Dockerfile creation
                      : Publishing to Docker Hub
                      : GitHub Actions setup
                      : Much harder than the code! 🐳

Alternative Timeline View:

🌟 Initial Idea → When was Wrapped released the first time!? Idea was born: Get Radio tracks to Spotify, run the Songs on a headless system...what a waste of energy.

📅 Dec 23, 2025 → Lying in bed googling stuff...Wrapped is asking me again, since my "musical age" is 66. I am again far behind my friends in minutes spent with music, which is unfair, because I am listening to super good stuff all the time, but it is unrecognized, unrecorded...I am losing street credibility.

🎄 Dec 24, 2025 → Starting with some tests while everyone is getting ready for Christmas Eve, working better than expected! API is understood and workflow is getting artist and title information. First scrobble is placed with pylast library. No efforts for me, all the work done by pylast. Time saved.

🎁 Dec 25, 2025 → While the kids are playing with their new toys, scrobbling works with some minor (?) flaws. Code needs to wait here for a second and adding exceptions there is doing the trick. Locally my work is done, next step docker, then unraid.

🐳 Dec 26-30, 2025 → Dockerfile, publishing to Docker Hub, using DHI, getting GitHub Actions working properly, makes me forget how easy the first part was.

Installation

This installation guide is provided to you by github copilot:

Installation Guide - BEO Radio Scrobbler

This guide covers two methods to install and run the BEO Radio Scrobbler: using uv (modern Python package manager) or running as a Docker container.

Prerequisites

Python 3.11 or higher (for uv installation)
Docker (for Docker installation)
Last.fm account with API credentials
Bang & Olufsen device on your network

Method 1: Installation with uv

uv is a fast Python package installer and resolver.

Step 1: Install uv

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2: Clone the Repository

git clone https://github.com/CaptainPimpJr/beo_radio_scrobbler.git
cd beo_radio_scrobbler

Step 3: Create Environment Variables

Create a .env file in appdata/config/:

# . env file
LASTFM_API_KEY=your_lastfm_api_key
LASTFM_API_SECRET=your_lastfm_api_secret
LASTFM_USERNAME=your_lastfm_username
LASTFM_PASSWORD=your_lastfm_password
LOCAL_TIMEZONE=Europe/Berlin
RUN_MODE=production
BEO_IP=192.168.1.100
LOGLEVEL=INFO

Environment Variables Explained:

LASTFM_API_KEY: Your Last.fm API key (get from https://www.last.fm/api/account/create)
LASTFM_API_SECRET: Your Last.fm API secret
LASTFM_USERNAME: Your Last.fm username
LASTFM_PASSWORD: Your Last.fm password
LOCAL_TIMEZONE: Your timezone (e.g., UTC, Europe/Berlin, America/New_York)
RUN_MODE: Operation mode (production, detect, detect_smpl, or notify_me)
BEO_IP: IP address of your Bang & Olufsen device
LOGLEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)

Step 4: Sync Dependencies

uv sync

This will create a virtual environment and install all dependencies.

Step 5: Run the Application

# Activate the virtual environment
source .venv/bin/activate  # On Linux/macOS
# or
. venv\Scripts\activate  # On Windows

# Run the scrobbler
python -m beo_radio_scrobbler

# Or use the CLI entry point
beo-radio-scrobbler

Step 6: Run as a Background Service (Optional)

For Linux systems with systemd, create a service file:

sudo nano /etc/systemd/system/beo-radio-scrobbler.service

Add the following content (adjust paths):

[Unit]
Description=BEO Radio Scrobbler
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/path/to/beo_radio_scrobbler
Environment="PATH=/path/to/beo_radio_scrobbler/. venv/bin"
ExecStart=/path/to/beo_radio_scrobbler/.venv/bin/python -m beo_radio_scrobbler
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable beo-radio-scrobbler
sudo systemctl start beo-radio-scrobbler
sudo systemctl status beo-radio-scrobbler

Method 2: Docker Installation

Step 1: Clone the Repository

git clone https://github.com/CaptainPimpJr/beo_radio_scrobbler.git
cd beo_radio_scrobbler

Step 2: Build the Docker Image

docker build -t beo-radio-scrobbler .

Step 3: Run the Container

Option A: Using Environment Variables

docker run -d \
  --name beo-radio-scrobbler \
  --restart unless-stopped \
  -e LASTFM_API_KEY=your_lastfm_api_key \
  -e LASTFM_API_SECRET=your_lastfm_api_secret \
  -e LASTFM_USERNAME=your_lastfm_username \
  -e LASTFM_PASSWORD=your_lastfm_password \
  -e LOCAL_TIMEZONE=Europe/Berlin \
  -e RUN_MODE=production \
  -e BEO_IP=192.168.1.100 \
  -e LOGLEVEL=INFO \
  -v $(pwd)/appdata:/app/appdata \
  beo-radio-scrobbler

Option B: Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  beo-radio-scrobbler:
    build: .
    container_name: beo-radio-scrobbler
    restart: unless-stopped
    environment:
      - LASTFM_API_KEY=your_lastfm_api_key
      - LASTFM_API_SECRET=your_lastfm_api_secret
      - LASTFM_USERNAME=your_lastfm_username
      - LASTFM_PASSWORD=your_lastfm_password
      - LOCAL_TIMEZONE=Europe/Berlin
      - RUN_MODE=production
      - BEO_IP=192.168.1.100
      - LOGLEVEL=INFO
    volumes: 
      - ./appdata:/app/appdata
    network_mode: host  # Required to access local network devices

Option A+ & B+: .env. in config folder

Create a .env file (instructions above) and place it inside appdata/config/. Where appdata/ is defined by '-v' of 'OPTION A' or volumes of 'OPTION B'

Then run:

docker-compose up -d

Step 4: View Logs

# Docker run
docker logs -f beo-radio-scrobbler

# Docker Compose
docker-compose logs -f

Or check logs folder.

Step 5: Stop the Container

# Docker run
docker stop beo-radio-scrobbler

# Docker Compose
docker-compose down

Run Modes

The RUN_MODE environment variable controls how the application behaves:

production: Continuously scrobbles tracks to Last.fm (recommended for 24/7 operation)
detect: Detects one track and exits (useful for testing)
notify_me: Notification mode for debugging

Log Files

Logs are stored in the appdata/logs/ directory:

log_radio_scrobbler.log: Main application log (rotated daily, kept for 7 days)
log_scrobbles.log: Scrobble history (production mode, kept for 5 years)
log_detections.log: Detection log (detect modes, kept for 1 week)
log_notifications.log: Notification log (notify_me mode, kept for 7 days)

Troubleshooting

Can't Find Bang & Olufsen Device

Ensure your device is powered on and connected to the network
Verify the IP address in your environment variables
Check that your Docker container has network_mode: host (for Docker)

Authentication Errors with Last.fm

Verify your API credentials are correct
Check that you've created an API account at https://www.last.fm/api/account/create

Application Exits Immediately

Check the logs in appdata/logs/log_radio_scrobbler.log
Ensure all required environment variables are set
Verify your RUN_MODE setting (use production for continuous operation)

Unraid Installation (Coming Soon)

Docker installation on Unraid will be supported through Community Applications once the project is published.

Documentation 📚

For more detailed information, check out these documentation files:

Run Modes - Different operation modes (production, detect, detect_smpl, notify_me)
Feature Requests - Planned features and how to contribute
How-Tos - Guides and tutorials for common tasks

Credits & Acknowledgments

Initial proof of work written using requests and pylast

Third Party Libraries used:

pylast - Python library for Last.fm scrobbling
BeoNetRemote Client API - Bang & Olufsen's API for third-party integration
- API Documentation
uv - An extremely fast Python package installer and resolver
Astral UV Docker Example - Dockerfile template and basic setup
python-dotenv - loading .env file
Arrow (Apache 2.0) - Better dates and times for Python
Loguru (MIT) - Python logging made simple
Pydantic (MIT) - Data validation using Python type hints
Requests (Apache 2.0) - HTTP library for Python
PyYAML (MIT) - YAML parser and emitter for Python
AI Assistance:
- Static if-else cases improved with Claude Sonnet 4.5
- Project structure modernized with GitHub Copilot
- This README enhanced with GitHub Copilot 🤖

Supported Devices

Copied from B&O documentation (B&O 3rd Party Integration):

Bang & Olufsen Audio Systems: Beosound Stage Beosound 35 Beosound Essence 2nd Gen Beosound Core Beosound Shape Beosound Edge Beosound 1 1st / 2nd Gen Beosound 2 1st / 2nd Gen Beolink Converter NL/ML Beoplay A9 2nd / 3rd / 4th Gen Beoplay A6 Beoplay M5 Beoplay M3

Bang & Olufsen Active Loudspeakers: BeoLab 90 BeoLab 50

Mozart API - recent Bang & Olufsen Models

I do not think I want to add a "Buy me a ~~coffee~~ new B&O Speaker"-Button.
But if you insist on supporting with a replacement for my Beosound 1, open an issue in github...
I will add Mozart API as soon as I have replaced my Beosound 1 (which is not planned), or I have access to a Mozart API supporting device.

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.github/workflows		.github/workflows
docs		docs
logo		logo
sample-data		sample-data
src/beo_radio_scrobbler		src/beo_radio_scrobbler
.dockerignore		.dockerignore
.gitignore		.gitignore
.python-version		.python-version
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

BeoRadio Scrobbler 🎵

Problem Statement

Timeline 🗓️

Installation

Installation Guide - BEO Radio Scrobbler

Prerequisites

Method 1: Installation with uv

Step 1: Install uv

Step 2: Clone the Repository

Step 3: Create Environment Variables

Step 4: Sync Dependencies

Step 5: Run the Application

Step 6: Run as a Background Service (Optional)

Method 2: Docker Installation

Step 1: Clone the Repository

Step 2: Build the Docker Image

Step 3: Run the Container

Option A: Using Environment Variables

Option B: Using Docker Compose

Option A+ & B+: .env. in config folder

Step 4: View Logs

Step 5: Stop the Container

Run Modes

Log Files

Troubleshooting

Can't Find Bang & Olufsen Device

Authentication Errors with Last.fm

Application Exits Immediately

Unraid Installation (Coming Soon)

Documentation 📚

Credits & Acknowledgments

Third Party Libraries used:

Supported Devices

Mozart API - recent Bang & Olufsen Models

did something stupid and corrupted the Docker Image with latest tag. Push to Main

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages