> For the complete documentation index, see [llms.txt](https://seanime.gitbook.io/seanime-extensions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://seanime.gitbook.io/seanime-extensions/plugins/ui/anime-library/mpv.md).

# MPV

Interact with the user's MPV instance.

## Permissions

{% hint style="warning" %}
`playback` permission is required
{% endhint %}

<pre class="language-json"><code class="lang-json">{
  //...
  "plugin": {
    "permissions": {
<strong>      "scopes": ["playback"]
</strong>    }
  }
}
</code></pre>

## Core Methods

### openAndPlay

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

**Parameters:**

* `filePath`: String - Path to a video file

**Example:**

```typescript
// 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:**

```typescript
// 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

```typescript
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:**

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