Difference between revisions of "Android Player"

Revision as of 11:45, 6 May 2021

It is possible to launch an external Android player (VLC, MX Player & Co.) via a system action (system:tvx:launch or system:tvx:launch:{APP_ID}) and to handle the results (e.g. the last video/audio position) via an application event (app:result). This API is available in Media Station X version 0.1.136 or higher for all Android and FireTV devices.

Syntax[edit]

{
    "action": "system:tvx:launch:com.example.app",
    "data": {
        "id": "request_id",
        "uri": "http://link.to.media",
        "type": "video/*",
        "component": {
            "package": "com.example.app",
            "class": "com.example.app.player"
        },
        "extra": {
            "extra_string": "Value",        
            "extra_boolean": true,
            "extra_int": 1,
            "extra_long": 1234567890123,
            "extra_double": 1.1,
            "extra_string_array": ["Value 1", "Value 2", "Value 3"],
            "extra_boolean_array": [true, false, true],
            "extra_int_array": [1, 2, 3],
            "extra_long_array": [1234567890123, 1234567890123, 1234567890123],
            "extra_double_array": [1.1, 2.2, 3.3],        
            "extra_uri": {
                "type": "uri",
                "value": "http://link.to.media"
            },
            "extra_string_alt": {
                "type": "string",
                "value": "Value"
            },        
            "extra_boolean_alt": {
                "type": "boolean",
                "value": true
            },
            "extra_byte": {
                "type": "byte",
                "value": 1
            },           
            "extra_short": {
                "type": "short",
                "value": 1
            },            
            "extra_int_alt": {
                "type": "int",
                "value": 1
            },
            "extra_long_alt": {
                "type": "long",
                "value": 1234567890123
            },
            "extra_float": {
                "type": "float",
                "value": 1.1
            },
            "extra_double_alt": {
                "type": "double",
                "value": 1.1
            },
            "extra_string_array_alt": {
                "type": "string",
                "values": ["Value 1", "Value 2", "Value 3"]
            },
            "extra_boolean_array_alt": {
                "type": "boolean",
                "values": [true, false, true]
            },
            "extra_byte_array": {
                "type": "byte",
                "values": [1, 2, 3]
            },           
            "extra_short_array": {
                "type": "short",
                "values": [1, 2, 3]
            },
            "extra_int_array_alt": {
                "type": "int",
                "values": [1, 2, 3]
            },
            "extra_long_array_alt": {
                "type": "long",
                "values": [1234567890123, 1234567890123, 1234567890123]
            },
            "extra_float_array": {
                "type": "float",
                "values": [1.1, 2.2, 3.3]
            },
            "extra_double_array_alt": {
                "type": "double",
                "values": [1.1, 2.2, 3.3]     
            },
            "extra_uri_array": {
                "type": "uri",
                "values": ["http://link.to.media1", "http://link.to.media2", "http://link.to.media3"]
            },
            "extra_string_list": {
                "type": "list:string",
                "values": ["Value 1", "Value 2", "Value 3"]
            },
            "extra_int_list": {
                "type": "list:int",
                "values": [1, 2, 3]
            },
            "extra_uri_list": {
                "type": "list:uri",
                "values": ["http://link.to.media1", "http://link.to.media2", "http://link.to.media3"]
            }
        }
    }
}

Property syntax of launch action data
Property	Type	Default Value	Mandatory	Since Version	Description
`id`	`string`	`null`	No	0.1.136	A custom request ID. This property must be set in order to trigger `app:result` events. Note: Please note that an `app:result` event is also triggered if the application could not be launched (with result code `0`).
`uri`	`string`	`null`	No	0.1.136	The data URI. Typically, this property is set to a video/audio URL that should be played.
`type`	`string`	`null`	No	0.1.136	The data mime type. Typically, this property is set to `"video/"` or `"audio/"`.
`component`	`object`	`null`	No	0.1.136	The component that should be launched. The object must conain a `package` property (of type `string`) and a `class` property (of type `string`). Typically, this property is not set, because the package is indicated in the action syntax (i.e. the `{APP_ID}` part) and the appropriate component is determined by the system.
`extra`	`object`	`null`	No	0.1.136	The extra data handled by the launched application. Note: Please note that some applications require special data types for the extra data. In such cases, you can use the `type` property to perform the required conversions.

Result[edit]

{
    "event": "app:result",
    "id": "request_id",
    "code": -1,
    "extra": {
        "extra_string": "Value",        
        "extra_boolean": true,
        "extra_int": 1,
        "extra_long": 1234567890123,
        "extra_double": 1.1,
        "extra_string_array": ["Value 1", "Value 2", "Value 3"],
        "extra_boolean_array": [true, false, true],
        "extra_int_array": [1, 2, 3],
        "extra_long_array": [1234567890123, 1234567890123, 1234567890123],
        "extra_double_array": [1.1, 2.2, 3.3],
        "extra_uri": "http://link.to.media",
        "extra_byte": 1,
        "extra_short": 1,
        "extra_float": 1.1,
        "extra_byte_array": [1, 2, 3],
        "extra_short_array": [1, 2, 3],
        "extra_float_array": [1.1, 2.2, 3.3],
        "extra_uri_array": ["http://link.to.media1", "http://link.to.media2", "http://link.to.media3"],
        "extra_string_list": ["Value 1", "Value 2", "Value 3"],
        "extra_int_list": [1, 2, 3],
        "extra_uri_list": ["http://link.to.media1", "http://link.to.media2", "http://link.to.media3"]
    }
}

Property syntax of result event data
Property	Type	Since Version	Description
`event`	`string`	0.1.136	The event type. Should be set to `"app:result"` for application result events.
`id`	`string`	0.1.136	The request ID.
`code`	`number`	0.1.136	The result code.
`extra`	`object`	0.1.136	The extra data returned by the launched application. Note: Please note that the properties of the extra data are converted to the appropriate JSON types (e.g. byte/short/int/long/float/double values are converted to numbers, URIs are converted to strings, etc.).

Example[edit]

This example uses an interaction plugin to create the content and to handle the application events. Please have a look at this implementation script: https://msx.benzac.de/interaction/js/android.js.

Screenshot[edit]

Example Screenshot (Android Player)

Code[edit]

{
    "reference": "request:interaction:init@http://msx.benzac.de/interaction/android.html",
    "pages": []
}

Demo[edit]

Launch via App: https://msx.benzac.de/?start=content:https://msx.benzac.de/info/xp/data/android_test.json
Launch via Demo Page: https://msx.benzac.de/info/?start=content:https://msx.benzac.de/info/xp/data/android_test.json

Note: This demo will only work properly on a Android or FireTV device with Media Station X 0.1.136 or higher.

@@ Line 138: / Line 138: @@
 |}
-== Result Example ==
+== Result ==
-'''Note: Please note that the properties of the extra data (which are returned by the application) are converted to the appropriate JSON types (e.g. byte/short/int/long/float/double values are converted to numbers, URIs are converted to strings, etc.).'''
 <syntaxhighlight lang="json">
 {
@@ Line 171: / Line 169: @@
 }
 </syntaxhighlight>
+{| class="wikitable sortable"
+|+ Property syntax of result event data
+|-
+! Property !! Type !! Since Version !! class="unsortable" | Description
+|-
+| <code>event</code> || <code>string</code> || data-sort-value=0|'''0.1.136''' ||
+The event type. Should be set to <code>"app:result"</code> for application result events.
+|-
+| <code>id</code> || <code>string</code> || data-sort-value=0|'''0.1.136''' ||
+The request ID.
+|-
+| <code>code</code> || <code>number</code> || data-sort-value=0|'''0.1.136''' ||
+The result code.
+|-
+| <code>extra</code> || <code>object</code> || data-sort-value=0|'''0.1.136''' ||
+The extra data returned by the launched application.
+'''Note: Please note that the properties of the extra data are converted to the appropriate JSON types (e.g. byte/short/int/long/float/double values are converted to numbers, URIs are converted to strings, etc.).'''
+|}
 == Example ==