Interface Overlay

The Overlay module provides a way to render custom contents on top of the video, which can be used to display lyrics, statistics, live comments, etc. The overlay is essentially a web view, therefore you can use HTML, CSS, and advanced techniques like WebGL to render the contents.

Two modes are provided to load the overlay contents:

"Simple Mode": activated by calling overlay.simpleMode(). In this mode, you directly set the HTML and CSS contents of the overlay using overlay.setContent() and overlay.setStyle().
Loading a HTML page: activated by calling overlay.loadFile(). The HTML file should contain the CSS and JavaScript code to render the contents.

When activating either mode, the previous mode will be deactivated and the overlay will be cleared.

As a web view, the overlay has its own JavaScript context, which cannot access the IINA API directly. It can only communicate with the plugin script via iina.postMessage and iina.onMessage to exchange data. See API in Web Views for more information.

Example

// simple mode
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();

Available In Entry

Main entry only

Hierarchy

Overlay

Index

Methods

show hide setOpacity setClickable loadFile simpleMode setStyle setContent postMessage onMessage

Methods

show

show(): void
Show the overlay. The overlay is hidden by default and you need to call this method to show it.

Returns void
- Defined in index.d.ts:1470

hide

hide(): void
Hide the overlay.

Returns void
- Defined in index.d.ts:1474

setOpacity

setOpacity(opacity: number): void
Set the opacity of the overlay.
Parameters
- opacity: number
  
  The opacity of the overlay, from 0 to 1.
Returns void
- Defined in index.d.ts:1479

setClickable

setClickable(clickable: boolean): void
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. In this case, buttons will become clickable and input fields will become editable. See API in Web Views for more information.
```
<button data-clickable>Click Me</button>
<input type="text" data-clickable>
```
Parameters
- clickable: boolean
  
  Whether the overlay is clickable.
Returns void
- Defined in index.d.ts:1494

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
- Defined in index.d.ts:1505

simpleMode

simpleMode(): void
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.

Returns void
- Defined in index.d.ts:1510

setStyle

setStyle(style: string): void
(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>. The suggested usage is to call setStyle once when activating the simple mode, and then use setContent (probably multiple times) to update the contents.
```
<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
- Defined in index.d.ts:1526

setContent

setContent(content: string): void
(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.
```
<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
- Defined in index.d.ts:1540

postMessage

postMessage(name: string, data: any): void
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. See API in Web Views for more information.
Parameters
- name: string
  
  The message name.
- data: any
  
  The message data.
Returns void
- Defined in index.d.ts:1548

onMessage

onMessage(name: string, callback: ((data: any) => void)): void
Register a listener for messages posted by the overlay webview. The overlay webview also has two methods, iina.postMessage and iina.onMessage, to exchange data with the plugin script. See API in Web Views for more information.
Parameters
- name: string
  
  The message name.
- callback: ((data: any) => void)
  
  The callback to be called when a message with the given name is received.
  - - (data: any): void
    - Parameters
      
      data: any
      
      The message data, posted by the JS script inside the overlay webview.
      
      Returns void
Returns void
- Defined in index.d.ts:1556

Interface Overlay

Example

Available In Entry

Hierarchy

Index

Methods

Methods

show

Returns void

hide

Returns void

setOpacity

Parameters

opacity: number

Returns void

setClickable

Parameters

clickable: boolean

Returns void

loadFile

Parameters

path: string

Returns void

simpleMode

Returns void

setStyle

Parameters

style: string

Returns void

setContent

Parameters

content: string

Returns void

postMessage

Parameters

name: string

data: any

Returns void

onMessage

Parameters

name: string

callback: ((data: any) => void)

Parameters

data: any

Returns void

Returns void

Settings

Member Visibility

Theme