Alexa Music Skill API Components Reference

This page describes the objects within the Music Skill API request and response messages. The objects are listed alphabetically.

AdMetadata

Contains metadata for an ad item.

Structure

Same as BaseMetadata.

Examples

{
  "type": "AD",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "some advertisement"
    },
    "display": "Some advertisement"
  },
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

Art

Contains artwork for a media content.

Synonyms

Cover Art, Cover

Structure

Field Description Required? Type
contentDescription Description of the art for accessibility purposes. Optional but recommended. no string
sources List of ArtSource objects each describing one size of the art. See the ArtSource object for more information. yes list

Examples

{
  "contentDescription": "A close-up picture of the artist Lady Gaga.",
  "sources": [
    {
      "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
      "size": "X_SMALL",
      "widthPixels": 48,
      "heightPixels": 48
    },
    {
      "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
      "size": "SMALL",
      "widthPixels": 60,
      "heightPixels": 60
    },
    {
      "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
      "size": "MEDIUM",
      "widthPixels": 110,
      "heightPixels": 110
    },
    {
      "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
      "size": "LARGE",
      "widthPixels": 256,
      "heightPixels": 256
    },
    {
      "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
      "size": "X_LARGE",
      "widthPixels": 600,
      "heightPixels": 600
    }
  ]
}

ArtSource

Contains information about a single size of a media content's art (for example, album cover art).

Synonyms

Cover Art Image, Cover URL

Structure

Field Description Required? Type
url The URL for the image of this size. URL must be HTTPS. yes string
size The size for the image. Alexa can use this optional field to help determine which size of ArtSource to use. If the skill knows the exact image dimensions and populates widthPixels or heightPixels, the skill should also populate this field to the appropriate size based on those values. However, this field can be populated without having to specify widthPixels or heightPixels if unknown. If an image size is unknown then this field can be left blank. Valid values and recommended image sizes for each:
"X_SMALL" (recommended for images approximately 48 x 48 pixels)
"SMALL" (recommended for 60 x 60 pixels)
"MEDIUM" (recommended for 110 x 110 pixels)
"LARGE" (recommended for 256 x 256 pixels)
"X_LARGE" (recommended for 600 x 600 pixels)
no string
widthPixels The exact width of the image in pixels, if known. If unknown, omit this field. no integer
heightPixels The exact height of the image in pixels, if known. If unknown, omit this field. no integer

Examples

{
  "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
  "size": "X_SMALL",
  "widthPixels": 48,
  "heightPixels": 48
}

BaseControl

BaseControl captures the base structure that is extended by ItemControl and QueueControl.

Structure

Field Description Required? Type
type The type of the control. This can be one of the following:
ADJUST - for controls such as seeking
COMMAND - for controls such as skipping
yes string
name The name of the control.

For type ADJUST, the value for name can be one of the following:
SEEK_POSITION - enables user to seek forward and back within a currently playing track

For type COMMAND, the value for name can be one of the following:
NEXT - for skipping to the next item
PREVIOUS - for skipping to the previous item
yes string
enabled Informs Alexa whether the control is enabled. For some control types, this determines whether the button for the control should be clickable: set the value to true when the control should be clickable by the user in the Alexa app. yes Boolean

Examples

{
  "type": "COMMAND",
  "name": "NEXT",
  "enabled": true
}

BaseMetadata

The base structure that is re-used across other metadata objects.

Structure

Field Description Required? Type
type Type of the metadata. The values for this field are different for each subtype of BaseMetadata. The type field determines what fields are expected in addition to the ones in the BaseMetadata object. yes string
name Name of the item to which this metadata applies, such as the name of an album or playlist. For example, this could be used in an Alexa voice prompt spoken before content begins to play. See the MetadataNameProperty object for more information. yes object
art An Art object containing specific artwork for the item to which this metadata applies, such as an album cover. Note that for use cases where content should be displayed to the user (for example, Search/Find/Browse use cases), this field is mandatory. See the Art object for more information. no object

Examples

{
  "type": "ARTIST",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "nirvana"
    },
    "display": "Nirvana"
  },
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

Content

The Content object includes an identifier (reference) and metadata (for example, album name, author name, title, "type", etc.). The Content object can represent a single track, an album, a playlist, a custom station, or a live station. Content objects are global and can be shared between different users. For example, if Content object 1234 is the album "King Animal" by Soundgarden, this is true for any user who receives Content object 1234, and if a user receives Content object 1234 a year later, it should still represent the album "King Animal" by Soundgarden.

Note that Content can also be a single song, where the Content ID encodes the audio item ID. This would happen for Search/Find/Browse utterances like "Alexa, show me songs by Fleet Foxes" where the provider would return a Content list where each Content ID points to one Fleet Foxes song.

Structure

Field Description Required? Type
id Globally (in the skill's domain) unique identifier of the Content (e.g. album ID, playlist ID, track ID, etc.). Note that this identifier should uniquely identify some piece of content like an album or a playlist or a track. yes string
actions An object describing whether the content is playable, browsable, or both. Note that this field should only be present for content returned for display use cases. See the ContentActions object for more details. no object
metadata Metadata for the Content. The value is an instance of MediaMetadata. See the MediaMetadata object for more details. yes object

Examples

{
  "id": "1021012f-12bb-4938-9723-067a4338b6d0",
  "actions": {
    "playable": true,
    "browsable": false
  },
  "metadata": {
    "type": "TRACK",
    "name": {
      "speech": {
        "type": "PLAIN_TEXT",
        "text": "remember high school"
      },
      "display": "Remember High School"
    },
    "authors": [
      {
        "name": {
          "speech": {
            "type": "PLAIN_TEXT",
            "text": "macklemore"
          },
          "display": "Macklemore"
        }
      }
    ],
    "album": {
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "the language of my world"
        },
        "display": "The Language of My World"
      }
    },
    "art": {
      "sources": [
        {
          "url": "https:example.com/images/cover/48x48-000000-80-0-0.jpg",
          "size": "X_SMALL",
          "widthPixels": 48,
          "heightPixels": 48
        },
        {
          "url": "https:example.com/images/cover/60x60-000000-80-0-0.jpg",
          "size": "SMALL",
          "widthPixels": 60,
          "heightPixels": 60
        },
        {
          "url": "https:example.com/images/cover/110x110-000000-80-0-0.jpg",
          "size": "MEDIUM",
          "widthPixels": 110,
          "heightPixels": 110
        },
        {
          "url": "https:example.com/images/cover/256x256-000000-80-0-0.jpg",
          "size": "LARGE",
          "widthPixels": 256,
          "heightPixels": 256
        },
        {
          "url": "https:example.com/images/cover/600x600-000000-80-0-0.jpg",
          "size": "X_LARGE",
          "widthPixels": 600,
          "heightPixels": 600
        }
      ]
    }
  }
}

ContentActions

An object describing whether a Content is playable, browsable, or both.

The flags in this object are intended to support display use cases where the user can click a Content object to play all its contents (for example, play an entire album) or the user can click a Content object to view the items within (for example, see the tracks listing for the album) and perhaps play one item.

Structure

Field Description Required? Type
playable Determines whether the content is playable. Defaults to true. no Boolean
browseable Determines whether the content is browsable. no Boolean

Examples

{
  "playable": true,
  "browsable": false
}

EntityMetadata

Metadata for entities like artists, songs, etc.

Structure

Field Description Required? Type
name Name of the entity to be used in Alexa voice prompts or for display use cases. See the MetadataNameProperty object for details. yes string

Examples

{
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "rap god"
    },
    "display": "Rap God (Explicit)"
  }
}

EntityType

The following list contains all entity types supported by the Alexa Music Skill API:

  • TRACK – a song like Lady Gaga's "Gypsy"
  • ALBUM – an album like Lady Gaga's "ARTPOP"
  • ARTIST – an artist like "Lady Gaga"
  • PLAYLIST – a playlist like "Relaxing Sounds"
  • GENRE – a genre like "Jazz"
  • STATION – a station like "C.N.N."
  • MEDIA_TYPE – describes different types of musical works, for example, song, etc.
  • SORT_TYPE – describes whether audio contents or selection criteria should be ranked by popularity or recency before being returned to Alexa

Feedback

Describes the user's feedback or preference about an item. For example, if the user said "I like this" while a song was playing.

Synonyms

Preference, Thumbs Up/Down

Structure

Field Description Required? Type
type The type of feedback. This only supported value is PREFERENCE. yes string
value The value of feedback. Can be either POSITIVE or NEGATIVE. yes string

Examples

{
    "type": "PREFERENCE",
    "value": "POSITIVE"
}

Filters

An object which describes filters that the skill should apply to search results (selection criteria and content) before returning a response to the Alexa service.

Structure

Field Description Required? Type
explicitLanguageAllowed Determines whether results with explicit language are allowed. yes Boolean

Examples

{
  "explicitLanguageAllowed": true
}

Item

An (audio) item that contains within it an identifier and metadata (for example, art URLs, author name, title, etc.), and a Stream containing the playback URL. Note that in some cases, the duration of an item needs to be displayed when there is no stream for that item. That is why the duration field is a peer to the stream field and not a member of it.

Synonyms

Audio Item, Track, Song

Structure

Field Description Required? Type
id A identifier for the item that is opaque to Alexa. Note that the item should be unique within the queue. yes string
playbackInfo Describes which business rules Alexa should run when playing or displaying this item. See the PlaybackInfo object for details. yes string
metadata Metadata for the item.

For playbackInfo types DEFAULT and SAMPLE, the value will be an instance of MediaMetadata, where the metadata type field can either be TRACK or STATION. See the MediaMetadata object for details.
For playbackInfo type AD, the value will be an instance of AdMetadata. See the AdMetadata object for details.
yes object
durationInMilliseconds Duration of the item in milliseconds. If the item is a live stream, do not return this field. no long
controls List of ItemControl objects used by Alexa to determine which controls should be clickable in the Alexa app. no list
rules Object which contains rules for the item. See ItemRules for details. yes object
stream Object that contains stream information for this item. See the Stream object for more information. yes object
feedback Rating of the item if it exists. For example, if the user had previously indicated "thumbs down" for this item, the skill should set feedback type to PREFERENCE and the feedback value to to NEGATIVE. See the Feedback object for more information. no object

Examples

{
  "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
  "playbackInfo": {
    "type": "DEFAULT"
  },
  "metadata": {
    "type": "TRACK",
    "name": {
      "speech": {
        "type": "PLAIN_TEXT",
        "text": "gypsy"
      },
      "display": "Gypsy"
    },
    "authors": [
      {
        "name": {
          "speech": {
            "type": "PLAIN_TEXT",
            "text": "lady gaga"
          },
          "display": "Lady Gaga"
        }
      }
    ],
    "album": {
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "art pop"
        },
        "display": "ARTPOP"
      }
    },
    "art": {
      "sources": [
        {
          "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
          "size": "X_SMALL",
          "widthPixels": 48,
          "heightPixels": 48
        },
        {
          "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
          "size": "SMALL",
          "widthPixels": 60,
          "heightPixels": 60
        },
        {
          "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
          "size": "MEDIUM",
          "widthPixels": 110,
          "heightPixels": 110
        },
        {
          "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
          "size": "LARGE",
          "widthPixels": 256,
          "heightPixels": 256
        },
        {
          "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
          "size": "X_LARGE",
          "widthPixels": 600,
          "heightPixels": 600
        }
      ]
    }
  },
  "durationInMilliseconds": 248000,
  "controls": [
    {
      "type": "COMMAND",
      "name": "NEXT",
      "enabled": true
    },
    {
      "type": "COMMAND",
      "name": "PREVIOUS",
      "enabled": false
    }
  ],
  "rules": {
    "feedbackEnabled": true
  },
  "stream": {
    "id": "STREAMID_92_14629004",
    "uri": "http://cdn.example.com/api/1/a2f318467fbf282999|6adc0880e0abd03d03b1ba6ac.mp3",
    "offsetInMilliseconds": 0,
    "validUntil": "2018-05-10T19:11:35Z"
  },
  "feedback": {
    "type": "PREFERENCE",
    "value": "POSITIVE"
  }
}

ItemControl

An object that describes a control that the user can take on an item. Examples are skip forward and skip backward buttons. Note that item controls will override any existing queue controls of the same type.

Synonyms

Track Button Control

Structure

The object has the same structure as BaseControl.

Examples

{
  "type": "COMMAND",
  "name": "NEXT",
  "enabled": true
}

ItemReference

Identifiers to identify a specific Item.

Structure

Field Description Required? Type
id The Item identifier. yes string
queueId The ID of the Queue containing the Item. yes string
contentId Content identifier that uniquely identifies the content to be played on the device. yes string

Examples

{
  "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
  "queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
  "contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
}

ItemRules

Describes rules for what the user can do with an item. One example of a rule is whether the user can provide feedback about an audio item. Note that item level rules will override queue level rules.

Synonyms

Item Rules

Structure

Field Description Required? Type
feedbackEnabled Determine whether the user is allowed to provide feedback for a given item. Defaults to the flag specified in the QueueFeedbackRule. no Boolean

Examples

{
  "feedbackEnabled": false
}

Location

Describes the location of a request. Use this information to enforce geographical restrictions on content or decide which language version of metadata to return to Alexa for media items.

Structure

Field Description Required? Type
originatingLocale The locale for the user. This is the locale that the user specified based on the language setting on the device. Locale is formatted as specified for languages in BCP-47. When the locale is not required for the skill to process a request, this field may be absent. no string
countryCode Code (based on ISO 3166-1 alpha-2) for the country where the request was made. This might be the country of the registered account of the user who made the request, or the country of the target device owned by that user. no string

Examples

{
  "originatingLocale": "en-US",
  "countryCode": "US"
}

MediaMetadata

Contains metadata (for example, album name, author name, title, "type", etc.) for a media item (i.e., Content or Item).

Base structure

MediaMetadata extends BaseMetadata, and supports the following metadata types:

  • ALBUM - for an album
  • ARTIST - for an artist
  • GENRE - for a genre
  • PLAYLIST - for a playlist
  • STATION - for a station
  • TRACK - for a track/song

Structure for ALBUM

The ALBUM type has the following fields in addition to the base fields.

Field Description Required? Type
authors A list of EntityMetadata objects for the authors of the album. This is usually used in the Alexa voice prompt spoken before the content begins to play. See the EntityMetadata object for more information. yes list

Structure for ARTIST, GENRE, PLAYLIST, and STATION

These types have the same structure as the base.

Structure for TRACK

The TRACK type has the following fields in addition to the base fields.

Field Description Required? Type
authors A list of EntityMetadata objects for the authors of the album containing the content. This is usually used in the Alexa voice prompt spoken before the content begins to play. See the EntityMetadata object for more information. no list
album An EntityMetadata object for the album that contains the content. This is usually used in the Alexa voice prompt spoken before the content begins to play. See the EntityMetadata object for more information. no object

Examples - ALBUM

{
  "type": "ALBUM",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "art pop"
    },
    "display": "ARTPOP"
  },
  "authors": [
    {
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "lady gaga"
        },
        "display": "Lady Gaga"
      }
    }
  ],
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

Examples - ARTIST

{
  "type": "ARTIST",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "lady gaga"
    },
    "display": "Lady Gaga"
  },
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

Examples - STATION

{
  "type": "STATION",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "c n n"
    },
    "display": "C.N.N."
  },
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

Examples - TRACK

{
  "type": "TRACK",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "thrift shop"
    },
    "display": "Thrift Shop"
  },
  "authors": [
    {
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "macklemore"
        },
        "display": "Macklemore"
      }
    }
  ],
  "album": {
    "name": {
      "speech": {
        "type": "",
        "text": ""
      },
      "display": ""
    }
  },
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

MediaReference

A polymorphic object used to identify a specific media item (Item) to be used in cases where a media item must be identified in a domain-agnostic manner.

Structure

Field Description Required? Type
namespace Identifies the interface of the property object. In the case of music skills, the namespace will be Alexa.Audio.PlayQueue. The value of this field identifies the possible types for the name and value fields in this object. yes string
name The name of the content being consumed by the Alexa user. The possible set of values for this field are determined by the value of the namespace field. In the case of music skills, this field's value is always item. yes object
value Identifies a specific piece of content. For the Alexa.Audio.PlayQueue namespace, and item name, the value property must contain an ItemReference object. See the following example. yes object

Examples

{
  "namespace": "Alexa.Audio.PlayQueue",
  "name": "item",
  "value": {
    "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
    "queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
    "contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
  }
}

MetadataNameProperty

Metadata used for voice prompt or display use cases of entity (artist, song, etc.) names.

Structure

Field Description Required? Type
speech Name of the entity to be used in Alexa voice prompts. See the SpeechInfo object for details. yes object
display Name of the entity to be used in display use cases such as in the Alexa app. Currently the Alexa service ignores this field. yes string

Examples

{
  "speech": {
    "type": "PLAIN_TEXT",
    "text": "thrift shop"
  },
  "display": "Thrift Shop"
}

PlaybackInfo

An object that describes which business rules Alexa should run when playing an item. More specifically:

For advertisements, Alexa will follow these rules:

  • No skipping or seeking allowed
  • No mention of the advertisement in prompts (or display use cases) for what's playing next
  • Alexa may want to inform users (in the app's Now Playing screen) that an advertisement is currently playing
  • Some potential differences in metadata for an advertisement versus a default track

For samples, Alexa will render different prompts (mentioning that an item is a sample and not the full track), and it may potentially augment the item's metadata.

Structure

Field Description Required? Type
type The type of playback info. The field can have one of the following values:

DEFAULT - describes an item that is neither a sample nor an ad
SAMPLE - describes an item whose stream is a shorter version of a full track
AD - describes an item whose stream is an advertisement
yes string

Examples

{
  "type": "DEFAULT"
}

PlaybackMethod

When Alexa has a reference to some content as a result of GetPlayableContent, and wants to start playback for the user, it invokes the skill with the content reference so the skill can realize the content into a PlaybackMethod. So, PlaybackMethod is a realization of Content.

It is up to the skill to determine whether a queue can be reused between users or streaming sessions. For example, to support concurrency limit use cases, a queue might have to be unique for each user or streaming session. As another example, music cast from an app to an Alexa device should likely share the same queue from which the app was playing before casting. It is important to note that you can optimize play queue creation by sharing the same queue between different users without storing any information for each user or device. This is possible because in the Queue interfaces, Alexa includes the item ID, queue ID, and content reference in each request. Therefore, you don't need to store progress state for each user within a certain play queue.

Synonyms

Queue

Structure

Field Description Required? Type
type The type of the playback method. The only allowed value is ALEXA_AUDIO_PLAYER_QUEUE. yes string

AudioPlayer-based (Queue)

Field Description Required? Type
id The identifier for this play queue that is opaque to Alexa. If the skill wants to enforce concurrency limits, then the queue ID should be unique for each user. Note that all Music Skill API requests after a queue is created will report this queue ID back to the skill in all requests. yes string
controls List of QueueControl objects used by Alexa to determine which controls should be clickable in the Alexa app. Note that some queue-level controls might be overridden at the item-level. See the QueueControl object for more information. no list
rules Identifies rules that apply to all audio items in the play queue. Note that some queue-level rules may be overridden at the item-level. yes object
queueIdsToDeactivate If the skill enforces concurrency limits, it can either reject new Initiate requests with a DEVICE_LIMIT_REACHED error or it can create a new queue and return a list of existing queue IDs for Alexa to deactivate before initiating playback for the new queue. no list
firstItem The first item from this queue that Alexa should play for the user. See the Item object for more information. yes string

Examples

AudioPlayer response

{
  "type": "ALEXA_AUDIO_PLAYER_QUEUE",
  "id": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
  "controls": [
    {
      "type": "TOGGLE",
      "name": "SHUFFLE",
      "enabled": true,
      "selected": false
    },
    {
      "type": "TOGGLE",
      "name": "LOOP",
      "enabled": true,
      "selected": false
    }
  ],
  "rules": {
    "feedback": {
      "type": "PREFERENCE",
      "enabled": true
    }
  },
  "firstItem": {
    "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
    "playbackInfo": {
      "type": "DEFAULT"
    },
    "metadata": {
      "type": "TRACK",
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "thrift shop"
        },
        "display": "Thrift Shop"
      },
      "art": {
        "sources": [
          {
            "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
            "size": "X_SMALL",
            "widthPixels": 48,
            "heightPixels": 48
          },
          {
            "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
            "size": "SMALL",
            "widthPixels": 60,
            "heightPixels": 60
          },
          {
            "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
            "size": "MEDIUM",
            "widthPixels": 110,
            "heightPixels": 110
          },
          {
            "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
            "size": "LARGE",
            "widthPixels": 256,
            "heightPixels": 256
          },
          {
            "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
            "size": "X_LARGE",
            "widthPixels": 600,
            "heightPixels": 600
          }
        ]
      }
    },
    "durationInMilliseconds": 235000,
    "controls": [
      {
        "type": "COMMAND",
        "name": "NEXT",
        "enabled": true
      },
      {
        "type": "COMMAND",
        "name": "PREVIOUS",
        "enabled": false
      }
    ],
    "rules": {
      "feedbackEnabled": true
    },
    "stream": {
      "id": "STREAMID_92_14629004",
      "uri": "http://cdn.example.com/api/1/a2f318467fbf2829996adc0880e0abd03d03b1ba6ac.mp3",
      "offsetInMilliseconds": 0,
      "validUntil": "2018-05-10T19:11:35Z"
    },
    "feedback": {
      "type": "PREFERENCE",
      "value": "POSITIVE"
    }
  }
}

QueueControl

An object that describes a control that the user could apply to a queue or the items in the queue. Examples are shuffle and loop. Note that some queue controls can be overridden at the item level. Note that if the enablement status of a control is not specified, Alexa assumes the control is disabled.

Structure

The base object extends BaseControl and has the following structure.

Field Description Required? Type
type The object supports the following types in addition to the base types:
TOGGLE - for controls such as shuffle
yes string
name The object supports the following names in addition to the base names:

For type TOGGLE, the value can be one of the following:
SHUFFLE - for toggling shuffle mode for the queue
LOOP - for toggling loop mode for the queue

Note the following controls are overridable at the item level: SEEK_POSITION, NEXT, PREVIOUS
yes string

TOGGLE Type

The TOGGLE type has the following fields in addition to the base fields above.

Field Description Required? Type
selected Indicates that a control should render in a selected state. For example, if a user has turned on loop mode in the provider's app, when the queue is casted to an Alexa device, the loop control will have a selected value of true. Defaults to false. no Boolean

Examples

{
  "type": "ADJUST",
  "name": "SEEK_POSITION",
  "enabled": true
}
{
  "type": "TOGGLE",
  "name": "LOOP",
  "enabled": true,
  "selected": true
}

QueueFeedbackRule

An object that describes whether feedback of a specific type is allowed at the queue level.

Synonyms

Queue Preference Setting, Queue Thumbs Up/Down Setting

Structure

Field Description Required? Type
type The type of feedback. The only supported value is PREFERENCE. yes string
enabled Whether feedback should be enabled. If false, Alexa will render error prompts (VUI) or show error messages (GUI) when the user tries to provide feedback. Note that this flag can be overridden on an item-by-item basis. yes Boolean

Examples

{
  "type": "PREFERENCE",
  "enabled": true
}

QueueRules

Identifies rules that apply to all items in the play queue.

Synonyms

Queue Settings

Structure

Field Description Required? Type
feedback Used to identify whether feedback of a specific type is allowed for a queue. If absent, Alexa assumes that no type of feedback is supported for this queue. See QueueFeedbackRule for details. Note that enablement of feedback can be overridden at the item level. no object

Examples

{
  "feedback": {
    "type": "PREFERENCE",
    "enabled": true
  }
}

RequestContext

Contains fields necessary for describing the context of an Alexa Music Skill API request.

Synonyms

Context

Structure

Field Description Required? Type
user Contains user-specific information from the request. See the User object for more information. yes object
location Object that describes a request's location. See the Location object for more information. no object

Examples

{
  "user": {
    "id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
    "accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
  },
  "location": {
    "originatingLocale": "en-US",
    "countryCode": "US"
  }
}

ResolvedSelectionCriteria

Content selection criteria in resolved form. A ResolvedSelectionCriteria object identifies attributes that can be resolved (by searching) to a Content object.

Structure

Field Description Required? Type
rawSelectionCriteriaId The opaque identifier for the RawSelectionCriteria that was used to come up with the attributes for this ResolvedSelectionCriteria. When returning resolved selection criteria back to Alexa, the skill must include this field based on the raw selection criteria that it used to come up with the resolved criteria. no string
attributes A list of ResolvedSelectionCriteriaAttribute objects where each one represents one attribute of the ResolvedSelectionCriteria. Note: The relationship between ResolvedSelectionCriteriaAttributes is of type AND. yes list

Examples

{
  "rawSelectionCriteriaId": "e7f74c2c-eec7-452c-ad53-7f82509232c8",
  "attributes": [
    {
      "type": "GENRE",
      "entityId": "G1"
    },
    {
      "type": "ARTIST",
      "entityId": "A2"
    },
    {
      "type": "MEDIA_TYPE",
      "value": "TRACK"
    }
  ]
}

ResolvedSelectionCriteriaAttribute

A single attribute within a resolved content selection criteria. A ResolvedSelectionCriteriaAttribute object conveys a single aspect of a user's request in refined or processed form, for example, the song name "Thrift Shop" (with skill-provided entity ID) in "Alexa, play the song Thrift Shop".

Synonyms

Catalog Match, Entity

Base structure

Field Description Required? Type
type The type of the attribute. See EntityType for all possible values. yes string

Structure for resolved attributes

Attributes whose type is neither MEDIA_TYPE nor SORT_TYPE will have the following structure that extends the base structure:

Field Description Required? Type
entityId A skill-provided identifier for the piece of content this attribute represents. This identifier gets ingested as part of one of the skill's catalogs. Note that the identifier should uniquely identify a specific piece of content in the skill's data domain. If a provider shares entity IDs across entity types, then because this ID is already scoped by the type (the other attribute in this object), the provider should still be able to uniquely identify content using this ID. Also note that Alexa will not modify the skill-provided identifier in any way before sending it to the skill as part of an API request. yes string

Structure for MEDIA_TYPE attributes

MEDIA_TYPE attributes will have the following structure that extends the base structure:

Field Description Required? Type
value The value for the attribute, which can be one of the following:
ALBUM
PLAYLIST
TRACK
STATION
yes string

Structure for SORT_TYPE attributes

SORT_TYPE attributes will have the following structure that extends the base structure:

Field Description Required? Type
value The value for the attribute, which can be one of the following:
RECENCY
POPULARITY
yes string

Examples

{
  "type": "ARTIST",
  "entityId": "126564"
}
{
  "type": "MEDIA_TYPE",
  "value": "TRACK"
}

SpeechInfo

Captures the details of how Alexa should render text in voice prompts to the user.

Structure

See the OutputSpeech Object for the structure of the object. Note that currently only PLAIN_TEXT is supported.

Examples

{
  "type": "PLAIN_TEXT",
  "text": "lady gaga"
}

Stream

Contains the stream URI that Alexa sends to devices as part of an AudioPlayer play directive, along with other stream-related information such as the playback offset in milliseconds, the expiration time of the URI, and an identifier for the stream.

Synonyms

URL, playback URL

Structure

Field Description Required? Type
id A unique opaque (to Alexa) identifier for the stream. Note that the same stream (with the same identifier) can be re-used across User and Queue instances. yes string
uri URI of the stream (file or audio-chunk playlist). This URI is sent to the Alexa device media player to play the content. URIs must be HTTPS. yes string
offsetInMilliseconds Offset in milliseconds of where to start playback of the stream. Defaults to 0. no long
validUntil ISO 8601 representation of when the stream URI expires. At the time of the skill returning a stream to Alexa, the validUntil date must be in the future, ideally at least 15 minutes, but it can be hours, days, or years in the future. This value is passed to Alexa devices in the play directive as part of the AudioResourceLocator. Defaults to roughly 60 seconds after the stream object is received from the music skill.

Note the expiration of the stream URI is defined as the latest point of time when the stream can be initiated with the given URI. Once initiated, the stream should be allowed to continue to completion without expiration.

For example, a 5-minute track has a validUntil value of 09:00 AM today. If the Alexa device begins streaming the track at 08:58 AM, the track should successfully play its entire 5 minute duration, ending at 09:04 AM.
no string

Examples

{
  "id": "STREAMID_92_14629004",
  "uri": "http://cdn.example.com/api/1/a2f318467fbf2829996adc0880e0abd03d03b1ba6ac.mp3",
  "offsetInMilliseconds": 0,
  "validUntil": "2018-11-10T19:11:35Z"
}

User

Describes information about the user who initiated a request to the music skill.

Synonyms

Customer Information

Structure

Field Description Required? Type
id Unique identifier for the user who made the request. Not all music skills will support account linking, and those skills can make use of the user identifier to distinguish API calls triggered by different Alexa users. As an example use case, for skills that do not require account linking, this identifier may be used by the skill to rate limit a specific user.

Note: This ID changes every time the user disables and re-enables the skill.
yes string
accessToken OAuth 2.0 access token from a user's linked account. This property will be set to null if the user has not linked an account with the skill. If this field is present, the skill should use this field to identify the user and should ignore the user identifier provided in this object. no string

Examples

{
  "id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
  "accessToken": "e70e10c7e02f092c6002e1234c54321ab192b4c"
}