Installation & Usage Guide

Installation

Xosms can be installed from npm via

npm install xosms

or

yarn add xosms

Xosms wll automatically depend on and use the proper vendored native for your platform

Important Notes

Xosms is a simple API and tries to minimize the friction with using it across different platforms but different systems media services operate in different ways and may require some things that others don't

Windows

• MediaPlayer.mediaType must be provided before you can set properties. Xosms will throw if you set properties before setting the mediaType

Linux

We recommend following the MPRIS specification for what you should handle and how to do so but a quick brief is

• MediaPlayer.trackId must be provided
• MediaPlayer.on("positionseeked") should be handled or you could miss out on proper functionality of seeking
  • If the position seeked would result in a negative start position clamp it to 0
  • If the position seeked exceeds the duration of the track then treat it like going to the next track
• MediaPlayer.stopButtonEnabled is permanently enabled as MPRIS does not have a separate enable property for this outside enabling or disabling all controls

Example Usage

let mediaPlayer = new MediaPlayer("xosms", "Xosms Example")

// Activate the MediaPlayer registering it or showing it on the operating systems media service
mediaPlayer.activate()

// Attach events
mediaPlayer.on("buttonpressed", (_error, button) => {
    // Handle the type of button being pressed here
    // Valid buttons are `play | pause | playpause | stop | next | previous`
})

mediaPlayer.on("positionchanged", (_error, position) => {
    // Handle the position being changed
    // `position` will always be 0 or above and less than the provided duration in the MediaPlayer
})

mediaPlayer.on("positionseeked", (_error, seek) => {
    // Handle the position being seeked
    // `seek` will be a relative offset from the current position in the MediaPlayer e.g. 10 for 10 seconds forward or -10 for 10 seconds backwards
})

// Set the media type as some media services require this
mediaPlayer.mediaType = MediaPlayerMediaType.Music;

// Enable the different buttons and abilities of the media service
mediaPlayer.playButtonEnabled = true
mediaPlayer.pauseButtonEnabled = true
mediaPlayer.stopButtonEnabled = true
mediaPlayer.nextButtonEnabled = true
mediaPlayer.previousButtonEnabled = true
mediaPlayer.seekEnabled = true

// Fill in the metadata
mediaPlayer.trackId = "xosmsExampleTrackId"
mediaPlayer.title = "Xosms Example Title"
mediaPlayer.artist = "Xosms Example Artist"
mediaPlayer.albumTitle = "Xosms Example Album"

// Set the playback status
mediaPlayer.playbackStatus = MediaPlayerPlaybackStatus.Playing

// Instruct the media service to update
mediaPlayer.update()

// Set the timeline information to provide the current duration and position
// This must be called every time the position changes to ensure the media service is synchronized. Failing to do so could cause desync or unnecessary seek emit events being sent to the media service
// Note that this does not require the MediaPlayer.update() method to be called after
mediaPlayer.setTimeline(60, 30)