From c05828b5cf564a431d828d24c1b0a2672f378778 Mon Sep 17 00:00:00 2001 From: Joseph Ruzzi Date: Tue, 21 Sep 2021 14:15:19 -0400 Subject: [PATCH] documented DeviceSettings platform implementation (cherry picked from commit 56ef2928c2d268be6ef8a70e5f8270c1c37352a4) --- PlayerInfo/PlayerInfo.json | 235 ++++++++++++------- PlayerInfo/doc/PlayerInfoPlugin.md | 360 +++++++++++++++++++++++++++-- 2 files changed, 499 insertions(+), 96 deletions(-) diff --git a/PlayerInfo/PlayerInfo.json b/PlayerInfo/PlayerInfo.json index dc340d3f86..d35ef6d757 100644 --- a/PlayerInfo/PlayerInfo.json +++ b/PlayerInfo/PlayerInfo.json @@ -7,94 +7,173 @@ "description": "The `PlayerInfo` plugin helps to get system supported audio and video codecs" }, "definitions": { - "audiocodecs": { - "description": "Audio Codec supported by the platform", - "type": "string", - "enum": [ - "Undefined", - "AAC", - "AC3", - "AC3Plus", - "DTS", - "MPEG1", - "MPEG2", - "MPEG3", - "MPEG4", - "OPUS", - "VorbisOGG", - "WAV" - ], - "enumvalues": [ - 0, - 1, - 2, - 3, - 4, - 5, - 6, - 7, - 8, - 9, - 10, - 11 - ], - "example": "AudioAAC" - }, - "videocodecs": { - "description": "Video Codec supported by the platform", - "type": "string", - "enum": [ - "Undefined", - "H263", - "H264", - "H265", - "H26510", - "MPEG", - "VP8", - "VP9", - "VP10" - ], - "enumvalues": [ - 0, - 1, - 2, - 3, - 4, - 5, - 6, - 7, - 8 - ], - "example": "VideoH264" - }, - "codecs": { - "type": "object", + "result": { + "type":"object", "properties": { - "audio": { - "type": "array", - "items": { - "$ref": "#/definitions/audiocodecs" - } - }, - "video": { - "type": "array", - "items": { - "$ref": "#/definitions/videocodecs" - } + "success": { + "$ref": "#/definitions/success" } }, "required": [ - "audio", - "video" + "success" ] + }, + "success": { + "summary": "Whether the request succeeded", + "type": "boolean", + "example": "true" + } + }, + "methods": { + "audiocodecs": { + "summary": "Returns the audio codec supported by the platform", + "result": { + "type":"array", + "items": { + "type": "string", + "enum": [ + "AudioUndefined", + "AudioAac", + "AudioAc3", + "AudioAc3Plus", + "AudioDts", + "AudioMpeg1", + "AudioMpeg2", + "AudioMpeg3", + "AudioMpeg4", + "AudioOpus", + "AudioVorbisOgg", + "AudioWav" + ], + "example": "AudioUndefined" + } + } + }, + "videocodecs": { + "summary": "Returns the video codec supported by the platform", + "result": { + "type":"array", + "items": { + "type": "string", + "enum": [ + "VideoUndefined", + "VideoH263", + "VideoH264", + "VideoH265", + "VideoH26510", + "VideoMpeg", + "VideoVp8", + "VideoVp9", + "VideoVp10" + ], + "example": "VideoUndefined" + } + } } }, "properties": { - "playerinfo": { - "summary": "Player general information", + "resolution": { + "summary": "Current video playback resolution", + "readonly": true, + "params": { + "type": "string", + "enum": [ + "ResolutionUnknown", + "Resolution480I", + "Resolution480P", + "Resolution576I", + "Resolution576P", + "Resolution720P", + "Resolution1080I", + "Resolution1080P", + "Resolution2160P30", + "Resolution2160P60" + ], + "example": "ResolutionUnknown" + } + }, + "isaudioequivalenceenabled": { + "summary": "Check for Loudness Equivalence in the platform", "readonly": true, "params": { - "$ref": "#/definitions/codecs" + "type": "boolean", + "example": false + } + }, + "dolby_atmosmetadata":{ + "summary": "Atmos capabilities of Sink", + "readonly": true, + "params": { + "type": "boolean", + "example": false + } + }, + "dolby_soundmode":{ + "summary": "Current sound mode", + "readonly": true, + "params": { + "type": "string", + "enum": [ + "Unknown", + "Mono", + "Stereo", + "Surround", + "Passthru" + ], + "example": "Unknown" + } + }, + "dolby_enableatmosoutput":{ + "summary": "Audio output enablement for Atmos", + "writeonly": true, + "params": { + "type": "boolean", + "example": false + } + }, + "dolby_mode":{ + "summary": "Dolby mode", + "params": { + "type": "string", + "enum": [ + "DigitalPcm", + "DigitalPlus", + "DigitalAc3", + "Auto", + "Ms12" + ], + "example": "DigitalPcm" + } + } + }, + "events": { + "dolby_audiomodechanged": { + "summary": "Triggered after the audio sound mode changes", + "params": { + "type": "object", + "properties": { + "mode":{ + "summary": "The sound mode", + "type": "string", + "enum": [ + "Unknown", + "Mono", + "Stereo", + "Surround", + "Passthru" + ], + "example": "Unknown" + }, + "enable":{ + "summary": "", + "type": "boolean", + "example": true + } + }, + "required": [ + "mode", + "enable" + ] } } } diff --git a/PlayerInfo/doc/PlayerInfoPlugin.md b/PlayerInfo/doc/PlayerInfoPlugin.md index 4d083c9109..2bad0b5cfd 100644 --- a/PlayerInfo/doc/PlayerInfoPlugin.md +++ b/PlayerInfo/doc/PlayerInfoPlugin.md @@ -13,7 +13,9 @@ PlayerInfo plugin for Thunder framework. - [Introduction](#head.Introduction) - [Description](#head.Description) - [Configuration](#head.Configuration) +- [Methods](#head.Methods) - [Properties](#head.Properties) +- [Notifications](#head.Notifications) # Introduction @@ -21,7 +23,7 @@ PlayerInfo plugin for Thunder framework. ## Scope -This document describes purpose and functionality of the PlayerInfo plugin. It includes detailed specification about its configuration and properties provided. +This document describes purpose and functionality of the PlayerInfo plugin. It includes detailed specification about its configuration, methods and properties provided, as well as notifications sent. ## Case Sensitivity @@ -75,6 +77,99 @@ The table below lists configuration options of the plugin. | locator | string | Library name: *libWPEPlayerInfo.so* | | autostart | boolean | Determines if the plugin shall be started automatically along with the framework | + +# Methods + +The following methods are provided by the PlayerInfo plugin: + +PlayerInfo interface methods: + +| Method | Description | +| :-------- | :-------- | +| [audiocodecs](#method.audiocodecs) | Returns the audio codec supported by the platform | +| [videocodecs](#method.videocodecs) | Returns the video codec supported by the platform | + + + +## *audiocodecs method* + +Returns the audio codec supported by the platform. + +### Parameters + +This method takes no parameters. + +### Result + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| result | array | | +| result[#] | string | (must be one of the following: *AudioUndefined*, *AudioAac*, *AudioAc3*, *AudioAc3Plus*, *AudioDts*, *AudioMpeg1*, *AudioMpeg2*, *AudioMpeg3*, *AudioMpeg4*, *AudioOpus*, *AudioVorbisOgg*, *AudioWav*) | + +### Example + +#### Request + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "method": "PlayerInfo.1.audiocodecs" +} +``` + +#### Response + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "result": [ + "AudioUndefined" + ] +} +``` + + +## *videocodecs method* + +Returns the video codec supported by the platform. + +### Parameters + +This method takes no parameters. + +### Result + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| result | array | | +| result[#] | string | (must be one of the following: *VideoUndefined*, *VideoH263*, *VideoH264*, *VideoH265*, *VideoH26510*, *VideoMpeg*, *VideoVp8*, *VideoVp9*, *VideoVp10*) | + +### Example + +#### Request + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "method": "PlayerInfo.1.videocodecs" +} +``` + +#### Response + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "result": [ + "VideoUndefined" + ] +} +``` + # Properties @@ -84,13 +179,53 @@ PlayerInfo interface properties: | Property | Description | | :-------- | :-------- | -| [playerinfo](#property.playerinfo) RO | Player general information | +| [resolution](#property.resolution) RO | Current video playback resolution | +| [isaudioequivalenceenabled](#property.isaudioequivalenceenabled) RO | Check for Loudness Equivalence in the platform | +| [dolby atmosmetadata](#property.dolby_atmosmetadata) RO | Atmos capabilities of Sink | +| [dolby soundmode](#property.dolby_soundmode) RO | Current sound mode | +| [dolby enableatmosoutput](#property.dolby_enableatmosoutput) WO | Audio output enablement for Atmos | +| [dolby mode](#property.dolby_mode) | Dolby mode | + + +## *resolution property* - -## *playerinfo property* +Provides access to the current video playback resolution. -Provides access to the player general information. +> This property is **read-only**. + +### Value + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| (property) | string | Current video playback resolution (must be one of the following: *ResolutionUnknown*, *Resolution480I*, *Resolution480P*, *Resolution576I*, *Resolution576P*, *Resolution720P*, *Resolution1080I*, *Resolution1080P*, *Resolution2160P30*, *Resolution2160P60*) | + +### Example + +#### Get Request + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "method": "PlayerInfo.1.resolution" +} +``` + +#### Get Response + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "result": "ResolutionUnknown" +} +``` + + +## *isaudioequivalenceenabled property* + +Provides access to the check for Loudness Equivalence in the platform. > This property is **read-only**. @@ -98,11 +233,7 @@ Provides access to the player general information. | Name | Type | Description | | :-------- | :-------- | :-------- | -| (property) | object | Player general information | -| (property).audio | array | | -| (property).audio[#] | string | Audio Codec supported by the platform (must be one of the following: *Undefined*, *AAC*, *AC3*, *AC3Plus*, *DTS*, *MPEG1*, *MPEG2*, *MPEG3*, *MPEG4*, *OPUS*, *VorbisOGG*, *WAV*) | -| (property).video | array | | -| (property).video[#] | string | Video Codec supported by the platform (must be one of the following: *Undefined*, *H263*, *H264*, *H265*, *H26510*, *MPEG*, *VP8*, *VP9*, *VP10*) | +| (property) | boolean | Check for Loudness Equivalence in the platform | ### Example @@ -112,7 +243,7 @@ Provides access to the player general information. { "jsonrpc": "2.0", "id": 1234567890, - "method": "PlayerInfo.1.playerinfo" + "method": "PlayerInfo.1.isaudioequivalenceenabled" } ``` @@ -122,13 +253,206 @@ Provides access to the player general information. { "jsonrpc": "2.0", "id": 1234567890, - "result": { - "audio": [ - "AudioAAC" - ], - "video": [ - "VideoH264" - ] + "result": false +} +``` + + +## *dolby_atmosmetadata property* + +Provides access to the atmos capabilities of Sink. + +> This property is **read-only**. + +### Value + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| (property) | boolean | Atmos capabilities of Sink | + +### Example + +#### Get Request + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "method": "PlayerInfo.1.dolby_atmosmetadata" +} +``` + +#### Get Response + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "result": false +} +``` + + +## *dolby_soundmode property* + +Provides access to the current sound mode. + +> This property is **read-only**. + +### Value + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| (property) | string | Current sound mode (must be one of the following: *Unknown*, *Mono*, *Stereo*, *Surround*, *Passthru*) | + +### Example + +#### Get Request + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "method": "PlayerInfo.1.dolby_soundmode" +} +``` + +#### Get Response + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "result": "Unknown" +} +``` + + +## *dolby_enableatmosoutput property* + +Provides access to the audio output enablement for Atmos. + +> This property is **write-only**. + +### Value + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| (property) | boolean | Audio output enablement for Atmos | + +### Example + +#### Set Request + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "method": "PlayerInfo.1.dolby_enableatmosoutput", + "params": false +} +``` + +#### Set Response + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "result": "null" +} +``` + + +## *dolby_mode property* + +Provides access to the dolby mode. + +### Value + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| (property) | string | Dolby mode (must be one of the following: *DigitalPcm*, *DigitalPlus*, *DigitalAc3*, *Auto*, *Ms12*) | + +### Example + +#### Get Request + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "method": "PlayerInfo.1.dolby_mode" +} +``` + +#### Get Response + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "result": "DigitalPcm" +} +``` + +#### Set Request + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "method": "PlayerInfo.1.dolby_mode", + "params": "DigitalPcm" +} +``` + +#### Set Response + +```json +{ + "jsonrpc": "2.0", + "id": 1234567890, + "result": "null" +} +``` + + +# Notifications + +Notifications are autonomous events, triggered by the internals of the implementation, and broadcasted via JSON-RPC to all registered observers. Refer to [[Thunder](#ref.Thunder)] for information on how to register for a notification. + +The following events are provided by the PlayerInfo plugin: + +PlayerInfo interface events: + +| Event | Description | +| :-------- | :-------- | +| [dolby audiomodechanged](#event.dolby_audiomodechanged) | Triggered after the audio sound mode changes | + + + +## *dolby_audiomodechanged event* + +Triggered after the audio sound mode changes. + +### Parameters + +| Name | Type | Description | +| :-------- | :-------- | :-------- | +| params | object | | +| params.mode | string | The sound mode (must be one of the following: *Unknown*, *Mono*, *Stereo*, *Surround*, *Passthru*) | +| params.enable | boolean | | + +### Example + +```json +{ + "jsonrpc": "2.0", + "method": "client.events.1.dolby_audiomodechanged", + "params": { + "mode": "Unknown", + "enable": true } } ```