lexstream

lexstream

Alexa Music skill for streaming your own music.

created by tigwen

Prerequisites

• Go
• ASK CLI
  • Complete the setup through step 3, install and initialize.
    • You can use your existing AWS credentials instead of having the ask-cli linked to your aws account.
  • You need to hava an Alexa device registered to be able to create the skill that drives this code
    • Global installation is not required, you can create an alias or similar shell script. i.e.
    • alias ask="node /path/to/node_modules/ask-cli/bin/ask.js"
• Node.js ASK CLI requires version 8.3 or higher.
• An AWS account and IAM credentials stored in ~/.aws/credentials
  • These credentials need to have permissions to manipulate S3, IAM, Lambda resources
  • Set the AWS_PROFILE environment variable when not using the default profile

Skill Creation

• Create a new skill with a Music model in the alexa console
• Complete steps 1,3,4,5 in the Music Skill Builder Checklist under the Build tab.
  • Skip "Upload Catalogs" which will be completed under Catalog Creation below.
  • Under "Define Endpoints" copy the Your Skill ID or know how to get back to it.
    • Leave the Default endpoint empty for now, it will be filled in once the Deploy Lambda below has been completed.
  • Complete the Skill Names, Interfaces, Features sections using:
    • The first 4 Interfaces need be checked as they are required.
    • If you have explicit language filtering enabled for your Alexa devices the checkbox on Features needs to be checked. Otherwise, your devices will refuse to talk to the skill.
• Click the Distribution tab and fill in some reasonable defaults for the preview / privacy / availability sections.
  • This is required to get the Certification to run and make sure the lambda works.
  • Most of this will not be used as we're not submitting the skill for publication.
• On the Certification tab click the Run button.
  • It should just output one line: The catalog is missing entities for locale en-US. Make sure the complete catalog is uploaded and associated, then try again.
  • If there are any other errors, fix them in the Build tab.

Configuration steps

Catalog Creation

• Update the catalog/track.json with the metadata (track/artist/album) of the files you are going to upload.
• Create the catalog, replacing the title with your preferred title

  $ ask smapi create-catalog \
  --title "Matt's Music" \
  --type AMAZON.MusicRecording \
  --usage AlexaMusic.Catalog.MusicRecording
  

  • Make sure to note the catalog "id" field from the last command.
  • It should be in the form amzn1.ask-catalog.cat.<your-unique-id>
  • You can also get this using ask smapi list-catalogs-for-vendor
• Associate the catalog with the skill

  # The -s parameter is your alexa skill id.
  # The -c parameter is the catalog id created in the previous step.
  $ ask smapi associate-catalog-with-skill \
  -s amzn1.ask.skill.<your-unique-id> \
  -c amzn1.ask-catalog.cat.<your-unique-id>
  

• Upload your music catalog tracks metadata file

  $ ask smapi upload-catalog \
  -c amzn1.ask-catalog.cat.<your-unique-id> \
  -f catalog/track.json
  

  • Save the upload-id output from the previous command.
  • The output from the previous command will indicate Catalog uploaded successfully this does not mean it has passed all validation checks or has been run through the Spoken Language Understanding
• Track progress of the catalog upload using

  # The --upload-id is from the previous step
  $ ask smapi get-content-upload-by-id \
  -c amzn1.ask-catalog.cat.<your-unique-id> \
  --upload-id amzn1.ask-catalog.upl.<your-unique-id> 
  

  • When an upload fails, the output of this command will contain some high level messages and a link to a log file with more details on why it failed.
• The catalog should be ready to go once the installationSteps element

  {
    "ingestionSteps": [{
      "errors": [],
      "logUrl": "",
      "name": "ER_INGESTION",
      "status": "SUCCEEDED"
    }]
  }
  

Deploy Lambda

• WARNING the bucket permissions will be re-set to no public access!!
• Copy settings.json.example to settings.json and update with the appropriate bucket and skill id
• Run the following command to create the required Bucket, IAM Role, and Lambda

  $ go run infra/sync.go
  

Update Endpoint and Re-Validate

• Back in the Alexa skills console, update the skill endpoint with the output of the previous command

TODO

• Build track catalog automatically from mp3 id tags
• Upload music automatically
• Periodically re-index mp3 files in bucket and create new track metadata and upload it
  • The ask cli does an browser based login to get the access tokens so this may be a pain doing it otherwise, more research needed