Smartskills

MediaServer Skill Help


The skill currently addresses 95 intents in categories ranging from query directives such as What's playing?, What's up next?, What's the duration of this song/playlist?, What's the Bedroom player status?, What players do I have?, Do I have the album Giants by Chicane?, Do I have the compilation album 101 Driving Songs?, List my favorites, List level 2 favorites, List the favorites in folder 'Podcasts', List my new albums, List any new albums by ZZ Top, to music requests like Play the album Ghost Stories by Coldplay, Play the compilation album American Road Trip, Play the single Sunny Days by Armin van Buuren, Play my newest album by Pearl Jam, Play the song Chasing Cars by Snow Patrol, Play songs about 'Girls', Play songs featuring Eddie Vedder, Play a random album by Steve Winwood, Play a random single by Madonna, Play some Deep House, Play favorite number 3, Play favorite 'JAZZ FM', to stream-to-Echo requests like Stream the album Parachutes by Coldplay, Stream the compilation album 101 Running Songs, Stream the single Alone Tonight by Above & Beyond, Stream my newest album by Peter Gabriel, Stream the song Chocolate by Snow Patrol, Stream songs about 'Alabama', Stream songs featuring ATB, Stream a random album by Pink Floyd, Stream a random single by Shakira, Stream some Acid Jazz, Stream favorite number 7, Stream favorite 'FUNK FM', to playlist directives like Play my Supperclub playlist, Stream my Bedtime playlist, Add this song to my Fitness playlist, Bookmark this track, Blacklist this song, to transport commands like Resume, Pause, Stop, Skip/next, Previous, Goto track 12, Skip ahead 2 minutes, Skip back 44 seconds, Seek directly to 17 minutes and 12 seconds, Start Over, to audio tweaks like Set the volume to 60, Increase/decrease volume by 10, Mute the Livingroom player, Unmute Kitchen, to power commands like Turn On the Library player, Power Off the Bedroom, Power Down everything, to transfer requests like Follow me to the Basement, Transfer playlist from Livingroom to Study, to sync-group directives like Synchronize the Bedroom, Bathroom, Office and Nursery players; Add Guestroom player to group, Remove Library player from group, Unsynchronize my players, to sleep requests like Sleep the Bedroom player in 10 mins, Sleep this player after the current song, Cancel sleep mode for Bathroom player, to shuffle commands like Turn on shuffle, Shuffle again, Enable shuffle-by-album on the Kitchen player, Enable shuffle-by-song for the Bedroom player, Deactivate shuffle, to repeat requests like Enable Repeat, Turn on repeat-playlist mode, Enable repeat-song mode, De-activate repeat on the Basement player. As a bonus, literally thousands of syntactical variations on the above examples are supported.

There are also commands to assume each Echo is associated with a default Squeezebox to allow player-name omission in utterances. Echos in open-plan spaces can be designated as being within earshot of each other to avoid confusion around what player is then targeted. You can ask to rename players, and by saying 'Alexa, repeat' you can request her to repeat the last thing the skill said (in case you missed it). Finally, you can ask the skill to provide longer or shorter responses and confirmations.

In a word, excellently! A few pointers:

The skill relies on querying your local LMS database and directing the LMS server accordingly (note your database is never copied to the cloud). A degree of fuzzy matching in the skill's logic allows for spelling inconsistencies typical of region/locale/dialect. However, if your tags are missing, inconsistent, (very) badly-spelled or just plain wrong, there's not much the skill can do to help. In the end, it's all about your tags !

When the music is very loud, Alexa may have difficulty interpreting what you say but this is true of any skill and not just this one.

Mixed-language utterances can be problematic. For example, requests such as Play the album "Liebe ist für alle da" by "Rammstein" on the Bedroom player are likely to be misinterpreted.

The skill works equally well with all the original hardware Squeezeboxes plus all the common software players. There's no distinction between LMS installations on any supported server platform such as NAS, PC, Linux, RPi, ESP32, etc.

During setup, the skill automatically retrieves the names of your players from your LMS server. Best results with the skill will be achieved if your players are named after the bareword version of the room-name in which they are situated, without possessives and without extra/qualifying words such as e.g. "player", "squeezebox" or "touch".

In other words, plain English single-word common names like "Livingroom", "Kitchen", "Study", "Office", "Garage", "Studio", "Bedroom", "Bathroom", "Diningroom", "Basement", "Guestroom", "Nursery", "Library", "Cellar", "Hall", "Lobby", "Conservatory", "Lounge", "Pantry", "Scullery", "Salon", "Washroom" are guaranteed to work, are concise, and fit well with the command structure

Names like "John's player", "Master bedroom", "Livingroom front player", "Bazinga", may work, but will need to be verified by trial-and-error. Same for contrived single-word names like "Kidsroom", "Babyroom", "Spareroom" and "Alexandersroom". In the end, it's best to work with names that Alexa can understand consistently for your locale.

Note that you can freely use the word player in your utterances if you like — you can also mix the use of "in the", "on" and "on the". Commands such as Play the album Mylo Xyloto by Coldplay in the Kitchen and Play the album Mylo Xyloto by Coldplay on the Kitchen player are fully interchangeable.

Using the Rename command it's possible to rename players to something other than the name reported by LMS. This only affects the name used in the skill, not the name known to the server or e.g. iPeng or Material. Re-doing player discovery will revert any renamed players back to their LMS original names.

Finally, any player names ending in an asterisk (e.g. "Reserve*") will be deliberately skipped during discovery.

MediaServer is a so-called custom skill, meaning it has to be invoked using the skill name in your utterance. Given that Alexa herself can play music sourced from e.g. Spotify or Amazon Music directly on an Echo's speaker, you omit the name at your peril !

Some different and freely interchangeable ways of invoking the skill include:

  • Alexa, ask Media Server to play the album Wildness by Snow Patrol in the Bedroom
  • Alexa, tell Media Server to play the album Abacab by Genesis on the Bedroom player
  • Alexa, open Media Server and play some Jazz
  • Alexa, launch Media Server and set the volume to 70
  • Alexa, start Media Server and cancel repeat mode
  • Alexa, next track using Media Server
  • Alexa, get what's playing from Media Server
Commands 3–7 above don't have a player name in the utterance. That's because they use an implicit player which is permanently associated with the Echo in question. You set it up like this:

  • Alexa, tell Media Server to assume the Kitchen player
You can query the current association by saying Alexa, get the assumed player from Media Server.

You can also tell e.g. the Kitchen Echo I'm within earshot of the Livingroom Echo. Subsequently, when you issue a command in the open area between your Livingroom and Kitchen Echos, you don't have to worry which Echo actually hears you and assumes the player to target. The skill will check which of the two players is actually playing a song and react accordingly. If both players happen to be playing, normal 1:1 association applies.

The account linking process for the skill is where you provide the connectivity details for your LMS server. You don't create an account with us and don't link to it as such, but we use the landing page shown during account linking to retrieve your configuration which is then stored in the skill. Simple, and it keeps your data safer.

First off, please understand that the required access can be as secure as today's best practices for internet security. You do not have to expose an unprotected LMS server to the outside world.

The skill works by interfacing with your LMS server's jsonrpc interface, usually on port 9000. That's the same port you use in a web browser to access LMS via e.g. the Material skin. On your local network, you use something like http://192.168.1.10:9000 for this. However, we need to specify an externally-valid IP address and also to support both encryption and authentication, so an extra step is needed — proxying.

We have two suggestions for your proxy, but you are free to use others:

  • Use ngrok, a combination of a free cloud service and a local helper-program. It's really easy to setup after downloading and running an ngrok executable (which then protects LMS when it runs). It's currently available for Windows and Linux — but not NAS — so if you're on NAS, you will need to install and run ngrok from a different machine in your network and point it towards your NAS. Otherwise, it can all be done on your LMS machine directly. Either way, it's trivial to configure and an RPi can handle the NAS-proxying no problem.

  • Roll your own reverse proxy using e.g. apache or nginx and handle it all locally without any cloud service. This is harder to setup than ngrok but you may already have done this anyway if you are a Smart Home enthusiast. You'll need a DDNS domain name, SSL cert from e.g. Letsencrypt, and you'll need to open a port on your router. However, the proxy's basic-auth ensures there's no unprotected exposure of LMS so it's very secure.

Please note that it is not possible to use a VPN or Synology QuickConnect with the skill.

Expand the following sections for instructions on each method:


Visit the ngrok.com website for an explanation of how it works and what plans are available. The free plan works just fine for us, but has the disadvantage that your server path URL will change every time you reboot the machine ngrok is running on. This means redoing account linking for the MediaServer skill as it is during that process that the skill picks up your external path information. If that bothers you because you often reboot, either get a paid plan for ngrok or use it from a dedicated proxying RPi that you never reboot.

Linux
After downloading, move the ngrok executable file to where the system expects to find it with sudo mv ngrok /usr/local/bin.

If ngrok is on the same machine as LMS, at a command prompt type:

ngrok http -auth "user:password" 9000 > /dev/null 2>&1 &

Otherwise, if ngrok is on a different machine, point it to LMS by typing:

ngrok http -auth "user:password" 192.168.x.y:9000 > /dev/null 2>&1 &

The ngrok service will start silently and run in the background due to the '&' at the end. Use the disown command to keep the ngrok process alive after you close the terminal if you find your linux version kills ngrok when you close it. Then, to find our assigned tunnel subdomain, we can query the ngrok web UI at port 4040 for the public_url entry by typing

curl -s http://localhost:4040/api/tunnels | grep -Po https://.+?\.io

The output will look something like https://19279a3a.ngrok.io. That's our server path.

Windows/MacOS
On Windows, run the relevant ngrok command listed above from a command line prompt without the " > /dev/null 2>&1 &" at the end. Instead of using curl to determine the assigned ngrok subdomain, use any browser on the same PC to browse to http://localhost:4040 and you will see the URL under the status tab.
On Mac you can run the relevant ngrok command listed above in a terminal and can use either curl or a browser to determine the URL.

Link the skill
Enter the https variant of your assigned ngrok URL as your full server path during skill-linking. Fill in the username and password you specified for the -auth switch. Submit, and you're good to go! You did pick a strong password, didn't you?

Please first read the introductory section on ngrok before attempting this.

If you want to autostart ngrok when your system boots, this section will explain the steps involved. Sign in to your (free) ngrok account from a browser and note the authtoken that appears on your dashboard. Next, at a command prompt on your ngrok host machine, type:

ngrok authtoken YOUR_AUTHTOKEN

This will have created a file called ngrok.yml in a hidden folder .ngrok2 in your home directory (e.g. /home/pi if on raspbian). Edit that file using e.g. nano ~/.ngrok2/ngrok.yml so that it looks as follows (note the indentation is required):

authtoken: 6hR173iJMYTfypshaexbe_8xgopkz39Cx2aqkz4Z7OT  <-- your authtoken
web_addr: 0.0.0.0:4040
inspect: false
region: eu
tunnels:
  mediaserver:
    proto: http
    addr: 192.168.1.10:9000
    auth: "username:password"

Explanation: web_addr allows you to use a browser to check the configuration from any machine in your local network, not just from localhost; inspect when set to false reduces logging and increases responsiveness once you're all set up; region defaults to 'us' if you don't override it to e.g. eu. The tunnels command allows us to pre-define the parameters for a tunnel so that it can then be started using the start command — the addr and auth should match your particular setup.

Now, we need to create the config file needed to start ngrok as a service. Create the file via sudo nano /etc/systemd/system/ngrok.service and give it the following content:

[Unit]
  Description=ngrok autostart 
  Wants=network.target 
  After=network.target

[Service]
  Type=simple 
  WorkingDirectory=/tmp 
  ExecStart=/usr/local/bin/ngrok start -config=/home/pi/.ngrok2/ngrok.yml mediaserver
  RestartSec=30
  StandardOutput=syslog
  StandardError=syslog
  SyslogIdentifier=ngrok

[Install]
  WantedBy=multi-user.target

With that file successfully created, type:

sudo systemctl daemon-reload
sudo systemctl enable ngrok
sudo systemctl start ngrok

If all is well, ngrok is now running as a service. You can check its status using sudo systemctl status ngrok and — more importantly — from any machine in your local network, you can watch what ngrok is doing by browsing to the IP address of the ngrok host machine on port 4040, e.g. http://192.168.1.1:4040. The status tab there will show you the ngrok subdomain you were assigned and which you will use in linking the skill. If you reboot the ngrok pi, just revisit that web page to see the newly-assigned subdomain for re-linking the skill.

Don't choose this option unless you are computer-savvy — use ngrok instead as detailed earlier. If you do want to do things this way, this is not a step-by-step tutorial but here's your checklist:

  • Get yourself a free dynamic DNS name via e.g. no-ip.com. An example of this would be joebloggs.myddns.me
  • Use Letsencrypt to get and install an SSL certificate for the DNS name you chose above using e.g. certbot.
  • Install apache or nginx on a machine of your choice (does not have to be the same as your LMS machine). Create a reverse proxy from 443 on localhost to port 9000 on your LMS server's IP address (in this example, 192.168.1.10 is the LMS machine). For apache2, this could look as follows:
  • 
    # put this in /etc/apache2/sites-available
    <VirtualHost *:443>
      ServerName joebloggs.myddns.me
      SSLEngine on
      Header always set Referrer-Policy "same-origin"
      Header always append X-Frame-Options SAMEORIGIN
      ProxyPass /lms/ http://192.168.178.10:9000/ Keepalive=On
      ProxyPassReverse /lms/ http://192.168.178.10:9000/
      SSLCertificateFile /etc/letsencrypt/live/joebloggs.myddns.me/cert.pem
      SSLCertificateKeyFile /etc/letsencrypt/live/joebloggs.myddns.me/privkey.pem
      SSLCertificateChainFile /etc/letsencrypt/live/joebloggs.myddns.me/chain.pem
      <Location />
        AuthType Basic
        AuthName "MyProxies"
        AuthUserFile /etc/apache2/.htpasswd
        Require valid-user
      </Location>
      <Directory "/">
        Require all denied
      </Directory>
    </VirtualHost>
                                                
  • Open a port in your router that forwards an external port such as 9443 to internal port 443 on the machine that apache runs on.
  • Now, your LMS server is externally accessible from https://joebloggs.myddns.me:9443/lms/
  • Use this as the server path during account linking. If you set up a username and password in apache in .htpasswd — and you should — use those in the username and password fields.

Always test that URL path first using a browser before entering the details on the account-linking page (the browser will prompt for the auth parameters). The skill will accept any valid https URL with a port number in it and cannot know if it's wrong until it tries to discover your Squeezebox players and fails to see a valid LMS server at the URL you typed.

You can enable the skill initially without account linking. After installing it, say "Alexa, open Media Server". The skill will tell you how to perform account-linking and then exit. This process will have placed an account linking card in your Alexa app, so you can open it and start the process.

When you start account linking, Amazon will redirect you to a smartskills.tech landing page. Normally, account linking involves logging in to an account with an external service, but in this case we just send the encoded access parameters straight to the skill in a token — there is no account concept.

See the Server Configuration help section for an explanation of what's required as a valid externally-accessible path to LMS. The username and password fields should be filled out with the -auth parameters you used for ngrok or your apache/nginx reverse proxy.

If you use ngrok, your tunnel and authorization parameters will be pre-validated and rejected if incorrect (e.g. tunnel not found or incorrect username/password). Local IP addresses will also be rejected during pre-validation. If your entries validate OK then the blue 'Press to validate' button becomes a green 'Submit' button. Do it !

When you have entered the details for your server connectivity, open the skill by saying "Alexa, open Media Server". The skill will automatically attempt to connect to your server and discover your Squeezebox players. If that fails, check that the path you entered during account linking was correct. To change it for whatever reason, you will have to disable the skill to unlink, then re-enable the skill and try account linking again.

If the discovery was successful, Alexa will tell you what players she found. Congrats! The first thing you should try out is creating an assumed player for each of your Echos. Go around to each Echo in your house and say "Alexa, tell Media Server to assume the Name-of-nearest-Squeezebox player". If you only have one player, it will always be automatically assumed for all commands, even if you have multiple Echos. If you have many players but only one Echo, still assign a nearest-player as assumed for the Echo.

Supposing you have a Squeezebox called e.g. Livingroom, try saying "Alexa, get the Livingroom player status using Media Server" to any Echo. If all is well, she'll tell you several things about what state that player is currently in. Next, try saying "Alexa, tell Media Server to Power ON" without saying the player name and verify that the assumed player indeed powers on. Which player that is will depend, of course, on which of your Echos you issue the command to.

The skill implements over 90 command categories, some of which are free to use with others requiring a subscription. The Command Reference section denotes premium commands with an asterisk after the name. The activation is handled as an In-Skill Purchase (ISP) which is managed entirely by voice. Ask "Alexa, how do I enable voice purchasing" for help.

To access premium commands, just say "Alexa, tell Media Server I want a subscription". She'll explain the applicable pricing structure for your regional Amazon account and ask for a verbal yes/no confirmation (plus your voice PIN code if you enabled that) so you can safely experiment with the ISP process without actually committing. First-time subscribers can access a free 7-day trial. Thereafter, the credit card associated with your Amazon account will be billed monthly but you can cancel at any time. Just say "Alexa, tell Media Server I want to cancel my subscription".

If you delete the skill while a subscription is currently active, re-enabling the skill will continue your subscription without having to sign up again. Your assumed players will also be retained. This means that having to re-perform account-linking because your ngrok tunnel subdomain changed does not affect your subscription.

Without an active subscription, your data is not persisted across re-enablements of the skill, meaning that you will also have to re-perform the player-assuming process for all your Echos. It's therefore best not to regularly change your (ngrok) server path connectivity parameters if not subscribed.