1. Home
  2. Docs
  3. Publishers
  4. Tutorial – Service templates walkthrough
  5. File player – Play your own mp3 files on smart speakers (Alexa skill)

File player – Play your own mp3 files on smart speakers (Alexa skill)

file player templateFile Player is one of the templates you can select during service creation, and use to quickly create your own music or podcast player.

The upcoming sections will walk you through the template and show how easy it is to customize it.

Let’s start with the initial setup.

Initial setup

To get the player up and running, we first need to specify the location of the audio files. That is, the player needs to know the file system path where we stored the files. And it also requires a base URL to form the publicly accessible MP3 URLs. You should store those values in BASE_PATH and BASE_URL variables located on the Variables view.

In the BASE_PATH field,  enter the path to the root folder containing the MP3 files. for example: /var/www/convo-proto/www/mp3. And in the BASE_URLfield, enter the public URL, for example: https://www.example.com/mp3/.
Both values are used in the workflow to configure the Filesystem mp3 source context.

There’s an additional variable, SERVICE_NAME, you can modify to change how your service is referred to in the workflow.

Once you set the values, you can connect the service to Amazon and start playing your files on your Echo device, or the Alexa app. If everything is working well, you can stop reading here. However, if you plan to modify or expand the service in any way, we recommend that you first go through the rest of the text.

How it works

filesystem mp3 source element

The aforementioned Filesystem MP3 source context is the component that makes your MP3s available to the system. All the other media playing related components use it and can be viewed as control mechanisms. You can find it by clicking the Contexts tab on right-hand side of the Editor view. It can filter audio files by file info (title, artist, filename) or by folder name (folder is treated as a playlist). The filtering is determined by the search variable. The user modifies it by requesting specific audio files or playlists. Finally, the modified search variables are passed down to the Filesystem MP3 source.

Note that we use the installation scope throughout the service to store search values. That’s because the installation scope attributes persist beyond the current skill session, which ends after the audio playback starts.

In other words, once the audio playback starts, your service is technically no longer running and you are inside the audio player environment. In that environment, you can trigger special built-in intents without using the service invocation name. But more on that in later sections.

Now that we’ve covered some technical basics, let’s take a deeper look at the service workflow.

Standard service Workflow

When you open the service, the session starts, and from the Session start block, you’re directed to the Home block. The audio playback starts there, and ends the current session. If you’re a first-time user, the player starts from the first track in your folder. If you’re a returning user, the playback resumes from the last played track.

As a user, you can request some of the things defined in the Handle play requests fragment, as well as ask for help or stop the playback.
You can find the help and stop intents in the Service processors system step.

Standard commands while in audio player environment

media player

Now, once the playback has started, all further requests are handled under the hood by the Audio player step. This step has a predefined role –  media_player. And as you can see in the image above, there’s not much you can do or modify in the media block, but it has a lot of hidden functionality. Primarily, it accepts and handles all supported player commands.

Here’s a list of all the voice commands that can be used strictly in the audio player environment, without explicitly invoking the service name:

  • Next/Previous
  • Stop, Pause, Cancel
  • Resume
  • Shuffle off, Shuffle on
  • Loop on, Loop off
  • Repeat – to repeat the currently playing song
  • Start over – to start from/go back to the first track

In addition to built-in commands, we have added some custom commands that users might find useful.

Additional commands that require skill invocation

custom player commandsYou are unable to trigger custom commands during audio playback without invoking the skill first.  In more technical terms, since custom commands aren’t available during audio playback, a combination of the invocation name and an intent request is necessary.

You can say something like: Alexa, ask File Player

  • what’s playing
  • how many tracks are there
  • to play the last song
  • to go to the track number [num]
  • to go [num] tracks forward/backward
  • to play [singer name]
  • to play [track name]
  • to play [folder name]
  • to play [genre]
  • to play all my music
  • to rewind [num] seconds
  • to fast forward [num] seconds
  • what’s the player status
  • for help

For the WordPress player version, check the Build your own music streaming skill with Amazon Alexa and WordPress blog post.