IINA Plugin API

https://docs.iina.io/
Admin
The IINA Plugin API provides developers with tools and modules to extend the functionality of the...
Tokens:45,068
Snippets:523
Trust Score:9.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### on(event: "iina.file-started", callback: (() => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Get notified when a new file has started playing.

```APIDOC
## on("iina.file-started", callback: () => void)

### Description
Get notified when a new file has started playing.

### Parameters
- **event** (string) - Required - The event name: "iina.file-started"
- **callback** (function) - Required - A function to be called when the file starts playing.

### Returns
- string: A unique ID for the listener, used for unsubscribing.
```

--------------------------------

### startServer

Source: https://docs.iina.io/interfaces/IINA.API.WebSocket.html

Starts the WebSocket server. This method must be called after `createServer()`. It is recommended to set up state update handlers before calling this method, as errors like 'port already in use' can occur after the server starts and are reported via state updates.

```APIDOC
## startServer

### Description
Starts the WebSocket server. This must be called after `createServer()`.

### Method
startServer

### Usage
Setup state update handlers before calling this method.

### Returns
void

### Throws
If the server is not in the correct state, an error will be thrown.
```

--------------------------------

### HTTP GET Request with Headers

Source: https://docs.iina.io/interfaces/IINA.API.HTTP.html

Example of sending an HTTP GET request with custom headers, such as a User-Agent.

```javascript
http.get("https://iina.io", { headers: { "User-Agent": "IINA" } });
```

--------------------------------

### on(event: "iina.mpv-inititalized", callback: (() => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Get notified when the mpv instance is initialized.

```APIDOC
## on("iina.mpv-inititalized", callback: () => void)

### Description
Get notified when the mpv instance is initialized.

### Parameters
- **event** (string) - Required - The event name: "iina.mpv-inititalized"
- **callback** (function) - Required - A function to be called when mpv is initialized.

### Returns
- string: A unique ID for the listener, used for unsubscribing.
```

--------------------------------

### Install iina-plugin-definition with npm

Source: https://docs.iina.io/index.html

Install the iina-plugin-definition package using npm. This is an alternative to using Yarn for package installation.

```bash
npm i iina-plugin-definition
```

--------------------------------

### Plugin Lifecycle Example

Source: https://docs.iina.io/pages/getting-started.html

Illustrates the basic flow from player creation to file playback within the IINA plugin system.

```text
Player Created -> Plugin Code executed -> User opens a file -> File starts to play
```

--------------------------------

### Install Plugin Definition Package

Source: https://docs.iina.io/pages/dev-guide

Install the iina-plugin-definition package to get type definitions for TypeScript and JavaScript users. This is a development dependency.

```bash
npm install --save-dev iina-plugin-definition

```

--------------------------------

### on(event: "iina.plugin-overlay-loaded", callback: (() => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Get notified when the video overlay view for this plugin is loaded.

```APIDOC
## on("iina.plugin-overlay-loaded", callback: () => void)

### Description
Get notified when the video overlay view for this plugin is loaded.

### Parameters
- **event** (string) - Required - The event name: "iina.plugin-overlay-loaded"
- **callback** (function) - Required - A function to be called when the overlay is loaded.

### Returns
- string: A unique ID for the listener, used for unsubscribing.

### See Also
The overlay module.
```

--------------------------------

### StandaloneWindow Example: Simple Mode and Load File

Source: https://docs.iina.io/interfaces/IINA.API.StandaloneWindow.html

Demonstrates how to activate simple mode, set content and style, and load an HTML file into a standalone window.

```javascript
// simple mode  
standaloneWindow.simpleMode();  
standaloneWindow.setContent(`<p>Hello World</p>`);  
standaloneWindow.setStyle(`p { color: red; }`);  
standaloneWindow.show();  
  
// load a HTML file  
standaloneWindow.loadFile("/path/to/sa-window.html");  
standaloneWindow.show();  
```

--------------------------------

### Install iina-plugin-definition with Yarn

Source: https://docs.iina.io/index.html

Install the iina-plugin-definition package using Yarn. This is the first step to using the package in a TypeScript project.

```bash
yarn add iina-plugin-definition
```

--------------------------------

### on(event: "iina.file-loaded", callback: ((url: string) => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Get notified when a new file is loaded.

```APIDOC
## on("iina.file-loaded", callback: (url: string) => void)

### Description
Get notified when a new file is loaded.

### Parameters
- **event** (string) - Required - The event name: "iina.file-loaded"
- **callback** (function) - Required - A function that accepts a string URL.
  - **url** (string) - The new file's URL.

### Returns
- string: A unique ID for the listener, used for unsubscribing.
```

--------------------------------

### Example HTML Structure for Preference Page

Source: https://docs.iina.io/pages/plugin-preferences

Demonstrates using default CSS classes and input elements with data attributes for binding preferences.

```html
<body>
  <div class="pref-section">
    Use custom youtube-dl/yt-dlp:
    <div style="margin-top: 2px">
      <input
        type="text"
        data-pref-key="ytdl_path"
        style="width: 100%; margin-top: 2px"
      />
    </div>
  </div>
  <div class="pref-section">
    <label>
      <input type="checkbox" data-type="bool" data-pref-key="use_manifest" />
      Use manifest URL
    </label>
    <p class="small secondary pref-help">
      Use the master manifest URL for formats like HLS and DASH, if available,
      allowing for video/audio selection in runtime.
    </p>
  </div>
</body>
```

--------------------------------

### Overlay Simple Mode Example

Source: https://docs.iina.io/interfaces/IINA.API.Overlay.html

Demonstrates how to activate simple mode, set HTML content and CSS styles, and show the overlay. This is useful for displaying dynamic text or simple UI elements.

```javascript
overlay.simpleMode();
overlay.setContent(`<p>Hello World</p>`);
overlay.setStyle(`p { color: red; }`);
overlay.show();

// load a HTML file
overlay.loadFile("/path/to/overlay.html");
overlay.show();
```

--------------------------------

### Create and Manage WebSocket Server

Source: https://docs.iina.io/interfaces/IINA.API.WebSocket

This snippet demonstrates how to create, configure, and start a WebSocket server. It also includes handlers for server state updates, new connections, connection state changes, and message reception. Use this to establish a communication channel for your plugin.

```javascript
ws.createServer({ port: 10010 });
ws.onStateUpdate((s, err) => {
  if (s == "failed") {
    console.log(err);
  }
})

ws.onNewConnection(conn => console.log("new connection"));
ws.onConnectionStateUpdate((conn, s) => console.log(conn + ": " + s));
ws.onMessage((conn, m) => {
  console.log(`Message from ${conn}: ${m.text()}`);
  ws.sendText(conn, "Received!");
)

ws.startServer();

```

--------------------------------

### IINA API Usage Example

Source: https://docs.iina.io/pages/getting-started.html

Demonstrates how to use IINA API modules for console logging, accessing core functionalities, and handling events like file loading.

```javascript
const { console, core, event } = iina;

console.log("Hello, world!");

event.on("mpv.file-loaded", () => {
  core.osd("Starts playing");
});
```

--------------------------------

### on(event: "iina.thumbnails-ready", callback: (() => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Get notified when the thumbnails of the current video are generated.

```APIDOC
## on("iina.thumbnails-ready", callback: () => void)

### Description
Get notified when the thumbnails of the current video are generated.

### Parameters
- **event** (string) - Required - The event name: "iina.thumbnails-ready"
- **callback** (function) - Required - A function to be called when thumbnails are ready.

### Returns
- string: A unique ID for the listener, used for unsubscribing.
```

--------------------------------

### Preferences Module Methods

Source: https://docs.iina.io/interfaces/IINA.API.Preferences.html

Provides methods to get, set, and synchronize plugin preferences.

```APIDOC
## get

### Description
Get the preference value corresponding to the key.

### Method
get(key: string): any

### Parameters
#### Path Parameters
* **key** (string) - Required - The preference key.

### Returns
any
```

```APIDOC
## set

### Description
Set the value for a preference key.

### Method
set(key: string, value: any): void

### Parameters
#### Path Parameters
* **key** (string) - Required - The preference key.
* **value** (any) - Required - The value to set.

### Returns
void
```

```APIDOC
## sync

### Description
Persist the preference changes to disk. It's recommended to call this method after invoking `set` programmatically.

### Method
sync(): void

### Returns
void
```

--------------------------------

### Overlay Clickable Elements Example

Source: https://docs.iina.io/interfaces/IINA.API.Overlay.html

Shows how to make overlay elements interactive by setting the overlay to clickable and using the `data-clickable` attribute on HTML elements like buttons and input fields.

```html
<button data-clickable>Click Me</button>
<input type="text" data-clickable>
```

--------------------------------

### Get Version Information

Source: https://docs.iina.io/interfaces/IINA.API.Core.html

Retrieves the version details for IINA, the build, and the underlying mpv player. This is helpful for debugging and compatibility checks.

```javascript
let versions = core.getVersion();
console.log(`IINA: ${versions.iina}, Build: ${versions.build}, mpv: ${versions.mpv}`);
```

--------------------------------

### Making an HTTP GET Request

Source: https://docs.iina.io/interfaces/IINA.API.HTTP.html

Use this snippet to fetch data from a given URL. It logs the text content of the response.

```javascript
// print the source of IINA's homepage  
const res = await http.get("https://iina.io");  
console.log(res.text);
```

--------------------------------

### HTML for Enabling Overlay Webview Interactions

Source: https://docs.iina.io/pages/webviews

Example HTML elements with the 'data-clickable' attribute to enable interactions in an overlay webview.

```html
<button id="open-btn" data-clickable>Clisk Me</button>  
<input type="text" id="input" data-clickable />
```

--------------------------------

### Add IINA CLI Tool to PATH

Source: https://docs.iina.io/pages/creating-plugins

Symlinks the IINA CLI tool to a location in your system's PATH for easier access. This is a one-time setup step.

```bash
ln -s /Applications/IINA.app/Contents/MacOS/iina-plugin /usr/local/bin/iina-plugin

```

--------------------------------

### Link a Development Plugin

Source: https://docs.iina.io/pages/creating-plugins

Creates a symlink for a development plugin, allowing IINA to load it directly from a local folder without installation. This is useful for rapid testing during development.

```bash
# manually  
ln -s /path/to/plugin ~/Library/Application\ Support/com.colliderli.iina/plugins/<name>.iinaplugin-dev  
  
# using the CLI  
iina-plugin link <dir>
iina-plugin unlink <dir>  # to remove the symlink

```

--------------------------------

### Get Chapters

Source: https://docs.iina.io/interfaces/IINA.API.Core.html

Retrieves a list of chapters available in the current media file. This is useful for navigation within media that has defined chapters.

```javascript
let chapters = core.getChapters();
```

--------------------------------

### Parcel Bundler Configuration for UI Target

Source: https://docs.iina.io/pages/dev-guide

Configure a separate Parcel target for building custom user interfaces. This example specifies the output directory and the source HTML file for the UI.

```json
{
  "targets": {
    "ui": {
      "distDir": "./dist/ui/",
      "source": "src/ui/index.html"
    }
  }
}
```

--------------------------------

### HTTP GET Request

Source: https://docs.iina.io/interfaces/IINA.API.HTTP.html

Sends an HTTP GET request to the specified URL. Supports custom headers and request options.

```APIDOC
## GET

### Description
Send an HTTP GET request.

### Method
GET

### Endpoint
`url: string`

### Parameters
* **url** (string) - The URL to send the GET request to.
* **options** (HTTPRequestOption<ReqData>) - Optional. The options for the request, including headers and parameters.

### Returns
Promise<HTTPResponse<ResData>>

### Example
```typescript
http.get("https://iina.io", { headers: { "User-Agent": "IINA" } });
```
```

--------------------------------

### Toggle Fullscreen Mode

Source: https://docs.iina.io/interfaces/IINA.API.WindowAPI.html

Get or set the current fullscreen state of the player window.

```javascript
// toggle fullscreen  
core.window.fullscreen = !core.window.fullscreen;
```

--------------------------------

### Specify Global Entry Point in Info.json

Source: https://docs.iina.io/pages/global-entry.html

Declare the global entry script in the Info.json file. This script is loaded before any player core is initialized.

```json
{
  "global": "global.js"
}
```

--------------------------------

### on(event: "iina.window-did-close", callback: (() => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Get notified when the player window is closed.

```APIDOC
## on("iina.window-did-close", callback: () => void)

### Description
Get notified when the player window is closed.

### Parameters
- **event** (string) - Required - The event name: "iina.window-did-close"
- **callback** (function) - Required - A function to be called when the window has closed.

### Returns
- string: A unique ID for the listener, used for unsubscribing.
```

--------------------------------

### Create and Manage WebSocket Server

Source: https://docs.iina.io/interfaces/IINA.API.WebSocket.html

This snippet demonstrates how to create a WebSocket server, handle state updates, manage new connections, track connection states, and process incoming messages. It also shows how to send a text response back to a client.

```javascript
ws.createServer({ port: 10010 });  
ws.onStateUpdate((s, err) => {  
  if (s == "failed") {  
    console.log(err);  
  }  
})
  
ws.onNewConnection(conn => console.log("new connection"));  
ws.onConnectionStateUpdate((conn, s) => console.log(conn + ": " + s));  
ws.onMessage((conn, m) => {  
  console.log(`Message from ${conn}: ${m.text()}`);  
  ws.sendText(conn, "Received!");  
)
  
ws.startServer();

```

--------------------------------

### on(event: "iina.window-will-close", callback: (() => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Get notified when the player window is about to close.

```APIDOC
## on("iina.window-will-close", callback: () => void)

### Description
Get notified when the player window is about to close.

### Parameters
- **event** (string) - Required - The event name: "iina.window-will-close"
- **callback** (function) - Required - A function to be called when the window is about to close.

### Returns
- string: A unique ID for the listener, used for unsubscribing.
```

--------------------------------

### Get MPV Property as String

Source: https://docs.iina.io/interfaces/IINA.API.MPV.html

Retrieves a property from mpv and returns it as a string. Suitable for most mpv properties.

```javascript
let pm = mpv.getString("video-params/pixelformat");
```

--------------------------------

### core.open

Source: https://docs.iina.io/interfaces/IINA.API.Core.html

Opens a new file in the current player window. Accepts a URL or file path.

```APIDOC
## core.open

### Description
Open a new file in the current player window.

### Method
open

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL or file path of the media.

### Returns void
```

--------------------------------

### Get MPV Property as Number

Source: https://docs.iina.io/interfaces/IINA.API.MPV.html

Retrieves a property from mpv and returns it as a number. Internally uses double format for precision.

```javascript
let pos = mpv.getNumber("stream-pos");
```

--------------------------------

### createServer

Source: https://docs.iina.io/interfaces/IINA.API.WebSocket.html

Creates a WebSocket server instance. This method initializes the server with specified options, such as the port number. It may throw an error if the provided options are invalid.

```APIDOC
## createServer

### Description
Creates a WebSocket server instance with the given options.

### Method
createServer

### Parameters
#### options: Partial<{
  port: number;
}> - Required
The options for the server, including the port number.

### Returns
void

### Throws
If the option is invalid, an error will be thrown.
```

--------------------------------

### Basic main.js Entry Point

Source: https://docs.iina.io/pages/getting-started.html

A simple JavaScript file that serves as the main entry point for an IINA plugin, logging a message to the console.

```javascript
// main.js  
iina.console.log("Hello, world!");
```

--------------------------------

### Get MPV Property as Boolean

Source: https://docs.iina.io/interfaces/IINA.API.MPV.html

Retrieves a property from mpv and returns it as a boolean value. Useful for checking flag-like properties.

```javascript
let muted = mpv.getFlag("mute");
```

--------------------------------

### StandaloneWindow Methods

Source: https://docs.iina.io/interfaces/IINA.API.StandaloneWindow.html

This section details the methods available for interacting with the StandaloneWindow module, including opening, closing, loading content, and managing window properties.

```APIDOC
## Methods

### open
  * open(): void
  * Open the standalone window.
#### Returns void

### close
  * close(): void
  * Close the standalone window.
#### Returns void

### loadFile
  * loadFile(path: string): void
  * Clear the overlay contents and load a HTML file into the overlay. The HTML file should contain the CSS and JavaScript code to render the contents. It is possible to put the JavaScript code in a separate file and load it using a `<script>` tag. The webpage can communicate with the Internet using standard methods like `fetch`, but it cannot access the IINA API directly. It should use `iina.postMessage` and `iina.onMessage` to exchange data with the plugin script. See API in Web Views for more information.
#### Parameters
    * ##### path: string
The path to the HTML file, related to the plugin root directory.
#### Returns void

### simpleMode
  * simpleMode(): void
  * Clear the window contents and activate the "Simple Mode". In the simple mode, you directly set the HTML and CSS contents of the overlay from the plugin script.
#### Returns void

### setStyle
  * setStyle(style: string): void
  * (Simple Mode Only) Set the CSS style of the standalone window. The CSS string will be put into a `<style>` tag at the end of `<head>`.
```html
<head>
   ...
   <style> [inserted here] </style>
</head>
```
An error will be raised if the overlay is not in simple mode.
#### Parameters
    * ##### style: string
The CSS string.
#### Returns void

### setContent
  * setContent(content: string): void
  * (Simple Mode Only) Set the HTML content of the standalone window. The HTML string will be put into a `<div>` tag inside `<body>`, with class `content`.
```html
<body>
   <div class="content"> [inserted here] </div>
</body>
```
An error will be raised if the overlay is not in simple mode.
#### Parameters
    * ##### content: string
The HTML string.
#### Returns void

### setProperty
  * setProperty(props: Partial<{
title: string;
resizable: boolean;
hudWindow: boolean;
fullSizeContentView: boolean;
hideTitleBar: boolean;
}>): void
  * Set various properties of the standalone window.
#### Parameters
    * ##### props: Partial<{
title: string;
resizable: boolean;
hudWindow: boolean;
fullSizeContentView: boolean;
hideTitleBar: boolean;
}>
Properties of the standalone window.
      * `title`: the title of the window.
      * `resizable`: whether the window is resizable.
      * `hudWindow`: whether the window is a HUD window, like IINA's Inspector window. This option will also make the window have translucency and vibrancy background effects.
      * `fullSizeContentView`: whether the window has a full size content view, that is, the content view is not inset by the title bar.
      * `hideTitleBar`: whether the window should hide the title bar.
#### Returns void
```

--------------------------------

### Create Player Instance with Global Module

Source: https://docs.iina.io/pages/global-entry.html

Use the 'global' module in the global entry script to create new player instances. Options like disabling window animations and UI are available for programmatically controlled windows.

```javascript
const player = global.createPlayerInstance({
  url: "/path/to/video.mp4",
  disableWindowAnimation: true,
  disableUI: true,
  enablePlugins: false,
});
```

--------------------------------

### handle

Source: https://docs.iina.io/interfaces/IINA.API.File.html

Opens a file for reading or writing binary data, returning a file handle.

```APIDOC
## handle

### Description
Opens a file for reading or writing binary data, returning a file handle.

### Method
handle

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the file.
- **mode** (string) - Required - The mode to open the file in. Can be either `"read"` or `"write"`.

#### Returns
- **FileHandle** - A handle to the opened file for binary operations.

### Example
```javascript
const fileHandle = File.handle('my_binary_file.bin', 'read')
// Use fileHandle for binary read operations
```
```

--------------------------------

### Symlinking Plugin for Development

Source: https://docs.iina.io/pages/dev-guide

Create a symbolic link to your plugin folder in the IINA plugins directory for development. This allows you to reload the plugin without reinstalling it.

```bash
ln -s /path/to/myplugin ~/Library/Application\ Support/com.colliderli.iina/plugins/myplugin.iinaplugin-dev
```

--------------------------------

### Pack a Plugin for Distribution

Source: https://docs.iina.io/pages/creating-plugins

Compresses a plugin directory into a distributable `.iinaplgz` file. This file is a zip archive with a different extension.

```bash
iina-plugin pack <dir>

```

--------------------------------

### Get Playback History

Source: https://docs.iina.io/interfaces/IINA.API.Core.html

Retrieves the list of entries in the playback history. This can be used to display recently played files or resume playback.

```javascript
let history = core.getHistory();
```

--------------------------------

### Get MPV Property as Native Object

Source: https://docs.iina.io/interfaces/IINA.API.MPV.html

Retrieves a property from mpv as a native JavaScript object. Ideal for dictionaries or lists like 'video-params'.

```javascript
let params = mpv.getNative("video-params");
// => { "stereo-in": "mono", "h": 1080, "w": 1920, "chroma-location": "mpeg2/4/h264", ... }
```

--------------------------------

### core.resume

Source: https://docs.iina.io/interfaces/IINA.API.Core.html

Resumes the current media playback.

```APIDOC
## core.resume

### Description
Resume the playback.

### Method
resume

### Returns void
```

--------------------------------

### Set and Get Plugin Preferences using JavaScript API

Source: https://docs.iina.io/pages/plugin-preferences

Access and modify plugin preferences using the `preferences.set` and `preferences.get` methods provided by IINA.

```javascript
const { preferences } = iina;
preferences.set("key", value);
preferences.get("key");
```

--------------------------------

### Create a New Plugin

Source: https://docs.iina.io/pages/creating-plugins

Generates a new plugin project folder with the specified name. Supports templates for React and Vue interfaces.

```bash
iina-plugin new <name>

```

--------------------------------

### on(event: "iina.pip.changed", callback: ((status: boolean) => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Get notified when the player enters or exits Picture-in-Picture (PIP) mode.

```APIDOC
## on("iina.pip.changed", callback: (status: boolean) => void)

### Description
Get notified when the player enters or exits Picture-in-Picture (PIP) mode.

### Parameters
- **event** (string) - Required - The event name: "iina.pip.changed"
- **callback** (function) - Required - A function that accepts a boolean status.
  - **status** (boolean) - The new PIP status.

### Returns
- string: A unique ID for the listener, used for unsubscribing.
```

--------------------------------

### Remove a Menu Item by Index

Source: https://docs.iina.io/interfaces/IINA.API.Menu.html

Use the `removeAt` method to remove a specific menu item from the plugin menu by its index. Indices start at 0.

```javascript
menu.removeAt(2); // Removes the third item in the menu
```

--------------------------------

### Input Module Overview

Source: https://docs.iina.io/interfaces/IINA.API.Input.html

The Input module provides methods to capture mouse and keyboard events. Listeners can be added with priorities to control the order of event handling. Higher priority listeners are called first. The event callback should return a boolean to indicate if the event was handled, preventing further propagation.

```APIDOC
## Module: Input

Provides methods to capture mouse and keyboard events in the player window.

### Event Handling Order:
1. Listeners with priority `>= PRIORITY_HIGH`
2. Default handlers (e.g., mpv key bindings)
3. Listeners with priority `< PRIORITY_HIGH`

**Note:** It is recommended to use `PRIORITY_LOW` unless necessary. The default priority is `PRIORITY_LOW`. Event propagation can be stopped by returning `true` from a listener callback.
```

--------------------------------

### Overlay Methods

Source: https://docs.iina.io/interfaces/IINA.API.Overlay.html

This section details the methods available for controlling and interacting with the IINA overlay. These methods allow you to show, hide, configure opacity, manage clickability, load content from files, and switch between different overlay modes.

```APIDOC
## show

### Description
Show the overlay. The overlay is hidden by default and you need to call this method to show it.

### Method
show(): void

### Returns
void

## hide

### Description
Hide the overlay.

### Method
hide(): void

### Returns
void

## setOpacity

### Description
Set the opacity of the overlay.

### Method
setOpacity(opacity: number): void

### Parameters
#### Path Parameters
* **opacity** (number) - Required - The opacity of the overlay, from 0 to 1.

### Returns
void

## setClickable

### Description
Indicate whether the overlay accepts input events. If set to `true`, mouse events will be passed to the overlay, but only for the HTML elements with the `data-clickable` attribute.

### Method
setClickable(clickable: boolean): void

### Parameters
#### Path Parameters
* **clickable** (boolean) - Required - Whether the overlay is clickable.

### Returns
void

## loadFile

### Description
Clear the overlay contents and load a HTML file into the overlay. The HTML file should contain the CSS and JavaScript code to render the contents. It is possible to put the JavaScript code in a separate file and load it using a `<script>` tag. The webpage can communicate with the Internet using standard methods like `fetch`, but it cannot access the IINA API directly. It should use `iina.postMessage` and `iina.onMessage` to exchange data with the plugin script.

### Method
loadFile(path: string): void

### Parameters
#### Path Parameters
* **path** (string) - Required - The path to the HTML file, related to the plugin root directory.

### Returns
void

## simpleMode

### Description
Clear the overlay contents and activate the "Simple Mode". In the simple mode, you directly set the HTML and CSS contents of the overlay from the plugin script.

### Method
simpleMode(): void

### Returns
void

## setStyle

### Description
(Simple Mode Only) Set the CSS style for the overlay. The CSS string will be put into a `<style>` tag at the end of `<head>`. An error will be raised if the overlay is not in simple mode.

### Method
setStyle(style: string): void

### Parameters
#### Path Parameters
* **style** (string) - Required - The CSS string.

### Returns
void

## setContent

### Description
(Simple Mode Only) Set the HTML contents for the overlay. The HTML string will be put into a `<div>` tag inside `<body>`, with class `content`. An error will be raised if the overlay is not in simple mode.

### Method
setContent(content: string): void

### Parameters
#### Path Parameters
* **content** (string) - Required - The HTML string.

### Returns
void

## postMessage

### Description
Post a message to the overlay webview. The overlay webview also has two methods, `iina.postMessage` and `iina.onMessage`, to exchange data with the plugin script.

### Method
postMessage(name: string, data: any): void

### Parameters
#### Path Parameters
* **name** (string) - Required - The message name.
* **data** (any) - Required - The message data.

### Returns
void
```

--------------------------------

### Get and Set Window Frame

Source: https://docs.iina.io/interfaces/IINA.API.WindowAPI.html

Retrieve the current frame (position and size) of the window or update its position and size. Use events to be notified of frame changes.

```javascript
// get the current frame  
let frame = core.window.frame;  
// move the window to (100, 100)  
core.window.frame = { ...frame, x: 100, y: 100 };
```

--------------------------------

### on(event: "iina.music-mode.changed", callback: ((status: boolean) => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Get notified when the player enters or exits music mode (mini player).

```APIDOC
## on("iina.music-mode.changed", callback: (status: boolean) => void)

### Description
Get notified when the player enters or exits music mode (mini player).

### Parameters
- **event** (string) - Required - The event name: "iina.music-mode.changed"
- **callback** (function) - Required - A function that accepts a boolean status.
  - **status** (boolean) - Whether the player is in music mode.

### Returns
- string: A unique ID for the listener, used for unsubscribing.
```

--------------------------------

### Register and Unregister Event Listeners

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Demonstrates how to register a callback for the 'iina.file-loaded' event and then unregister it. Also shows how to listen to mpv property changes like volume.

```javascript
// show the file's path when playing a new file  
const eventID = event.on("iina.file-loaded", () => {  
  core.osd(`Playing ${core.status.url}`);  
})  
  
// remove the listener  
event.off("iina.file-loaded", eventID);  
  
// using the mpv API: show the current volume when it changes  
event.on("mpv.volume.changed", () => {  
  core.osd(`Volume: ${mpv.getNumber("volume")}`);  
});
```

--------------------------------

### core.getVersion

Source: https://docs.iina.io/interfaces/IINA.API.Core.html

Returns the version information for IINA, its build, and the underlying mpv player.

```APIDOC
## core.getVersion

### Description
Returns the version information of IINA and mpv.

### Method
getVersion

### Returns {
  iina: string;
  build: string;
  mpv: string;
}

#### Response Fields
- **iina** (string)
- **build** (string)
- **mpv** (string)
```

--------------------------------

### open

Source: https://docs.iina.io/interfaces/IINA.API.Utils.html

Opens a given URL using the system's default handler. This can be a web URL opened in the default browser or a file path revealed in Finder.

```APIDOC
## open

### Description
Open a URL in the system. It can be a http or https link, or a file path. When it is a web URL, the default browser will be used to open the link. When it is a file path, magic variables like `@data` will be resolved, and the file will be revealed in Finder.

### Method
N/A (SDK Method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
#### url (string) - Required
The URL to open.

### Request Example
N/A

### Response
#### Success Response
`true` if the URL is opened successfully, `false` otherwise.

#### Response Example
N/A
```

--------------------------------

### core.getChapters

Source: https://docs.iina.io/interfaces/IINA.API.Core.html

Retrieves a list of chapters available in the current media file.

```APIDOC
## core.getChapters

### Description
Returns the list of chapters in the current file.

### Method
getChapters

### Returns Chapter[]
```

--------------------------------

### Downloading a File

Source: https://docs.iina.io/interfaces/IINA.API.HTTP.html

This snippet demonstrates how to download a file to the plugin's data folder. Ensure the 'file-system' permission is granted if downloading outside the sandbox.

```javascript
// download a file to the plugin's data folder  
await http.download("https://example.com/file.zip", "@data/file.zip");
```

--------------------------------

### Get Recent Documents

Source: https://docs.iina.io/interfaces/IINA.API.Core.html

Fetches the list of recently opened files from the system's recent documents list. This is useful for providing quick access to recently used files.

```javascript
let recentDocs = core.getRecentDocuments();
```

--------------------------------

### Playlist Methods

Source: https://docs.iina.io/interfaces/IINA.API.Playlist.html

The Playlist module offers several methods to manage playlist items and customize the context menu.

```APIDOC
## Playlist Module

The `Playlist` module provides methods to manipulate the playlist and add custom menu items to the playlist context menu.

### Methods

#### `list()`

* **Description**: Get all items in the playlist.
* **Returns**: `PlaylistItem[]`

#### `count()`

* **Description**: Get the number of items in the playlist.
* **Returns**: `number`

#### `add(url: string, at?: number)`

* **Description**: Add an item to the playlist.
* **Parameters**:
  * `url` (string): The URL of the item.
  * `at` (number, Optional): The index to insert the item. If not specified, the item will be appended to the end of the playlist.
* **Returns**: `PlaylistItem`
* **Example**:
```javascript
playlist.add("https://example.com/video.mp4", 0 /* insert at the beginning * /);
```

#### `remove(index: number)`

* **Description**: Remove an item from the playlist.
* **Parameters**:
  * `index` (number): The index of the item to remove.
* **Returns**: `PlaylistItem`

#### `move(index: number, to: number)`

* **Description**: Move an item in the playlist.
* **Parameters**:
  * `index` (number): The index of the item to move.
  * `to` (number): The destination index.
* **Returns**: `PlaylistItem`

#### `play(index: number)`

* **Description**: Play an item in the playlist.
* **Parameters**:
  * `index` (number): The index of the item to play.
* **Returns**: `void`

#### `playNext()`

* **Description**: Play the next item in the playlist.
* **Returns**: `void`

#### `playPrevious()`

* **Description**: Play the previous item in the playlist.
* **Returns**: `void`

#### `registerMenuBuilder(builder: (entries: PlaylistItem[]) => MenuItem[])`

* **Description**: Provide a menu builder function to add custom menu items to the playlist context menu. When the user selects one or more items in the playlist and right-clicks on them, the menu builder function will be called with the selected items as an argument. It should return an array of menu items, which will be inserted into the context menu.
* **Parameters**:
  * `builder` ((entries: PlaylistItem[]) => MenuItem[]): The menu builder function.
    * `entries` (PlaylistItem[]): The user-selected playlist items.
* **Returns**: `void`
* **Example**:
```javascript
// trash the selected items  
playlist.registerMenuBuilder(entries => [
  menu.item(`Trash these ${entries.length} files`, () => {
    for (const entry of entries) {
       file.trash(entry.filename);
    }
  }),
]);
```
```

--------------------------------

### Parcel Bundler Configuration for Plugin Entry

Source: https://docs.iina.io/pages/dev-guide

Configure Parcel to bundle your plugin code into a single file. This example sets the output directory, source file, and specifies it's not a library.

```json
{
  "targets": {
    "entry": {
      "distDir": "./dist/",
      "source": "src/index.ts",
      "isLibrary": false
    }
  }
}
```

--------------------------------

### chooseFile

Source: https://docs.iina.io/interfaces/IINA.API.Utils.html

Opens a system file chooser panel, allowing the user to select a file or directory with optional filtering by file type or directory selection mode.

```APIDOC
## chooseFile

### Description
Show a system file chooser panel.

### Method
`chooseFile(title: string, options: Partial<{ chooseDir: boolean; allowedFileTypes: string[]; }>): string`

### Parameters
#### Path Parameters
- **title** (string) - Required - The title of the panel.
- **options** (Partial<{ chooseDir: boolean; allowedFileTypes: string[]; }>) - Optional - Optional options.
  - **chooseDir** (boolean) - Choose a directory instead of a file.
  - **allowedFileTypes** (string[]) - Specify a list of available file extensions. Files without these extensions will be disabled in the panel.

### Returns
- **string** - Full path of the chosen file or directory.

### Example
```javascript
const path = utils.chooseFile("Please select a subtitle file", {
  allowedFileTypes: ["ass", "srt"],
});
core.subtitle.loadTrack(path);
```
```

--------------------------------

### on(event: "iina.window-main.changed", callback: ((status: boolean) => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Get notified when the player window becomes or stops being the main window. This essentially means that the player window is or is not the frontmost window that accepts keyboard and mouse input.

```APIDOC
## on("iina.window-main.changed", callback: (status: boolean) => void)

### Description
Get notified when the player window becomes or stops being the main window. This essentially means that the player window is or is not the frontmost window that accepts keyboard and mouse input.

### Parameters
- **event** (string) - Required - The event name: "iina.window-main.changed"
- **callback** (function) - Required - A function that accepts a boolean status.
  - **status** (boolean) - Whether the window is the main window.

### Returns
- string: A unique ID for the listener, used for unsubscribing.
```

--------------------------------

### onStateUpdate

Source: https://docs.iina.io/interfaces/IINA.API.WebSocket.html

Handles updates to the server's state. It's crucial to respond to 'failed' or 'cancelled' states, as the server will be removed, requiring re-initialization. Errors during server startup are reported through this handler.

```APIDOC
## onStateUpdate

### Description
Handles the server's state update. It is important to properly respond to the "failed" or "cancelled" state, as the server will be removed and require re-creation.

### Method
onStateUpdate

### Parameters
#### callback: (state: "setup" | "ready" | "waiting" | "failed" | "cancelled", error?: {
  message: string;
  description: string;
}) => void - Required
The callback function to handle state changes.
  * **state**: "setup" | "ready" | "waiting" | "failed" | "cancelled" - The server's new state.
  * **error**: Optional - The error details if the state is `failed` or `waiting`.
    * **message**: string
    * **description**: string

### Returns
void
```

--------------------------------

### Create a Simple Menu Item

Source: https://docs.iina.io/interfaces/IINA.API.Menu.html

Use the `item` method to create a new menu item with a title. An optional action callback can be provided to execute when the item is clicked, and options can configure its enabled state, selection, and key binding.

```javascript
menu.item("My Menu Item", () => { console.log("Item clicked!"); }, { enabled: true, selected: false, keyBinding: "Ctrl+Shift+O" });
```

--------------------------------

### Simple Webview Mode in IINA Plugin

Source: https://docs.iina.io/pages/webviews

Use simple mode for basic UI elements like displaying statistical information. Call `simpleMode()`, `setStyle()`, and `setContent()` to define the webview's appearance and content directly from the plugin script. The content can be updated dynamically, for example, using `setInterval` to show live data.

```javascript
const { overlay } = iina;

overlay.simpleMode();
overlay.setStyle(
  "body {
    color: green;
  }"
);
setInterval(() => {
  overlay.setContent(
    `<p>Current time: ${core.status.position}</p>`
  );
}, 1000);
```

--------------------------------

### on(event: `mpv.${string}`, callback: (() => void)): string

Source: https://docs.iina.io/interfaces/IINA.API.Event.html

Add listener to an mpv event.

```APIDOC
## on(`mpv.${string}`, callback: () => void)

### Description
Add listener to an mpv event.

### Parameters
- **event** (string) - Required - The mpv event name (e.g., "mpv.someEvent").
- **callback** (function) - Required - A function to be called when the mpv event occurs.

### Returns
- string: A unique ID for the listener, used for unsubscribing.
```

--------------------------------

### ask

Source: https://docs.iina.io/interfaces/IINA.API.Utils.html

Displays a system dialog with 'OK' and 'Cancel' buttons, allowing for user confirmation or simple message display.

```APIDOC
## ask

### Description
Show a system dialog with "OK" and "Cancel" buttons. Can be used to ask for confirmation or simply show a message to the user.

### Method
`ask(title: string): boolean`

### Parameters
#### Path Parameters
- **title** (string) - Required - The content of the dialog.

### Returns
- **boolean** - `true` if the user clicks "OK", `false` if the user clicks "Cancel".

### Example
```javascript
const yes = utils.ask("Are you sure you want to delete these files?");  

utils.ask("This is a message");
```
```

--------------------------------

### MPV Interface Methods

Source: https://docs.iina.io/interfaces/IINA.API.MPV.html

This section details the available methods for interacting with the mpv player through the MPV module.

```APIDOC
## getFlag

### Description
Get a property as a boolean (flag).

### Method Signature
`getFlag(name: string): boolean`

### Parameters
#### name (string) - Required
The name of the property.

### Returns
boolean

### Example
```javascript
// is muted?
let muted = mpv.getFlag("mute");
```
```

```APIDOC
## getNumber

### Description
Get a property as a number. Internally, it always reads the double format of the property.

### Method Signature
`getNumber(name: string): number`

### Parameters
#### name (string) - Required
The name of the property.

### Returns
number

### Example
```javascript
// get the raw byte position in the source stream
let pos = mpv.getNumber("stream-pos");
```
```

```APIDOC
## getString

### Description
Get a property as a string. Most mpv properties are available as strings.

### Method Signature
`getString(name: string): string`

### Parameters
#### name (string) - Required
The name of the property.

### Returns
string

### Example
```javascript
// get the pixel format of the current video
let pm = mpv.getString("video-params/pixelformat");
```
```

```APIDOC
## getNative

### Description
Try to get the property as a native JavaScript object. It's useful for getting dictionaries (e.g. `video-params`) and lists (e.g. `vf`).

### Method Signature
`getNative<T>(name: string): T`

### Type Parameters
#### T

### Parameters
#### name (string) - Required
The name of the property.

### Returns
T

### Example
```javascript
// get the current video's parameters
let params = mpv.getNative("video-params");
// => { "stereo-in": "mono", "h": 1080, "w": 1920, "chroma-location": "mpeg2/4/h264", ... }
```
```

```APIDOC
## set

### Description
Set the value of a property.

### Method Signature
`set(name: string, value: any): void`

### Parameters
#### name (string) - Required
The name of the property.
#### value (any) - Required
The value to set. If the value is a JavaScript object, it will be treated as a dictionary and converted to a mpv node.

### Returns
void
```

```APIDOC
## command

### Description
Run a mpv command.

### Method Signature
`command(name: string, args: string[]): void`

### Parameters
#### name (string) - Required
The name of the command.
#### args (string[]) - Required
The argument list.

### Returns
void

### Example
```javascript
// seek to 00:10, at the nearest keyframe
mpv.command("seek", ["10", "absolute+keyframes"]);
```
```

```APIDOC
## addHook

### Description
Adds a mpv hook.

### Method Signature
`addHook(name: string, priority: number, callback: ((next?: (() => void)) => void)): void`

### Parameters
#### name (string) - Required
The name of the hook, such as `on_load` or `on_load_fail`.
#### priority (number) - Required
The priority of the hook, should be an integer. Higher priority hooks are executed first.
#### callback ((next?: (() => void)) => void) - Required
The callback function to run when the hook is triggered. If it is an `async` function, the `next` function **must** be called manually when the hook is finished. If it is a normal function, the `next` function should be ignored. The hook callback is considered finished when the function returns.
  * Parameters:
    * `next` (Optional, (() => void)): The function to call when the hook is finished, if the callback is async.

### Returns
void

### Example
```javascript
// the user opened an unrecognized web URL;
// run an external handler (e.g. yt-dlp) to get the actual video URL
mpv.addHook("on_load", 50, async (next) => {
  // get the current URL
  const url = mpv.getString("stream-open-filename");
  // run the external parser
  const actualURL = await runCustomHandler(url);
  // set the actual URL
  mpv.set("stream-open-filename", actualURL);
  // continue loading the video; MUST be called if the callback is async
  next();
});
```

### Seealso
mpv's hook API.
```

--------------------------------

### Basic Core Module Operations

Source: https://docs.iina.io/interfaces/IINA.API.Core.html

Demonstrates pausing playback, displaying an OSD message, and retrieving subtitle track titles. Use these for common player control and information gathering tasks.

```javascript
// pause the playback  
core.pause();  
  
// display a message (OSD) at the top of the window  
core.osd("The plugin is running!");  
  
// get the names of all subtitle tracks  
let subtitles = core.subtitle.tracks.map(track => track.title);
```

--------------------------------

### Open System File Chooser

Source: https://docs.iina.io/interfaces/IINA.API.Utils.html

Launches a system file chooser panel, allowing the user to select a file or directory. Supports filtering by allowed file types and choosing directories.

```javascript
const path = utils.chooseFile("Please select a subtitle file", {
  allowedFileTypes: ["ass", "srt"],
});
core.subtitle.loadTrack(path);
```

--------------------------------

### Declare Preferences Page in Info.json

Source: https://docs.iina.io/pages/plugin-preferences

Specify the HTML file for your plugin's preference page in the Info.json configuration.

```json
{
  "preferencesPage": "preferences.html"
}
```
Tokens:
Raw