Media Player Interface (mediaplayer)

The Media Player (mediaplayer) interface is implemented by devices that provide media playback. This can include hardware-based media players such as 7thSense and Pixera or software-based devices such as MadMapper, VLC Player, or a custom application you develop.

Controls

MediaPlayerControl

The MediaPlayerControl enum provides constants for gettable, settable media player properties and states.

Constant	Value	Type	Range	Description
DURATION	duration	int	> 0	(Get) The duration of the currently selected media item in seconds
FULLSCREEN	fullscreen	bool	-	(Get/Set) The fullscreen state of the media player
LOOP	loop	bool	-	(Get/Set) The looping behavior for the selected playlist
PLAYING	playing	bool	-	(Get) Is the media player currently playing
POSITION	position	float	0.0 - 1.0	(Get/Set) Relative playhead position as a percentage of duration
PROGRAM	program	str	–	(Get/Set) The playlist nanoid to play/load (may not be implemented by all media players.)
SELECTED	selected	str	-	(Get/Set) The currently playing media item in the playlist, ID/handle will vary by media player
VOLUME	volume	float	0.0 - 1.0	(Get/Set) media player volume, contrained to 100%, typically used in conjunction with mute/unmute. Note When audio is piped through a DSP, it is recommended that volume be set in the DSP and not the media player.
VERSION	version	str	-	(Get) The media player version. Returns version as a ControlState for consistency, but version should be implemented through the version method on the SystemInterface.

Example object:

class MediaPlayerControl(str, Enum):
    DURATION = 'duration'
    FULLSCREEN = 'fullscreen'
    LOOP = 'loop'
    PLAYING = 'playing'
    POSITION = 'position'
    SELECTED = 'selected'
    VOLUME = 'volume'
    VERSION = 'version'

Actions

load

Load a new piece of media for playback. The support and behavior of this action will depend on the media player (not all players support hot loading). In some instances this may be implemented as a playlist picker by filename.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "load",
    "data": {
        "type": "ValueSet",
        "value": "/path/to/media.mp4"
    },
    "mid": "123abc"
}

Returns: ControlStates for each MediaPlayerControl

mute

Mute the audio from the media player. Many media players do not support a mute toggle, in this instance, mute will typically set the playback volume to 0.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "mute",
    "mid": "123abc"
}

Returns: ControlState for volume

next

Advance to the next item in the playlist.

If there is only one item in the playist, this will typically restart the item - but this behavior is media player dependent.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "next",
    "mid": "123abc"
}

Returns: ControlStates for each MediaPlayerControl

pause

Pause the current media or playlist without seeking back to the beginning:

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "pause",
    "mid": "123abc"
}

Returns: ControlStates for each MediaPlayerControl

play

Start, or resume playing the currently loaded media item or playlist.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "play",
    "mid": "123abc"
}

Returns: ControlStates for each MediaPlayerControl

previous

Return to the previous media item in the playlist.

If there is only one item in the playist, this will typically restart the item - but this behavior is media player dependent.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "previous",
    "mid": "123abc"
}

Returns: ControlStates for each MediaPlayerControl

resume

Resume playback from the current position.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "resume",
    "mid": "123abc"
}

Returns: ControlStates for each MediaPlayerControl

stop

Stop the current media or playlist and reset the playhead to the beginning. Depending on the media player behavior, stop may unload the window, or the playlist.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "stop",
    "mid": "123abc"
}

Returns: ControlStates for each MediaPlayerControl

unmute

Unmute the audio from the media player. Many media players do not support a mute toggle, in this instance, mute will typically set the playback volume to a normalized value of 1.0.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "unmute",
    "mid": "123abc"
}

Returns: ControlStates for each MediaPlayerControl

---

Getters

controls

Get the current value of all controls in the system.

controls is also implemented by ControlInterface.controls and performs the same function.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "status",
    "mid": "123abc"
}

Returns: ControlStates for each MediaPlayerControl

duration

Get the duration of the current playlist item.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "duration",
    "mid": "123abc"
}

Returns: ControlState for duration

playing

Current playback status, is the media playing?

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "playing",
    "mid": "123abc"
}

Returns: ControlState for playing

---

Getters/Setters

The following control can get and set values. To set a value, provide data.value, to get a value omit data from the ControlRequest.

fullscreen

Get/Set the fullscreen status/value.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "fullscreen",
    "data": {
        "type": "ValueSetBoolean",
        "value": true | false
    },
    "mid": "123abc"
}

Returns: ControlState for fullscreen

loop

Get/Set the fullscreen status/value.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "loop",
    "data": {
        "type": "ValueSetBoolean",
        "value": true | false
    },
    "mid": "123abc"
}

Returns: ControlState for loop

position

Seek to the relative position in the currently loaded media as a percentage of the total duration 0.0 to 1.0.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "position",
    "data": {
        "type": "ValueSetFloat",
        "value": 0.5
    },
    "mid": "123abc"
}

Returns: ControlState for position

selected

Get/set the Selected media file (currently playing).

Implementation may vary based on the media player, may be absolute path to a file, or media handle/id.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "selected",
    "data": {
        "type": "ValueSet",
        "value": "item-id"
    },
    "mid": "123abc"
}

Returns: ControlState for volume

volume

Seek to the media player volume as a percentage of the current playing medias level 0.0 to 1.0.

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "volume",
    "data": {
        "type": "ValueSetFloat",
        "value": 0.5
    },
    "mid": "123abc"
}

Returns: ControlState for volume