{"id":27013982,"url":"https://github.com/tmunz/musicbox","last_synced_at":"2026-05-06T02:36:02.245Z","repository":{"id":273436365,"uuid":"919714385","full_name":"tmunz/musicbox","owner":"tmunz","description":"Python Service sending NTag and RemoteControl information via Mqtt to Home Assistant","archived":false,"fork":false,"pushed_at":"2025-04-03T21:00:42.000Z","size":27,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-13T19:31:40.193Z","etag":null,"topics":["diy","ha","homeassistant","mfrc522","mpd","mqtt","musicbox","ndef","ndef-nfc","ndef-record","ntag","ntag213","ntag215","ntag216","python","raspberry-pi","raspberrypi","remote-control","spotify"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tmunz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-20T21:47:56.000Z","updated_at":"2025-04-03T21:00:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"97c279c3-3c9a-4d20-a9e5-b57b4e823dc8","html_url":"https://github.com/tmunz/musicbox","commit_stats":null,"previous_names":["tmunz/musicbox"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tmunz/musicbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmunz%2Fmusicbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmunz%2Fmusicbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmunz%2Fmusicbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmunz%2Fmusicbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmunz","download_url":"https://codeload.github.com/tmunz/musicbox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmunz%2Fmusicbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279016916,"owners_count":26085888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diy","ha","homeassistant","mfrc522","mpd","mqtt","musicbox","ndef","ndef-nfc","ndef-record","ntag","ntag213","ntag215","ntag216","python","raspberry-pi","raspberrypi","remote-control","spotify"],"created_at":"2025-04-04T13:19:25.544Z","updated_at":"2025-10-13T19:32:19.935Z","avatar_url":"https://github.com/tmunz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# musicbox\nThis project is an open-source solution for media playback with **NTAGs**, **MQTT commands**, and providing an optional **web interface**. Designed to integrate seamlessly with platforms like **Home Assistant**, it offers a fun and flexible way to control smart devices or trigger automations using NFC tags and remote controls. \nYou are welcome to incorporate parts of this project into your own and customize the code to suit your requirements.\n\n---\n\n## **Features**\n\n### 1. **NTAG Reading and Writing with MFRC522**\nThis project utilizes the **MFRC522** RFID reader to read and write NTAGs in the NFC Data Exchange Format (NDEF).\n\n### 2. **MQTT Integration**\nThe project can communicate with MQTT-compatible (e.g. Home Assistant) applications by publishing commands to a configurable MQTT topic. Common use cases include:\n- Controlling media playback.\n- Controlling volume and go to previous or next media.\n\n### 3. **Optional Web Interface**\nA lightweight web interface enhances the project with features like:\n- **Status Monitoring**: View the system state and active commands.\n- **Tag Management**: Write identifiers to NTAGs, including converting Spotify URLs into the proposed format (`spotify:album:\u003cID\u003e`).\n- **Debugging**: Monitor logs and commands for troubleshooting.\n\n### 4. **Remote Control Support**\nThe project can capture commands from remote controls using Linux input handling (evdev) and publish them to MQTT. This enables integration of physical remote buttons into the musicbox setup.\n\n---\n\n## **Use Cases**\n- **Media Playback**: Use NFC tags to trigger specific albums, playlists, or other media via platforms like Spotify.\n- **Home Automation**: Assign tags to control lights, scenes, or custom scripts in Home Assistant.\n- **Child-Friendly Control**: Provide an interactive way for kids to trigger their favorite actions using NFC tags.\n- **Remote Control Integration**: Repurpose existing remotes to send MQTT commands or trigger automations.\n\n---\n\n## **Home Assistant Integration**\nExample configurations are included to help you integrate the project with Home Assistant. These examples demonstrate how to:\n- Respond to MQTT commands for media playback, automations, or other actions.\n- Use NTAGs as automation triggers (e.g., play a Spotify album, adjust lighting).\n- Configure MQTT topics and payloads for seamless communication.\n- The example workflow shows that the setup can be used with the data written on tags as well as managed in Home Assistant Tag page by setting the name to the ID (proposed format is `\u003cDOMAIN\u003e:\u003cTYPE\u003e:\u003cID\u003e`, examples would be `spotify:album:7MSnJiBuHQMTckW9K3L6bu` or `mpd:playlist:depeche_mode_rarities`). \n\n---\n\n## **Getting Started**\n\n### **Hardware Requirements**\n- MFRC522 RFID reader.\n- NTAG-compatible NFC tags.\n- (Optional) A remote control compatible with Linux input handling.\n\n### **Software Requirements**\n- Python 3.x.\n- MQTT broker (e.g., Mosquitto).\n- (Optional) Home Assistant for advanced automations.\n\n### **Setup**\n\nThis guide provides examples for step-by-step instructions for setting up MusicBox, including its dependencies, environment, systemd service, and integration with Spotify (Raspotify) and Music Player Daemon (MPD). Adjust the steps according to your needs.\n\n---\n\n#### **1. Installation and Environment Setup**\n\nNavigate to the MusicBox directory, create a Python virtual environment, and install the required dependencies:\n\n```bash\ncd /usr/local/bin/musicbox/ # or choose another designate folder\n# Now, copy the code of the src folder into the designated folder and modify the run.sh script to match your environment and needs.\npython3 -m venv env-musicbox # create virtual python environment\nsudo chown -R $USER:$USER ./env-musicbox  # Run this if you encounter permission issues\nsource env-musicbox/bin/activate\npip install -r requirements.txt\n```\n\n---\n\n#### **2. Setting Up the Systemd Service**\n\nYou can use Systemd to start the service automatically at each startup. Create a new service file and user with the following commands:\n\n**User**\n```bash\nsudo useradd -m -s /bin/bash musicbox\nsudo passwd musicbox\nsudo usermod -aG gpio musicbox # GPIO access to RFID Reader, assuming using a MFRC522 over GPIO\nsudo usermod -aG spi musicbox # SPI access to RFID Reader\nsudo usermod -aG input musicbox # needed when using a remote controller\nsudo chown musicbox:musicbox /usr/local/bin/musicbox/run.sh\n```\n\n**Service**\n```bash\ncat \u003c\u003cEOF | sudo tee /etc/systemd/system/musicbox.service\n[Unit]\nDescription=MusicBox\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nExecStart=/usr/local/bin/musicbox/run.sh\nWorkingDirectory=/usr/local/bin/musicbox\nStandardOutput=journal\nStandardError=journal\nRestart=always\nUser=musicbox\n\n[Install]\nWantedBy=multi-user.target\nEOF\n```\n\n**Reload and check Service**\n\nReload systemd to recognize the new service, enable it to start at boot, and start it immediately:\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable musicbox.service\nsudo systemctl start musicbox.service\n```\n\nCheck the status of the service or view recent logs for debugging:\n```bash\nsudo systemctl status musicbox.service\nsudo journalctl -u musicbox.service --since \"10 minutes ago\"\n```\n\n### The following steps are optional if you want to use your musicbox also as speaker\n\n#### **3. Spotify Integration (Raspotify)**\n\nInstall and configure Raspotify to enable Spotify playback, for further details see [Raspotify Github Repository](https://github.com/dtcooper/raspotify):\n\n```bash\ncurl -sL https://dtcooper.github.io/raspotify/install.sh | sh\nsudo nano /etc/raspotify/conf\n```\n\nIn the configuration file, add or modify the following line if you want to use the RaspberryPi audio output (default is hdmi):\n\n```\nLIBRESPOT_DEVICE=hw:CARD=Headphones,DEV=0\n```\n\nEnable Raspotify to start at boot:\n\n```bash\nsudo systemctl enable raspotify\n```\n\n---\n\n#### **4. Music Player Daemon (MPD) Setup**\n\nInstall MPD and ALSA utilities, then configure MPD for audio playback:\n\n```bash\nsudo apt update\nsudo apt install alsa-utils mpd mpc\nsudo nano /etc/mpd.conf\n```\n\nModify the `audio_output` section in the configuration file if you want to use the RaspberryPi audio output (default is hdmi):\n\n```ini\naudio_output {\n    type            \"alsa\"\n    name            \"Raspberry Pi Headphones\"\n    device          \"hw:2,0\"   # Use the device from the `aplay -l` output\n    mixer_type      \"software\"\n}\n```\n\nEnable MPD to start at boot:\n\n```bash\nsudo systemctl enable mpd\n```\n\n---\n\nWith these steps, you will have MusicBox system ready to use with Home Assistant. You need to configure Spotify, and/or MPD as well as the automations (examples for different steps can be found in the [HA-Folder](./ha)). For troubleshooting or additional configuration options, refer to the documentation for each component.\n\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmunz%2Fmusicbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmunz%2Fmusicbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmunz%2Fmusicbox/lists"}