diff --git a/requirements/specifications/media/media-capabilities.md b/requirements/specifications/media/media-capabilities.md new file mode 100644 index 000000000..dfea6bafd --- /dev/null +++ b/requirements/specifications/media/media-capabilities.md @@ -0,0 +1,698 @@ +# Media Capabilities Requirements + +Document Status: Candidate Specification + +See [Firebolt Requirements Governance](../../governance.md) for more info. + +| Contributor | Organization | +| --------------- | -------------- | +| Anthony Borzota | Comcast | +| Jeremy LaCivita | Comcast | +| Stuart Harris | Sky | +| Joe Martin | Comcast | +| Farhan Mood | Liberty Global | + +## 1. Overview + +App developers need to know which audio and video formats can be successfully played on a Firebolt device and its attached peripherals. + +An audio format includes values such as the audio codec, container, codec level, and bit rate of the audio stream. + +A video format may include values such as the video container, format/codec, HDR profile, and resolution of the video stream. + +Further, apps may also need to know about the media format currently playing in the media pipeline. + +An app may need to check IP video playback that it has initiated to see if Dolby Audio is in fact active (as opposed to just present in the encoded data) in order to display metadata or badges to the user. Apps may also be playing [user-cultivated media](./media-access.md), and therefore have no metadata about the format of the files. + +A first-party app may need to check all [Media Pipelines](./media-pipeline.md) for media format characteristics to display a global badge. + +Additionally, apps may need to know what is supported by the device, *before* initiating any media playback. + +To solve this, Firebolt APIs will be created to detect the formats and codecs currently being decoded by the [Media Pipeline](./media-pipeline.md). Firebolt APIs will also be created to query whether the device and its peripherals support playing content of various formats. + +> TODO: Fix the above links + +### 1.1. User Stories + +#### 1.1.1. As an OTT App developer + +I want to know what is supported by the device and it's active AV chain: + +- I want to know if content of a particular video or audio format (Dolby Vision, Dolby Atmos, HEVC, etc.) is supported +- I want to know if content decoding with a particular codec profile or level (HEVC Main 10, VP9 Profile 2, etc.) is supported. +- I want to know whether content of a particular resolution and frame rate is supported + +I want to know what kind of content I'm currently playing: + +- I want to know which video or audio format the media I'm currently playing is sending to the decoder. +- I want to know which video or audio format profile or level the media I'm currently playing is being sent to the decoder. +- I want to know what resolution and frame rate is currently being sent to the decoder. + +#### 1.1.2. As a first-party App developer + +I want to show an audio/videophile overlay with detailed information: + +- I want to know all video or audio formats that are currently being sent to a decoder. +- I want to know all video or audio format profiles/levels currently being sent to a decoder. +- I want to know all resolution and framerates currently being sent to a decoder. + +## 2. Table of Contents + +- [1. Overview](#1-overview) + - [1.1. User Stories](#11-user-stories) + - [1.1.1. As an OTT App developer](#111-as-an-ott-app-developer) + - [1.1.2. As a first-party App developer](#112-as-a-first-party-app-developer) +- [2. Table of Contents](#2-table-of-contents) +- [3. Constants, Types, and Schemas](#3-constants-types-and-schemas) + - [3.1. Media Container Types](#31-media-container-types) + - [3.2. Media Codecs](#32-media-codecs) + - [3.3. Dimensions](#33-dimensions) + - [3.4. Resolution User-Friendly Name](#34-resolution-user-friendly-name) + - [3.5. Video Modes](#35-video-modes) + - [3.6. HDR Profiles](#36-hdr-profiles) + - [3.7. Colorimetry](#37-colorimetry) + - [3.8. Color Depth](#38-color-depth) + - [3.9. Color Space \& Chroma Subsampling](#39-color-space--chroma-subsampling) + - [3.10. Audio Output Mode](#310-audio-output-mode) + - [3.11. Quantization Range](#311-quantization-range) +- [4. Media Capabilities](#4-media-capabilities) + - [4.1. Audio Format Supported](#41-audio-format-supported) + - [4.2. Video Format Supported](#42-video-format-supported) + - [4.3. Supported Audio Modes](#43-supported-audio-modes) + - [4.4. Supported Video Modes](#44-supported-video-modes) + - [4.5. Supported Audio Codecs](#45-supported-audio-codecs) + - [4.6. Supported Video Codecs](#46-supported-video-codecs) + - [4.7. Color Depth](#47-color-depth) + - [4.8. HDR Profiles](#48-hdr-profiles) + - [4.9. Atmos Supported](#49-atmos-supported) +- [5. Display Support](#5-display-support) + - [5.1. HDR Profiles](#51-hdr-profiles) + - [5.2. Color Depth](#52-color-depth) + - [5.3. Display Size](#53-display-size) + - [5.4. Native Resolution](#54-native-resolution) + - [5.5. Native Resolution Name](#55-native-resolution-name) + - [5.6. Native Refresh Rate](#56-native-refresh-rate) + - [5.7. Colorimetry](#57-colorimetry) + - [5.10. Supported Video Modes](#510-supported-video-modes) +- [6. Audio Output](#6-audio-output) + - [6.1. Mode](#61-mode) +- [7. Video Output](#7-video-output) + - [7.1. Mode](#71-mode) + - [7.2. Resolution](#72-resolution) + - [7.3. HDR Profile](#73-hdr-profile) + - [7.4. Color Depth](#74-color-depth) + - [7.5. Color Space \& Chroma Subsampling](#75-color-space--chroma-subsampling) + - [7.6. Quantization Range](#76-quantization-range) + - [7.7. Current Output Settings](#77-current-output-settings) + +## 3. Constants, Types, and Schemas + +### 3.1. Media Container Types + +The Firebolt `Media` module **MUST** have an `AudioContainer` enumeration of the following media container content types: + +| Name | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| `audio/mp4` | [MP4 Audio](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#mpeg-4_mp4) | +| `audio/mpeg` | [Moving Picture Experts Group (MPEG1/MPEG2)](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#mpegmpeg-2) | +| `audio/ogg` | [OGG](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#ogg) | +| `audio/wave` | [Waveform Audio File Format](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#wave_wav) | +| `audio/webm` | [Web Media](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#webm) | + +The Firebolt `Media` module **MUST** have a `VideoContainer` enumeration of the following media container content types: + +| Name | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| `video/mp2t` | [MPEG transport stream](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) | +| `video/mp4` | [MP4 Audio](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/) | +| `video/mpeg` | [Moving Picture Experts Group (MPEG1/MPEG2)](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#mpegmpeg-2) | +| `video/webm` | [Web Media](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#webm) | + +### 3.2. Media Codecs + +The Firebolt `Media` module **MUST** have an `AudioCodec` enumeration: + +| Name | Description | +| -------- | ---------------------------------------------- | +| `aac` | Advanced Audio Coding | +| `ac3` | Dolby Digital / Dolby Audio Codec 3 | +| `ac4` | Dolby Audio Codec 4 | +| `eac3` | Dolby Digital Plus / Dolby Enhanced AC-3 / DD+ | +| `mpeg3` | MPEG-1 Part 3 & MPEG-2 Part 3 | +| `opus` | IETF Opus | +| `pcm` | Pulse Code Modulation/WAVE | +| `truehd` | Dolby TrueHD / MLP | +| `vorbis` | Xiph.org Vorbis | + +The Firebolt `Media` module **MUST** have a `VideoCodec` enumeration: + +| Name | Description | +| ------- | ---------------------------------------------- | +| `av1` | AOMedia Video 1 | +| `avc` | Advanced Video Coding / MPEG-4 Part 10 (H.264) | +| `hevc` | High Efficiency Video Coding (H.265) | +| `mpeg1` | MPEG-1 Part 2 Visual | +| `mpeg2` | MPEG-2 Part 2 Visual | +| `vp8` | Video Processor 8 | +| `vp9` | Video Processor 9 | + +### 3.3. Dimensions + +The Firebolt `Types` module must have a `Dimensions` object of the following schema: + +| Field | Type | +| -------- | -------- | +| `height` | `number` | +| `width` | `number` | + +### 3.4. Resolution User-Friendly Name + +The Firebolt `Media` module **MUST** have a `ResolutionName` enumeration: + +| Class | Applicable Resolutions | +| --------- | ---------------------- | +| `sd` | `576p` and lower | +| `hd` | `720p` | +| `fhd` | `1080p` | +| `uhd` | `2160` and higher | +| `unknown` | unknown or no display | + +### 3.5. Video Modes + +For the purposes of the Firebolt API, a `VideoMode` shall be defined as the shorthand vertical resolution and frame rate of video content. + +The Firebolt `Media` module **MUST** have a `VideoMode` enumeration: + +- `480i` +- `480p` +- `576i25` +- `576p50` +- `576p60` +- `720p50` +- `720p60` +- `1080i50` +- `1080i60` +- `1080p24` +- `1080p25` +- `1080p30` +- `1080p50` +- `1080p60` +- `2160p24` +- `2160p25` +- `2160p30` +- `2160p50` +- `2160p60` +- `4320p60` +- `unknown` + +Any methods relating to the video mode (such as a device's video output mode) **MUST** return `Media.VideoMode` values. + +### 3.6. HDR Profiles + +The Firebolt `Media` module **MUST** have an `HDRProfile` enumeration: + +- `dolbyVision` +- `hdr10` +- `hdr10plus` +- `hlg` +- `sdr` +- `technicolor` +- `unknown` + +### 3.7. Colorimetry + +The Firebolt `Display` module **MUST** have a `Colorimetry` enumeration: + +- `BT2020cYCC` +- `BT2020RGB` +- `BT2020YCC` +- `DCI-P3` +- `opRGB` +- `opYCC601` +- `sYCC601` +- `xvYCC601` +- `xvYCC709` +- `unknown` + +> TODO: Do we need to add `ICtCp`? https://professional.dolby.com/siteassets/pdfs/ictcp_dolbywhitepaper_v071.pdf + +### 3.8. Color Depth + +The Firebolt `Media` module **MUST** have a `ColorDepth` enumeration: + +- `8` +- `10` +- `12` +- `auto` +- `unknown` + +### 3.9. Color Space & Chroma Subsampling + +The Firebolt `Media` module **MUST** have a `ColorSpace` enumeration: + +| Name | Chroma | +| ---------- | ------ | +| `RGB444` | 4:4:4 | +| `YCbCr420` | 4:2:0 | +| `YCbCr422` | 4:2:2 | +| `YCbCr444` | 4:4:4 | +| `other` | | +| `unknown` | | + +### 3.10. Audio Output Mode + +The Firebolt `Media` module **MUST** have an `AudioMode` enumeration: + +- `auto` +- `mono` +- `passthrough` +- `stereo` +- `surround` +- `unknown` + +### 3.11. Quantization Range + +The Firebolt `VideoOutput` module **MUST** have a `QuantizationRange` enumeration: + +- `full` +- `limited` +- `unknown` + +## 4. Media Capabilities + +Apps need to know what types of media support the device and any connected peripherals are together capable of. + +To facilitate this, the `MediaCapabilities` module will provide convenience methods that encapsulate the media-playing capabilities of the device as well as any of its connected peripherals, including (but not limited to) displays, sound bars, and receivers. + +These values **MUST NOT** change without a settings change, peripheral change, or firmware update. + +### 4.1. Audio Format Supported + +The `MediaCapabilities` module **MUST** have an `audioFormatSupported` method that returns a boolean that provides whether or not the specified format is commonly supported by the device and all relevant peripherals in the user's AV chain. + +This method **MUST** have a required `codec` parameter with the type `Media.AudioCodec`. + +This method **MUST** have an optional `options` parameter which **MUST** be an object with zero or more of the following properties: + +| Property | Type | Description | +| -------------- | ----------------- | ----------------------------------------------------- | +| `atmos` | `boolean` | Whether or not Dolby Atmos support is being requested | +| `codecLevel` | `string` | The codec level | +| `codecProfile` | `string` | The codec profile:
**aac**: `mp2lc`, `mp4he` | +| `container` | `Media.Container` | The container format type | +| `sampleRate` | `number` | The sample rate being requested, in kHz | + +If the `options` parameter is provided, then this method **MUST NOT** return `true` unless the format specified is supported with **all** of the properties specified by `options` *at the same time*. + +As multiple audio output modes may be set at the same time, the response **MUST** be based on the best possible audio configuration supported by the device and its AV chain. For instance, if the device is configured for stereo output (which cannot support Atmos) but the AV chain supports Surround 5.1 (which can support Atmos), the latter would be considered the best possible audio configuration and thus used as the basis for the decision. + +```javascript +MediaCapabilities.audioFormatSupported(Media.AudioCodec.AC4, { + atmos: true +}) +//> true + +MediaCapabilities.audioFormatSupported(Media.AudioCodec.TRUEHD, { + atmos: true + mode: 'mono' +}) +//> false (mono output not supported with dolby atmos) +``` + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. + +### 4.2. Video Format Supported + +The `MediaCapabilities` module **MUST** have a `videoFormatSupported` method that returns boolean that provides whether or not the specified format is commonly supported by the device and all relevant peripherals in the user's AV chain. + +This method **MUST** have a required `codec` parameter with the type `Media.VideoCodec`. + +This method **MUST** have an optional `info` parameter which **MUST** be an object with zero or more of the following properties: + +| Property | Type | Description | +| ------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------ | +| `container` | `Media.VideoContainer` | The content container format | +| `hdr` | `Media.HDRProfile` | The HDR profile to check | +| `level` | `string` | The codec level:
**hevc**: `4.1`, `4.2`, `5.0`, `5.1`
**vp9**:`3.0`, `3.1`, `4.0`, `4.1`, `5.0`, `5.1` | +| `profile` | `string` | The codec profile:
**hevc**: `main`, `high`, `main10`
**vp9**: `p0`, `p2` | +| `resolution` | `Types.Dimensions` | The dimensions of the media content, in pixels | + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. + +```javascript +MediaCapabilities.videoFormatSupported(Media.VideoCodec.HEVC, { + profile: "main10", + hdr: Media.HDRProfile.HDR10_PLUS +}) +//> true + +MediaCapabilities.videoFormatSupported(Media.VideoCodec.VP9, { + profile: "p2", + hdr: Media.HDRProfile.HDR10_PLUS, + resolution: { "width": 3840, "height": 2160 } +}) +//> true +``` + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. + +### 4.3. Supported Audio Modes + +The `MediaCapabilities` module **MUST** have an `audioModes` method that returns an array of `Media.AudioMode` values describing the audio modes commonly supported across all relevant peripherals in the user's AV chain. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. + +```javascript +MediaCapabilities.audioModes() +//> ["passthrough", "stereo", "surround"] +``` + +### 4.4. Supported Video Modes + +The `MediaCapabilities` module **MUST** have a `videoModes` method that returns an array of `Media.VideoMode` values describing the video modes commonly supported across all relevant peripherals in the user's AV chain. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. + +```javascript +MediaCapabilities.videoModes() +//> ["720p50", "720p60", "1080p50", "1080p60"] +``` + +### 4.5. Supported Audio Codecs + +The `MediaCapabilities` module **MUST** have an `audioCodecs` method that returns an array of `Media.AudioCodec` values describing the audio codecs commonly supported across all relevant peripherals in the user's AV chain. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. + +```javascript +MediaCapabilities.audioCodecs() +//> [ +//> "aac", +//> "ac3", +//> "ac4", +//> "eac3", +//> "mpeg3", +//> "pcm" +//> ] +``` + +### 4.6. Supported Video Codecs + +The `MediaCapabilities` module **MUST** have an `videoCodecs` method that returns an array of `Media.VideoCodec` values describing the video codecs commonly supported across all relevant peripherals in the user's AV chain. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. + +```javascript +MediaCapabilities.videoCodecs() +//> [ +//> "av1", +//> "avc", +//> "hevc", +//> "mpeg1", +//> "mpeg2", +//> "vp8", +//> "vp9", +//> "vp10" +//> ] +``` + +### 4.7. Color Depth + +The `MediaCapabilities` module **MUST** have a `colorDepth` method that returns a numeric value describing the maximum color depth commonly supported across all relevant peripherals in the user's AV chain. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. + +```javascript +MediaCapabilities.colorDepth() +//> 10 +``` + +### 4.8. HDR Profiles + +The `MediaCapabilities` module **MUST** have an `hdrProfiles` method that returns an array of `Media.HDRProfile` values describing the HDR capabilities commonly supported across all relevant peripherals in the user's AV chain. + +If no display is present, an empty array **MUST** be returned. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. + +```javascript +MediaCapabilities.hdrProfiles() +//> ["dolbyVision", "hdr10", "hdr10plus", "hlg"] +``` + +### 4.9. Atmos Supported + +The `MediaCapabilities` module **MUST** have an `atmosSupported` method that returns a boolean describing whether or not Dolby Atmos is commonly supported across all relevant peripherals in the user's AV chain for immersive audio output. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. + +```javascript +MediaCapabilities.atmosSupported() +//> true +``` + +## 5. Display Support + +Apps need to know various aspects of the current (or built-in) video output properties of a device and its connected display. + +These will be surfaced in the `Display` module. + +### 5.1. HDR Profiles + +The `Display` module **MUST** have an `hdrProfiles` method that returns an array of `Media.HDRProfile` values describing the display's supported HDR profiles. + +If no display is present, an empty array **MUST** be returned. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. + +```javascript +Display.hdrProfiles() +//> ["dolbyVision", "hdr10", "hdr10plus", "hlg"] +``` + +### 5.2. Color Depth + +The `Display` module **MUST** have a `colorDepth` method that returns a numeric value describing the display's supported color depth. + +If no display is present, a value of `0` **MUST** be returned. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. + +```javascript +Display.colorDepth() +//> 10 +``` + +### 5.3. Display Size + +The `Display` module **MUST** have a `size` method that returns a `Types.Dimensions` object describing the physical width and height of the display, in centimeters. + +If no display is present, the height and width values **MUST** both be zero. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. + +```javascript +Display.size() +//> { "width": 157, "height": 91 } +``` + +### 5.4. Native Resolution + +The `Display` module **MUST** have an `nativeResolution` method that returns a `Types.Dimensions` object describing the `width` and `height` of the display's native resolution as numbers, in pixels. + +If no display is present, the height and width values **MUST** both be zero. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. + +```javascript +Display.nativeResolution() +//> { "width": 1920, "height": 1080 } +``` + +### 5.5. Native Resolution Name + +The `Display` module **MUST** have a `nativeResolutionName` method that returns a `Media.ResolutionName` value describing the user-friendly name of the display's native resolution. + +If no display is present, a value of `unknown` **MUST** be returned. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. + +```javascript +Display.nativeResolutionName() +//> "uhd" +``` + +### 5.6. Native Refresh Rate + +The `Display` module **MUST** have a `nativeRefreshRate` method that returns an number value describing the native refresh rate of the display (in Hz). + +If no display is present, a value of zero **MUST** be returned. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. + +```javascript +Display.nativeRefreshRate() +//> 120 +``` + +### 5.7. Colorimetry + +The `Display` module **MUST** have a `colorimetry` method that returns an array of `Media.Colorimetry` values describing the display's supported colorimetry values. + +If no display is present, an empty array **MUST** be returned. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. + +```javascript +Display.colorimetry() +//> ["BT2020RGB", "BT2020YCC", "xvYCC601", "xvYCC709"] +``` + +### 5.10. Supported Video Modes + +The `Display` module **MUST** have a `videoModes` method that returns an array of `Media.VideoMode` values describing the video modes supported by the display. + +If no display is present, an empty array **MUST** be returned. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. + +```javascript +Display.videoModes() +//> ["720p50", "720p60", "1080p50", "1080p60"] +``` + +## 6. Audio Output + +Apps need to know various aspects of the audio system, such as which audio output mode is currently set. + +These APIs will be surfaced in the `AudioOutput` module. + +### 6.1. Mode + +The `AudioOutput` module **MUST** include a `mode` method that returns a `Media.AudioMode` value describing the device's current audio output mode. + +This method **MUST** have a corresponding `onModeChanged` event to notify listeners after a change to this property has been made and that change has taken effect. + +Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:audio-output:config` capability. + +```javascript +AudioOutput.mode() +//> "stereo" +``` + +## 7. Video Output + +Apps need to know various aspects of the video output system, such as the current video mode/resolution. + +These APIs will be surfaced in the `VideoOutput` module. + +### 7.1. Mode + +The `VideoOutput` module **MUST** have a `mode` property that returns a `Media.VideoMode` value describing the currently set video output mode. + +If no display is present, a value of `unknown` is returned. + +This method **MUST** have a corresponding `onModeWillChange` event to notify listeners when a change to this property has been made but before that change has taken effect. + +This method **MUST** have a corresponding `onModeChanged` event to notify listeners after a change to this property has been made and that change has taken effect. + +Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:video-output:config` capability. + +```javascript +VideoOutput.mode() +//> "1080p60" +``` + +### 7.2. Resolution + +The `VideoOutput` module **MUST** have a `resolution` method that returns a `Types.Dimensions` object describing the current video output resolution, in pixels. + +If no display is present, the height and width values **MUST** both be zero. + +This method **MUST** have a corresponding `onResolutionChanged` event to notify listeners after a change to the device's `videoMode` property has been made and that change has taken effect. + +Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:video-output:config` capability. + +```javascript +VideoOutput.resolution() +//> { "width": 1920, "height": 1080 } +``` + +### 7.3. HDR Profile + +The `VideoOutput` module **MUST** have an `hdrProfile` method that returns a `Media.HDRProfile` value describing the HDR profile currently set for video output. + +This method **MUST** have a corresponding `onHdrProfileChanged` event to notify listeners after this property has changed and that change has taken effect. + +Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:video-output:config` capability. + +```javascript +VideoOutput.hdrProfile() +//> "hdr10plus" +``` + +### 7.4. Color Depth + +The `VideoOutput` module **MUST** have a `colorDepth` method that returns a `Media.ColorDepth` value describing the current color depth setting for video output. + +This method **MUST** have a corresponding `onColorDepthChanged` event to notify listeners after this property has changed and that change has taken effect. + +Access to these methods **MUST** be governed by the `xrn:firebolt:capability:video-output:config` capability. + +```javascript +VideoOutput.colorDepth() +//> "10" +``` + +### 7.5. Color Space & Chroma Subsampling + +The `VideoOutput` module **MUST** have a `colorSpace` method that returns a `Media.ColorSpace` value describing the color space and chroma subsampling value currently set for video output. + +This method **MUST** have a corresponding `onColorSpaceChanged` event to notify listeners after this property has changed and that change has taken effect. + +Access to these methods **MUST** be governed by the `xrn:firebolt:capability:video-output:config` capability. + +```javascript +VideoOutput.colorSpace() +//> "YCbCr422" +``` + +### 7.6. Quantization Range + +The `VideoOutput` module **MUST** have a `quantizationRange` method that returns a `VideoOutput.QuantizationRange` value describing the quantization range currently set for video output. + +Access to this method **MUST** be governed by the `xrn:firebolt:capability:video-output:config` capability. + +```javascript +VideoOutput.quantizationRange() +//> "limited" +``` + +### 7.7. Current Output Settings + +The `VideoOutput` module **MUST** have a `currentSettings` method that returns an object describing various properties currently used for video output. + +This method **MUST** return the following properties: + +| Property | Type | +| ------------ | ------------------ | +| `colorDepth` | `Media.ColorDepth` | +| `colorSpace` | `Media.ColorSpace` | +| `hdrProfile` | `Media.HDRProfile` | +| `mode` | `Media.VideoMode` | +| `resolution` | `Types.Dimensions` | + +Access to this method **MUST** be governed by the `xrn:firebolt:capability:video-output:config` capability. + +This method **MUST** have a corresponding `onCurrentSettingsChanged` event to notify listeners after any of the specified output properties have changed and that those changes have taken effect. + +```javascript +Video.currentSettings() +//> { +//> "colorDepth": "10", +//> "colorSpace": "YCbCr422", +//> "hdrProfile": "hdr10plus", +//> "mode": "1080p60", +//> "resolution": { "width": 1920, "height": 1080 } +//> } +``` diff --git a/requirements/specifications/media/media-info.md b/requirements/specifications/media/media-info.md deleted file mode 100644 index ae63a4807..000000000 --- a/requirements/specifications/media/media-info.md +++ /dev/null @@ -1,882 +0,0 @@ -# Media Info Requirements - -Document Status: Candidate Specification - -See [Firebolt Requirements Governance](../../governance.md) for more info. - -| Contributor | Organization | -| --------------- | -------------- | -| Anthony Borzota | Comcast | -| Jeremy LaCivita | Comcast | -| Stuart Harris | Sky | -| Joe Martin | Comcast | -| Farhan Mood | Liberty Global | - -## 1. Overview - -App developers need to know which audio and video formats can be successfully played on a Firebolt device and its attached peripherals. - -An audio format includes values such as the audio container, codec, codec level, and bit rate of the audio stream. - -A video format may include values such as the video container, codec, HDR profile, and resolution of the video stream. - -Further, apps may also need to know about the media format currently playing in the media pipeline. - -An app may need to check IP video playback that it has initiated to see if Dolby Audio is in fact active (as opposed to just present in the encoded data) in order to display metadata or badges to the user. Apps may also be playing [user-cultivated media](./media-access.md), and therefore have no metadata about the format of the files. - -A first-party app may need to check all [Media Pipelines](./media-pipeline.md) for media format characteristics to display a global badge. - -Additionally, apps may need to know what is supported by the device, *before* initiating any media playback. - -To solve this, Firebolt APIs will be created to detect the formats and codecs currently being decoded by the [Media Pipeline](./media-pipeline.md). Firebolt APIs will also be created to query whether the device and its peripherals support playing content of various formats. - -> TODO: Fix the above links - -### 1.1. User Stories - -#### 1.1.1. As an OTT App developer - -I want to know what is supported by the device and it's active AV chain: - -- I want to know if a video or audio format (Dolby Vision, Dolby Atmos, HEVC, etc.) will work if playback is attempted. -- I want to know if a format profile or level (HEVC Main 10, VP9 Profile 2, etc.) is supported. -- I want to know how many audio output channels (e.g. 7.1, 5.1) are available. -- I want to know what resolutions and frame rates are supported (e.g. 1080p60). - -I want to know what kind of content I'm currently playing: - -- I want to know which video or audio format the media I'm currently playing is sending to the decoder. -- I want to know which video or audio format profile or level the media I'm currently playing is being sent to the decoder. -- I want to know how many audio output channels (e.g. 7.1, 5.1) are currently being sent to the decoder. -- I want to know what resolution and frame rate is currently being sent to the decoder. - -#### 1.1.2. As a first-party App developer - -I want to show an audio/videophile overlay with detailed information: - -- I want to know all video or audio formats that are currently being sent to a decoder. -- I want to know all video or audio format profiles/levels currently being sent to a decoder. -- I want to know all audio output channel profiles (e.g. 7.1, 5.1) currently being sent to a decoder. -- I want to know all resolution and framerates currently being sent to a decoder. - -## 2. Table of Contents - -- [1. Overview](#1-overview) - - [1.1. User Stories](#11-user-stories) - - [1.1.1. As an OTT App developer](#111-as-an-ott-app-developer) - - [1.1.2. As a first-party App developer](#112-as-a-first-party-app-developer) -- [2. Table of Contents](#2-table-of-contents) -- [3. Constants, Types, and Schemas](#3-constants-types-and-schemas) - - [3.1. Media Container Types](#31-media-container-types) - - [3.2. Media Formats](#32-media-formats) - - [3.3. Dimensions](#33-dimensions) - - [3.4. Resolution User-Friendly Name](#34-resolution-user-friendly-name) - - [3.5. Video Modes](#35-video-modes) - - [3.6. HDR Profiles](#36-hdr-profiles) - - [3.7. HDCP Versions](#37-hdcp-versions) - - [3.8. Colorimetry](#38-colorimetry) - - [3.9. Color Depth](#39-color-depth) - - [3.9. Color Space \& Chroma Subsampling](#39-color-space--chroma-subsampling) - - [3.10. Audio Output Mode](#310-audio-output-mode) - - [3.11. Transfer Function](#311-transfer-function) - - [3.12. Quantization Range](#312-quantization-range) -- [4. AV System Support](#4-av-system-support) - - [4.1. Video Format Supported](#41-video-format-supported) - - [4.2. Audio Format Supported](#42-audio-format-supported) -- [5. Display Support](#5-display-support) - - [5.1. HDR Profiles](#51-hdr-profiles) - - [5.2. Color Depth](#52-color-depth) - - [5.3. Display Size](#53-display-size) - - [5.4. Native Resolution](#54-native-resolution) - - [5.5. Native Resolution Name](#55-native-resolution-name) - - [5.6. Refresh Rate](#56-refresh-rate) - - [5.7. Colorimetry](#57-colorimetry) - - [5.8. Manufacturer](#58-manufacturer) - - [5.9. Model](#59-model) - - [5.10. Source Physical Address](#510-source-physical-address) - - [5.11. Electro Optical Transfer Function (EOTF)](#511-electro-optical-transfer-function-eotf) -- [6. Device Support](#6-device-support) - - [6.1. Audio Mode](#61-audio-mode) - - [6.2. Video Mode](#62-video-mode) - - [6.3. Pre-Video Mode Change Event](#63-pre-video-mode-change-event) - - [6.4. Supported Audio Modes](#64-supported-audio-modes) - - [6.5. Supported Video Modes](#65-supported-video-modes) - - [6.6. Video Resolution](#66-video-resolution) - - [6.7. HDR Profile](#67-hdr-profile) - - [6.8. Supported HDR Profiles](#68-supported-hdr-profiles) - - [6.9. Maximum Supported HDCP Version](#69-maximum-supported-hdcp-version) - - [6.11. Color Depth](#611-color-depth) - - [6.11. Maximum Supported Color Depth](#611-maximum-supported-color-depth) - - [6.12. Color Space \& Chroma Subsampling](#612-color-space--chroma-subsampling) - - [6.13. Quantization Range](#613-quantization-range) -- [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. Constants, Types, and Schemas - -### 3.1. Media Container Types - -The Firebolt `Media` module **MUST** have an `AudioContainer` enumeration of the following media container content types: - -| Name | Description | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | -| `audio/mp4` | [MP4 Audio](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#mpeg-4_mp4) | -| `audio/mpeg` | [Moving Picture Experts Group (MPEG1/MPEG2)](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#mpegmpeg-2) | -| `audio/ogg` | [OGG](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#ogg) | -| `audio/wave` | [Waveform Audio File Format](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#wave_wav) | -| `audio/webm` | [Web Media](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#webm) | - -The Firebolt `Media` module **MUST** have a `VideoContainer` enumeration of the following media container content types: - -| Name | Description | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | -| `video/mp2t` | [MPEG transport stream](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) | -| `video/mp4` | [MP4 Audio](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/) | -| `video/mpeg` | [Moving Picture Experts Group (MPEG1/MPEG2)](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#mpegmpeg-2) | -| `video/webm` | [Web Media](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers#webm) | - -### 3.2. Media Formats - -The Firebolt `Media` module **MUST** have an `AudioFormat` enumeration: - -| Name | Description | -| -------- | ---------------------------------------------- | -| `aac` | Advanced Audio Coding | -| `ac3` | Dolby Digital / Dolby Audio Codec 3 | -| `ac4` | Dolby Audio Codec 4 | -| `dts-x` | Digital Theater Systems X | -| `eac3` | Dolby Digital Plus / Dolby Enhanced AC-3 / DD+ | -| `mpeg3` | MPEG-1 Part 3 & MPEG-2 Part 3 | -| `opus` | IETF Opus | -| `pcm` | Pulse Code Modulation/WAVE | -| `truehd` | Dolby TrueHD / MLP | -| `vorbis` | Xiph.org Vorbis | - -The Firebolt `Media` module **MUST** have a `VideoFormat` enumeration: - -| Name | Description | -| ------- | ------------------------------------ | -| `av1` | AOMedia Video 1 | -| `avc` | Advanced Video Coding (H.264) | -| `hevc` | High Efficiency Video Coding (H.265) | -| `mpeg1` | MPEG-1 Part 2 Visual | -| `mpeg2` | MPEG-2 Part 2 Visual | -| `vp8` | Video Processor 8 | -| `vp9` | Video Processor 9 | -| `vp10` | Video Processor 10 | - -### 3.3. Dimensions - -The Firebolt `Types` module must have a `Dimensions` object of the following schema: - -| Field | Type | -| -------- | -------- | -| `height` | `number` | -| `width` | `number` | - -### 3.4. Resolution User-Friendly Name - -The Firebolt `Media` module **MUST** have a `ResolutionName` enumeration: - -| Class | Applicable Resolutions | -| --------- | ---------------------- | -| `sd` | `576p` and lower | -| `hd` | `720p` | -| `fhd` | `1080p` | -| `uhd` | `2160` and higher | -| `unknown` | unknown or no display | - -### 3.5. Video Modes - -For the purposes of the Firebolt API, a `VideoMode` shall be defined as the shorthand vertical resolution and frame rate of video content. - -The Firebolt `Media` module **MUST** have a `VideoMode` enumeration: - -- `480i` -- `480p` -- `576i25` -- `576p50` -- `576p60` -- `720p50` -- `720p60` -- `1080i50` -- `1080i60` -- `1080p24` -- `1080p25` -- `1080p30` -- `1080p50` -- `1080p60` -- `2160p24` -- `2160p25` -- `2160p30` -- `2160p50` -- `2160p60` -- `4320p60` -- `unknown` - -Any methods relating to the video mode (such as a device's video output mode) **MUST** return `Media.VideoMode` values. - -### 3.6. HDR Profiles - -The Firebolt `Media` module **MUST** have an `HDRProfile` enumeration: - -- `dolbyVision` -- `hdr10` -- `hdr10plus` -- `hlg` -- `sdr` -- `technicolor` -- `unknown` - -### 3.7. HDCP Versions - -The Firebolt `Media` module **MUST** have an `HDCPVersion` enumeration: - -- `1.4` -- `2.2` -- `unknown` - -### 3.8. Colorimetry - -The Firebolt `Display` module **MUST** have a `Colorimetry` enumeration: - -- `BT2020cYCC` -- `BT2020RGB` -- `BT2020YCC` -- `DCI-P3` -- `ICtCp` -- `opRGB` -- `opYCC601` -- `sYCC601` -- `xvYCC601` -- `xvYCC709` -- `unknown` - -### 3.9. Color Depth - -The Firebolt `Media` module **MUST** have a `ColorDepth` enumeration: - -- `8` -- `10` -- `12` -- `auto` -- `unknown` - -### 3.9. Color Space & Chroma Subsampling - -The Firebolt `Media` module **MUST** have a `ColorSpace` enumeration: - -| Name | Chroma | -| ---------- | ------ | -| `RGB444` | 4:4:4 | -| `YCbCr420` | 4:2:0 | -| `YCbCr422` | 4:2:2 | -| `YCbCr444` | 4:4:4 | -| `other` | | -| `unknown` | | - -### 3.10. Audio Output Mode - -The Firebolt `Media` module **MUST** have an `AudioMode` enumeration: - -- `auto` -- `mono` -- `passthrough` -- `stereo` -- `surround` -- `unknown` - -### 3.11. Transfer Function - -The Firebolt `Display` module **MUST** have a `TransferFunction` enumeration: - -| Name | Description | -| -------------- | ---------------------------------------- | -| `BT1886` | ITU-R BT.1886 | -| `BT2100` | ITU-R BT.2100 | -| `SMPTE_ST2084` | SMPTE ST.2084; Perceptual quantizer (PQ) | -| `other` | other | -| `unknown` | unknown | - -### 3.12. Quantization Range - -The Firebolt `Device` module **MUST** have a `QuantizationRange` enumeration: - -- `full` -- `limited` -- `unknown` - -## 4. AV System Support - -Apps need to know what types of media support the device and any connected peripherals are together capable of. - -To facilitate this, the `AVSystem` module will provide convenience methods that encapsulate the capabilities of the device as well as any of its connected peripherals, including but not limited to, displays, sound bars, and receivers. - -These values **MUST NOT** change without a settings change, peripheral change, or firmware update. - -### 4.1. Video Format Supported - -The `AVSystem` module **MUST** have a `videoFormatSupported` method that returns boolean that provides whether or not the specified format is supported by the current device and its AV chain. - -This method **MUST** have a required `format` parameter with the type `Media.VideoFormat`. - -This method **MUST** have an optional `info` parameter which **MUST** be an object with zero or more of the following properties: - -| Property | Type | Description | -| ------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------ | -| `container` | `Media.VideoContainer` | The content container format | -| `hdr` | `Media.HDRProfile` | The HDR profile to check | -| `level` | `string` | The codec level:
**hevc**: `4.1`, `4.2`, `5.0`, `5.1`
**vp9**:`3.0`, `3.1`, `4.0`, `4.1`, `5.0`, `5.1` | -| `profile` | `string` | The codec profile:
**hevc**: `main`, `high`, `main10`
**vp9**: `p0`, `p2` | -| `resolution` | `Types.Dimensions` | The dimensions of the media content, in pixels | - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -AVSystem.videoFormatSupported(Media.VideoFormat.HEVC, { - profile: "main10", - hdr: Media.HDRProfile.HDR10_PLUS -}) -//> true - -AVSystem.videoFormatSupported(Media.VideoFormat.VP9, { - profile: "p2", - hdr: Media.HDRProfile.HDR10_PLUS, - resolution: { "width": 3840, "height": 2160 } -}) -//> true -``` - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:avsystem:info` capability. - -### 4.2. Audio Format Supported - -The `AVSystem` module **MUST** have an `audioFormatSupported` method that returns a boolean that provides whether or not the specified format is supported by the current device configuration and its AV chain. - -This method **MUST** have a required `format` parameter with the type `Media.AudioFormat`. - -This method **MUST** have an optional `options` parameter which **MUST** be an object with zero or more of the following properties: - -| Property | Type | Description | -| -------------- | ----------------- | -------------------------------------------------------------------------- | -| `atmos` | `boolean` | Whether or not Dolby Atmos support for the given format is being requested | -| `codecLevel` | `string` | The codec level | -| `codecProfile` | `string` | The codec profile:
**aac**: `mp2lc`, `mp4he` | -| `container` | `Media.Container` | The container format type | -| `sampleRate` | `number` | The sample rate being requested, in kHz | - -If the `options` parameter is provided, then this method **MUST NOT** return `true` unless the format specified is supported with **all** of the properties specified by `options` *all at the same time*. - -As multiple audio output modes may be set at the same time, the response **MUST** be based on the best possible audio configuration supported by the device and its AV chain. For instance, if the device is configured for stereo output (which cannot support Atmos) but the AV chain supports Surround 5.1 (which can support Atmos), the latter would be considered the best possible audio configuration and thus used as the basis for the decision. - -```javascript -AVSystem.audioFormatSupported(Media.AudioFormat.AC4, { - atmos: true -}) -//> true - -AVSystem.audioFormatSupported(Media.AudioFormat.TRUEHD, { - atmos: true - mode: 'mono' -}) -//> false (mono output not supported with dolby atmos) -``` - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:avsystem:info` capability. - -## 5. Display Support - -Apps need to know various aspects of the current (or built-in) display of a device. - -These will be surfaced in the `Display` module. - -### 5.1. HDR Profiles - -The `Display` module **MUST** have an `hdrProfiles` method that returns an array of `Media.HDRProfile` values denoting the display's supported HDR profiles. - -If no display is present, an empty array **MUST** be returned. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.hdrProfiles() -//> ["dolbyVision", "hdr10", "hdr10plus", "hlg"] -``` - -### 5.2. Color Depth - -The `Display` module **MUST** have a `colorDepth` method that returns a `Media.ColorDepth` value denoting the display's supported color depth. - -If no display is present, a value of `unknown` **MUST** be returned. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.colorDepth() -//> "10" -``` - -### 5.3. Display Size - -The `Display` module **MUST** have a `size` method that returns a `Types.Dimensions` object denoting the physical width and height of the display, in centimeters. - -If no display is present, the height and width values **MUST** both be zero. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.size() -//> { "width": 157, "height": 91 } -``` - -### 5.4. Native Resolution - -The `Display` module **MUST** have a `resolution` method that returns a `Types.Dimensions` object denoting the `width` and `height` of the display's native resolution as numbers, in pixels. - -If no display is present, the height and width values **MUST** both be zero. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.resolution() -//> { "width": 1920, "height": 1080 } -``` - -### 5.5. Native Resolution Name - -The `Display` module **MUST** have a `resolutionName` method that returns a `Media.ResolutionName` value denoting the user-friendly name of the display's native resolution. - -If no display is present, a value of `unknown` **MUST** be returned. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.resolutionName() -//> "uhd" -``` - -### 5.6. Refresh Rate - -The `Display` module **MUST** have a `refreshRate` method that returns an number value denoting the optimal refresh rate of the display (in Hz). - -If no display is present, a value of zero **MUST** be returned. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.refreshRate() -//> 120 -``` - -### 5.7. Colorimetry - -The `Display` module **MUST** have a `colorimetry` method that returns an array of `Media.Colorimetry` values denoting the display's supported colorimetry values. - -If no display is present, an empty array **MUST** be returned. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.colorimetry() -//> ["BT2020RGB", "BT2020YCC", "xvYCC601", "xvYCC709"] -``` - -### 5.8. Manufacturer - -The `Display` module **MUST** have a `manufacturer` method that returns a string denoting the display's manufacturer. - -If no display is present, an empty string **MUST** be returned. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.manufacturer() -//> "Samsung Electric Company" -``` - -### 5.9. Model - -The `Display` module **MUST** have a `model` method that returns a string denoting the display's model number/product name. - -If no display is present, an empty string **MUST** be returned. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.model() -//> "Q80A" -``` - -### 5.10. Source Physical Address - -The `Display` module **MUST** have a `sourcePhysicalAddress` method that returns a string denoting the display's source physical address. - -If no display is present, an empty string **MUST** be returned. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.sourcePhysicalAddress() -//> "3.0.0.0" -``` - -### 5.11. Electro Optical Transfer Function (EOTF) - -The `Display` module **MUST** have an `eotf` method that returns a `Display.TransferFunction` value denoting the display's EOTF. - -If no display is present, a value of `unknown` **MUST** be returned. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. - -```javascript -Display.eotf() -//> "SMPTE_ST2084" -``` - -## 6. Device Support - -Apps need to know various aspects of the device, including its media playing capabilities. - -These will be surfaced in the `Device` module. - -### 6.1. Audio Mode - -The `Device` module **MUST** include an `audioMode` method that returns a `Media.AudioMode` value denoting the device's current audio output mode. - -This method **MUST** have a corresponding event to notify listeners after a change to this property has been made and that change has taken effect. - -Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.audioMode() -//> "stereo" -``` - -### 6.2. Video Mode - -The `Device` module **MUST** have a `videoMode` method that returns a `Media.VideoMode` value denoting the device's current video mode. - -If no display is present, a value of `unknown` is returned. - -This method **MUST** have a corresponding event to notify listeners after a change to this property has been made and that change has taken effect. - -Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.videoMode() -//> "1080p60" -``` - -### 6.3. Pre-Video Mode Change Event - -The `Device` module **MUST** have a `onPreVideoModeChanged` event that that returns a `Media.VideoMode` value denoting the device's current video mode. - -This method **MUST** notify listeners after a change to this property has been made but before the change has taken effect. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.onPreVideoModeChanged((value) => { - console.log(value) - //> "1080p60" -}) -``` - -### 6.4. Supported Audio Modes - -The `Device` module **MUST** have an `audioModes` method that returns an array of `Media.AudioMode` values denoting the audio modes supported by the device. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.audioModes() -//> ["passthrough", "stereo", "surround"] -``` - -### 6.5. Supported Video Modes - -The `Device` module **MUST** have a `videoModes` method that returns an array of `Media.VideoMode` values denoting the video modes supported by the device. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.videoModes() -//> ["720p50", "720p60", "1080p50", "1080p60"] -``` - -### 6.6. Video Resolution - -The `Device` module **MUST** have a `videoResolution` method that returns a `Types.Dimensions` object denoting the current video output resolution, in pixels. - -If no display is present, the height and width values **MUST** both be zero. - -This method **MUST** have a corresponding event to notify listeners after a change to the device's `videoMode` property has been made and that change has taken effect. - -Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.videoResolution() -//> { "width": 1920, "height": 1080 } -``` - -### 6.7. HDR Profile - -The `Device` module **MUST** have an `hdrProfile` method that returns a `Media.HDRProfile` value denoting the HDR profile currently set on the device for video output. - -This method **MUST** have a corresponding event to notify listeners after this property has changed and that change has taken effect. - -Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.hdrProfile() -//> "hdr10plus" -``` - -### 6.8. Supported HDR Profiles - -The `Device` module **MUST** have an `hdrProfiles` method that returns an array of `Media.HDRProfile` values denoting the HDR profiles supported by the device. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.hdrProfiles() -//> ["dolbyVision", "hdr10", "hdr10plus", "hlg"] -``` - -### 6.9. Maximum Supported HDCP Version - -The `Device` module **MUST** have a `maxHdcpVersion` method that returns a `Media.HDCPVersion` value denoting the maximum HDCP version supported by the device for media protection. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.maxHdcpVersion() -//> "2.2" -``` - -### 6.11. Color Depth - -The `Device` module **MUST** have a `colorDepth` method that returns a `Media.ColorDepth` value denoting the color depth currently set on the device for video output. - -This method **MUST** have a corresponding event to notify listeners after this property has changed and that change has taken effect. - -Access to these methods **MUST** be governed by the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.colorDepth() -//> "10" -``` - -### 6.11. Maximum Supported Color Depth - -The `Device` module **MUST** have a `maxColorDepth` method that returns a `Media.ColorDepth` value denoting the maximum color depth supported by the device for video output. - -Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.maxColorDepth() -//> "10" -``` - -### 6.12. Color Space & Chroma Subsampling - -The `Device` module **MUST** have a `colorSpace` method that returns a `Media.ColorSpace` value denoting the color space and chroma subsampling value currently set on the device for video output. - -This method **MUST** have a corresponding event to notify listeners after this property has changed and that change has taken effect. - -Access to these methods **MUST** be governed by the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.colorSpace() -//> "YCbCr422" -``` - -### 6.13. Quantization Range - -The `Device` module **MUST** have a `quantizationRange` method that returns a `Device.QuantizationRange` value denoting the quantization range currently set on the device for video output. - -This method **MUST** have a corresponding event to notify listeners after this property has changed and that change has taken effect. - -Access to these methods **MUST** be governed by the `xrn:firebolt:capability:device:info` capability. - -```javascript -Device.quantizationRange() -//> "limited" -``` - -## 7. Media Info - -The Firebolt `MediaInfo` module consists of APIs to get information about any media actively being decoded by the Media Pipeline or an active HDMI input. - -### 7.1. MediaInfo for Current App - -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.: - -```javascript -MediaInfo.videoFormat(1) // return the video format in the current app's media pipeline 1 -MediaInfo.videoFormat(2) // return the video format in the current app's media pipeline 2 -``` - -**TODO**: where do we map video tags to ids? need a spec for this? same spec, new spec? -JL: i linked to the Media Pipeline spec and merged it into this branch... we should review. - -The `pipeline` parameter is required for the JSON-RPC request, however, the Firebolt SDK **SHOULD** provide a default value of `1` if not provided by the calling app. - -For example, the following would query the video format for the app's pipeline `1` in JavaScript (which supports default values for parameters). - -```javascript -MediaInfo.videoFormat() -``` - -#### 7.1.1. Video Format - -The `MediaInfo` module **MUST** have a `videoFormat` method that returns an `object` with the video codec (e.g. `avc`, `vp9`, etc.) and resolution of the media currently in the media pipeline (either playing or paused). - -The `videoFormat` result **MUST** have an `pipelineId` integer property that denotes the media pipeline/session ID. - -The `videoFormat` result **MUST** have a `format` property with one of the values from the `Media.VideoFormat` enum. - -The `videoFormat` result **MUST** have an `hdr` array property with zero or more `Media.HDRProfile` values. - -If a value is included in the `hdr` array then the media currently in the media pipeline **MUST** include the denoted HDR metadata in the decoded video. - -The `videoFormat` result **MUST** have a `resolution` property with a `Types.Dimensions` value. - -The `videoFormat` result **MAY** have a `codecProfile` string property that denotes the profile of the codec. - -The `videoFormat` result **MAY** have a `codecLevel` string property that denotes the level of the codec. - -The `videoFormat` method **MUST** be a Firebolt `property:readonly` API, and -have a corresponding `onVideoFormatChanged` notification. - -Access to the `videoFormat` method requires access to the `use` role of the -`xrn:firebolt:capability:media-info:video-format` capability. - -```javascript -MediaInfo.videoFormat(1) -/* -{ - "pipelineId": 1, - "codecLevel": "4.2", - "codecProfile": "main", - "container": "video/mp4", - "format": "hevc", - "frameRate": 30, - "hdr": [ - "hdr10" - ], - "resolution": { - "width": 1920, - "height": 1080 - } -} -*/ -``` - -#### 7.1.2. Audio Format - -The `MediaInfo` module **MUST** have a `audioFormat` method that returns an `object` with the below values describing media currently in the media pipeline (either playing or paused). - -The `audioFormat` result **MUST** have an `pipelineId` integer property that denotes the media pipeline/session ID. - -The `audioFormat` result **MUST** have a `biteRate` number property that denotes the audio bit rate. - -The `audioFormat` result **MUST** have a `channels` string property that denotes the audio output channels. - -The `audioFormat` result **MUST** have a `format` property with one of the values from the `Media.AudioFormat` enum. - -The `audioFormat` result **MUST** have a `sampleRate` number property that denotes the audio sample rate. - -The `audioFormat` result **MAY** have a `codecLevel` string property that denotes the level of the codec. - -The `audioFormat` result **MAY** have a `codecProfile` string property that denotes the profile of the codec. - -The `audioFormat` method **MUST** have a corresponding `onAudioFormatChanged` notification. - -Access to the `audioFormat` method requires access to the `use` role of the `xrn:firebolt:capability:media-info:audio-format` capability. - -```javascript -MediaInfo.audioFormat(1) -/* -{ - "pipelineId": 1, - "bitRate": 128, - "channels": 2, - "format": "aac", - "container": "audio/mp4", - "sampleRate": 48 -} -*/ -``` - -### 7.2. Global MediaInfo - -First party apps need a way to query which media formats are currently being output to the [media pipeline](./media-pipeline.md), without caring about which pipeline. - -#### 7.2.1. Active Video Formats - -The `MediaInfo` module **MUST** have a `activeVideoFormats` method that returns an array of `objects` for all media currently in the media pipeline (either playing or paused). - -Each item in the `activeVideoFormats` result array **MUST** conform to the same requirements as the individual results from the [`videoFormat` method](#711-video-format). - -Additionally, the `MediaInfo` module **MUST** have an `onActiveVideoFormatsChanged` event that fires whenever any pipeline starts, stops, or changes its current video format. - -Example: - -```javascript -MediaInfo.activeVideoFormats().find(f => f.format === Media.VideoFormat.HEVC) -/* -[ - { - "pipelineId": 1, - "codecLevel": "4.2", - "codecProfile": "main", - "container": "video/mp4", - "format": "hevc", - "frameRate": 30, - "hdr": [ - "hdr10" - ], - "resolution": { - "width": 1920, - "height": 1080 - } - } -] -*/ -``` - -Access to the `activeVideoFormats` method is gated by `manage` access to the `xrn:firebolt:capability:media-info:video-format` capability. - -#### 7.2.2. Active Audio Formats - -The `MediaInfo` module **MUST** have a `activeAudioFormats` method that returns an array of `objects` for all media currently in the media pipeline (either playing or paused). - -Each item in the `activeAudioFormats` result array **MUST** conform to the same requirements as the individual results from the [`audioFormat` method](#712-audio-format). - -Additionally, the `MediaInfo` module **MUST** have an `onActiveAudioFormatsChanged` event that fires whenever any pipeline starts, stops, or changes its current audio format. - -Example: - -```javascript -MediaInfo.activeAudioFormats().find(f => f.format === Media.AudioFormat.AAC) -/* -[ - { - "pipelineId": 1, - "bitRate": 128, - "channels": 2, - "container": "audio/mp4", - "format": "aac", - "sampleRate": 48 - } -] -*/ -``` - -Access to the `activeAudioFormats` method is gated by `manage` access to the `xrn:firebolt:capability:media-info:audio-format` capability. diff --git a/src/openrpc/audio_output.json b/src/openrpc/audio_output.json new file mode 100644 index 000000000..f91940e0a --- /dev/null +++ b/src/openrpc/audio_output.json @@ -0,0 +1,40 @@ +{ + "openrpc": "1.2.4", + "info": { + "title": "AudioOutput", + "description": "A module for the device's audio output system, including its output capabilities and configuration.", + "version": "0.0.0" + }, + "methods": [ + { + "name": "mode", + "summary": "The current audio output mode of the device.", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:audio-output:config" + ] + } + ], + "params": [], + "result": { + "name": "mode", + "summary": "The audio output mode.", + "schema": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioMode" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": "stereo" + } + } + ] + } + ] +} diff --git a/src/openrpc/av_system.json b/src/openrpc/av_system.json deleted file mode 100644 index d99b286ee..000000000 --- a/src/openrpc/av_system.json +++ /dev/null @@ -1,202 +0,0 @@ -{ - "openrpc": "1.2.4", - "info": { - "title": "AVSystem", - "description": "A module for querying the capabilities of the device any of its connected perirpherals (such as displays and soundbars).", - "version": "0.0.0" - }, - "methods": [ - { - "name": "audioFormatSupported", - "summary": "Check whether content of a given audio format is supported by the device's current configuration and its AV output system. The result is based on the device's best possible audio output configuration. These values may change as different AV inputs or peripherals are activated or connected.", - "tags": [ - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:avsystem:info" - ] - } - ], - "params": [ - { - "name": "format", - "summary": "Audio format used to check whether its supported.", - "required": true, - "schema": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioFormat" - } - }, - { - "name": "options", - "summary": "Additional options to use for checking whether an audio format is supported by the device. All values must be true for the content to be playable.", - "schema": { - "$ref": "#/components/schemas/AudioFormatOptions" - } - } - ], - "result": { - "name": "audioFormatSupported", - "summary": "Whether audio content of the given format is supported by the device's current configuration.", - "schema": { - "type": "boolean" - } - }, - "examples": [ - { - "name": "Check whether EAC3 codec with Atmos is supported", - "params": [ - { - "name": "format", - "value": "eac3" - }, - { - "name": "options", - "value": { - "atmos": true - } - } - ], - "result": { - "name": "Default Result", - "value": true - } - } - ] - }, - { - "name": "videoFormatSupported", - "summary": "Check whether video content of the given format is supported by the device's current configuration and its AV output system. These values may change as different AV inputs or peripherals are activated or connected.", - "tags": [ - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:avsystem:info" - ] - } - ], - "params": [ - { - "name": "format", - "summary": "The video format to check whether its supported by the device's current configuration.", - "required": true, - "schema": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoFormat" - } - }, - { - "name": "options", - "summary": "Additional options to use for checking whether a video is supported by the device. All values must be true for the content to be playable.", - "schema": { - "$ref": "#/components/schemas/VideoFormatOptions" - } - } - ], - "result": { - "name": "videoFormatSupported", - "summary": "Whether video content of the given format is supported by the device's current configuration.", - "schema": { - "type": "boolean" - } - }, - "examples": [ - { - "name": "Specify the video format to check", - "params": [ - { - "name": "format", - "value": "avc" - }, - { - "name": "options", - "value": { - "resolution": { - "width": 1920, - "height": 1080 - } - } - } - ], - "result": { - "name": "Default Result", - "value": true - } - } - ] - } - ], - "components": { - "schemas": { - "AudioFormatOptions": { - "description": "Options for checking audio playback support", - "type": "object", - "properties": { - "atmos": { - "description": "Whether Dolby Atmos support is being requested", - "type": "boolean" - }, - "codecLevel": { - "description": "The level of the audio codec", - "type": "string" - }, - "codecProfile": { - "description": "The profile of the audio codec", - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioCodecProfile" - }, - "container": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioContainer" - }, - "sampleRate": { - "description": "The sample rate of the audio, in kHz", - "type": "number" - } - } - }, - "VideoFormatOptions": { - "description": "Options for checking video playback support", - "type": "object", - "properties": { - "atmos": { - "description": "Whether Dolby Atmos support is being requested", - "type": "boolean" - }, - "codecLevel": { - "description": "The level of the video codec", - "type": "string", - "enum": [ - "4.1", - "4.2", - "5.0", - "5.1", - "high", - "main" - ] - }, - "codecProfile": { - "description": "The profile of the video codec", - "type": "string", - "enum": [ - "high", - "main", - "main10", - "p0", - "p2" - ] - }, - "container": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoContainer" - }, - "frameRate": { - "description": "The frame rate of the video content", - "type": "integer" - }, - "hdr": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDRProfile" - }, - "resolution": { - "$ref": "https://meta.comcast.com/firebolt/types#/definitions/Dimensions" - } - } - } - } - } -} diff --git a/src/openrpc/device.json b/src/openrpc/device.json index 293000d38..e5620504b 100644 --- a/src/openrpc/device.json +++ b/src/openrpc/device.json @@ -450,11 +450,6 @@ "x-uses": [ "xrn:firebolt:capability:device:info" ] - }, - { - "name": "deprecated", - "x-since": "1.2.0", - "x-alternative": "Device.hdcpVersion()" } ], "params": [], @@ -479,42 +474,12 @@ } ] }, - { - "name": "maxHdcpVersion", - "summary": "The latest/maximum HDCP version supported by the device.", - "tags": [ - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "params": [], - "result": { - "name": "maxHdcpVersion", - "summary": "The latest/maximum HDCP version", - "schema": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDCPVersion" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": "2.2" - } - } - ] - }, { "name": "hdr", "summary": "Returns an array of valid HDR profiles that the device supports", "tags": [ { - "name": "property:immutable" + "name": "property:readonly" }, { "name": "capabilities", @@ -525,7 +490,7 @@ { "name": "deprecated", "x-since": "1.2.0", - "x-alternative": "Device.hdrProfiles()" + "x-alternative": "MediaCapabilies.hdrProfiles()" } ], "params": [], @@ -552,97 +517,6 @@ } ] }, - { - "name": "hdrProfile", - "summary": "The HDR profile set for video output.", - "tags": [ - { - "name": "property:readonly" - }, - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "params": [], - "result": { - "name": "hdrProfile", - "summary": "The HDR profile", - "schema": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDRProfile" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": "hdr10" - } - } - ] - }, - { - "name": "hdrProfiles", - "summary": "The HDR profiles supported by the device, regardless of any connected display.", - "tags": [ - { - "name": "property:immutable" - }, - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "params": [], - "result": { - "name": "hdrProfiles", - "summary": "The supported HDR profiles", - "schema": { - "type": "array", - "items": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDRProfile" - } - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": [ - "hdr10", - "hdr10plus", - "hlg" - ] - } - }, - { - "name": "Example with either a device or display that does not support HDR", - "params": [], - "result": { - "name": "Default Result", - "value": [ - "sdr" - ] - } - }, - { - "name": "Example where no display is present", - "params": [], - "result": { - "name": "Default Result", - "value": [] - } - } - ] - }, { "name": "audio", "summary": "The supported audio profiles", @@ -697,7 +571,7 @@ { "name": "deprecated", "x-since": "1.2.0", - "x-alternative": "Display.resolution()" + "x-alternative": "Video.resolution()" } ], "params": [], @@ -724,107 +598,7 @@ }, { "name": "videoResolution", - "summary": "The width and height of the current video output, in pixels. Returns a zero value for width and height if no display is present.", - "tags": [ - { - "name": "property:readonly" - }, - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "params": [], - "result": { - "name": "videoResolution", - "summary": "The video output resolution", - "schema": { - "$ref": "https://meta.comcast.com/firebolt/types#/definitions/Dimensions" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": { - "width": 1920, - "height": 1080 - } - } - } - ] - }, - { - "name": "colorDepth", - "summary": "The color depth set on the device for video output.", - "params": [], - "tags": [ - { - "name": "property:readonly" - }, - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "result": { - "name": "colorDepth", - "summary": "The color depth set on the device.", - "schema": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/ColorDepth" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": "10" - } - } - ] - }, - { - "name": "maxColorDepth", - "summary": "The maximum color depth supported by the device for video output.", - "params": [], - "tags": [ - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "result": { - "name": "colorDepth", - "summary": "The color depth set on the device.", - "schema": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/ColorDepth" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": "10" - } - } - ] - }, - { - "name": "colorSpace", - "summary": "The color space set on the device for video output.", - "params": [], + "summary": "The width and height of the current video output resolution", "tags": [ { "name": "property:readonly" @@ -834,157 +608,19 @@ "x-uses": [ "xrn:firebolt:capability:device:info" ] - } - ], - "result": { - "name": "colorSpace", - "summary": "The color space set on the device.", - "schema": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/ColorSpace" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": "YCbCr422" - } - } - ] - }, - { - "name": "audioMode", - "summary": "The audio output mode of the device.", - "tags": [ - { - "name": "property:readonly" }, { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "params": [], - "result": { - "name": "audioMode", - "summary": "The audio output mode.", - "schema": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioMode" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": "stereo" - } - } - ] - }, - { - "name": "audioModes", - "summary": "All valid audio output modes supported by the device, regardless of any connected peripherals.", - "tags": [ - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "params": [], - "result": { - "name": "audioModes", - "summary": "The audio output modes", - "schema": { - "type": "array", - "items": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioMode" - } - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": [ - "passthrough", - "stereo", - "surround" - ] - } - } - ] - }, - { - "name": "videoMode", - "summary": "The video output mode of the device.", - "tags": [ - { - "name": "property:readonly" - }, - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "params": [], - "result": { - "name": "videoMode", - "summary": "The video output mode.", - "schema": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoMode" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": "1080p60" - } - }, - { - "name": "No Display Example", - "params": [], - "result": { - "name": "No Display Result", - "value": "unknown" - } - } - ] - }, - { - "name": "videoModes", - "summary": "All valid video output modes supported by the device, regardless of any connected peripherals.", - "tags": [ - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] + "name": "deprecated", + "x-since": "1.2.0", + "x-alternative": "Video.resolution()" } ], "params": [], "result": { - "name": "videoModes", - "summary": "The video output modes", + "name": "videoResolution", + "summary": "The video output resolution", "schema": { - "type": "array", - "items": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoMode" - } + "$ref": "#/components/schemas/Resolution" } }, "examples": [ @@ -994,85 +630,13 @@ "result": { "name": "Default Result", "value": [ - "720p50", - "720p60", - "1080i50", - "1080i60", - "1080p24", - "1080p30", - "1080p50", - "1080p60" + 1920, + 1080 ] } } ] }, - { - "name": "onPreVideoModeChanged", - "summary": "Notify when the video mode setting has changed but before it has taken effect.", - "tags": [ - { - "name": "event" - }, - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "params": [], - "result": { - "name": "onPreVideoModeChanged", - "summary": "The video output mode.", - "schema": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoMode" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": "1080p60" - } - } - ] - }, - { - "name": "quantizationRange", - "summary": "The quantization range set on the device for video output.", - "tags": [ - { - "name": "property:readonly" - }, - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:device:info" - ] - } - ], - "params": [], - "result": { - "name": "quantizationRange", - "summary": "The quantization range", - "schema": { - "$ref": "#/components/schemas/QuantizationRange" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": "limited" - } - } - ] - }, { "name": "network", "summary": "The network status and type", @@ -1223,16 +787,6 @@ } ] }, - "HDCPVersion": { - "description": "The HDCP version", - "type": "string", - "enumKeyPrefix": "hdcp", - "enum": [ - "1.4", - "2.2", - "unknown" - ] - }, "NetworkState": { "description": "The state of the network interface", "type": "string", @@ -1250,15 +804,6 @@ "wifi" ] }, - "QuantizationRange": { - "description": "The quantization range of video output", - "type": "string", - "enum": [ - "full", - "limited", - "unknown" - ] - }, "Resolution": { "type": "array", "items": [ diff --git a/src/openrpc/display.json b/src/openrpc/display.json index f871fb4b5..33699f9e9 100644 --- a/src/openrpc/display.json +++ b/src/openrpc/display.json @@ -2,13 +2,13 @@ "openrpc": "1.2.4", "info": { "title": "Display", - "description": "A module for querying various aspects of the current (or built-in) display on a device", + "description": "A module for querying various aspects of the currently connected display (connected or built-in).", "version": "0.0.0" }, "methods": [ { "name": "colorDepth", - "summary": "Get the maximum color depth supported by the display panel.", + "summary": "The color depth supported by the display.", "params": [], "tags": [ { @@ -20,7 +20,7 @@ ], "result": { "name": "colorDepth", - "summary": "The color depth supported by the display panel.", + "summary": "The color depth supported by the display.", "schema": { "type": "number" } @@ -46,7 +46,7 @@ }, { "name": "colorimetry", - "summary": "Get all colorimetry values from the display panel.", + "summary": "The colorimetry values supported by the display.", "params": [], "tags": [ { @@ -58,7 +58,7 @@ ], "result": { "name": "colorimetry", - "summary": "The colorimetry values supported by the display panel.", + "summary": "The colorimetry values supported by the display.", "schema": { "type": "array", "items": { @@ -77,42 +77,20 @@ "BT2020YCC" ] } - } - ] - }, - { - "name": "eotf", - "summary": "Get the display's Electro Optical Transfer Function (EOTF).", - "params": [], - "tags": [ - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:display:info" - ] - } - ], - "result": { - "name": "eotf", - "summary": "The EOTF value supported by the display panel.", - "schema": { - "$ref": "#/components/schemas/TransferFunction" - } - }, - "examples": [ + }, { - "name": "Default Example", + "name": "Example with no display", "params": [], "result": { "name": "Default Result", - "value": "SMPTE_ST2084" + "value": [] } } ] }, { "name": "hdrProfiles", - "summary": "Get the display's supported HDR profiles.", + "summary": "The display's supported HDR profiles.", "tags": [ { "name": "capabilities", @@ -129,8 +107,7 @@ "type": "array", "items": { "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDRProfile" - }, - "minItems": 1 + } } }, "examples": [ @@ -146,42 +123,20 @@ "hlg" ] } - } - ] - }, - { - "name": "manufacturer", - "summary": "Get the manufacturer of the display device.", - "tags": [ - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:display:info" - ] - } - ], - "params": [], - "result": { - "name": "manufacturer", - "summary": "The manufacturer of the display device.", - "schema": { - "type": "string" - } - }, - "examples": [ + }, { - "name": "Default Example", + "name": "Example with no display", "params": [], "result": { "name": "Default Result", - "value": "Samsung Electric Company" + "value": [] } } ] }, { - "name": "model", - "summary": "Get the model/product name of the display device.", + "name": "nativeRefreshRate", + "summary": "The native refresh rate of the display device.", "tags": [ { "name": "capabilities", @@ -192,10 +147,10 @@ ], "params": [], "result": { - "name": "model", - "summary": "The model/product name of the display device.", + "name": "refreshRate", + "summary": "The refresh rate of the display device.", "schema": { - "type": "string" + "type": "number" } }, "examples": [ @@ -204,44 +159,22 @@ "params": [], "result": { "name": "Default Result", - "value": "Q80A" + "value": 60 } - } - ] - }, - { - "name": "refreshRate", - "summary": "Get the native refresh rate of the display device.", - "tags": [ - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:display:info" - ] - } - ], - "params": [], - "result": { - "name": "refreshRate", - "summary": "The refresh rate of the display device.", - "schema": { - "type": "number" - } - }, - "examples": [ + }, { - "name": "Default Example", + "name": "Example with no display", "params": [], "result": { "name": "Default Result", - "value": 60 + "value": 0 } } ] }, { - "name": "resolution", - "summary": "Get the resolution of the display device in pixels. Returns a zero value for width and height if no display is present.", + "name": "nativeResolution", + "summary": "The native resolution of the display device in pixels. Returns a zero value for width and height if no display is present.", "tags": [ { "name": "capabilities", @@ -271,7 +204,7 @@ } }, { - "name": "No Display Example", + "name": "Example with no display", "params": [], "result": { "name": "Default Result", @@ -284,8 +217,8 @@ ] }, { - "name": "resolutionName", - "summary": "Get a user-friendly resolution name of the display device.", + "name": "nativeResolutionName", + "summary": "The user-friendly representation of the display's native resolution.", "tags": [ { "name": "capabilities", @@ -310,12 +243,20 @@ "name": "Default Result", "value": "uhd" } + }, + { + "name": "Example with no display", + "params": [], + "result": { + "name": "Default Result", + "value": "unknown" + } } ] }, { "name": "size", - "summary": "Get the width and height of the display panel (in centimeters).", + "summary": "The physical width and height of the display panel (in centimeters).", "tags": [ { "name": "capabilities", @@ -343,12 +284,23 @@ "height": 91 } } + }, + { + "name": "Example with no display", + "params": [], + "result": { + "name": "Default Result", + "value": { + "width": 0, + "height": 0 + } + } } ] }, { - "name": "sourcePhysicalAddress", - "summary": "Get the source physical address of the display device.", + "name": "videoModes", + "summary": "The video modes supported by the display device.", "tags": [ { "name": "capabilities", @@ -359,10 +311,13 @@ ], "params": [], "result": { - "name": "sourcePhysicalAddress", - "summary": "The source physical address of the display device.", + "name": "videoModes", + "summary": "The video modes", "schema": { - "type": "string" + "type": "array", + "items": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoMode" + } } }, "examples": [ @@ -371,7 +326,24 @@ "params": [], "result": { "name": "Default Result", - "value": "3.0.0.0" + "value": [ + "720p50", + "720p60", + "1080i50", + "1080i60", + "1080p24", + "1080p30", + "1080p50", + "1080p60" + ] + } + }, + { + "name": "Example with no display", + "params": [], + "result": { + "name": "Default Result", + "value": [] } } ] @@ -387,7 +359,6 @@ "BT2020RGB", "BT2020YCC", "DCI-P3", - "ICtCp", "opRGB", "opYCC601", "sYCC601", @@ -395,17 +366,6 @@ "xvYCC709", "unknown" ] - }, - "TransferFunction": { - "description": "Electro-optical transfer function of the display", - "type": "string", - "enum": [ - "BT1886", - "BT2100", - "SMPTE_ST2084", - "other", - "unknown" - ] } } } diff --git a/src/openrpc/media_capabilities.json b/src/openrpc/media_capabilities.json new file mode 100644 index 000000000..cb91dd898 --- /dev/null +++ b/src/openrpc/media_capabilities.json @@ -0,0 +1,455 @@ +{ + "openrpc": "1.2.4", + "info": { + "title": "MediaCapabilities", + "description": "A module for querying the capabilities of the device all of its connected perirpherals (such as displays and soundbars).", + "version": "0.0.0" + }, + "methods": [ + { + "name": "audioCodecs", + "summary": "The audio codecs commonly supported by the device and all its connected audio peripherals.", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:media-capabilities:info" + ] + } + ], + "params": [], + "result": { + "name": "audioCodecs", + "summary": "The supported audio codecs", + "schema": { + "type": "array", + "items": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioCodec" + } + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": [ + "aac", + "ac3", + "ac4", + "eac3", + "mpeg3", + "pcm" + ] + } + } + ] + }, + { + "name": "videoCodecs", + "summary": "The video codecs commonly supported by the device and all of its connected video peripherals.", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:media-capabilities:info" + ] + } + ], + "params": [], + "result": { + "name": "videoCodecs", + "summary": "The supported video codecs", + "schema": { + "type": "array", + "items": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoCodec" + } + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": [ + "av1", + "avc", + "hevc", + "mpeg1", + "mpeg2", + "vp8", + "vp9" + ] + } + } + ] + }, + { + "name": "audioFormatSupported", + "summary": "Check whether content of a given audio format is supported by the device's current configuration and its AV output system. The result is based on the device's best possible audio output configuration. These values may change as different AV inputs or peripherals are activated or connected.", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:media-capabilities:info" + ] + } + ], + "params": [ + { + "name": "codec", + "summary": "Audio codec used to check whether its supported.", + "required": true, + "schema": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioCodec" + } + }, + { + "name": "options", + "summary": "Additional options to use for checking whether an audio format is supported by the device. All values must be true for the content to be playable.", + "schema": { + "$ref": "#/components/schemas/AudioFormatOptions" + } + } + ], + "result": { + "name": "audioFormatSupported", + "summary": "Whether audio content of the given format is supported by the device's current configuration.", + "schema": { + "type": "boolean" + } + }, + "examples": [ + { + "name": "Check whether EAC3 codec with Atmos is supported", + "params": [ + { + "name": "codec", + "value": "eac3" + }, + { + "name": "options", + "value": { + "atmos": true + } + } + ], + "result": { + "name": "Default Result", + "value": true + } + } + ] + }, + { + "name": "videoFormatSupported", + "summary": "Check whether video content of the given format is supported by the device's current configuration and its AV output system. These values may change as different AV inputs or peripherals are activated or connected.", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:media-capabilities:info" + ] + } + ], + "params": [ + { + "name": "codec", + "summary": "The video codec to check whether its supported by the device's current configuration.", + "required": true, + "schema": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoCodec" + } + }, + { + "name": "options", + "summary": "Additional options to use for checking whether a video is supported by the device. All values must be true for the content to be playable.", + "schema": { + "$ref": "#/components/schemas/VideoFormatOptions" + } + } + ], + "result": { + "name": "videoFormatSupported", + "summary": "Whether video content of the given format is supported by the device's current configuration.", + "schema": { + "type": "boolean" + } + }, + "examples": [ + { + "name": "Specify the video format to check", + "params": [ + { + "name": "codec", + "value": "hevc" + }, + { + "name": "options", + "value": { + "resolution": { + "width": 1920, + "height": 1080 + } + } + } + ], + "result": { + "name": "Default Result", + "value": true + } + } + ] + }, + { + "name": "audioModes", + "summary": "The audio output modes commonly supported by the device and its connected audio peripherals", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:media-capabilities:info" + ] + } + ], + "params": [], + "result": { + "name": "audioModes", + "summary": "The supported audio output modes", + "schema": { + "type": "array", + "items": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioMode" + } + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": [ + "passthrough", + "stereo", + "surround" + ] + } + } + ] + }, + { + "name": "videoModes", + "summary": "The video output modes commonly supported by the device and its connected video peripherals.", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:media-capabilities:info" + ] + } + ], + "params": [], + "result": { + "name": "videoModes", + "summary": "The supported video output modes", + "schema": { + "type": "array", + "items": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoMode" + } + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": [ + "720p50", + "720p60", + "1080p50", + "1080p60" + ] + } + } + ] + }, + { + "name": "colorDepth", + "summary": "The maximum color depth commonly supported by the device and its connected video peripherals.", + "params": [], + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:media-capabilities:info" + ] + } + ], + "result": { + "name": "colorDepth", + "summary": "The supported color depth", + "schema": { + "type": "number" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": 10 + } + } + ] + }, + { + "name": "hdrProfiles", + "summary": "The HDR profiles commonly supported by the device and its connected video peripherals.", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:media-capabilities:info" + ] + } + ], + "params": [], + "result": { + "name": "hdrProfiles", + "summary": "The supported HDR profiles", + "schema": { + "type": "array", + "items": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDRProfile" + } + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": [ + "hdr10", + "hdr10plus", + "hlg" + ] + } + } + ] + }, + { + "name": "atmosSupported", + "summary": "Whether or not Dolby Atmos immersive audio is commonly supported by the device and its connected audio peripherals.", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:media-capabilities:info" + ] + } + ], + "params": [], + "result": { + "name": "atmosSupported", + "summary": "Whether Dolby Atmos is supported", + "schema": { + "type": "boolean" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": true + } + } + ] + } + ], + "components": { + "schemas": { + "AudioFormatOptions": { + "description": "Options for checking audio playback support", + "type": "object", + "properties": { + "atmos": { + "description": "Whether Dolby Atmos support is being requested", + "type": "boolean" + }, + "codecLevel": { + "description": "The level of the audio codec", + "type": "string" + }, + "codecProfile": { + "description": "The profile of the audio codec", + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioCodecProfile" + }, + "container": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioContainer" + }, + "sampleRate": { + "description": "The sample rate of the audio, in kHz", + "type": "number" + } + } + }, + "VideoFormatOptions": { + "description": "Options for checking video playback support", + "type": "object", + "properties": { + "atmos": { + "description": "Whether Dolby Atmos support is being requested", + "type": "boolean" + }, + "codecLevel": { + "description": "The level of the video codec", + "type": "string", + "enum": [ + "4.1", + "4.2", + "5.0", + "5.1", + "high", + "main" + ] + }, + "codecProfile": { + "description": "The profile of the video codec", + "type": "string", + "enum": [ + "high", + "main", + "main10", + "p0", + "p2" + ] + }, + "container": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoContainer" + }, + "frameRate": { + "description": "The frame rate of the video content", + "type": "integer" + }, + "hdr": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDRProfile" + }, + "resolution": { + "$ref": "https://meta.comcast.com/firebolt/types#/definitions/Dimensions" + } + } + } + } + } +} diff --git a/src/openrpc/media_info.json b/src/openrpc/media_info.json deleted file mode 100644 index 7c6d1b6d2..000000000 --- a/src/openrpc/media_info.json +++ /dev/null @@ -1,324 +0,0 @@ -{ - "openrpc": "1.2.4", - "info": { - "title": "MediaInfo", - "description": "A module for query info about the media currently in the media pipeline (either playing or paused).", - "version": "0.0.0" - }, - "methods": [ - { - "name": "activeAudioFormats", - "summary": "Get a list of the active audio formats currently used across all media pipelines.", - "tags": [ - { - "name": "property:readonly" - }, - { - "name": "capabilities", - "x-manages": [ - "xrn:firebolt:capability:media-info:audio-format" - ] - } - ], - "params": [], - "result": { - "name": "activeAudioFormats", - "summary": "The active audio formats used across all pipelines.", - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AudioFormat" - } - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": [ - { - "bitRate": 128, - "channels": "2", - "format": "aac", - "codecProfile": "mp2lc", - "container": "audio/mp4", - "pipelineId": 1, - "sampleRate": 48 - } - ] - } - } - ] - }, - { - "name": "activeVideoFormats", - "summary": "Get a list of the active video formats currently used across all media pipelines.", - "tags": [ - { - "name": "property:readonly" - }, - { - "name": "capabilities", - "x-manages": [ - "xrn:firebolt:capability:media-info:video-format" - ] - } - ], - "params": [], - "result": { - "name": "activeVideoFormats", - "summary": "The active video formats used across all pipelines.", - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/VideoFormat" - } - } - }, - "examples": [ - { - "name": "Default Example", - "params": [], - "result": { - "name": "Default Result", - "value": [ - { - "codecLevel": "4.2", - "codecProfile": "main", - "container": "video/mp4", - "format": "hevc", - "frameRate": 30, - "hdr": [ - "hdr10" - ], - "pipelineId": 1, - "resolution": { - "width": 1920, - "height": 1080 - } - } - ] - } - } - ] - }, - { - "name": "audioFormat", - "summary": "Get the audio format currently used by the specified media pipeline.", - "tags": [ - { - "name": "property:readonly" - }, - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:media-info:audio-format" - ] - } - ], - "params": [ - { - "name": "pipelineId", - "required": true, - "schema": { - "$ref": "#/components/schemas/PipelineId" - } - } - ], - "result": { - "name": "audioFormat", - "summary": "Audio format used by the pipeline.", - "schema": { - "$ref": "#/components/schemas/AudioFormat" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [ - { - "name": "pipelineId", - "value": 1 - } - ], - "result": { - "name": "Default Result", - "value": { - "bitRate": 128, - "channels": "2", - "container": "audio/mp4", - "format": "aac", - "pipelineId": 1, - "sampleRate": 48 - } - } - } - ] - }, - { - "name": "videoFormat", - "summary": "Get the video format currently used by the specified media pipeline.", - "tags": [ - { - "name": "property:readonly" - }, - { - "name": "capabilities", - "x-uses": [ - "xrn:firebolt:capability:media-info:video-format" - ] - } - ], - "params": [ - { - "name": "pipelineId", - "required": true, - "schema": { - "$ref": "#/components/schemas/PipelineId" - } - } - ], - "result": { - "name": "videoFormat", - "summary": "Video format used by the pipeline.", - "schema": { - "$ref": "#/components/schemas/VideoFormat" - } - }, - "examples": [ - { - "name": "Default Example", - "params": [ - { - "name": "pipelineId", - "value": 1 - } - ], - "result": { - "name": "Default Result", - "value": { - "codecLevel": "4.2", - "codecProfile": "main", - "container": "video/mp4", - "format": "hevc", - "frameRate": 30, - "hdr": [ - "hdr10" - ], - "pipelineId": 1, - "resolution": { - "width": 1920, - "height": 1080 - } - } - } - } - ] - } - ], - "components": { - "schemas": { - "AudioFormat": { - "type": "object", - "description": "Details on the audio content format.", - "properties": { - "bitRate": { - "description": "The audio bitrate in kbps.", - "type": "number" - }, - "channels": { - "description": "The audio output channels.", - "type": "string" - }, - "codecLevel": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioCodecLevel" - }, - "codecProfile": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioCodecProfile" - }, - "container": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioContainer" - }, - "format": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/AudioFormat" - }, - "pipelineId": { - "$ref": "#/components/schemas/PipelineId" - }, - "sampleRate": { - "description": "The audio sample rate in kHz.", - "type": "number" - } - }, - "required": [ - "format", - "channels", - "pipelineId", - "sampleRate" - ] - }, - "PipelineId": { - "type": "integer", - "description": "The media pipeline/session ID", - "minimum": 0, - "maximum": 15 - }, - "VideoFormat": { - "type": "object", - "description": "Details on the video content format.", - "properties": { - "codecLevel": { - "type": "string", - "enum": [ - "4.1", - "4.2", - "5.0", - "5.1", - "high", - "main" - ] - }, - "codecProfile": { - "type": "string", - "enum": [ - "high", - "main", - "main10", - "p0", - "p2" - ] - }, - "container": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoContainer" - }, - "format": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoFormat" - }, - "frameRate": { - "type": "number" - }, - "hdr": { - "type": "array", - "items": { - "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDRProfile" - } - }, - "pipelineId": { - "$ref": "#/components/schemas/PipelineId" - }, - "resolution": { - "$ref": "https://meta.comcast.com/firebolt/types#/definitions/Dimensions" - } - }, - "required": [ - "format", - "hdr", - "pipelineId", - "resolution" - ] - } - } - } -} diff --git a/src/openrpc/video_output.json b/src/openrpc/video_output.json new file mode 100644 index 000000000..9903f9f6a --- /dev/null +++ b/src/openrpc/video_output.json @@ -0,0 +1,320 @@ +{ + "openrpc": "1.2.4", + "info": { + "title": "VideoOutput", + "description": "A module for the device's video output system, including its output capabilities and configuration.", + "version": "0.0.0" + }, + "methods": [ + { + "name": "colorDepth", + "summary": "The color depth set for video output.", + "params": [], + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:video-output:config" + ] + } + ], + "result": { + "name": "colorDepth", + "summary": "The color depth set.", + "schema": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/ColorDepth" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": "10" + } + } + ] + }, + { + "name": "colorSpace", + "summary": "The color space and chroma set for video output.", + "params": [], + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:video-output:config" + ] + } + ], + "result": { + "name": "colorSpace", + "summary": "The color space set on the device.", + "schema": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/ColorSpace" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": "YCbCr422" + } + } + ] + }, + { + "name": "currentSettings", + "summary": "A convenience method that returns various properties currently set on the device related to video output.", + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:video-output:config" + ] + } + ], + "params": [], + "result": { + "name": "currentSettings", + "summary": "Current video output properties", + "schema": { + "type": "object", + "properties": { + "colorDepth": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/ColorDepth" + }, + "colorSpace": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/ColorSpace" + }, + "hdrProfile": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDRProfile" + }, + "mode": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoMode" + }, + "resolution": { + "$ref": "https://meta.comcast.com/firebolt/types#/definitions/Dimensions" + } + }, + "required": [ + "colorDepth", + "colorSpace", + "hdrProfile", + "mode", + "resolution" + ] + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": { + "colorDepth": "10", + "colorSpace": "YCbCr422", + "hdrProfile": "hdr10plus", + "mode": "1080p60", + "resolution": { + "width": 1920, + "height": 1080 + } + } + } + } + ] + }, + { + "name": "hdrProfile", + "summary": "The HDR profile set for video output.", + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:video-output:config" + ] + } + ], + "params": [], + "result": { + "name": "hdrProfile", + "summary": "The HDR profile", + "schema": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDRProfile" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": "hdr10plus" + } + } + ] + }, + { + "name": "quantizationRange", + "summary": "The quantization range set for video output.", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:video-output:config" + ] + } + ], + "params": [], + "result": { + "name": "quantizationRange", + "summary": "The quantization range", + "schema": { + "$ref": "#/components/schemas/QuantizationRange" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": "limited" + } + } + ] + }, + { + "name": "mode", + "summary": "The current video output mode of the device.", + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:video-output:config" + ] + } + ], + "params": [], + "result": { + "name": "mode", + "summary": "The video output mode.", + "schema": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoMode" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": "1080p60" + } + } + ] + }, + { + "name": "onModeWillChange", + "summary": "Be notified when the video output mode setting has changed but it has not yet taken effect on the device.", + "tags": [ + { + "name": "event" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:video-output:config" + ] + } + ], + "params": [], + "result": { + "name": "mode", + "summary": "The video output mode.", + "schema": { + "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoMode" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": "1080p60" + } + } + ] + }, + { + "name": "resolution", + "summary": "The width and height of the current video output, in pixels.", + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:video-output:config" + ] + } + ], + "params": [], + "result": { + "name": "resolution", + "summary": "The video output resolution", + "schema": { + "$ref": "https://meta.comcast.com/firebolt/types#/definitions/Dimensions" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": { + "width": 1920, + "height": 1080 + } + } + } + ] + } + ], + "components": { + "schemas": { + "QuantizationRange": { + "description": "The quantization range of video output", + "type": "string", + "enum": [ + "full", + "limited", + "unknown" + ] + } + } + } +} diff --git a/src/schemas/media.json b/src/schemas/media.json index 59cd69764..74eac0249 100644 --- a/src/schemas/media.json +++ b/src/schemas/media.json @@ -2,20 +2,18 @@ "$id": "https://meta.comcast.com/firebolt/schemas/media", "title": "Media", "definitions": { - "AudioFormat": { + "AudioCodec": { "type": "string", - "description": "Audio format", + "description": "Audio codec", "enum": [ "aac", "ac3", "ac4", - "dts-x", "eac3", "mpeg3", "opus", "pcm", "truehd", - "unknown", "vorbis" ] }, @@ -93,15 +91,6 @@ "unknown" ] }, - "HDCPVersion": { - "type": "string", - "description": "HDCP version", - "enum": [ - "1.4", - "2.2", - "unknown" - ] - }, "HDRProfile": { "type": "string", "description": "HDR profile", @@ -126,19 +115,9 @@ "unknown" ] }, - "VideoContainer": { - "description": "Video container format", + "VideoCodec": { "type": "string", - "enum": [ - "video/mpeg", - "video/mp2t", - "video/mp4", - "video/webm" - ] - }, - "VideoFormat": { - "type": "string", - "description": "video format", + "description": "Video codec", "enum": [ "av1", "avc", @@ -146,8 +125,17 @@ "mpeg1", "mpeg2", "vp8", - "vp9", - "vp10" + "vp9" + ] + }, + "VideoContainer": { + "description": "Video container format", + "type": "string", + "enum": [ + "video/mpeg", + "video/mp2t", + "video/mp4", + "video/webm" ] }, "VideoMode": { diff --git a/src/sdks/core/sdk.config.json b/src/sdks/core/sdk.config.json index 66ac6f224..2cea36a50 100644 --- a/src/sdks/core/sdk.config.json +++ b/src/sdks/core/sdk.config.json @@ -26,6 +26,12 @@ "xrn:firebolt:capability:privacy:advertising" ] }, + { + "module": "Audio", + "use": [ + "xrn:firebolt:capability:audio:config" + ] + }, { "module": "Authentication", "use": [ @@ -35,12 +41,6 @@ "xrn:firebolt:capability:token:session" ] }, - { - "module": "AVSystem", - "use": [ - "xrn:firebolt:capability:avsystem:info" - ] - }, { "module": "Capabilities", "use": [ @@ -117,10 +117,9 @@ ] }, { - "module": "MediaInfo", + "module": "MediaCapabilities", "use": [ - "xrn:firebolt:capability:media-info:audio-format", - "xrn:firebolt:capability:media-info:video-format" + "xrn:firebolt:capability:media-capabilities:info" ] }, { @@ -156,6 +155,12 @@ "use": [ "xrn:firebolt:capability:storage:secure" ] + }, + { + "module": "VideoOutput", + "use": [ + "xrn:firebolt:capability:video:config" + ] } ] }