**AskNavidrome** is an Alexa skill which allows you to play music hosted on a SubSonic API compatible media server, like Navidrome.
This allows to you stream your own music collection to your Echo devices without the restrictions you would normally face with regular
streaming services like Amazon Music or Spotify. AskNavidrome allows you to:
- Skip backwards and forwards in your current queue or playlist without limitation.
- Avoid paying subscription costs.
- Avoid being forced to listen to adverts at regular intervals.
- Actually use the music collection you have already paid for!
- Run the service on a PC directly or inside a Docker container.
This skill was inspired by `AskSonic <https://github.com/srichter/asksonic>`_, however AskSonic was missing two features I required,
the ability to play playlists and the ability to play an individual song. Instead of contributing to that project I have opted to
create a new skill based on the **Alexa Skills Kit SDK for Python** as this has been updated more recently than *flask-ask* which is used
by AskSonic, AskNavidrome is not a replacement for AskSonic and it does not implement all of AskSonic's features, it is however a viable
alternative for those that would like a simple skill to let you stream your own music collection.
..warning::
The skill requires a username and password for your Navidrome installation which is stored in clear text. As the web service needs to be
publicly accessible there is a chance that this password could be compromised. Please do not use an administrative account for your
Navidrome installation or a password that you use on any other service. This software is distributed under the MIT license and no warranty
is provided.
Requirements
************
In order to use AskNavidrome you will need:
**Your Music Collection**
Your collection needs to have been converted to a digital format like MP3. There are many tutorials available on the web to help you do this, but do
be aware that there are limitations on the types of files that Echo devices can stream. You should review these before converting your collection as if
you do not meet the requirements they will need to be transcoded before your Echo device can stream them. This article explains `Amazon's
-:class:`Previous / Back <app.PreviousPlaybackHandler>`
-:class:`Pause <app.PausePlaybackHandler>`
-:class:`Resume <app.ResumePlaybackHandler>`
Due to the way that Alexa skills operate there are some limitations. Full music Alexa skills require a catalog of content to be provided and this defeats
the purpose of being able to search and stream from your own server directly. Because of this a custom skill type is used along with the AudioPlayer interface,
but this has some limitations:
1. You need to open the skill to use it, say *Alexa, open Navisonic*.
2. Some intents that you would expect to be able to use when a track is playing need a full skill invocation. For example if you want to get
information on the track that is playing you will need to invoke the skill and call the intent by saying the following while the track is playing:
- Alexa, open Navisonic
- What is playing?
You will then be given information about the current track and it will automatically resume. This is also required for the *star* and *unstar* intents.
Installation and Setup
**********************
Creating the AskNavidrome Alexa Skill
-------------------------------------
#. Login to the Amazon Alexa Skills Kit Builder at https://developer.amazon.com.
- You must use the same account that is set on your Echo devices.
#. Click *Create Skill*
#. Configure the skill:
..image:: resources/create_skill_1.png
:width:800
:align:center
:alt:Skill Creation Step 1
- Set *Skill name* to the name you wish to use to invoke the skill. This should be two words or a warning will be raised, I have found that a single word
still works when testing. It can be hard to find a good skill name so feel free to experiment!
- Set *Primary locale* to your locale, this **must** also be the locale set on your Echo device.
..note:: The locale setting is extremely important, if the skill locale and the locale set on your Echo device do not match the skill will not work. In
addition there are no error messages generated making the issue quite difficult to troubleshoot. The locale on your Echo device can be set via the Alexa Android
app. Please do check the locale setting if you have trouble setting up the skill as the Alexa Skill Builder will default to your local locale, but Echo devices
are set to the US locale by default. Checking this first will save you a few hours of troubleshooting!
- Set sync locales to *No*
- Choose *Custom* as the model.
- Choose *Provision your own* as the hosting method for backend resources.
- Click *Create skill* again
#. Choose the template
..image:: resources/create_skill_2.png
:width:800
:align:center
:alt:Skill Creation Step 2
- Choose *Start from Scratch*
- Click *Continue with template* and wait while the skill is created.
#. Upload the intents
..image:: resources/create_skill_3.png
:width:800
:align:center
:alt:Skill Creation Step 3
- Click *Interaction Model*, then *JSON Editor*
- Delete everything that is currently in the editor and paste in the contents of **alexa.json**
- Click *Save Model*
#. Configure playlists
To be able to play your playlists you must add the name of each playlist to the *playlist_names* slot type.
You will need to maintain the list and add additional playlist names as you create them to allow them to
be played via the AskNavisonic skill.
..image:: resources/create_skill_4.png
:width:800
:align:center
:alt:Skill Creation Step 4
- Click *Slot Types*.
- Click *playlist_names*.
- Add and remove names as required.
- Click the *Save Model* button when you are done.
#. Enable the Audio Player interface
..image:: resources/create_skill_5.png
:width:800
:align:center
:alt:Skill Creation Step 5
- Click *Interfaces*, enable *Audio Player*, then click *Save Interfaces*
#. Set the endpoint
The skill's endpoint is the location of the AskNavidrome web service.
..image:: resources/create_skill_6.png
:width:800
:align:center
:alt:Skill Creation Step 6
- Click *Endpoint*
- Select *HTTPS*
- Enter the the URL to the web service in the *Default Region* box.
- Select the SSL certificate type. This will depend on your setup, if you are using Let's Encrypt
choose *My development endpoints has a certificate from a trusted certificate authority*
- Click *Save Endpoints*
#. Build the skill
..image:: resources/create_skill_7.png
:width:800
:align:center
:alt:Skill Creation Step 7
- Click *Invocations*, *Skill Invocation Name*.
- Click *Save Model*.
- Click *Build Model*, the process will take a few minutes.
#. Add the skill to your Echo devices.
The skill you just created should now be available as a development skill in your Alexa app, you can add the development skill to your
Echo devices.
..warning:: It is important that you **do not** publish the skill. If you do anyone that uses the skill will be able to stream your music
collection, it may also be possible for credentials to be retrieved.
Deploying the AskNavidrome Web Service
--------------------------------------
The AskNavidrome Web Service is written in Python and can be run directly on a PC with a Python installation, or as a Docker container (recommended).
Whichever method you use, the service and your Navidrome installation must be available via HTTPS with a well known certificate. One of the easiest
ways to implement this is with a reverse proxy. There are several
Troubleshooting and debugging Alexa skills can be a little frustrating, here are the best ways I have found to do it.
#. Understand that the Alexa skill is effectively just a set of buttons.
All the skill does is call functions in the web service, it does nothing other than translate what you say to the function name that will perform the task.
Very little can go wrong with this, but here is a list of things to check:
* Does the locale of the skill match the locale on your Echo device? If this is mismatched it looks like nothing happens when you try to invoke the skill.
* Is the endpoint set correctly? The endpoint is the URL to the web service, if the skill cannot communicate with the web service check this first.
you must ensure that the URL is https and the certificate is compatible with Amazon services.
* If an intent does not work, you might need to add an additional phrase to the intent in the developer console. The included phrases work for me, you might
want to make some changes though.
#. Enable debugging and look at the logs generated by the web service.
#. When debugging is enabled the following web pages are available from the web service
* url-to-web-service/queue
* Shows the tracks in the current queue
* url-to-web-service/history
* Shows the tracks that have already been played
* url-to-web-service/buffer
* Shows the tracks in the buffer. Note that the buffer and queue differ as Amazon will request the next track to be queued before the track playing is
finished. The buffer can be thought of as the list of tracks still to be sent to Amazon, where as the queue is the list of tracks still to be played.
#. Use the test page in the developer console
The test page will show you the responses between Amazon and an simulated Echo device, this can help you uncover error messages that are normally hidden.
..image:: resources/debugging_1.png
:width:800
:align:center
:alt:debugging Step 1
* Click test and make sure you tick **Device Log**
* You can type instructions in the box or use the microphone on your device
..image:: resources/debugging_2.png
:width:800
:align:center
:alt:debugging Step 2
* After you have entered a command you will get the Alexa response back, scroll down to the **Device Log** section and click through the entries
the entries will contain any errors that were thrown.
