Implement Podcast Skill Features

Terminology

This topic uses the following terms:

• Program series – A podcast or other on-demand audio content. A program series is an entity with a name that typically has multiple audio files. There are a few variations in specific terminology given how API fields have been named. The following terms are used to refer to program series:
  • Program series
  • Program series name (RSS tag: <title>)
• Program – An episode, one of the audio files that make up a program series. Each program has its own unique metadata, such as episode title, number, and release date. The following terms refer to programs (episodes):
  • Program name – the episode title (RSS tag: <itunes:title>)
  • Program number – the number of the episode in a program series (RSS tag: <itunes:episode>)
  • Program season number – the number of the season in a program series (RSS tag: <itunes:season>)
• Type – The type of program series. Your skill should follow the correct playing sequence for each type. (RSS tag: <itunes:type>)
  • Serialized program series that are meant to be consumed sequentially. The playing sequence is oldest to latest.
  • Episodic program series, where consumption order of programs is less important. The playing sequence is latest to oldest.
• Resume marker – The customer's listening history. Based on the history maintained by the provider, the resume marker signifies the program of a program series that a customer most recently listened to and the offset of the program where Alexa should resume. The resume marker is the lastPlayed field in the UserContentProperties structure.
• Subscription play queue – A list of episodes from the customer’s subscribed podcasts, intended to be consumed in sequence.

Implement required podcast features in your skill's Lambda function

After you create a music skill and a Lambda function, you must add the code for your podcast skill to the Lambda function.

For a consistent customer experience, all podcast skills must implement the following features. Before implementing each feature, we highly recommend that you review the Podcast customer experience overview to understand what's expected and how to test the feature.

Implement basic playback

Prerequisite: none

Basic playback allows customers to play, fast-forward, and rewind program series content on Alexa.

To implement basic podcast playback

1. Implement the following directives: GetPlayableContent, Initiate, GetNextItem, GetPreviousItem.
2. Add explicit SEEK_POSITION control in Initiate, GetNextItem, and GetPreviousItem responses to enable fast-forward, rewind, and restart for a program.

Implement continuous play

Prerequisite: basic playback

Continuous play allows the next program in the play queue to start automatically after the previous program in the queue has completed. Episodic program series continuously play in reverse chronological order. Serialized program series play continuously in chronological order unless interrupted by the customer.

Implement Get previous/Get next

Prerequisite: basic playback

Get previous/Get next allows the customer to ask Alexa to move to the next or previous program. Asking to "play the next episode" moves the customer to the program published after the one currently playing and asking to "play previous episode" moves the customer to the program published before the one currently playing while maintaining the state of in-progress programs.

To implement Get previous/Get next

1. Maintain customer program series and program listening history.
2. Implement proper playing sequence in Initiate, GetNextItem, and GetPreviousItem responses, based on the type of program series (serial or episodic).

Implement state persistence

Prerequisite: basic playback

State persistence allows customers to resume their program series listening based on their account activity on a specific provider, whether that activity was in a smartphone app or on an Alexa-enabled device. The provider communicates to Alexa which program and what offset in that program to use for the requested program. State persistence should synchronize listening between the customer's Alexa devices and non-Alexa endpoints through account linking.

This feature relies on the provider using and maintaining a unified storage system for the listening history of the customer. If the customer has a linked account, this listening history should contain history from Alexa devices and non-Alexa endpoints.

Alexa resumes content playback ten seconds ahead of the offset sent by the provider.

To implement state persistence

1. Maintain customer program series and program listening history.
2. Implement event subscriptions and use them to update customer listening history.
3. By default, Alexa music skills use Alexa's state persistence service to enable resuming a podcast. Alternatively, the provider can handle the state persistence themselves by opting to receive a GetPlayableContent request for resume utterances. To choose this option, add the following field to the "music" field of the skill manifest:

"contentTypes": [{
    "name": "PODCAST"
}]

To determine when your skill last played an item for the customer, see the lastPlayed field in the UserContentProperties structure.

Implement the ability to play the latest or oldest programs

Prerequisites: basic playback and state persistence

This feature allows customers to jump to the latest (most recent) or oldest (earliest) program or season within a program series.

To determine when a program was released, see the releaseDate field in the PROGRAM structure.

To implement the ability to play the latest or oldest programs

1. Identify the currently playing program series from the customer's listening history even though the information isn't included in the SelectionCriteria from GetPlayableContent request and return the latest program for the first item to play.
2. In Initiate responses, if the chosen program is the latest, the isLatest attribute is required and must be true. For details about how to set the isLatest flag, see the Initiate response examples for podcasts.

Alternatively, you can use the program's <pubDate> value in the podcast's RSS feed. This value is a timestamp indicating when the program was initially published. Unless otherwise stated, use ISO 8601-formatted strings for timestamps.

Implement episode search by timeframe

Prerequisite: basic playback

This feature allows customers to search for programs in a program series that fall within a specific timeframe.

To implement episode search by timeframe

1. Check to make sure the skill has a program series that matches the customer's requested program series name.
2. If there isn't a match for the program series, respond with an error message.
3. If there is a match for the program series, return programs whose release dates match the specified timeframe.
4. Consider sending releaseDate in the Initiate response payload and including the episode release date in the prompt. This helps customers validate that they're getting the desired episode. For example, "Alexa, play The Daily from March 3rd." "Okay. Playing the March 3rd episode of The Daily from <provider>, episode <episodeName>." For examples, see Initiate response event.

Implement episode search by topic

Prerequisite: basic playback

This feature allows customers to search for programs in a program series that are about a specified topic.

To implement episode search by topic

1. Check to make sure the skill has a program series that matches the customer's requested program series name.
2. If there isn't a match for the program series, respond with an error message.
3. If there is a match for the program series, return programs that match the specified topic.

Implement episode search by season and program number

Prerequisite: basic playback

This feature allows customers to search for programs in a program series by season and/or program number.

To implement the ability to search by season and program number

1. Store the available season and program number metadata for the program series.
   Note: This is a requirement for all podcasts in your content catalog, whether they are serialized or episodic.
2. Find and play the season and/or program number of the requested program series.
3. If multiple episode matches are found, use resume markers to infer the best program to play. Following is the recommended logic:
   1. If the customer requests episode x of a serialized program series and there's no resume marker, play the earliest season with episode x.
   2. If the requested program is episodic and there's no resume marker, play the latest season with episode x.
   3. If the requested program is serialized or episodic, and there's a resume marker in episode x, play episode x from the most recent resume marker.
   4. If the requested program is serialized or episodic, and there's a resume marker but not within episode x, play the episode whose release date is closest to the resume marker.
4. If a partial match is found, honor the matched season or program number when selecting the program to play, following the recommended logic.
5. If no program matches the specified season or program number, fall back to the basic playback experience.

Implement optional podcast features in your skill's Lambda function

You can implement the following optional podcast features by adding code to your skill's Lambda function.

Implement subscription playback

Prerequisite: basic playback

Subscription playback allows customers to have Alexa play their podcast episodes from multiple program series as a single subscription playlist. With this feature, customers aren't required to open an app or remember the title of every podcast they subscribe to.

In subscription playback, next and previous utterances are the only ones that we expect customers to use to navigate the subscription queue. Other in-focus utterances, such as "Alexa, play the latest episode", would cause the subscription queue to be discarded.

To implement subscription playback

1. Add support for the FOLLOW_STATUS selection criteria attribute in GetPlayableContent.
2. Create a subscription play queue consisting of the latest episodes from the program series that the customer subscribes to or follows. Providers are responsible for defining the playback sequence when the customer asks Alexa to play episodes in their subscription queue. Following is the recommended logic:
   1. Include episodes from the podcasts the customer follows. Only include episodes that the customer hasn't listen to or has only partially listened to.
   2. Include multiple episodes from the same podcast or episodes from different podcasts.
   3. For episodic podcasts, order the episodes from newest to oldest (by publication date).
   4. Order the program series by how frequently the customer listens to them.

Last updated: Nov 27, 2023