Plugin System

The plugin system allows you to extend IINA's functionality with JavaScript. You can control the playback, call the mpv API, access the network and file system, adding custom UI elements, and more. The plugin system is available in IINA 1.4.0.

Concise API, powerful features

With several lines of code, you can implement the exact feature tailored to your needs. Furthermore, with the Official User Scripts plugin, you can just copy-and-paste code snippets into IINA without writing plugin packages.

const { core, event, overlay } = iina;
event.on("iina.file-loaded", () => {
  overlay.simpleMode();
  overlay.setContent(`<p>${core.status.title}</p>`);
  overlay.setStyle(`p { font-size: 48px; }`);
  overlay.show();
})
Display the video title in a large font on the top of the video
const { core, event } = iina;
event.on("mpv.pause.changed", () => {
  core.window.miniaturized = core.status.paused;
});
event.on("iina.window-deminiaturized", () => {
  core.resume();
});
Minimize the window when the video is paused, and resume when restored

What you can do with the plugin system

Core
Control the playback and get/set various status from the window frame to subtitle tracks.
MPV
Access the mpv API with properties and hooks for advanced playback control.
Event
Register and remove listeners for IINA and mpv events.
HTTP
Make HTTP and XMLRPC requests.
Playlist
Control the playlist and add custom playlist context menu items.
Subtitle
Register custom subtitle downloaders that integrates with IINA's user interface.
Menu
Add menu items with keyboard shortcuts under the Plugin menu.
Overlay
Render custom webview-based content on the top of videos.
Sidebar View
Add a tab in the sidebar with custom webview-based contents.
Standalone Window
Display a webview-based standalone window for complicated user interface.
Global Controller
Spawn and control multiple player instances.
File
Access the user file system or read/write sandboxed temporary files and data files.
Preferences
Store preferences and display a settings page in IINA's preferences panel.
Utils
Display system dialogs and run custom executables.
Console
Print logs for debugging, viewable from IINA's log viewer.

Start building your plugin

An iina-plugin command line tool is included with the IINA installation to help you create, build, and run plugins. We have also prepared a complete documentation with tutorials and API references.

Read the documentation
at docs.iina.io

You may also find these resources helpful:

  • Official User Scripts plugin: simply enter iina/iina-plugin-userscript when installing.
  • TypeScript definitions: TypeScript definitions for the plugin API. It is included automatically when you create a new plugin with the iina-plugin command line tool.