Skip to content

Commit

Permalink
fix: Iteration w/ Simon's feedback
Browse files Browse the repository at this point in the history
  • Loading branch information
@jlacivita
jlacivita committed Aug 15, 2023
1 parent 81ba8cb commit 5aed451
Showing 1 changed file with 104 additions and 48 deletions.
152 changes: 104 additions & 48 deletions requirements/specifications/intents/play.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,66 +9,78 @@ See [Firebolt Requirements Governance](../../governance.md) for more info.
| Jeremy LaCivita | Comcast |
| Liz Sheffield | Comcast |
| Seth Kelly | Comcast |
| Simon Grist | Sky |

## 1. Overview
There are many use cases where a Firebolt device will need to inform an app of a user's intention to play something. This could originate from a voice remote, an editorial tile, a developer tool, or any number of places. Having a standard message to play something allows an app to integrate with this message once, while allowing the platform to change when and where the intent comes from w/out further work from the app.

Apps will need to be able to play specific entities from a back-office meta-data integration, entities from a federated meta-data integration, or non-specific entities based on a query.

The existing Firebolt `playback` intent does not meet these requirements. This document outlines a more flexible `play` intent to replace it.
The existing Firebolt `playback` intent does not meet these requirements. This document outlines a more flexible `play-entity` and `play-query` intent to replace it.

TODO:

## 2. Table of Contents
- [1. Overview](#1-overview)
- [2. Table of Contents](#2-table-of-contents)
- [3. Play Intent](#3-play-intent)
- [3.1. Play First Option for a Playlist Entity](#31-play-first-option-for-a-playlist-entity)
- [3.2. Play Options for Query](#32-play-options-for-query)
- [4. Core APIs](#4-core-apis)
- [3. Play Entity Intent](#3-play-entity-intent)
- [3.1. Playlist Entity Options](#31-playlist-entity-options)
- [3.1.1. Play First Option](#311-play-first-option)
- [4. Play Query Intent](#4-play-query-intent)
- [4.1. Play Options for Query](#41-play-options-for-query)
- [5. Core APIs](#5-core-apis)

## 3. Play Intent
The Firebolt `navigateTo` notification **MUST** support a `play` intent, which tells an app to initiate playback of either a specific entity or to find content that matches a query and play that content.
## 3. Play Entity Intent
The Firebolt `navigateTo` notification **MUST** support a `play-entity` intent, which tells an app to initiate playback of specific entity.

The `play` intent **MUST** have an `action` property, whose value is `'play'`.
The `play-entity` intent **MUST** have an `action` property, whose value is `"play-entity"`.

The `play` intent **MUST** have `data` property, which is an object conforming to the following:
The `play-entity` intent **MUST** have a `data` object property, which is an object conforming to the following:

> The `data` object **MUST** have either an `entity` object property or a `query` string property and **MUST NOT** have both.
> The `data` object **MUST** have an `entity` object property.
>
> The `entity` object, if present, **MUST** be an [Entity](../entities/index.md).
> The `entity` object, **MUST** be an [Entity](../entities/index.md).
>
> The `data` object **MAY** have an `options` object property that conforms to [Play Options](#31-play-options).
> The `data` object **MAY** have an `options` object property that conforms to [Play Entity Options](#31-play-entity-options).
The `play` intent **MUST** have a `context` object property that conforms to the [Intent Context](./context.md).
The `play-entity` intent **MUST** have a `context` object property that conforms to the [Intent Context](./context.md).

An example play intent:
An example play-entity intent:

```json
{
"action": "play",
"action": "play-entity",
"data": {
"query": "Ed Sheeran"
"entity": {
"entityType": "program",
"programType": "movie",
"entityId": "movie/xyz"
}
},
"context": {
"source": "voice"
}
}
}
```

Which would instruct an app to search for content matching the query "Ed Sheeran" and then play the results.
Which would instruct an app to play the movie entity with id `movie/xyz`.

### 3.1. Playlist Entity Options

### 3.1. Play First Option for a Playlist Entity
For `play` intents with an `entity` whose `entityType` is `"playlist"`, e.g.:
#### 3.1.1. Play First Option
For `play-entity` intents with an `entity` whose `entityType` is `"playlist"`, e.g.:

```json
{
"action": "play",
"action": "play-entity",
"data": {
"entity": {
"entityType": "playlist",
"entityId": "playlist/xyz"
}
},
"context": {
"source": "voice"
}
}
```
Expand All @@ -78,15 +90,18 @@ identify an entity to play *before* starting the playlist, e.g.:

```json
{
"action": "play",
"action": "play-entity",
"data": {
"entity": {
"entityType": "playlist",
"entityId": "playlist/xyz"
},
"options": {
"playFirstId": "song/xyz"
}
},
"options": {
"playFirstId": "song/xyz"
"context": {
"source": "voice"
}
}
```
Expand All @@ -100,15 +115,18 @@ identify an entity from the playlist to play *before* the rest of the playlist,

```json
{
"action": "play",
"action": "play-entity",
"data": {
"entity": {
"entityType": "playlist",
"entityId": "playlist/xyz"
},
"options": {
"playFirstTrack": 3
}
},
"options": {
"playFirstTrack": 3
"context": {
"source": "voice"
}
}
```
Expand All @@ -117,14 +135,46 @@ If `playFirstTrack` is provided and the playlist has at least that many items, t

The options object **MUST NOT** have both a `playFirstId` and a `playFirstTrack` property.

### 3.2. Play Options for Query
For `play` intents with a `query`, e.g.:
## 4. Play Query Intent
The Firebolt `navigateTo` notification **MUST** support a `play-query` intent, which tells an app to find content that matches a query and play that content.

The `play-query` intent **MUST** have an `action` property, whose value is `"play-query"`.

The `play-query` intent **MUST** have `data` property, which is an object conforming to the following:

> The `data` object **MUST** have a `query` string property.
>
> The `data` object **MAY** have an `options` object property that conforms to [Play Options](#41-play-options-for-query).
The `play-query` intent **MUST** have a `context` object property that conforms to the [Intent Context](./context.md).

An example play intent:

```json
{
"action": "play-query",
"data": {
"query": "Ed Sheeran"
},
"context": {
"source": "voice"
}
}
```

Which would instruct an app to search for content matching the query "Ed Sheeran" and then play the results.

### 4.1. Play Options for Query
For `play-query` intents with a `query`, e.g.:

```json
{
"action": "play",
"action": "play-query",
"data": {
"query": "Ed Sheeran"
},
"context": {
"source": "voice"
}
}
```
Expand All @@ -134,14 +184,17 @@ filter which program entity typess, e.g. `[ "movie", "episode" ]` should be incl

```json
{
"action": "play",
"action": "play-query",
"data": {
"query": "Ed Sheeran"
"query": "Ed Sheeran",
"options": {
"programTypes": [
"movie"
]
}
},
"options": {
"programTypes": [
"movie"
]
"context": {
"source": "voice"
}
}
```
Expand All @@ -151,29 +204,32 @@ filter which music entity typess, e.g. `[ "song", "album" ]` should be included,

```json
{
"action": "play",
"action": "play-query",
"data": {
"query": "Ed Sheeran"
"query": "Ed Sheeran",
"options": {
"programTypes": [
"movie"
],
"musicTypes": [
"song"
]
}
},
"options": {
"programTypes": [
"movie"
],
"musicTypes": [
"song"
]
"context": {
"source": "voice"
}
}
```

## 4. Core APIs
The Firebolt Core SDK will support listening to `play` intents via the `Discovery.navigateTo` notification.
## 5. Core APIs
The Firebolt Core SDK will support listening to `play-query` and `play-entity` intents via the `Discovery.navigateTo` notification.

```javascript
import { Discovery } from '@firebolt-js/sdk'

Discovery.listen('navigateTo', (intent) => {
if (intent.action === 'play') {
if (intent.action === 'play-query')
// do stuff with play intent!
}
})
Expand Down

0 comments on commit 5aed451

Please sign in to comment.