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

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

File Player is one of the templates you can select during service creation if you have convo-filesystem package enabled on your installation. You can use it to quickly create your own music player.

Initial setup

First, we have to configure where will we read our mp3s from. In order to play, our players needs to know exact filesystem path where the files are stored and it requires base URL which will be used to form the publicly accessible mp3 URLs. We exposed those settings as a service variables.

In the BASE_PATH field, enter the path to the root folder containing the mp3 files. Example: /var/www/convo-proto/www/mp3.
In the BASE_URLfield, enter the public URL to expose songs from. Example: https://www.example.com/mp3/.
BASE_PATH and BASE_URL are used in the workflow to configure Filesystem mp3 source context.
In the SERVICE_NAME field, enter the name how the service introduces itself.

Once you set the values you can connect it to Amazon and start testing on your Echo device.

How it works

Filesystem mp3 source context is the main component which makes your mp3s available to the system. All other media playing related components are using it and serve just as control mechanisms. It has ability to filter by a file info (title, artist, filename) or by a folder name (folder is treated as a playlist).
In this service we are catching user intents (PlayAll and PlaySong intents) and according to them we are modifying search and search_folders variables, which are passed to the Filesystem mp3 source context. Please note that we are using the Installation scope to store values. That is because the audio player itself works without session and is bound to the particular device.

Standard service Workflow – inside session

When you open the service, you are in standard, session enabled conversation and you end up on our service Home step. Service will welcome you and ask for your search term. In the processors, we are expecting play song intents. Once we got them, we have them, we adjust our search parameters and if there are results we start the playback.
Besides play related intents defined in Handle play requests fragment user can ask for help or stop the service which is defined in Service processors system step.

Once the audio playback starts, the standard conversation ends and your device starts working in the audio player mode.

Standard commands while in audio player mode

Once the player has started, all further requests are performed directly on the Audio player step. This step has a predefined role media_player which enables us to make correct responses, even if we are not in the session. As you can see, there is not much to configure or do in the media block itself, but it has lots of hidden functionality under the hood. Primary, it will accept all supported player commands, invoked either as voice command or through graphic interface and execute desired command.

Here is the list of all voice commands you can use while in audio player mode, without explicitly naming your service:

  • 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 the first result

Additional, including skill name commands

If you want to change search criteria while already playing, you have to invoke your service explicitly, following with the desired command. It is all handled by our Session start conversation step.

Try to say something like: Alexa, ask File Player

  • for playlist info
  • for player info
  • to play the last song
  • to resume
  • to play all
  • to play songs by The Police

For WordPress variant check the Build your own music streaming skill with Amazon Alexa and WordPress