NFC-Music-Handoff - Hand your Music to an Amazon Echo

Showcase

https://drive.google.com/file/d/1K9RIQCwd4ozeSVhF6uJ6OZjbh7uiDyns/view

Introduction

The idea of this project is to imitate the new feature of iOS 13 which is used to hand your Music from your Apple device to a HomePod. I personally own an Amazon Echo Dot, so I tried to create my own "Handoff-System". I will share multiple versions of this script depending on which Streaming-Provider you prefer. You also have to know that this project mostly depends other great projects - you can find all of them below.

Credits and dependencies

• Mike Brady´s incredible AirPlay Server (shairport-sync) and his Metadata-Reader
• Paul Lamere´s Python implementation of the Spotify WEB-API
• screen

Prerequisites

• An Amazon Echo that supports the streaming of music
• An Spotify Premium Account that is connected to that Echo
• An Apple Device with the latest Shortcuts App installed
• Any kind of Linux based system that can be accesed via SSH e.g. an Raspberry Pi

Unfortunately Apple Music is currently not supported for the use on our Amazon Echo because of its missing API. Nevertheless we can use it on our iOS device to synchronize our music from Apple Music with our Amazon Echo. But you need to know that in this case you would need an Apple Music subscription for your iOS device AND a subscription to Spotify Premium for your Echo. If you just want to synchronize the Spotify Music of your iOS device with your Echo via NFC you ONLY need to own Spotify Premium.

As a result there are two different use cases:

• Method 1: You want to use Spotify on your iOS device and transfer that music to your Echo which is also running Spotify
• Method 2: You want to use Apple Music on your iOS device e and transfer that music to your Echo which is running Spotify

Method 1: Spotify → Amazon Echo

• Download this repository and navigate to the "Spotify" folder.
• Upload the "nfc-handoff" folder to your Linux Server and note down the location

I. Install Python and the required libaries:

# sudo apt install python3.7 python3-pip
# pip install spotipy
# pip install git+https://github.com/plamere/spotipy.git --upgrade

II. We will now proceed in the Shortcuts App on our iOS-Device:

First open the App and create a new Shortcut

Click "Add Action"

Search for SSH and add the shown action

1. Enter the IP, the username and the password for your user account choose nothing for "Input". 2. Enter the command you can see in the picture and adjust the path according to the location you have chosen for the "nfc-handoff" folder at the beginning - DO NOT change the file start.sh, only adjust the folder location!

Example: You installed the folder under /opt/nfc-handoff/ so you have to adjust the command to "cd /opt/nfc-handoff/ && bash start.sh"

After that you can save your Shorcut

IV. After we created the shortcut on our device we start configuring the script:

• Navigate to your "nfc-handoff" folder and open config.txt with any text editor
• There you will find the following settings: - ClientID: ID of your Spotify Developer App (see below) - ClientSecret: Secret of your Spotify App (see below) - Username: Your Spotify Username - Country: Your two-letter country-code e.g. DE for Germany - Device: Not important for now, we will configure that later on

To obtain the username of your Spotify Account open your Account Page

How to create an Spotify Developer App:

• Open the Spotify Developer Dashboard and login to your normal Spotify Account

  

• Create a new app

  

• Enter a name and a description, select a project type and click next

• After that you will be asked if your App is intended for commercial use, just click no, check the three boxes on the next page and click submit.

  

• You can find your ID and Secret on the App´s page

• Click edit settings and add http://localhost/ to the Redirect URLs and save:

Now you can fill in your data like that:

V. Initialisation:

• Execute bash getKey.sh

• If you filled in the config correctly the script will show a URL starting with "https://accounts.spotify.com/authorize?scope=..."

• You have to copy that URL and open it in your browser

• Enter your Spotify E-Mail and Password to authorize the Application

• After that Spotify will redirect you to "http://localhost/?code=..." You will get an error because localhost is not the valid domain of our server, just copy the link paste it into the terminal running the getKey.sh script and hit enter

• After that you will get back to the command line and a new file named ".cache-..." will get created That file contains the so called Authorization code for the user you logged in with

VI. Get your DeviceID:

• Execute the following command: # python getDevices.py
• The script will output a json object that contains the devices that are connected to the user you selected in the config.txt
• You should be able to find the name of your Echo pretty easily

Example: The name of my Echo Dot is "Davids Echo Dot" After I executed the command I got the following output:

{u'devices': [{u'name': u'Davids Echo Dot', u'volume_percent': 36, u'is_private_session': False, u'is_active': False, u'is_restricted': False, u'type': u'Speaker', u'id': u'27aXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX7213'}

You can see the name of the device, its volume level and its ID. The ID in this case would be: 27aXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX7213.

Just enter the exact name of the device in the config.txt

VII. Finalization:

Now you should be able to "handoff" your music to your Amazon Echo by simply starting the shortcut on your phone. Try it by playing a song from Spotify and starting the shortcut in the meantime. The music should pause on your phone and continue to play on your Amazon Echo at the same position. If you encounter any errors review the Troubleshooting and Known Bugs section down below before opening an issue.

Method 2: Apple Music → Amazon Echo

• Download this repository and navigate to the "Apple Music" folder.
• Upload the "nfc-handoff" folder to your Linux Server and note down the location

I. First we install shairport-sync:

# sudo apt update && sudo apt upgrade -y
# sudo apt install build-essential git xmltoman autoconf automake libtool libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev screen
# git clone https://github.com/mikebrady/shairport-sync.git
# cd shairport-sync
# autoreconf -fi
# ./configure --sysconfdir=/etc --with-alsa --with-soxr --with-avahi --with-ssl=openssl --with-systemd --with-metadata
# make
# sudo make install

After the installation is completed we have to edit the configuration of shairport:

/etc/shairport-sync.conf

metadata = {
    enabled = "yes"; // set this to yes to get Shairport Sync to solicit metadata from the source and to pass it on via a pipe
    include_cover_art = "yes"; // set to "yes" to get Shairport Sync to solicit cover art from the source and pass it via the pipe. You must also set "enabled" to "yes".
    pipe_name = "/tmp/shairport-sync-metadata";
//      pipe_timeout = 5000; // wait for this number of milliseconds for a blocked pipe to unblock before giving up
//      socket_address = "226.0.0.1"; // if set to a host name or IP address, UDP packets containing metadata will be sent to this address. May be a multicast address. "soc$
//      socket_port = 5555; // if socket_address is set, the port to send UDP packets to
//      socket_msglength = 65000; // the maximum packet size for any UDP metadata. This will be clipped to be between 500 or 65000. The default is 500.
};

Just copy that part of the config

II. After that we install the shairport-sync-metadata-reader and start the AirPlay Server:

# git clone https://github.com/mikebrady/shairport-sync-metadata-reader.git
# cd shairport-sync-metadata-reader
# autoreconf -i -f
# ./configure
# make
# sudo make install
# sudo systemctl enable shairport-sync
# sudo systemctl start shairport-sync

III. Now we install Python and the required libaries:

# sudo apt install python3.7 python3-pip
# pip install spotipy
# pip install git+https://github.com/plamere/spotipy.git --upgrade

IV. We will now proceed in the Shortcuts App on our iOS-Device:

First open the App and create a new Shortcut

Click "Add Action"

Search for SSH and add the shown action

1. Enter the IP, the username and the password for your user account choose nothing for "Input". 2. Enter the command you can see in the picture and adjust the path according to the location you have chosen for the "nfc-handoff" folder at the beginning - DO NOT change the file clearCache.py, only adjust the folder location!

Example: You installed the folder under /opt/nfc-handoff/ so you have to change the path to /opt/nfc-handoff/clearCache.py

1. Enter the IP, the username and the password for your user account choose nothing for "Input". 2. Enter the command you can see in the picture and adjust the path according to the location you have chosen for the "nfc-handoff" folder at the beginning - DO NOT change the file airplay.txt, only adjust the folder location!

Example: You installed the folder under /opt/nfc-handoff/ so you have to change the path to /opt/nfc-handoff/airplay.txt

After that you add the two actions you can see in the picture. For the second action you have to choose your Server as device for AirPlay (Second Picture)

Add another SSH-Script Here you again have to adjust the path to the folder but DO NOT modify the start.sh file EDIT: You can ignore the 2 seconds wait fuction that is shown in the picture, because it is not necessary any longer

To end your shortcut just add these two actions, click "Next", enter a name and save it

V. After we created the shortcut on our device we start configuring the script:

• Navigate to your "nfc-handoff" folder and open config.txt with any text editor
• There you will find the following settings: - ClientID: ID of your Spotify Developer App (see below) - ClientSecret: Secret of your Spotify App (see below) - Username: Your Spotify Username - Country: Your two-letter country-code e.g. DE for Germany - Device: Not important for now, we will configure that later on

To obtain the username of your Spotify Account open your Account Page

How to create an Spotify Developer App:

• Open the Spotify Developer Dashboard and login to your normal Spotify Account

  

• Create a new app

  

• Enter a name and a description, select a project type and click next

• After that you will be asked if your App is intended for commercial use, just click no, check the three boxes on the next page and click submit.

  

• You can find your ID and Secret on the App´s page

• Click edit settings and add http://localhost/ to the Redirect URLs and save:

Now you can fill in your data like that:

VI. Initialisation:

• Execute bash getKey.sh

• If you filled in the config correctly the script will show a URL starting with "https://accounts.spotify.com/authorize?scope=..."

• You have to copy that URL and open it in your browser

• Enter your Spotify E-Mail and Password to authorize the Application

• After that Spotify will redirect you to "http://localhost/?code=..." You will get an error because localhost is not the valid domain of our server, just copy the link paste it into the terminal running the getKey.sh script and hit enter

• After that you will get back to the command line and a new file named ".cache-..." will get created That file contains the so called Authorization code for the user you logged in with

VII. Get your DeviceID:

• Execute the following command: # python getDevices.py
• The script will output a json object that contains the devices that are connected to the user you selected in the config.txt
• You should be able to find the name of your Echo pretty easily

Example: The name of my Echo Dot is "Davids Echo Dot" After I executed the command I got the following output:

{u'devices': [{u'name': u'Davids Echo Dot', u'volume_percent': 36, u'is_private_session': False, u'is_active': False, u'is_restricted': False, u'type': u'Speaker', u'id': u'27aXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX7213'}

You can see the name of the device, its volume level and its ID. The ID in this case would be: 27aXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX7213.

Just enter the exact name of the device in the config.txt

VIII. Finalization:

Now you should be able to "handoff" your music to your Amazon Echo by simply starting the shortcut on your phone. Try it by playing a song from Apple Music and starting the shortcut in the meantime. The music should pause on your phone and continue to play on your Amazon Echo at the same position. If you encounter any errors review the Troubleshooting and Known Bugs section down below before opening an issue.

How this script works

This project is based on 3 different systems that are combined in a Python script - nfc.py

Part 1: Apple´s Shortcut App on your iOS device. This section is the trigger of the script. If the shortcut is started different SSH commands are sent to our server. The server will start the required applications and the Python script. The Shortcut App also takes care of all the things we have to do on our iOS device (e.g. play/pause playback, set up AirPlay, ...).

Part 2: Shairport-sync and the corresponding reader for metadata: Shairport-sync is used to emulate an AirPlay Server. At the beginning I tried to transfer the required information of the song (Songname, current postion, ...) over the Shortcut App. Unfortunately the data that is accesed by Shortcuts is not updated in real time so I searched for an alternative method of transmission and chose AirPlay for this project. If we choose our server as AirPlay-Reciever our iOS device transfers the information of the current playback to that reciever. We use this reader for metadata to access that data and save it for the Python script.

Part 3: The script itself with the WEB-API of Spotify: Part 3 controls the final playback on the Amazon Echo. It uses the WEB-API of Spotify to search for the songname we got through AirPlay and skips to the position in the song at which we stoped listening with Apple Music.

Known bugs and limitations

• Problems with selecting the correct playback device inside the Shortcuts App (Missing options inside the App itself)
• The music does not get resumed at the exact same location at which it was stoped because of some inaccuracies using AirPlay
• Error when no music or other content than music is played and the shortcut gets activated (tried to fix that by forcing the phone to start music but sometimes it still results in errors because of song´s progress time)

Troubleshooting

• Check if the paths you entered in the Shortcuts App match the path of the "nfc-handoff" folder
• Check if shairport-sync is running and configured correctly (# service shairport-sync status)
• Check if the needed Python libary is installed
• Check the syntax of config.txt
• Try restarting your server

If the problem still persists feel free to open an issue containing your error.

Implementation of NFC

To get started with NFC you will need the following things:

• An iOS device (iPhone XR, XS or newer) with at least iOS 13.1 installed
• The latest version of the Shortcuts App
• A working installation of this script
• Any kind of NFC-Chip (e.g. Hotel Keycard, Credit Card with NFC or NFC Tags/Stickers)

To enable the NFC functionality open up your Shortcuts App and follow the actions below:

Switch to the Automation tab and click the blue plus in the top right corner

Click on "Create Personal Automation"

Look for NFC and select it

Click on Scan

Bring your device near your NFC-Chip, enter a name and save

After the configuration of NFC add an action

Search for "Shortcut" and choose the Shortcuts App

Choose "Run Shortcut" and select the shortcut you created during the installation of the script

Turn off "Ask Before Running" and save your automation. After that you are done and the shortcut will start if your phone detects the NFC-Chip.

Security

Please be aware of the fact that you are dealing with sensitive data. I do not recommend running this script in an unsecure network or on a server that is directly accesible through the internet. Only use it in safe enviroments because the script itself is NOT secure. All tokens that are needed for the API are stored in form of clear text, so everybody that has access to this data could take control over your Premium or Developer Account at Spotify. Keep that in mind!