View on GitHub

TagTuner music player

Powered by ESPHome and ESP Web Tools

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 and the 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:

TagTuner is made with ESPHome and includes

All of this is housed in a sleek, custom design case. B71AED4C-08D7-4F52-AC81-285DC6743BAC

Here is an exploded view of the TagTuner 3D model with a round tag card
35F8BCBF-CFB4-4F8B-A8F3-9931829DD101

Installation

You can use the button below to install the pre-built firmware directly to your device via USB from the browser.

Getting started

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

8D01B378-9F47-4FF3-8D71-280600690BE8_1_102_a

Assuming you already have Home Assistant (HAss) with Music Assistant (MAss) or Sonos set up and running, TagTuner supports Improv via Serial for Wi-Fi configuration.
If the Wi-Fi connection is misconfigured, the device will start a Wi-Fi access point, allowing you to connect and set the password.
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.
A2F404BB-9D49-482E-803A-38D39FF03134

1CE9F457-F305-4B00-A466-14A5B7033EF4_1_102_a

Using TagTuner

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

Open your Home Assistant instance and show the blueprint import dialog with a specific blueprint pre-filled.

Create automation with this blueprint.
Select your TagTuner device (you can have more than one!) and media player that will be your speaker
AA88EF99-C0A6-40CE-A8F9-60A0C926069F

B459D72A-3B97-4AFB-BF86-19F3298A521F_1_102_a

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

Single click: play/pause
Double click: next
Long click (>1s): mute/unmute

Volume control

Rotate the dial left: volume down.
Rotate the dial right: volume up.

Feedback

Watch the LED light in the button:
white blink: operation confirmed
flashing red: writing operation in progress
flashing green: writing success

Diagnostic

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

AA29C1D0-BE96-452C-B2BF-FDD8AF05B9F1_1_102_a

How to get tags for TagTuner

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

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.

On the TagTuner device page, you’ll find all the fileds nesesary to write the playlist URI to your tag
38842E5D-4B81-4B88-8815-FD35B67D8357

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
15B48F29-212B-4739-B62A-51EE45BEE9E9

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.
864038B7-970D-4120-AF52-DD503CA11BEE

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
Open your Home Assistant instance and show your tags.
D88754F6-5199-47EA-B71D-4B262B060160

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

8C579E90-8189-417C-8D1E-49295F2F88D9_1_102_a

Build your own TagTuner

Choose and print your enclosure with preffered colors and surface patterns 150898D9-AA77-4470-9DA3-2A89EE304011

I suggest a cool white base and a dark front plate with a nice carbon fibre pattern.

Parts for Atom grove version

This version is focused on minimum soldering since it’s based on Grove parts and connectors

The SeeedStudio rotary encoder already has its connector. For the other end of the cable, simply use grove angle connector directly to the Atom controller
7D603FCA-9D48-485F-8AD4-685A469D73F6_1_201_a

It’s really as simple as that 8CD41A9B-E7F6-46FE-8770-5138BF0B893E_1_201_a

Everything will fit into the enclosure.
Use short (<5mm) M2 screw for Atom and longer (10mm) M2.5 screws for everything else (nfc board, volume encoder, front plate). BD16EF90-5222-40EF-A131-2C27C6EE5493_1_102_o

Parts for custom-built version

Firmware options

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 paypal.me/lukagra

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

In case you’re interested in buying a ready-made TagTuner, please drop me an email at tagtuner at icloud.com.

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

ESPhome components modifications are licensed under ESPHome license