Difference between revisions of "Android Player"

Latest revision as of 12:12, 12 June 2023

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 result (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.

Note: Please note that iOS devices also support the TVX system actions. However, the syntax for launching external applications is different. For iOS devices, the {APP_ID} part must be replaced with a URL (e.g. system:tvx:launch:vlc://http://link.to.media), for Android devices, it must be replaced with a package name (e.g. system:tvx:launch:org.videolan.vlc). Additionally, iOS devices do not support extra data, but it is possible to check if the application could be launched.

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 application launch action data
Property	Type	Default Value	Mandatory	Since Version	Description
`id`	`string`	`null`	No	0.1.136	A custom request ID. Note: This property must be set in order to trigger application result events. For iOS devices, the result event is directly triggered. For Android devices, the result event is triggered after the launched application is closed (or the application could not be launched).
`uri`	`string`	`null`	No	0.1.136	The data URI. Typically, this property is set to a video/audio URL that should be played. Note: This property is not supported by iOS devices.
`type`	`string`	`null`	No	0.1.136	The data mime type. Typically, this property is set to `"video/"` or `"audio/"`. Note: This property is not supported by iOS devices.
`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 name is indicated in the action syntax (i.e. the `{APP_ID}` part) and the appropriate component is determined by the system. Note: This property is not supported by iOS devices.
`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 (e.g. `android.net.Uri` objects) for the extra data. In such cases, you can use the `type` property to perform the required conversions (please see the syntax examples). This property is not supported by iOS devices.

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 application result event
Property	Type	Since Version	Description
`event`	`string`	0.1.136	The event type. For application result events, this property is set to `"app:result"`.
`id`	`string`	0.1.136	The custom request ID.
`code`	`number`	0.1.136	The result code. `-3`: Internal error occurred. `-2`: Application could not be launched. `-1`: Operation succeeded (Android-compliant). `0`: Operation canceled (Android-compliant). `1`: All codes of `1` or higher are application-specific (Android-compliant). Note: For iOS devices, only negative codes are possible (i.e. `-1`, `-2`, and `-3`).
`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 `number` values, `android.net.Uri` objects are converted to `string` values, etc.). This property is always set to `null` for iOS devices.

Example[edit]

This example uses an interaction plugin to create the content and to handle the application result 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 an Android or FireTV device with Media Station X 0.1.136 or higher.

@@ Line 1: / Line 1: @@
-It is possible to launch an external Android player (VLC, MX Player & Co.) via a system action (<code>system:tvx:launch</code> or <code>system:tvx:launch:{APP_ID}</code>) and to handle the results (e.g. the last video/audio position) via an application event (<code>app:result</code>). This API is available in Media Station X version '''0.1.136''' or higher for all Android and FireTV devices.
+It is possible to launch an external Android player (VLC, MX Player & Co.) via a system action (<code>system:tvx:launch</code> or <code>system:tvx:launch:{APP_ID}</code>) and to handle the result (e.g. the last video/audio position) via an application event (<code>app:result</code>). This API is available in Media Station X version '''0.1.136''' or higher for all Android and FireTV devices.
+'''Note: Please note that iOS devices also support the TVX system actions. However, the syntax for launching external applications is different. For iOS devices, the <code>{APP_ID}</code> part must be replaced with a URL (e.g. <code>system:tvx:launch:vlc://http://link.to.media</code>), for Android devices, it must be replaced with a package name (e.g. <code>system:tvx:launch:org.videolan.vlc</code>). Additionally, iOS devices do not support extra data, but it is possible to check if the application could be launched.'''
 == Syntax ==
@@ Line 114: / Line 116: @@
 {| class="wikitable sortable"
-|+ Property syntax of launch action data
+|+ Property syntax of application launch action data
 |-
 ! Property !! Type !! Default Value !! Mandatory !! Since Version !! class="unsortable" | Description
 |-
 | <code>id</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|'''0.1.136''' ||
-A custom request ID. This property must be set in order to trigger <code>app:result</code> events.
+A custom request ID.
-'''Note: Please note that an <code>app:result</code> event is also triggered if the application could not be launched (with result code <code>0</code>).'''
+'''Note: This property must be set in order to trigger application result events. For iOS devices, the result event is directly triggered. For Android devices, the result event is triggered after the launched application is closed (or the application could not be launched).'''
 |-
 | <code>uri</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|'''0.1.136''' ||
 The data URI. Typically, this property is set to a video/audio URL that should be played.
+'''Note: This property is not supported by iOS devices.'''
 |-
 | <code>type</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|'''0.1.136''' ||
 The data mime type. Typically, this property is set to <code>"video/*"</code> or <code>"audio/*"</code>.
+'''Note: This property is not supported by iOS devices.'''
 |-
 | <code>component</code> || <code>object</code> || <code>null</code> || No || data-sort-value=0|'''0.1.136''' ||
-The component that should be launched. The object must conain a <code>package</code> property (of type <code>string</code>) and a <code>class</code> property (of type <code>string</code>). Typically, this property is not set, because the package is indicated in the action syntax (i.e. the <code>{APP_ID}</code> part) and the appropriate component is determined by the system.
+The component that should be launched. The object must conain a <code>package</code> property (of type <code>string</code>) and a <code>class</code> property (of type <code>string</code>). Typically, this property is not set, because the package name is indicated in the action syntax (i.e. the <code>{APP_ID}</code> part) and the appropriate component is determined by the system.
+'''Note: This property is not supported by iOS devices.'''
 |-
 | <code>extra</code> || <code>object</code> || <code>null</code> || No || data-sort-value=0|'''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 <code>type</code> property to perform the required conversions.'''
+'''Note: Please note that some applications require special data types (e.g. <code>android.net.Uri</code> objects) for the extra data. In such cases, you can use the <code>type</code> property to perform the required conversions (please see the syntax examples). This property is not supported by iOS devices. '''
 |}
@@ Line 171: / Line 179: @@
 {| class="wikitable sortable"
-|+ Property syntax of result event data
+|+ Property syntax of application result event
 |-
 ! Property !! Type !! Since Version !! class="unsortable" | Description
 |-
 | <code>event</code> || <code>string</code> || data-sort-value=0|'''0.1.136''' ||
-The event type. For application result events, this is set to <code>"app:result"</code>.
+The event type. For application result events, this property is set to <code>"app:result"</code>.
 |-
 | <code>id</code> || <code>string</code> || data-sort-value=0|'''0.1.136''' ||
-The request ID.
+The custom request ID.
 |-
 | <code>code</code> || <code>number</code> || data-sort-value=0|'''0.1.136''' ||
 The result code.
-* <code>-2</code>: Internal Error (MSX).
+* <code>-3</code>: Internal error occurred.
-* <code>-1</code>: OK (System).
+* <code>-2</code>: Application could not be launched.
-* <code>0</code>: Canceled (System).
+* <code>-1</code>: Operation succeeded (Android-compliant).
-* <code>1</code>: All codes of <code>1</code> or higher are application specific.
+* <code>0</code>: Operation canceled (Android-compliant).
+* <code>1</code>: All codes of <code>1</code> or higher are application-specific (Android-compliant).
+'''Note: For iOS devices, only negative codes are possible (i.e. <code>-1</code>, <code>-2</code>, and <code>-3</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.).'''
+'''Note: Please note that the properties of the extra data are converted to the appropriate JSON types (e.g. <code>byte</code>/<code>short</code>/<code>int</code>/<code>long</code>/<code>float</code>/<code>double</code> values are converted to <code>number</code> values, <code>android.net.Uri</code> objects are converted to <code>string</code> values, etc.). This property is always set to <code>null</code> for iOS devices.'''
 |}
 == Example ==
-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.
+This example uses an interaction plugin to create the content and to handle the application result events. Please have a look at this implementation script: https://msx.benzac.de/interaction/js/android.js.
 === Screenshot ===
@@ Line 213: / Line 224: @@
 * 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.'''
+'''Note: This demo will only work properly on an Android or FireTV device with Media Station X 0.1.136 or higher.'''
+== See also ==
+* [[Android Plugin]]

Difference between revisions of "Android Player"

Latest revision as of 12:12, 12 June 2023

Contents

Syntax[edit]

Result[edit]

Example[edit]

Screenshot[edit]

Code[edit]

Demo[edit]

See also[edit]

Navigation menu

Search