From eb9449e80d870637d4507596bacbfe0138a80f18 Mon Sep 17 00:00:00 2001 From: Joe Martin Date: Thu, 25 Jul 2024 12:58:24 -0400 Subject: [PATCH] fix: Fix docs; add errors for when display is not connected --- .../media/media-capabilities.md | 81 ++++++----- src/openrpc/display.json | 126 ++++++++---------- src/openrpc/media_capabilities.json | 7 +- src/openrpc/video_output.json | 10 ++ src/schemas/media.json | 6 +- 5 files changed, 119 insertions(+), 111 deletions(-) diff --git a/requirements/specifications/media/media-capabilities.md b/requirements/specifications/media/media-capabilities.md index ebab71f5d..e92e3d53d 100644 --- a/requirements/specifications/media/media-capabilities.md +++ b/requirements/specifications/media/media-capabilities.md @@ -1,6 +1,6 @@ # Media Capabilities Requirements -Document Status: Candidate Specification +Document Status: Proposed Specification See [Firebolt Requirements Governance](../../governance.md) for more info. @@ -200,18 +200,21 @@ The Firebolt `Media` module **MUST** have an `HDRProfile` enumeration: The Firebolt `Media` 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 +| Value | Description | +| ------------- | ----------------------------------------------------- | +| `BT2020cYCC` | Rec. ITU-R BT.2020 Y’cC’BCC’RC | +| `BT2020RGB` | Rec. ITU-R BT.2020 R’G’B’ | +| `BT2020YCC` | Rec. ITU-R BT.2020 Y’C’BC’R | +| `defaultRGB` | Default chromaticity information of the display | +| `ICtCp` | Rec. ITU-R BT.2100 | +| `opRGB` | IEC 61966-2-5; previously named `AdobeRGB` | +| `opYCC601` | IEC 61966-2-5 Annex A; previously named `AdobeYCC601` | +| `sRGB` | IEC 61966-2-1 | +| `ST2113RGB24` | SMPTE ST 2113 R’G’B’; previously named `DCI-P3` | +| `sYCC601` | IEC 61966-2-1/Amendment 1 | +| `xvYCC601` | Standard Definition; based on IEC 61966-2-4 | +| `xvYCC709` | High Definition; based on IEC 61966-2-4 | +| `unknown` | Reserved for edge cases (no display, etc.) | ### 3.7. Color Depth @@ -261,8 +264,6 @@ Apps need to know what type of media the device and its connected peripherals ar 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. 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. @@ -287,7 +288,15 @@ MediaCapabilities.videoModes() ### 4.3. 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. +The `MediaCapabilities` module **MUST** have an `audioCodecs` method that returns an array of `Media.AudioCodec` values describing the audio codecs supported by the current audio decoding device. + +This method's response is dictated by the currently selected audio output mode and the device responsible for decoding the audio stream. + +If the device is currently in `passthrough` audio mode, audio codecs supported by the audio sink **MUST** be returned. + +If the device is not in `passthrough` audio mode, audio codecs supported by the device **MUST** be returned. + +This method **MUST** have a corresponding `onAudioCodecsChanged` event to notify listeners when the available audio codecs have changed. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. @@ -305,7 +314,7 @@ MediaCapabilities.audioCodecs() ### 4.4. 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. +The `MediaCapabilities` module **MUST** have an `videoCodecs` method that returns an array of `Media.VideoCodec` values describing the video codecs supported by the device. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:media-capabilities:info` capability. @@ -366,7 +375,7 @@ These will be surfaced in the `Display` module. 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. +If no display is present, a JSON-RPC error response of `{"code": -40400, "message": "No display connected"}` **MUST** be returned. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. @@ -379,7 +388,7 @@ Display.hdrProfiles() 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. +If no display is present, a JSON-RPC error response of `{"code": -40400, "message": "No display connected"}` **MUST** be returned. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. @@ -392,7 +401,7 @@ Display.colorDepth() 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. +If no display is present, a JSON-RPC error response of `{"code": -40400, "message": "No display connected"}` **MUST** be returned. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. @@ -405,7 +414,7 @@ Display.size() 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. +If no display is present, a JSON-RPC error response of `{"code": -40400, "message": "No display connected"}` **MUST** be returned. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. @@ -418,7 +427,7 @@ Display.nativeResolution() 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. +If no display is present, a JSON-RPC error response of `{"code": -40400, "message": "No display connected"}` **MUST** be returned. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. @@ -431,7 +440,7 @@ Display.nativeResolutionName() 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. +If no display is present, a JSON-RPC error response of `{"code": -40400, "message": "No display connected"}` **MUST** be returned. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. @@ -444,7 +453,7 @@ Display.nativeRefreshRate() 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. +If no display is present, a JSON-RPC error response of `{"code": -40400, "message": "No display connected"}` **MUST** be returned. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. @@ -457,7 +466,7 @@ Display.colorimetry() 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. +If no display is present, a JSON-RPC error response of `{"code": -40400, "message": "No display connected"}` **MUST** be returned. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:display:info` capability. @@ -586,27 +595,31 @@ The `VideoOutput` module **MUST** have a `currentSettings` method that returns a This method **MUST** return the following properties: -| Property | Type | -| ------------- | ------------------- | -| `colorDepth` | `Media.ColorDepth` | -| `colorimetry` | `Media.Colorimetry` | -| `colorSpace` | `Media.ColorSpace` | -| `hdrProfile` | `Media.HDRProfile` | -| `mode` | `Media.VideoMode` | -| `resolution` | `Types.Dimensions` | +| Property | Type | +| ------------------- | ------------------------------- | +| `colorDepth` | `Media.ColorDepth` | +| `colorimetry` | `Media.Colorimetry` | +| `colorSpace` | `Media.ColorSpace` | +| `frameRate` | `number` | +| `hdrProfile` | `Media.HDRProfile` | +| `mode` | `Media.VideoMode` | +| `quantizationRange` | `VideoOutput.QuantizationRange` | +| `resolution` | `Types.Dimensions` | Access to this method **MUST** be governed by the `xrn:firebolt:capability:video-output:info` 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() +VideoOutput.currentSettings() //> { //> "colorDepth": "10", //> "colorimetry": "BT2020YCC", //> "colorSpace": "YCbCr422", +//> "frameRate": 60, //> "hdrProfile": "hdr10plus", //> "mode": "1080p60", +//> "quantizationRange": "limited", //> "resolution": { "width": 1920, "height": 1080 } //> } ``` diff --git a/src/openrpc/display.json b/src/openrpc/display.json index 3d2da4969..e11532318 100644 --- a/src/openrpc/display.json +++ b/src/openrpc/display.json @@ -25,6 +25,12 @@ "type": "number" } }, + "errors": [ + { + "code": -51000, + "message": "No display connected" + } + ], "examples": [ { "name": "Default Example", @@ -33,14 +39,6 @@ "name": "Default Result", "value": 10 } - }, - { - "name": "Example with no display", - "params": [], - "result": { - "name": "Default Result", - "value": 0 - } } ] }, @@ -66,6 +64,12 @@ } } }, + "errors": [ + { + "code": -51000, + "message": "No display connected" + } + ], "examples": [ { "name": "Default Example", @@ -77,14 +81,6 @@ "BT2020YCC" ] } - }, - { - "name": "Example with no display", - "params": [], - "result": { - "name": "Default Result", - "value": [] - } } ] }, @@ -110,6 +106,12 @@ } } }, + "errors": [ + { + "code": -51000, + "message": "No display connected" + } + ], "examples": [ { "name": "Default Example", @@ -123,14 +125,6 @@ "hlg" ] } - }, - { - "name": "Example with no display", - "params": [], - "result": { - "name": "Default Result", - "value": [] - } } ] }, @@ -153,6 +147,12 @@ "type": "number" } }, + "errors": [ + { + "code": -51000, + "message": "No display connected" + } + ], "examples": [ { "name": "Default Example", @@ -161,14 +161,6 @@ "name": "Default Result", "value": 60 } - }, - { - "name": "Example with no display", - "params": [], - "result": { - "name": "Default Result", - "value": 0 - } } ] }, @@ -185,12 +177,18 @@ ], "params": [], "result": { - "name": "resolution", - "summary": "The resolution of the display device.", + "name": "nativeResolution", + "summary": "The native resolution of the display device.", "schema": { "$ref": "https://meta.comcast.com/firebolt/types#/definitions/Dimensions" } }, + "errors": [ + { + "code": -51000, + "message": "No display connected" + } + ], "examples": [ { "name": "Default Example", @@ -202,17 +200,6 @@ "height": 1080 } } - }, - { - "name": "Example with no display", - "params": [], - "result": { - "name": "Default Result", - "value": { - "width": 0, - "height": 0 - } - } } ] }, @@ -229,12 +216,18 @@ ], "params": [], "result": { - "name": "resolutionName", - "summary": "The resoltuion name of the display device.", + "name": "nativeResolutionName", + "summary": "The native resolution name of the display device.", "schema": { "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/ResolutionName" } }, + "errors": [ + { + "code": -51000, + "message": "No display connected" + } + ], "examples": [ { "name": "Default Example", @@ -243,14 +236,6 @@ "name": "Default Result", "value": "uhd" } - }, - { - "name": "Example with no display", - "params": [], - "result": { - "name": "Default Result", - "value": "unknown" - } } ] }, @@ -273,6 +258,12 @@ "$ref": "https://meta.comcast.com/firebolt/types#/definitions/Dimensions" } }, + "errors": [ + { + "code": -51000, + "message": "No display connected" + } + ], "examples": [ { "name": "Default Example", @@ -284,17 +275,6 @@ "height": 91 } } - }, - { - "name": "Example with no display", - "params": [], - "result": { - "name": "Default Result", - "value": { - "width": 0, - "height": 0 - } - } } ] }, @@ -320,6 +300,12 @@ } } }, + "errors": [ + { + "code": -51000, + "message": "No display connected" + } + ], "examples": [ { "name": "Default Example", @@ -337,14 +323,6 @@ "1080p60" ] } - }, - { - "name": "Example with no display", - "params": [], - "result": { - "name": "Default Result", - "value": [] - } } ] } diff --git a/src/openrpc/media_capabilities.json b/src/openrpc/media_capabilities.json index 72cca1447..3f0346596 100644 --- a/src/openrpc/media_capabilities.json +++ b/src/openrpc/media_capabilities.json @@ -8,8 +8,11 @@ "methods": [ { "name": "audioCodecs", - "summary": "The audio codecs commonly supported by the device and all its connected audio peripherals.", + "summary": "The audio codecs supported by the audio output sink. The response is based on the current audio output mode. If the output mode is passthrough, the codecs of the audio sink (such as the soundbar or AV receiver) are returned. Otherwise, the supported audio codecs of the device are returned.", "tags": [ + { + "name": "property:readonly" + }, { "name": "capabilities", "x-uses": [ @@ -48,7 +51,7 @@ }, { "name": "videoCodecs", - "summary": "The video codecs commonly supported by the device and all of its connected video peripherals.", + "summary": "The video codecs supported by the device.", "tags": [ { "name": "capabilities", diff --git a/src/openrpc/video_output.json b/src/openrpc/video_output.json index 4b4f83e9c..57ad6f4e5 100644 --- a/src/openrpc/video_output.json +++ b/src/openrpc/video_output.json @@ -132,12 +132,18 @@ "colorSpace": { "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/ColorSpace" }, + "frameRate": { + "type": "number" + }, "hdrProfile": { "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/HDRProfile" }, "mode": { "$ref": "https://meta.comcast.com/firebolt/schemas/media#/definitions/VideoMode" }, + "quantizationRange": { + "$ref": "#/components/schemas/QuantizationRange" + }, "resolution": { "$ref": "https://meta.comcast.com/firebolt/types#/definitions/Dimensions" } @@ -146,8 +152,10 @@ "colorDepth", "colorimetry", "colorSpace", + "frameRate", "hdrProfile", "mode", + "quantizationRange", "resolution" ] } @@ -162,8 +170,10 @@ "colorDepth": "10", "colorimetry": "BT2020YCC", "colorSpace": "YCbCr422", + "frameRate": 60, "hdrProfile": "hdr10plus", "mode": "1080p60", + "quantizationRange": "limited", "resolution": { "width": 1920, "height": 1080 diff --git a/src/schemas/media.json b/src/schemas/media.json index 7464894ee..fd2beb977 100644 --- a/src/schemas/media.json +++ b/src/schemas/media.json @@ -9,6 +9,7 @@ "aac", "ac3", "ac4", + "dts-x", "eac3", "mpeg3", "opus", @@ -48,9 +49,12 @@ "BT2020cYCC", "BT2020RGB", "BT2020YCC", - "DCI-P3", + "defaultRGB", + "ICtCp", "opRGB", "opYCC601", + "sRGB", + "ST2113RGB24", "sYCC601", "xvYCC601", "xvYCC709",