MPV

Interact with the user's MPV instance.

Permissions

playback permission is required

{
  //...
  "plugin": {
    "permissions": {
      "scopes": ["playback"]
    }
  }
}

Core Methods

openAndPlay

Opens and plays a file with MPV (without tracking).

Parameters:

• filePath: String - Path to a video file

Example:

// Play a file directly with MPV without tracking
try {

  await ctx.mpv.openAndPlay("/path/to/video.mkv")
  console.log("MPV playback started")
  
} catch (error) {
  console.error("MPV playback error:", error)
}

onEvent

Registers a listener for MPV player events (fires frequently).

Parameters:

• callback: Function(event, closed) - Callback function for events

Example:

// Monitor MPV events (use carefully - fires multiple times per second)
const unsubscribe = ctx.mpv.onEvent((event, closed) => {
  if (closed) {
    console.log("MPV connection closed")
    return
  }
  
  console.log("MPV loaded file:", event.data)
})

// Unsubscribe anytime
unsubscribe()

getConnection

Returns the underlying connection object to the MPV instance.

Returns: MpvConnection | undefined - The MPV connection if available

const conn = ctx.mpv.getConnection()

// Check the connection first
if (conn && !conn.isClosed()) {
    // shortcut to call("set_property", property, value)
    conn.set("time-pos", 90)
    
    // shortcut call("get_property", property)
    conn.get("time-pos")
    
    // This works but you should use ctx.mpv.close() instead
    conn.close()
}

stop

Stops the MPV player.

Example:

// Stop playback
try {
  ctx.mpv.stop()
} catch (e) {
  console.log("Failed to stop player", e)
}