DASL Wiki

User Tools

Site Tools

Trace: • lego_dynamixel_control_xl320
music_player_skill

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
music_player_skill [2016/12/30 23:53] – Continuing tutorial text santiagoricoymusic_player_skill [2017/01/02 00:38] (current) – santiagoricoy
Line 1: Line 1:
 ====== Creating an Alexa Skill to Play a Music File ====== ====== Creating an Alexa Skill to Play a Music File ======
 +
 +
 +{{ youtube>Yco-tKQ4k1k?large }} 
 +
 +
 +
 +
 <!-- Replace the above line with the name of your "How To" Tutorial e.g. How to Laser cut Your Name in Wood --> <!-- Replace the above line with the name of your "How To" Tutorial e.g. How to Laser cut Your Name in Wood -->
  
Line 10: Line 17:
 **Keywords:** alexa skill tutorial voice audio playback alexa sdk **Keywords:** alexa skill tutorial voice audio playback alexa sdk
 \\ \\
 +
 +----
  
 <!-- Add a representative photo of your tutorial below.  Make it centered in the page --> <!-- Add a representative photo of your tutorial below.  Make it centered in the page -->
Line 15: Line 24:
 {{ sricoy:alexatesting.jpg?500 |}} {{ sricoy:alexatesting.jpg?500 |}}
 \\ \\
-By the end of this tutorial, you'll have a working Alexa Skill that can be run by +By the end of this tutorial, you'll have a working Alexa Skill that plays music, which can be run by speaking a predefined phrase. 
 + 
 +This picture shows part of the Amazon Developer console, which allows you to use many items offered by Amazon to developers; in this case, testing the voice-controlled side of an Alexa skill. We need to understand how to stream files through our Alexa-enabled device. Solving this some degree is important because it demonstrates the ability to fetch files from the web with the Alexa Voice Service (AVS), which implies it can be used to manipulate and control other items in the cloud, and connected devices. This tutorial shows you how to set up a lambda function that talks to the voice-operated end of an Alexa skill.  It takes approximately 40 minutes to complete.  
 + 
  
-This picture shows part of the Amazon Developer console, which allows you to use many items offered by Amazon to developers; in this case, testing the voice-controlled side of an Alexa skill. We need to understand how to stream files through our Alexa-enabled device. Solving this is to some degree is important because it demonstrates the ability to fetch files from the web with the Alexa Voice Service (AVS), which implies it can be used to manipulate and control other items in the cloud, and connected devices. This tutorial shows you how to set up a lambda function that talks to the voice-operated end of an Alexa skill.  It takes approximately 1.5 hours to complete. +----
  
 \\ \\
Line 42: Line 55:
   * [[music_player_skill#Programming | Programming]]   * [[music_player_skill#Programming | Programming]]
   * [[music_player_skill#Final Words | Final Words]]   * [[music_player_skill#Final Words | Final Words]]
 +
 +
 +----
 +
  
 ==== Required Items ==== ==== Required Items ====
Line 47: Line 64:
 To complete this tutorial, you'll need the following items: To complete this tutorial, you'll need the following items:
    
-  * The files within this zip file **Coming soon**+  * The contents of this git repository: [[https://github.com/santidingo/alexa_Music_Example_DASL|https://github.com/santidingo/alexa_Music_Example_DASL]]
   * Computer with Internet access   * Computer with Internet access
   * Wireless internet access (if using an Amazon device)   * Wireless internet access (if using an Amazon device)
Line 60: Line 77:
 ^PART NAME/DESCRIPTION             ^VENDOR              ^VENDOR Number or URL       ^PRICE          ^QTY       ^ ^PART NAME/DESCRIPTION             ^VENDOR              ^VENDOR Number or URL       ^PRICE          ^QTY       ^
 | Amazon Echo Dot   | Amazon.com         |https://www.amazon.com/All-New-Amazon-Echo-Dot-Add-Alexa-To-Any-Room/dp/B01DFKC2SO/ref=sr_1_2?ie=UTF8&qid=1483065428&sr=8-2&keywords=echo    |$49.99     | 1 | | Amazon Echo Dot   | Amazon.com         |https://www.amazon.com/All-New-Amazon-Echo-Dot-Add-Alexa-To-Any-Room/dp/B01DFKC2SO/ref=sr_1_2?ie=UTF8&qid=1483065428&sr=8-2&keywords=echo    |$49.99     | 1 |
 +
 +
 +
 +----
  
  
Line 71: Line 92:
 Most Alexa skills are made up of a skill created with the Alexa Skills Kit in the AWS Developer Console and an AWS Lambda function that the skill sends its requests to. Most Alexa skills are made up of a skill created with the Alexa Skills Kit in the AWS Developer Console and an AWS Lambda function that the skill sends its requests to.
  
-Here we'll initiate the two parts and then set up our skill:+Here we'll initiate the two parts and then connect our skill to complete it:
  
  
Line 79: Line 100:
  
 If you do not already have one, create an [[https://developer.amazon.com/|Amazon Developer Account]] and sign in to the **Amazon Developer Console**. If you do not already have one, create an [[https://developer.amazon.com/|Amazon Developer Account]] and sign in to the **Amazon Developer Console**.
-\\ 
-\\ 
  
-\\ 
-\\ 
 **Step 2**: **Step 2**:
  
Line 93: Line 110:
  
 Creating an IAM role: Creating an IAM role:
 +
 +{{:sricoy:echo_music:selection_024.png?500|}}
  
 From the AWS Management Console, under the "Security, Identity, and Compliance" category, click "IAM". Go to "Roles" and create a new role. Name the role whatever you like; the name doesn't matter. Go to the next page. From the AWS Management Console, under the "Security, Identity, and Compliance" category, click "IAM". Go to "Roles" and create a new role. Name the role whatever you like; the name doesn't matter. Go to the next page.
 +
 +{{:sricoy:echo_music:selection_006.png?500|}}
  
 This role will be given to a Lambda function, so we will select that option. Click through to the next page. This role will be given to a Lambda function, so we will select that option. Click through to the next page.
 +
 +{{:sricoy:echo_music:selection_007.png?500|}}
  
 Select "CloudWatchlogsfullaccess" and "DynamoDBFullAccess". Click to the next page. Select "CloudWatchlogsfullaccess" and "DynamoDBFullAccess". Click to the next page.
Line 105: Line 128:
  
 Creating a Lambda function: Creating a Lambda function:
 +
 +In the upper right-hand corner, confirm that your region is set to "N. Virginia". The AVS can only work with Lambda in this region.
  
 In the upper left of the window, click "Services", and under "Compute" select "Lambda". You should get some sort of introduction page if you're new. Click through to get started and "Create a Lambda Function".  In the upper left of the window, click "Services", and under "Compute" select "Lambda". You should get some sort of introduction page if you're new. Click through to get started and "Create a Lambda Function". 
 +
 +{{:sricoy:echo_music:selection_012.png?500|}}
  
 Now we are prompted to select a blueprint. Click "Configure Triggers" on the left. Now we are prompted to select a blueprint. Click "Configure Triggers" on the left.
 +
 +{{:sricoy:echo_music:selection_013.png?500|}}
  
 Select the Alexa Skills Kit as your trigger. Move onto the next page. Select the Alexa Skills Kit as your trigger. Move onto the next page.
  
-Here you'll be prompted to give a name, description, and runtime. The first two are for your reference. For this demo we'll use Node.js 4.3.+{{:sricoy:echo_music:selection_014.png?500|}}
  
-Scroll down to "Lambda function handler and role". We will use an existing role, and choose the name of the IAM role we created in the previous step.+Here you'll be prompted to give a name, description, and runtime. The first two are for your reference. As for the runtime, for this demo we'll use Node.js 4.3.
  
-We will review our program now+{{:sricoy:echo_music:selection_015.png?500|}}
  
 +Scroll down to "Lambda function handler and role". We will use an existing role, and choose the name of the IAM role we created in the previous step.
  
 +We will complete the Lambda function right after creating the Alexa Skill.
  
  
 +**Step 5**:
  
 +Configuring the Alexa Skill:
 +
 +{{:sricoy:echo_music:selection_025.png?500|}}
  
 <!--==========================================================--> <!--==========================================================-->
 From the Amazon Developer Console dashboard, click on the "Alexa" tab and then "Get Started" with the Alexa Skills Kit. From the Amazon Developer Console dashboard, click on the "Alexa" tab and then "Get Started" with the Alexa Skills Kit.
  
 +{{:sricoy:echo_music:selection_026.png?500|}}
  
 Click "Add a new skill". This will put you into the sequence for configuring your Alexa skill. We will be creating a "custom skill", so please select that option. Click "Add a new skill". This will put you into the sequence for configuring your Alexa skill. We will be creating a "custom skill", so please select that option.
    
-The first section of the Alexa Skill, "Skill Information", shows you the skill's application ID, and allows you to change the skills name, as well as the invocation name.+{{:sricoy:echo_music:selection_027.png?500|}} 
 + 
 +The first section of the Alexa Skill, "Skill Information", allows you to change the skills name, as well as the invocation name. This is also where you can come back to find the skill's app ID after it is generated.
  
 The skill's name is for your reference and is what shows up in the Alexa app should your skill be published. The invocation name is what will be said aloud to initiate the skill with an Alexa-enabled device. There is a link next to these options that can teach you more about invocation phrases. The skill's name is for your reference and is what shows up in the Alexa app should your skill be published. The invocation name is what will be said aloud to initiate the skill with an Alexa-enabled device. There is a link next to these options that can teach you more about invocation phrases.
Line 136: Line 173:
 Please select the "yes" radio button that confirms that our skill will use audio directives, since we will be playing music. Then click "Next". Please select the "yes" radio button that confirms that our skill will use audio directives, since we will be playing music. Then click "Next".
  
-**Step 4**: 
  
 This page allows us to create our interaction model. The top text box allows us to define what intents we would like to use in an intent schema. Intents are requests that can be triggered by verbal commands. A few of our intents are required by the Alexa skills kit because we will be streaming music. Intents are specified in JSON format. This page allows us to create our interaction model. The top text box allows us to define what intents we would like to use in an intent schema. Intents are requests that can be triggered by verbal commands. A few of our intents are required by the Alexa skills kit because we will be streaming music. Intents are specified in JSON format.
  
-Please extract the zip archive that can be downloaded in the "Required Items" section. In the extracted folder, inside the "speechAssets" folder, there is a file named "IntentSchema". Copy and paste its contents into the intent schema text entry field. More information can be found on intents with the provided links next to the text box.+{{:sricoy:echo_music:selection_028.png?500|}} 
 + 
 +In the extracted folder, inside the "speechAssets" folder, there is a file named "IntentSchema". Copy and paste its contents into the intent schema text entry field. More information can be found on intents with the provided links next to the text box. 
 + 
 +{{:sricoy:echo_music:selection_029.png?500|}}
  
 Also in the "speechAssets" folder is a file named "Utterances.txt". Please copy and paste its contents into the "Sample Utterances" text entry field. The first portion of each line (here it is "PlayAudio") is the intent that is invoked by the sample phrase written after it. Also in the "speechAssets" folder is a file named "Utterances.txt". Please copy and paste its contents into the "Sample Utterances" text entry field. The first portion of each line (here it is "PlayAudio") is the intent that is invoked by the sample phrase written after it.
Line 146: Line 186:
 Click "Next" to save and move to the next page. Click "Next" to save and move to the next page.
  
-**Step 5**:+**Step 6**:
  
-The Global Fields page is where we set up where our requests will be sent.+The Global Fields page is where we define where our requests will be sent. 
 + 
 +{{:sricoy:echo_music:selection_016.png?500|}} 
 + 
 + 
 +We need to complete our lambda function in order to complete this portion. Go into the "Skill Information" section of the Alexa skill and copy the Alexa Skill App ID. Go into the repository downloaded earlier and in the "constants.js" file, paste the Alexa skill App ID into the "appId" value. 
 + 
 + 
 +Scroll back up to "Lambda function code". For this step, open the repository that can be downloaded, found in the "Required Items" section above. 
 + 
 +With node.js installed, using a command line (the Git shell is what I used on Windows), navigate to the "js" directory within the "skill-sample-nodejs-audio-player" folder. 
 + 
 +Use this command: 
 + 
 + 
 +<fc green> 
 +npm install 
 +</fc>  
 + 
 + 
 +{{:sricoy:echo_music:selection_018.png?500|}} 
 + 
 + 
 +It will probably stall for a second, don't worry. Once complete, you will see a "node_modules" folder has been created in the "js" directory.  
 + 
 +{{:sricoy:echo_music:selection_019.png?500|}} 
 + 
 +Select everything within the "js" directory, and compress it into a zip file. 
 + 
 +{{:sricoy:echo_music:selection_030.png?300|}} 
 + 
 +We will now upload the created zip file into the section of our Lambda function called "Lambda function code". Move onto the next page and hit "Create function". Once created, you will be given an Amazon Resource Number (ARN) at the top right of the page. Copy this. 
 + 
 +{{:sricoy:echo_music:selection_021.png?500|}} 
 + 
 +In your Alexa Skill configuration page, select ARN as your service endpoint type, and paste your ARN into the text box, being sure to check the North America box. Move on to the next page and now everything is done! 
 + 
 +It's time to begin testing...maybe troubleshooting? 
 + 
 + 
 +---- 
 + 
 + 
 +==== Programming ==== 
 +  
 +We got it working, so, how exactly does this thing work? 
 + 
 +Well, we'll go through a quick overview here, and I'll link relevant content as I go. 
 + 
 +1. **The Alexa Skill** 
 +     
 +The skill built through the developer console has no actual programming involved.  
 + 
 +What we do define is what the end user will say to invoke our skill, or navigate options within the skill. 
 + 
 +{{:sricoy:echo_music:alexainteractionmodel.png?nolink&600|}} 
 + 
 +The intent schema and sample utterances combined represent things the user might say, and what to do in response. 
 + 
 +The intent schema is where we set up which intents we will use. Intents are a way of specifying the request sent by the skill to our function in Lambda. 
 + 
 +In our example, we use a custom intent called "PlayAudio". In the sample utterances section, we wrote possible things the end user will say that we want to invoke the "PlayAudio" intent. You will notice that there are other intents in our intent schema. These are built-in intents and we do not have to define the possible utterances for that Alexa will understand.  
 + 
 +For more on defining an Alexa skill's voice interface, please visit this [[https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/defining-the-voice-interface#The Intent Schema|link]]. 
 + 
 +{{:alexaglobalfields.png?nolink&500|}} 
 + 
 + 
 +We must send our request somewhere, and the global fields section of our skill allows us to specify whether we are sending requests to our own URL or to an AWS Lambda function. It is easier to use the Amazon Resource Number (ARN) of a Lambda function, because we do not have to deal with any specifics concerning how our requests are sent to the Lambda function, we only need to write the code that our function will use to handle requests. 
 + 
 +  
 +2. **The Lambda Function** 
 + 
 +The Lambda function is where our code is hosted and responds when triggered by the Alexa skill. Otherwise, the function will sit idle and do nothing, making it very efficient for our purposes. With that said, let's take a brief look at our code below. 
 + 
 +<code javascript> 
 + 
 +'use strict'; 
 + 
 +var Alexa = require('alexa-sdk'); //import Alexa SDK  
 +var constants = require('./constants'); //will need values from constants.js 
 +var stateHandlers = require('./stateHandlers'); //need to register statehandlers 
 +var audioEventHandlers = require('./audioEventHandlers');//must register audio event handlers 
 + 
 +exports.handler = function(event, context, callback){ 
 +    var alexa = Alexa.handler(event, context); 
 +    alexa.appId = constants.appId; 
 +    alexa.dynamoDBTableName = constants.dynamoDBTableName; //table name 
 +    alexa.registerHandlers( //this function allows us to register our handlers 
 +        stateHandlers.startModeIntentHandlers,//we can register multiple at a time 
 +        stateHandlers.playModeIntentHandlers, 
 +        stateHandlers.remoteControllerHandlers, 
 +        stateHandlers.resumeDecisionModeIntentHandlers, 
 +        audioEventHandlers //there are multiple in this file 
 +    ); 
 + 
 +    alexa.execute(); //just makes it all happen 
 +     
 +}; 
 + 
 +</code> 
 + 
 + 
 +If you recall in the Lambda function, we use "index.handler" when we defined our handler in the configuration page. That is how our lambda function accesses the handlers that are used to process the requests. A handler looks for a specific intent and when it is invoked, runs the actions we program. Inside of the files imported into index.js, we can find the actual handlers.  
 + 
 +For more on handling requests, please visit this link: [[https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/handling-requests-sent-by-alexa|Handling Requests]] 
 + 
 +3. **IAM and the DynamoDB Table** 
 +    
 +{{:iammanagement.png?nolink&500|}} 
 +    
 +In our example, we don't explicitly setup an Amazon DynamoDB table, but rather it is set up by our Lambda function. However, when we created a role with the Identity and Access Management service (IAM) and set it as our Lambda function's role, we were giving our function permission to create that table for us, as well as access to our Amazon Cloudwatch service. 
 + 
 +Amazon CloudWatch is a service that allows us to track metrics of our Amazon Web Services (AWS) account. This ability isn't explicitly used by the skill, but there may be overlap in permissions from CloudWatch that let the function create a table in DynamoDB.  
 + 
 +**NOTE:** If you intend to repurpose this sample and change what is actually played by the skill, you will need to go into DynamoDB and delete the table created by the function, as it holds details about what the user has played, but may not replace them correctly with new audio sources. 
 + 
 +----
  
  
 ==== Final Words ==== ==== Final Words ====
-<!-- 
-This tutorial's objective was to <fill in the blank>. Complete <choose: construction details, source code and program descriptions> for <fill in the blank>. Once the concepts were conveyed the reader could <fill in the blank. 
  
-Speculating future work derived from this tutorial, includes <fill in the blank>. In the big picture, the problem of <fill in the blank> can be solved with this tutorial.+This walkthrough has gotten us off the ground with a music-playing Alexa skill, using built-in intents, Amazon DynamoDB, and Amazon IAM. For more on how skills work, please review other links [[echo_tutorial|here]] for an introduction to developing for Alexa. 
 + 
 +For more information on this particular sample, please go through the README.md file. 
 + 
  
---> 
 For questions, clarifications, etc, Email: <ricoys1@unlv.nevada.edu>  For questions, clarifications, etc, Email: <ricoys1@unlv.nevada.edu> 
  
music_player_skill.1483170831.txt.gz · Last modified: by santiagoricoy