TagTuner music player

TagTuner is a device that enables you to access music playlists or albums using NFC tags.
It only works when integrated with Home Assistant media players. Music Assistant music library is optional. This setup seamlessly blends your digital only music collection with the tactile experience of playing a physical record, tape or cd.
Physical music media offer several advantages:

• it’s easy
• it’s fast
• it’s inclusive

TagTuner is made with ESPHome and includes

• an NFC reader
• a dial with a button
• a LED light

All of this is housed in a sleek, custom design case only 16mm high

Here is an exploded view of the TagTuner 3D model with a round tag card

TagTuner is a device approved by the Made for ESPHome program.

Check out also the TagTuner on HA Voice PE version

Getting started

To start using TagTuner, you’ll need the following:

• Home Assistant 2025.12.x
• Music Assistant 2.7.x or Sonos speaker
• configured MAss music library and/or a streaming subscription
• TagTuner device configured in HAss
• any NFC tags or programmable NTAG213/215/216

Assuming you already have Home Assistant (HAss) with Music Assistant (MAss) or Sonos set up and running, TagTuner supports Improv via Serial and Improv via BLE for Wi-Fi configuration.
Home Assistant will automatically detect your new TagTuner as ESPhome device.
In the Diagnostic panel of TagTuner you can see detailed state of your device.
Simply place any NFC tag and watch Status messages.

Build your own TagTuner

Case

Custom model cases are print-ready

• printables
• ko-fi/shop

Choose and print your enclosure with preferred colors and surface patterns.
I suggest a cool-white (signal white) base and a dark front plate with a nice carbon fibre pattern.

BOM for XIAO-Custom version

• XIAO esp32-c6 controller with built-in antenna
• pn532 NFC reader
• grove angle connectors
• grove cables
• hw040 rotary encoder
• dupont cables for hw040
• M2.5 10mm screws

Wiring XIAO-Custom

pn532 connector (use grove cable):

• GND: GND (bottom cable)
• VCC: VBUS (+5V, bottom cable)
• SDA/TXD: D4
• SCL/RXD: D5

hw040 connector (use dupont cable):

• CLK: D8
• DT: D9
• SW: D10
• +: 3V3 (+3.3V)
• GND: GND

Route and solder the VCC (red) and GND (white) wires along the bottom side of XIAO to ensure the front LED remains unobstructed.

XIAO will fit perfectly into the bottom part braces

Built-in LED is used as confirmation light. Print the led peg with clear filament and it will give great results
(TODO: XIAO front plate LED pic)

I prefer soldering the grove angle connector to the PN532 NFC board

Just use the force ;-)

Remember to set the DIP switches to 10 to enable I2C. Correct switches position for I2c is marked by yellow lines.

Everything will fit into the enclosure.

Use 10mm M2.5 screws (nfc board, volume encoder, front plate).

Firmware

• quick start: use pre-built firmware with ESP Web Tools powered installer here
• tagtuner-XIAO-custom.yaml: XIAO ESP32-C6 with HW-040 rotary encoder and button. Bluetooth & BLE proxy, ESP-IDF framework

Other options

• D1 mini: TagTuner Custom1 based on the ESP32 D1 Mini; previously my preferred version but dropped in favor of the XIAO because of the poor quality of available D1 boards
• HA Voice PE version: TagTuner on HA Voice PE device
• tagtuner-for-tagreader.yaml: TagTuner firmware for Adonno tagreader device (buzzer only, no led support)
• Atom version: based on m5stack Atom Echo and grove connectors; free model case but much thicker (23.5mm)
• Compact Case: card-sized case by Youddha (thank you!)

Using TagTuner

TagTuner relies heavily on Home Assistant automation. To get it working, import TagTuner for HAss blueprint

Create automation with this blueprint.
Select your TagTuner device (you can have more than one!) and media player that will be your speaker

I do a monthly updates of the blueprint. You can watch my repo to get email notifications.
Current list of features:

• separate settings for MAss player and HAss player (http sources). If you don’t need double setting, just set the same player in both
• Stop music on tag removed: choose if you want this
• Announce every playlist: you can choose your TTS engine and TagTuner will use your speaker to read artist and playlist names
• Shuffle every playlist: choose if you want this. You can also add ‘/shuffle’ (without quotes or spaces) at the end of the source URI to shuffle just this album
• Volume limiter: to limit the maximum volume set with TagTuner knob (kids friendly!)
• Default volume on start playing
• Notify about version mismatch: shoose if you want HA dashboard notification that your blueprint version is to new vs your TagTuner yaml firmware. Currently there are no breaking changes so this is future proofing the blueprint and your experience

Playing music

Place your tag flat on the TagTuner or use the slot to position it nicely.
TagTuner will read the tag and send the playlist information to Home Assistant. Using automation, HAss will play music on the speaker you’ve set up for this TagTuner.

Button operations

undefinedSingle click: next
undefinedDouble click: play/pause
undefinedLong click (>1s): mute/unmute
undefinedTriple click: previous

Volume control

Rotate the dial left: volume down
Rotate the dial right: volume upundefined

Feedback

Watch the LED light in the button:
undefinedblink: operation confirmed
undefinedflashing constant: writing operation in progress
undefinedflashing few times: operation success

XIAO-Custom has a single color led so it’s only blinking but it’s really easy to understand what’s going on. Use HAss device Diagnostic dashboard in case you would need status info.

Diagnostic

Check the Diagnostic->Status messages on the device page in Home Assistant.
The ladybug icon is your guide.

How to get tags for TagTuner

Upcycle tags you already have

Use whatever nfc tags you have that work with PN532.
Simply scan them with TagTuner and check you HA tags panel.
Try Amiibos, NFC rings, work badges, etc.
You can even recycle a Sonicare toothbrush head 🤙

Check the read-only tags section below.

Buy tags

Choose NTAG215 (504 bytes) or NTAG216 (888 bytes) tags if you want to include the playlist name and artist. Otherwise, NTAG213 (144 bytes) will suffice for just links to playlists

• Plain white cards
• Wooden cards
• Round stickers

Record-like cards can be printed (model file included) or you can buy those nice looking vinyl coasters. Just remember to put NFC stickers on them ;-)
Stickers can be used with 3d printed cards or any other object you can place on your TagTuner to play music.
I use Canon KC-18IF card-sized labels to customize my wooden NFC cards.

Program tags for Music Assistant

If your speaker is one of Music Assistant media players, your tags need to have a MAss URI.
Here you can find instructions on how to get URI for the playlist or album you want. In the latest versions you can basically copy the URI directly from the Provider details section for that media.

On the TagTuner device page, you’ll find all the fileds nesesary to write the playlist URI to your tag

Minimum information needed is URI.
Fill in the Playlist URI -> click Write Tag -> LED starts flashing red -> Place the tag on TagTuner
Successful writing will be confirmed with green light.
Check Diagnostic->Status for any additional information.

Program tags for Sonos

If your speaker is Sonos media player, your tags can have a plain HTTP playlist URL.
Here you can find instructions on how to get the album or playlist url for Apple Music. Just copy it.
It should work the same with Spotify

On the TagTuner device page, you’ll find all the fileds nesesary to write the playlist URL (URI) to your tag

Minimum information needed is URL.
Fill in the Playlist URL -> click Write Tag -> LED starts flashing red -> Place the tag on TagTuner
Successful writing will be confirmed with green light.
Check Diagnostic->Status for any additional information.

Other options

You can also write your tags with any NFC NDEF tag writer, such as NXP NFC TagWriter for iOS or Android

or

More options

for Sonos

You can also play any Sonos app favorite playlist, album, or station!
Simply write the name of the playlist or station exactly as it appears in the Sonos app.
Then, enter sonos-2:// in the URI field.

for read-only tags

If you have any read-only tags that can be read by TagTuner (give it a try to check), you can use them too!
To set the playlist URL, place it as the name of the tag in HAss panel

Any tag id read by TagTuner will be pushed to HAss blueprint automation.

Help

OK, I can try. Please choose your preferred way of communication

• HAss community
• MAss discord
• reddit

A little history

It all began one day back in 2022.
I’ve seen all those cool NFC jukebox projects but found myself too lazy to automate each tag individually.
So, I contributed to the Adonno tagreader project to enable it to push playlist URLs as HAss events.
Here’s original story posted on Home Assistant communities.
Since then, TagTuner has been completely refactored and physically redesigned.

Disclaimer

All of this is my personal hobby project, available for free download and personal use. If you’d like to support me with a coffee, beer, filament, or electronic parts, feel free to use paypal.me/lukagra or ko-fi.com/lukagra

Links to parts listed above are affiliate links, which allow me to earn a small commission from your purchase. Thank you! 🙏

This work, including yaml files, 3d model (Atom version) and documentation, is licensed under
Creative Commons (4.0 International License) Attribution—Noncommercial—Share Alike

ESPhome components modifications are licensed under ESPHome license