diff --git a/requirements/specifications/media/media-info.md b/requirements/specifications/media/media-info.md index 30429dca1..1bbcd692e 100644 --- a/requirements/specifications/media/media-info.md +++ b/requirements/specifications/media/media-info.md @@ -14,7 +14,7 @@ See [Firebolt Requirements Governance](../../governance.md) for more info. ## 1. Overview App developers need to know which audio and video formats can be successfully played on a Firebolt device. -Video formats include... +Video formats include... **TODO**: Rewrite this section. **TODO**: check Farhan's emails!! @@ -70,34 +70,35 @@ I want to know what my device *would* support if i upgraded my AV peripherals: - I want to know what resolutions and framerates *would* be supported with upgraded peripherals. (e.g. 1080p60). ## 2. Table of Contents -- [1. Overview](#1-overview) - - [1.1. User Stories](#11-user-stories) - - [1.2. As an OTT App developer](#12-as-an-ott-app-developer) - - [1.3. As a first-party App developer](#13-as-a-first-party-app-developer) -- [2. Table of Contents](#2-table-of-contents) -- [3. Format MimeTypes](#3-format-mimetypes) -- [Resolutions](#resolutions) -- [4. Device Media Support](#4-device-media-support) - - [4.1. Negotiated Media Support](#41-negotiated-media-support) - - [4.1.1. Video Format Supported](#411-video-format-supported) - - [4.1.2. Audio Format Supported](#412-audio-format-supported) - - [4.2.3. Hdr Supported](#423-hdr-supported) -- [5. Display Properties](#5-display-properties) - - [5.1. Color Information...](#51-color-information) - - [5.2. Display Width and Height](#52-display-width-and-height) - - [5.3. Current and Optimal Resolution](#53-current-and-optimal-resolution) - - [5.4. Supported Resolutions](#54-supported-resolutions) - - [5.5. Device Supported Resolutions](#55-device-supported-resolutions) - - [5.7. Use Source Framerate](#57-use-source-framerate) -- [6. Audio Output Properties](#6-audio-output-properties) - - [6.1. Mode](#61-mode) -- [7. Media Info](#7-media-info) - - [7.1. MediaInfo for current app](#71-mediainfo-for-current-app) - - [7.1.1. Video Format](#711-video-format) - - [7.1.2. Audio Format](#712-audio-format) - - [7.2. Global MediaInfo](#72-global-mediainfo) - - [7.2.1. Active Video Formats](#721-active-video-formats) - - [7.2.2. Active Audio Formats](#722-active-audio-formats) +- [Media Info Requirements](#media-info-requirements) + - [1. Overview](#1-overview) + - [1.1. User Stories](#11-user-stories) + - [1.2. As an OTT App developer](#12-as-an-ott-app-developer) + - [1.3. As a first-party App developer](#13-as-a-first-party-app-developer) + - [2. Table of Contents](#2-table-of-contents) + - [3. Format MimeTypes](#3-format-mimetypes) + - [Resolutions](#resolutions) + - [4. Device Media Support](#4-device-media-support) + - [4.1. Negotiated Media Support](#41-negotiated-media-support) + - [4.1.1. Video Format Supported](#411-video-format-supported) + - [4.1.2. Audio Format Supported](#412-audio-format-supported) + - [4.2.3. Hdr Supported](#423-hdr-supported) + - [5. Display Properties](#5-display-properties) + - [5.1. Color Information...](#51-color-information) + - [5.2. Display Width and Height](#52-display-width-and-height) + - [5.3. Current and Optimal Resolution](#53-current-and-optimal-resolution) + - [5.4. Supported Resolutions](#54-supported-resolutions) + - [5.5. Device Supported Resolutions](#55-device-supported-resolutions) + - [5.7. Use Source Framerate](#57-use-source-framerate) + - [6. Audio Output Properties](#6-audio-output-properties) + - [6.1. Mode](#61-mode) + - [7. Media Info](#7-media-info) + - [7.1. MediaInfo for current app](#71-mediainfo-for-current-app) + - [7.1.1. Video Format](#711-video-format) + - [7.1.2. Audio Format](#712-audio-format) + - [7.2. Global MediaInfo](#72-global-mediainfo) + - [7.2.1. Active Video Formats](#721-active-video-formats) + - [7.2.2. Active Audio Formats](#722-active-audio-formats) ## 3. Format MimeTypes The Firebolt `Media` module **MUST** have a `Formats` enumeration audio and video formats: @@ -111,10 +112,10 @@ The Firebolt `Media` module **MUST** have a `Formats` enumeration audio and vide | `AUDIO_DTS` | `audio/vnd.dts` | | `AUDIO_DTS_X` | `audio/vnd.dts.uhd;profile=p2` | | `AUDIO_EAC3` | `audio/eac3` | Note we call this AC3+ in RDK... | -| `AUDIO_MPEG` | `audio/mpeg` | -| `AUDIO_MPEG1` | `audio/mpeg-L1` | -| `AUDIO_MPEG2` | `audio/mpeg-L2` | -| `AUDIO_MPEG4` | `audio/mp4` | +| `AUDIO_MPEG` | `audio/mpeg` | +| `AUDIO_MPEG1` | `audio/mpeg-L1` | +| `AUDIO_MPEG2` | `audio/mpeg-L2` | +| `AUDIO_MPEG4` | `audio/mp4` | | `AUDIO_OPUS` | `audio/opus` | | `AUDIO_OGG` | `audio/ogg` | | `AUDIO_TRUEHD` | `audio/true-hd` | @@ -190,14 +191,15 @@ const hdr10plusWithVP9 = videoFormatSupported(Media.Formats.VIDEO_VP9_P2) When calling videoFormatSupported with a `resolution` parameter, then the Display support for that resolution is factored into the response. -The `audioFormatSupported` API **MUST** have an `options` parameter +The `videoFormatSupported` API **MUST** have an `options` parameter which **MUST** be an object with zero or more of the following properties: | Property | Type | Description | |----------|------|-------------| -| codec | `string` | the Code | +| codec | `string` | the Codec | | profile | `string` | the Codec profile:
**h.265**: "main", "high", "main10"
**vp9**: "p0", "p2"
**AAC**: "mp2lc", "mp4he" | -| level | `string` | the Codec level:
**h.265**: "4.1", "4.2", "5.0", "5.1"
**vp9**:"3.0", "3.1", "4.0", "4.1", "5.0", "5.1" || atmos | `boolean` | Whether or not Dolby Atmos support for the given format is being requested | +| level | `string` | the Codec level:
**h.265**: "4.1", "4.2", "5.0", "5.1"
**vp9**:"3.0", "3.1", "4.0", "4.1", "5.0", "5.1" | +| atmos | `boolean` | Whether or not Dolby Atmos support for the given format is being requested | | resolution | `Display.Resolution` | The Resolution, e.g. `1080p` of the support being requested. | | hdr | HDRProfile | The HDR profile that support is being checked for. | @@ -272,7 +274,7 @@ which **MUST** be an object with zero or more of the following properties: | atmos | `boolean` | Whether or not Dolby Atmos support for the given format is being requested | | channels | `int` | Required number of audio channels | | sampleRate | `int` | The sample rate being requested. | -| mode | `AudioOutput.Mode` | Specify which mode should be used to evaluate the reqeuest. Defaults to the current mode if not specified. | +| mode | `AudioOutput.Mode` | Specify which mode should be used to evaluate the request. Defaults to the current mode if not specified. | **TODO**: Roku also has: Container, Bitrate @@ -280,7 +282,7 @@ If the `options` parameter is provided, then the `audioFormatSupported` API **MU return `true` unless the format specified is supported with **all** of the properties specified by `options` *all at the same time*. -Use of the `videoFormatSupported` API requires access to the `use` role of the +Use of the `audioFormatSupported` API requires access to the `use` role of the `xrn:firebolt:capability:device:info` capability. #### 4.2.3. Hdr Supported @@ -317,7 +319,7 @@ The `optimalResolution` **MUST** come from the HDMI edid. For built-in displays `optimalResolution` **MUST** also be provided. ### 5.4. Supported Resolutions - + The `Display` module **MUST** have a `supportedResolutions` method that returns an array of valid resolutions that the display supports. This method **MUST** return a value from the `Display.Resolution` enum. @@ -358,7 +360,7 @@ about any media actively being decoded by the Media Pipeline or an active HDMI i ### 7.1. MediaInfo for current app -Apps need a way to query the media info for media currently being played +Apps need a way to query the media info for media currently being played by the app. All of the following methods take a single `pipeline` parameter, which identifies the Media Pipeline in the current app's scope that is being queried, e.g.: diff --git a/requirements/specifications/media/media-pipeline.md b/requirements/specifications/media/media-pipeline.md index 1b620a368..4bbdad9f2 100644 --- a/requirements/specifications/media/media-pipeline.md +++ b/requirements/specifications/media/media-pipeline.md @@ -41,7 +41,7 @@ TODO: we need a few additions to support Netflix: - loudness eq The audioSettings **MUST** include an `atmosOutputLock` boolean property. -The audioSettings **MUST** include an `audioLoundnessEquivalence` boolean property. +The audioSettings **MUST** include an `audioLoudnessEquivalence` boolean property. The audioSettings API **MUST** be a Firebolt `property:readonly` API, and have a corresponding `onAudioSettingsChanged` notification. @@ -56,22 +56,23 @@ to the `use` role of the `xrn:firebolt:capability:device:audio-settings` capabil generated](../../../../requirements/images/specifications/media/media-pipeline/media/image1.png) ## 2. Table of Contents -- [1. Overview](#1-overview) -- [2. Table of Contents](#2-table-of-contents) -- [3. Media Pipeline](#3-media-pipeline) - - [3.1. Media Pipeline Commands](#31-media-pipeline-commands) - - [3.2. MediaPipeline Notifications](#32-mediapipeline-notifications) - - [3.3. Media Pipeline Management](#33-media-pipeline-management) -- [4. W3C Media APIs](#4-w3c-media-apis) - - [4.1. MediaSource](#41-mediasource) - - [4.2. MediaElement](#42-mediaelement) -- [5. Supported Media](#5-supported-media) - - [5.1. Container formats](#51-container-formats) - - [5.2. Video codecs](#52-video-codecs) - - [5.3. Audio codecs](#53-audio-codecs) -- [6. Supported Decryption](#6-supported-decryption) - - [6.1. DRM Key Systems](#61-drm-key-systems) - - [6.2. Decryption Schemes](#62-decryption-schemes) +- [Media Pipeline Requirements](#media-pipeline-requirements) + - [1. Overview](#1-overview) + - [2. Table of Contents](#2-table-of-contents) + - [3. Media Pipeline](#3-media-pipeline) + - [3.1. Media Pipeline Commands](#31-media-pipeline-commands) + - [3.2. MediaPipeline Notifications](#32-mediapipeline-notifications) + - [3.3. Media Pipeline Management](#33-media-pipeline-management) + - [4. W3C Media APIs](#4-w3c-media-apis) + - [4.1. MediaSource](#41-mediasource) + - [4.2. MediaElement](#42-mediaelement) + - [5. Supported Media](#5-supported-media) + - [5.1. Container formats](#51-container-formats) + - [5.2. Video codecs](#52-video-codecs) + - [5.3. Audio codecs](#53-audio-codecs) + - [6. Supported Decryption](#6-supported-decryption) + - [6.1. DRM Key Systems](#61-drm-key-systems) + - [6.2. Decryption Schemes](#62-decryption-schemes) ## 3. Media Pipeline diff --git a/src/openrpc/device.json b/src/openrpc/device.json index 5d918fd29..5fd66a092 100644 --- a/src/openrpc/device.json +++ b/src/openrpc/device.json @@ -361,7 +361,7 @@ }, { "name": "hdcp", - "summary": "Get the supported HDCP profiles", + "summary": "Get the supported HDCP versions available for content transmission", "params": [], "tags": [ { @@ -375,15 +375,15 @@ } ], "result": { - "name": "supportedHdcpProfiles", - "summary": "the supported HDCP profiles", + "name": "supportedHdcpVersions", + "summary": "the supported HDCP versions", "schema": { "$ref": "https://meta.comcast.com/firebolt/types#/definitions/BooleanMap" } }, "examples": [ { - "name": "Getting the supported HDCP profiles", + "name": "Getting the supported HDCP versions", "params": [], "result": { "name": "Default Result", @@ -395,6 +395,72 @@ } ] }, + { + "name": "currentHdcpVersion", + "summary": "Get the current HDCP version used for content transmission", + "params": [], + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:device:info" + ] + } + ], + "result": { + "name": "HdcpVersion", + "summary": "The current HDCP version", + "schema": { + "$ref": "#/components/schemas/HdcpVersion" + } + }, + "examples": [ + { + "name": "Get the current HDCP version", + "params": [], + "result": { + "name": "Default Result", + "value": "hdcp2.2" + } + } + ] + }, + { + "name": "onHdcpVersionChanged", + "tags": [ + { + "name": "event" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:device:info" + ] + } + ], + "summary": "Get notified when the HDCP version used for content transmission has changed", + "params": [], + "result": { + "name": "value", + "summary": "The updated HDCP version used", + "schema": { + "$ref": "#/components/schemas/HdcpVersion" + } + }, + "examples": [ + { + "name": "Getting the device name", + "params": [], + "result": { + "name": "Default Result", + "value": "2.x" + } + } + ] + }, { "name": "hdr", "summary": "Returns an array of valid HDR profiles that the device supports", @@ -433,6 +499,39 @@ } ] }, + { + "name": "currentHdrProfile", + "summary": "Returns the current HDR profile set by the device", + "params": [], + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:device:info" + ] + } + ], + "result": { + "name": "HdrProfile", + "summary": "The current HDR profile", + "schema": { + "$ref": "#/components/schemas/HdrProfile" + } + }, + "examples": [ + { + "name": "The supported HDR profiles", + "params": [], + "result": { + "name": "Default Result", + "value": "hdr10" + } + } + ] + }, { "name": "audio", "summary": "Get the supported audio profiles", @@ -545,7 +644,7 @@ }, { "name": "videoFormatSupported", - "summary": "Check whether content of a given a video format and resolution is supported by the device's current configuration. These values may change as different AV inputs are activated or connected.", + "summary": "Check whether content of a given a video format is supported by the device's current configuration. These values may change as different AV inputs are activated or connected.", "params": [ { "name": "format", @@ -556,10 +655,10 @@ } }, { - "name": "resolution", - "summary": "The video resolution used to check whether its supported by the device's current configuration.", + "name": "options", + "summary": "Additional options to use for checking whether a video format is supported by the device.", "schema": { - "$ref": "#/components/schemas/VideoFormatResolution" + "$ref": "#/components/schemas/VideoFormatOptions" } } ], @@ -655,7 +754,7 @@ }, { "name": "audioFormatSupported", - "summary": "Check whether content of a given audio format and channel output is supported by the device's current configuration. These values may change as different AV inputs are activated or connected.", + "summary": "Check whether content of a given audio format is supported by the device's current configuration. These values may change as different AV inputs are activated or connected.", "params": [ { "name": "format", @@ -666,10 +765,10 @@ } }, { - "name": "channels", - "summary": "An audio channels value used to check whether its supported.", + "name": "options", + "summary": "Additional options to use for checking whether an audio format is supported by the device.", "schema": { - "$ref": "#/components/schemas/AudioChannels" + "$ref": "#/components/schemas/AudioFormatOptions" } } ], @@ -698,7 +797,7 @@ }, { "name": "channels", - "value": "MONO" + "value": 2 } ], "result": { @@ -934,6 +1033,122 @@ } ] }, + { + "name": "networkInterfaces", + "summary": "Get a list of the device's network interfaces and statuses", + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:network:status" + ] + } + ], + "params": [], + "result": { + "name": "The device's network interfaces and statuses", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NetworkInterface" + } + } + }, + "examples": [ + { + "name": "Get the network interfaces and statuses", + "params": [], + "result": { + "name": "Default Result", + "value": [ + { + "interface": "WIFI", + "macAddress": "AA:AA:AA:AA:AA:AA", + "enabled": true, + "connected": true + } + ] + } + } + ] + }, + { + "name": "defaultNetworkInterface", + "summary": "Get the device's default network interface", + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:network:status" + ] + } + ], + "params": [], + "result": { + "name": "The device's network interfaces and status", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NetworkInterface" + } + } + }, + "examples": [ + { + "name": "Get the network interfaces", + "params": [], + "result": { + "name": "Default Result", + "value": [ + { + "interface": "WIFI", + "macAddress": "AA:AA:AA:AA:AA:AA", + "enabled": true, + "connected": true + } + ] + } + } + ] + }, + { + "name": "hdmiPort", + "summary": "Get the name of the device's HDMI output port", + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:device:info" + ] + } + ], + "params": [], + "result": { + "name": "hdmiPort", + "schema": { + "#ref": "#/components/schemas/HDMIPortId" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": "HDMI0" + } + } + ] + }, { "name": "provision", "summary": "Used by a distributor to push provision info to firebolt.", @@ -1055,6 +1270,25 @@ ], "description": "The type of network that is currently active" }, + "NetworkInterface": { + "title": "NetworkInterface", + "type": "object", + "properties": { + "connected": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "interface": { + "type": "string" + }, + "macAddress": { + "type": "string", + "pattern": "^([0-9A-F]{2}[:-]){5}([0-9A-F]{2})$" + } + } + }, "AudioProfiles": { "title": "AudioProfiles", "allOf": [ @@ -1069,6 +1303,10 @@ } ] }, + "HDMIPortId": { + "type": "string", + "pattern": "^HDMI[0-9]+$" + }, "VideoFormat": { "title": "VideoFormat", "type": "string", @@ -1088,6 +1326,61 @@ ], "description": "The video format supported by the platform" }, + "VideoFormatOptions": { + "title": "VideoFormatOptions", + "type": "object", + "properties": { + "atmos": { + "type": "boolean" + }, + "codec": { + "type": "string", + "enum": [ + "VIDEO_AV1", + "VIDEO_DOLBYVISION", + "VIDEO_H263", + "VIDEO_H264", + "VIDEO_H265", + "VIDEO_MPEG", + "VIDEO_VP8", + "VIDEO_VP9", + "VIDEO_VP9_P2", + "VIDEO_VP10", + "VIDEO_VC1" + ] + }, + "hdr": { + "$ref": "#/components/schemas/HdrProfile" + }, + "level": { + "type": "string", + "enum": [ + "3.0", + "3.1", + "4.0", + "4.1", + "4.2", + "5.0", + "5.1" + ] + }, + "profile": { + "type": "string", + "enum": [ + "high", + "main", + "main10", + "mp2lc", + "mp4he", + "p0", + "p2" + ] + }, + "resolution": { + "$ref": "#/components/schemas/VideoFormatResolution" + } + } + }, "VideoFormatResolution": { "title": "VideoFormatResolution", "type": "string", @@ -1134,6 +1427,34 @@ ], "description": "The audio format supported by the platform" }, + "AudioFormatOptions": { + "title": "AudioFormatOptions", + "type": "object", + "properties": { + "atmos": { + "type": "boolean" + }, + "channels": { + "type": "integer" + }, + "level": { + "type": "string" + }, + "mode": { + "$ref": "audio_output.json#/components/schemas/AudioMode" + }, + "profile": { + "type": "string", + "enum": [ + "mp2lc", + "mp4he" + ] + }, + "sampleRate": { + "type": "integer" + } + } + }, "AudioChannels": { "title": "AudioChannels", "type": "string", @@ -1161,6 +1482,29 @@ "2160p60" ], "description": "The list of resolutions supported by the device" + }, + "HdcpVersion": { + "title": "HdcpVersion", + "type": "string", + "enum": [ + "Hdcp1x", + "Hdcp2x", + "HdcpAuto", + "HdcpUnencrypted" + ], + "description": "The list of HDCP versions supported by the device" + }, + "HdrProfile": { + "title": "HdrProfile", + "type": "string", + "enum": [ + "DolbyVision", + "Hdr10", + "Hdr10Plus", + "St2084", + "hlg" + ], + "description": "The list of HDR profiles supported by the device" } } } diff --git a/src/openrpc/display.json b/src/openrpc/display.json index b0c22da7f..b25a7c02e 100644 --- a/src/openrpc/display.json +++ b/src/openrpc/display.json @@ -230,6 +230,42 @@ } ] }, + { + "name": "supportedColorDepthCapabilities", + "summary": "Get the supported color depth capabilities of the display device.", + "params": [], + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:display:info" + ] + } + ], + "result": { + "name": "ColorDepths", + "summary": "The supported color depth capabilities", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ColorDepth" + } + } + }, + "examples": [ + { + "name": "Get the supported color depth capabilities", + "params": [], + "result": { + "name": "Default Result", + "value": [ + "8 Bit", + "10 Bit" + ] + } + } + ] + }, { "name": "useSourceFrameRate", "summary": "Set the HDMI output frame rate to follow the video source frame rate.", @@ -263,6 +299,16 @@ ], "components": { "schemas": { + "ColorDepth": { + "title": "ColorDepth", + "type": "string", + "enum": [ + "8 Bit", + "10 Bit", + "12 Bit" + ], + "description": "The list of color depth supported by the display" + }, "DisplayResolution": { "title": "DisplayResolution", "type": "string", diff --git a/src/openrpc/media-info.json b/src/openrpc/media_info.json similarity index 94% rename from src/openrpc/media-info.json rename to src/openrpc/media_info.json index 1b53863b0..cd0600535 100644 --- a/src/openrpc/media-info.json +++ b/src/openrpc/media_info.json @@ -28,8 +28,7 @@ "schema": { "type": "integer", "default": 1 - }, - "required": true + } } ], "result": { @@ -55,6 +54,22 @@ } ] }, + { + "name": "videoFormat", + "summary": "Returns details on the video content currently in the media pipeline (either playing or paused).", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:media-info:video-format" + ] + } + ] + }, + { + "name": "onVideoFormatChanged", + "summary": "" + }, { "name": "audioCodec", "summary": "Get the audio codec of the specified media session.",