From 96687291669062c54a3555f826512fbb70508d87 Mon Sep 17 00:00:00 2001 From: Jeremy LaCivita Date: Fri, 27 Oct 2023 12:52:34 -0400 Subject: [PATCH] fix: Fix links and formatting --- .../specifications/entities/channels.md | 35 +++-- requirements/specifications/entities/index.md | 53 ++++--- requirements/specifications/entities/music.md | 44 +++--- .../specifications/entities/programs.md | 52 ++++--- requirements/specifications/intents/index.md | 63 ++++---- requirements/specifications/intents/play.md | 138 +++++++++++------- 6 files changed, 228 insertions(+), 157 deletions(-) diff --git a/requirements/specifications/entities/channels.md b/requirements/specifications/entities/channels.md index 5a742d365..275e1d385 100644 --- a/requirements/specifications/entities/channels.md +++ b/requirements/specifications/entities/channels.md @@ -1,17 +1,22 @@ # Channel Entities -Document Status: Working Draft +Document Status: Proposed Specification -See [Firebolt Requirements Governance](../../governance.md) for more info. +See [Firebolt Requirements Governance](../../governance.md) for more info. -| Contributor | Organization | -| -------------- | -------------- | -| Jeremy LaCivita | Comcast | +| Contributor | Organization | +| --------------- | ------------ | +| Jeremy LaCivita | Comcast | ## 1. Overview -TBD... +TBD... -The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. +The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL +NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT +RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be +interpreted as described in [BCP +14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and +only when, they appear in all capitals, as shown here. ## 2. Table of Contents - [1. Overview](#1-overview) @@ -20,16 +25,18 @@ The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL ## 3. Channel Entities -Every Channel Entity **MUST** be an [Entity](./index.md#3-entities). +Every Channel Entity **MUST** be an [Entity](./index.md#3-entities). -Every Channel Entity **MUST** have a `const` property named `entityType`, which **MUST** have the value `"channel"`. +Every Channel Entity **MUST** have a `const` property named `entityType`, which +**MUST** have the value `"channel"`. -Every Channel Entity **MUST** have a `string` property named `channelType`, whose value **MUST** be one of: +Every Channel Entity **MUST** have a `string` property named `channelType`, +whose value **MUST** be one of: - `"streaming"` - `"broadcast"` -An example Channel Entity: +An example Channel Entity: ```json { @@ -37,9 +44,9 @@ An example Channel Entity: "channelType": "streaming", "entityId": "streaming/xyz" } -``` +``` -Another example Channel Entity: +Another example Channel Entity: ```json { @@ -47,4 +54,4 @@ Another example Channel Entity: "channelType": "broadcast", "entityId": "broadcast/xyz" } -``` +``` diff --git a/requirements/specifications/entities/index.md b/requirements/specifications/entities/index.md index d9c2be5ab..9f3b80c1e 100644 --- a/requirements/specifications/entities/index.md +++ b/requirements/specifications/entities/index.md @@ -1,15 +1,22 @@ # Firebolt Entities -Document Status: Working Draft +Document Status: Proposed Specification -See [Firebolt Requirements Governance](../../governance.md) for more info. +See [Firebolt Requirements Governance](../../governance.md) for more info. ## 1. Overview -Entities are object which identify a piece of content that an end-user may consume within an app. +Entities are object which identify a piece of content that an end-user may +consume within an app. -Firebolt uses Entities or Entity Ids as parameters and/or results of content-centric Firebolt APIs that an App may interact with. +Firebolt uses Entities or Entity Ids as parameters and/or results of +content-centric Firebolt APIs that an App may interact with. -The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. +The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL +NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT +RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be +interpreted as described in [BCP +14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and +only when, they appear in all capitals, as shown here. ## 2. Table of Contents - [1. Overview](#1-overview) @@ -19,23 +26,33 @@ The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL - [5. Entity Specifications](#5-entity-specifications) ## 3. Entities -Every Entity **MUST** be of type `object`. +Every Entity **MUST** be of type `object`. -Every Entity object **MUST** have a `string` property named `entityId`, which identifies the entity. The scope of entity identifiers **SHOULD** be defined by the app providing or receiving the Entity, so that the App may work across Firebolt distrubutions without mapping IDs from a distributor space to the App's space. +Every Entity object **MUST** have a `string` property named `entityId`, which +identifies the entity. The scope of entity identifiers **SHOULD** be defined by +the app providing or receiving the Entity, so that the App may work across +Firebolt distrubutions without mapping IDs from a distributor space to the +App's space. -Every Entity object **MAY** have a `string` property named `assetId`, which disambiguates the asset from the entity, if needed. The scope of asset identifiers **SHOULD** be defined by the app providing or receiving the Entity, so that the App may work across Firebolt distrubutions without mapping IDs from a distributor space to the App's space. +Every Entity object **MAY** have a `string` property named `assetId`, which +disambiguates the asset from the entity, if needed. The scope of asset +identifiers **SHOULD** be defined by the app providing or receiving the Entity, +so that the App may work across Firebolt distrubutions without mapping IDs from +a distributor space to the App's space. -Every Entity object **MAY** have a `string` property named `appContentData`, limited to 256 characters, which provides additional information useful for targeting that Entity, e.g. a deeplink path. +Every Entity object **MAY** have a `string` property named `appContentData`, +limited to 256 characters, which provides additional information useful for +targeting that Entity, e.g. a deeplink path. -An example Entity: +An example Entity: ```json { "entityId": "entity/abc" } -``` +``` -Another example Entity: +Another example Entity: ```json { @@ -43,14 +60,16 @@ Another example Entity: "assetId": "asset/123", "appContentData": "xyz" } -``` +``` -Firebolt platforms **MUST NOT** infer anything from the values of these fields, although back-office systems operated by Firebolt distributors may. +Firebolt platforms **MUST NOT** infer anything from the values of these fields, +although back-office systems operated by Firebolt distributors may. ## 4. Playlist Entities -A playlist is a type of entity that points to a list of other entities. +A playlist is a type of entity that points to a list of other entities. -Since entity IDs are in the target app's scope, it is up to each app to know what to do with the contents of a given playlist. +Since entity IDs are in the target app's scope, it is up to each app to know +what to do with the contents of a given playlist. ```json @@ -58,7 +77,7 @@ Since entity IDs are in the target app's scope, it is up to each app to know wha "entityType": "playlist", "entityId": "playlist/xyz" } -``` +``` ## 5. Entity Specifications diff --git a/requirements/specifications/entities/music.md b/requirements/specifications/entities/music.md index e6dd9ae89..80727aa99 100644 --- a/requirements/specifications/entities/music.md +++ b/requirements/specifications/entities/music.md @@ -1,18 +1,23 @@ # Music Entities -Document Status: Working Draft +Document Status: Proposed Specification -See [Firebolt Requirements Governance](../../governance.md) for more info. +See [Firebolt Requirements Governance](../../governance.md) for more info. -| Contributor | Organization | -| --------------- | -------------- | -| Jeremy LaCivita | Comcast | -| Liz Sheffield | Comcast | +| Contributor | Organization | +| --------------- | ------------ | +| Jeremy LaCivita | Comcast | +| Liz Sheffield | Comcast | ## 1. Overview -TBD... +TBD... -The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. +The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL +NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT +RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be +interpreted as described in [BCP +14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and +only when, they appear in all capitals, as shown here. ## 2. Table of Contents - [1. Overview](#1-overview) @@ -22,16 +27,18 @@ The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL ## 3. Music Entities -Every Music Entity **MUST** be an [Entity](../index#3-entities). +Every Music Entity **MUST** be an [Entity](./index.md#3-entities). -Every Music Entity **MUST** have a `const` property named `entityType`, which **MUST** have the value `"music"`. +Every Music Entity **MUST** have a `const` property named `entityType`, which +**MUST** have the value `"music"`. -Every Music Entity **MUST** have a `string` property named `musicType`, whose value **MUST** be one of: +Every Music Entity **MUST** have a `string` property named `musicType`, whose +value **MUST** be one of: - `"song"` - `"album"` -An example Music Entity: +An example Music Entity: ```json { @@ -39,9 +46,9 @@ An example Music Entity: "musicType": "song", "entityId": "song/xyz" } -``` +``` -Another example Music Entity: +Another example Music Entity: ```json { @@ -49,12 +56,13 @@ Another example Music Entity: "musicType": "album", "entityId": "album/xyz" } -``` +``` ### 3.1. Optional Music Entity Properties -A Music Entity **MAY** have a `string` property named `albumId` if its musicType is `song`, otherwise the entity **MUST NOT** have this property. +A Music Entity **MAY** have a `string` property named `albumId` if its +musicType is `song`, otherwise the entity **MUST NOT** have this property. -An example Music Entity: +An example Music Entity: ```json { @@ -63,4 +71,4 @@ An example Music Entity: "entityId": "song/xyz", "albumId": "album/xyz" } -``` +``` diff --git a/requirements/specifications/entities/programs.md b/requirements/specifications/entities/programs.md index e8d89701f..3aa4b3431 100644 --- a/requirements/specifications/entities/programs.md +++ b/requirements/specifications/entities/programs.md @@ -1,18 +1,23 @@ # Program Entities -Document Status: Working Draft +Document Status: Proposed Specification -See [Firebolt Requirements Governance](../../governance.md) for more info. +See [Firebolt Requirements Governance](../../governance.md) for more info. -| Contributor | Organization | -| -------------- | -------------- | -| Seth Kelly | Comcast | -| Jeremy LaCivita | Comcast | +| Contributor | Organization | +| --------------- | ------------ | +| Seth Kelly | Comcast | +| Jeremy LaCivita | Comcast | ## 1. Overview -TBD... +TBD... -The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. +The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL +NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT +RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be +interpreted as described in [BCP +14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and +only when, they appear in all capitals, as shown here. ## 2. Table of Contents - [1. Overview](#1-overview) @@ -22,11 +27,13 @@ The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL ## 3. Program Entities -Every Program Entity **MUST** be an [Entity](./index.md#3-entities). +Every Program Entity **MUST** be an [Entity](./index.md#3-entities). -Every Program Entity **MUST** have a `const` property named `entityType`, which **MUST** have the value `"program"`. +Every Program Entity **MUST** have a `const` property named `entityType`, which +**MUST** have the value `"program"`. -Every Program Entity **MUST** have a `string` property named `programType`, whose value **MUST** be one of: +Every Program Entity **MUST** have a `string` property named `programType`, +whose value **MUST** be one of: - `"movie"` - `"episode"` @@ -41,7 +48,7 @@ Every Program Entity **MUST** have a `string` property named `programType`, whos - `"musicVideo"` - `"minisode"` -An example Program Entity: +An example Program Entity: ```json { @@ -49,9 +56,9 @@ An example Program Entity: "programType": "movie", "entityId": "entity/abc" } -``` +``` -Another example Entity: +Another example Entity: ```json { @@ -59,14 +66,17 @@ Another example Entity: "programType": "episode", "entityId": "entity/xyz" } -``` +``` ### 3.1. Optional TV Entity Properties -A Program Entity **MAY** have a `string` property named `seasonId` if its programType is `episode`, otherwise the entity **MUST NOT** have this property. +A Program Entity **MAY** have a `string` property named `seasonId` if its +programType is `episode`, otherwise the entity **MUST NOT** have this property. -A Program Entity **MAY** have a `string` property named `seriesId` if its programType is either `episode` or `season`, otherwise the entity **MUST NOT** have this property. +A Program Entity **MAY** have a `string` property named `seriesId` if its +programType is either `episode` or `season`, otherwise the entity **MUST NOT** +have this property. -An example TV Program Entity: +An example TV Program Entity: ```json { @@ -76,9 +86,9 @@ An example TV Program Entity: "seriesId": "entity/hij", "seasonId": "entity/klm" } -``` +``` -Another example TV Program Entity: +Another example TV Program Entity: ```json { @@ -87,4 +97,4 @@ Another example TV Program Entity: "entityId": "entity/klm", "seriesId": "entity/hij" } -``` +``` diff --git a/requirements/specifications/intents/index.md b/requirements/specifications/intents/index.md index a7c4e8378..6925376e4 100644 --- a/requirements/specifications/intents/index.md +++ b/requirements/specifications/intents/index.md @@ -1,19 +1,25 @@ # Intents -Document Status: Working Draft +Document Status: Proposed Specification -See [Firebolt Requirements Governance](../../governance.md) for more info. +See [Firebolt Requirements Governance](../../governance.md) for more info. -| Contributor | Organization | -| --------------- | -------------- | -| Jeremy LaCivita | Comcast | +| Contributor | Organization | +| --------------- | ------------ | +| Jeremy LaCivita | Comcast | ## 1. Overview -Offen times an end-user has a specific intention that needs to be communicated to an app by the platform. A common reason for this is that a platform may have a voice interface, and an end-user has given an instruction that needs to be carried out by a specific app, e.g. a deep link to content w/in that app. +Offen times an end-user has a specific intention that needs to be communicated +to an app by the platform. A common reason for this is that a platform may have +a voice interface, and an end-user has given an instruction that needs to be +carried out by a specific app, e.g. a deep link to content w/in that app. -Other use cases include editorially placed calls to action in the main user experience, developer tools, and app-to-app communication brokered by Firebolt intents. +Other use cases include editorially placed calls to action in the main user +experience, developer tools, and app-to-app communication brokered by Firebolt +intents. -All intents have an `action`, and `context` property, and many intents have an additional `data` property. +All intents have an `action`, and `context` property, and many intents have an +additional `data` property. ## 2. Table of Contents - [1. Overview](#1-overview) @@ -24,46 +30,35 @@ All intents have an `action`, and `context` property, and many intents have an a - [Intent Types](#intent-types) ## 3. Intent Action -The intent `action` denotes what type of intent it is. +The intent `action` denotes what type of intent it is. -All intents **MUST** have a `string` attribute denoting the type of intent. +All intents **MUST** have a `string` attribute denoting the type of intent. -See the various [Intent Types](#intent-types) below for values. +See the various [Intent Types](#intent-types) below for values. ## 4. Intent Context -The intent `context` provides information on where the intent orginated from. +The intent `context` provides information on where the intent orginated from. -All intents **MUST** have a `context` property, which is an object. +All intents **MUST** have a `context` property, which is an object. -The `context` object **MUST** have a `source` string property with one of the following values: +The `context` object **MUST** have a `source` string property with one of the +following values: - | Value | Description | - |-------|-------------| - | `voice` | This intent originated from a voice service | - | `editorial` | This intent originated from an editorial CMS | + | Value | Description | + |-------------|-------------------------------------------------------------------------------------| + | `voice` | This intent originated from a voice service | + | `editorial` | This intent originated from an editorial CMS | | `api` | This intent originated from some other API on the platform, e.g. `Discovery.launch` | - The `context` object **MAY** have a `campaign` string property, which can have any string value. This property denotes an editorial campaign. +The `context` object **MAY** have a `campaign` string property, which can have +any string value. This property denotes an editorial campaign. ## 5. Intent Data -If an intent has any additional data, it **MUST** be in the `data` property. +If an intent has any additional data, it **MUST** be in the `data` property. ## Intent Types - [Play](./play.md) - [Tune](./tune.md) - [Basic Navigation](./navigation.md) - - - -```typescript -import { Metrics } from '@firebolt-js/sdk' - -//Metrics.build("1.2.3 special Comcast blend") - -Metrics.provide("xrn:firebolt:cap:metrics:build-info", { - getBuild() { - return "dumb string" - } -}) -``` \ No newline at end of file + \ No newline at end of file diff --git a/requirements/specifications/intents/play.md b/requirements/specifications/intents/play.md index 913507934..349932be5 100644 --- a/requirements/specifications/intents/play.md +++ b/requirements/specifications/intents/play.md @@ -1,22 +1,31 @@ # Play Intent -Document Status: Candidate Specification +Document Status: Proposed Specification -See [Firebolt Requirements Governance](../../governance.md) for more info. +See [Firebolt Requirements Governance](../../governance.md) for more info. -| Contributor | Organization | -| --------------- | -------------- | -| Jeremy LaCivita | Comcast | -| Liz Sheffield | Comcast | -| Seth Kelly | Comcast | -| Simon Grist | Sky | +| Contributor | Organization | +| --------------- | ------------ | +| 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. +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. +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-entity` and `play-query` 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. ## 2. Table of Contents - [1. Overview](#1-overview) @@ -29,21 +38,26 @@ The existing Firebolt `playback` intent does not meet these requirements. This d - [5. Core APIs](#5-core-apis) ## 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 Firebolt `navigateTo` notification **MUST** support a `play-entity` intent, +which tells an app to initiate playback of specific entity. -The `play-entity` intent **MUST** have an `action` property, whose value is `"play-entity"`. +The `play-entity` intent **MUST** have an `action` property, whose value is +`"play-entity"`. -The `play-entity` intent **MUST** have a `data` object 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 an `entity` object property. -> -> The `entity` object, **MUST** be an [Entity](../entities/). +> The `data` object **MUST** have an `entity` object property. > -> The `data` object **MAY** have an `options` object property that conforms to [Play Entity Options](#31-play-entity-options). +> The `entity` object, **MUST** be an [Entity](../entities/). +> +> The `data` object **MAY** have an `options` object property that conforms to +> [Play Entity Options](#31-play-entity-options). -The `play-entity` intent **MUST** have a `context` object property that conforms to the [Intent Context](./#5-intent-context). +The `play-entity` intent **MUST** have a `context` object property that +conforms to the [Intent Context](./index.md#4-intent-context). -An example play-entity intent: +An example play-entity intent: ```json { @@ -59,14 +73,15 @@ An example play-entity intent: "source": "voice" } } -``` +``` -Which would instruct an app to play the movie entity with id `movie/xyz`. +Which would instruct an app to play the movie entity with id `movie/xyz`. ### 3.1. Play Entity Options #### 3.1.1. Play First Option -For `play-entity` intents with an `entity` whose `entityType` is `"playlist"`, e.g.: +For `play-entity` intents with an `entity` whose `entityType` is `"playlist"`, +e.g.: ```json { @@ -81,10 +96,10 @@ For `play-entity` intents with an `entity` whose `entityType` is `"playlist"`, e "source": "voice" } } - ``` +``` -The `options` property of the intent **MAY** contain a `playFirstId` string property, to -identify an entity to play *before* starting the playlist, e.g.: +The `options` property of the intent **MAY** contain a `playFirstId` string +property, to identify an entity to play *before* starting the playlist, e.g.: ```json { @@ -102,14 +117,19 @@ identify an entity to play *before* starting the playlist, e.g.: "source": "voice" } } - ``` +``` - If `playFirstId` is provided, the the targeted app **MUST** attempt to play the entity denoted by `playFirstId` first, regardless of whether it is part of the identified playlist or not. +If `playFirstId` is provided, the the targeted app **MUST** attempt to play the +entity denoted by `playFirstId` first, regardless of whether it is part of the +identified playlist or not. - If the `playFirstId` was successfully played, then the app **SHOULD** remove the `playFirstId` entity from any later position in the playlist, if appropriate. +If the `playFirstId` was successfully played, then the app **SHOULD** remove +the `playFirstId` entity from any later position in the playlist, if +appropriate. -The `options` property of the intent **MAY** contain a `playFirstTrack` integer property, to -identify an entity from the playlist to play *before* the rest of the playlist, e.g.: +The `options` property of the intent **MAY** contain a `playFirstTrack` integer +property, to identify an entity from the playlist to play *before* the rest of +the playlist, e.g.: ```json { @@ -127,26 +147,34 @@ identify an entity from the playlist to play *before* the rest of the playlist, "source": "voice" } } - ``` +``` -If `playFirstTrack` is provided and the playlist has at least that many items, then the item denoted by `playFirstTrack` **MUST** be moved from it's original position to the front of the playlist for playback. +If `playFirstTrack` is provided and the playlist has at least that many items, +then the item denoted by `playFirstTrack` **MUST** be moved from it's original +position to the front of the playlist for playback. -The options object **MUST NOT** have both a `playFirstId` and a `playFirstTrack` property. +The options object **MUST NOT** have both a `playFirstId` and a +`playFirstTrack` property. ## 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 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 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 `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 **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 `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](./index.md#5-intent-context). +The `play-query` intent **MUST** have a `context` object property that conforms +to the [Intent Context](./index.md#4-intent-context). -An example play intent: +An example play intent: ```json { @@ -158,12 +186,13 @@ An example play intent: "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 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.: +For `play-query` intents with a `query`, e.g.: ```json { @@ -175,10 +204,11 @@ For `play-query` intents with a `query`, e.g.: "source": "voice" } } - ``` +``` -The `options` property of the intent **MAY** contain a `programTypes` array-of-strings property, to -filter which program entity typess, e.g. `[ "movie", "episode" ]` should be included, e.g.: +The `options` property of the intent **MAY** contain a `programTypes` +array-of-strings property, to filter which program entity typess, e.g. `[ +"movie", "episode" ]` should be included, e.g.: ```json { @@ -195,10 +225,11 @@ filter which program entity typess, e.g. `[ "movie", "episode" ]` should be incl "source": "voice" } } - ``` +``` -The `options` property of the intent **MAY** contain a `musicTypes` array-of-strings property, to -filter which music entity typess, e.g. `[ "song", "album" ]` should be included, e.g.: +The `options` property of the intent **MAY** contain a `musicTypes` +array-of-strings property, to filter which music entity typess, e.g. `[ "song", +"album" ]` should be included, e.g.: ```json { @@ -218,10 +249,11 @@ filter which music entity typess, e.g. `[ "song", "album" ]` should be included, "source": "voice" } } - ``` +``` ## 5. Core APIs -The Firebolt Core SDK will support listening to `play-query` and `play-entity` intents via the `Discovery.navigateTo` notification. +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' @@ -231,4 +263,4 @@ Discovery.listen('navigateTo', (intent) => { // do stuff with play intent! } }) -``` \ No newline at end of file +``` \ No newline at end of file