Plugins (User Shaders)

Void Video supports loading external MPV-format .glsl shader plugins at runtime. Plugins can replace or augment the built-in tone mapping pipeline.

Installation

Place .glsl shader files in the shaders/ directory next to the Void Video executable:

void_video
shaders/
  astra.glsl
  my_tonemap.glsl

Void Video scans this directory on startup and loads all .glsl files automatically.

Shader Format

Plugins use the mpv user shader format parsed by libplacebo. A minimal shader looks like:

//!HOOK OUTPUT
//!BIND HOOKED
//!DESC My Custom Shader

vec4 hook() {
    vec4 color = HOOKED_texOff(vec2(0.0));
    // your processing here
    return color;
}

Custom Directives

Void Video extends the mpv format with two additional directives:

Directive	Example	Description
//!CATEGORY	//!CATEGORY hdr/tonemapping	Pipeline insertion category. Tone mapping shaders (hdr/tonemapping) are inserted after the built-in tone mapper and appear in the Tone Curves menu.
//!DESC	//!DESC Astra HDR Tone Mapping	Display name shown in menus. Falls back to the filename if omitted.

These directives must appear before any //!HOOK or //!PARAM lines.

Parameters

Shaders can expose adjustable parameters using //!PARAM:

//!PARAM strength
//!DESC Effect Strength
//!TYPE float
//!MINIMUM 0.0
//!MAXIMUM 1.0
//!DEFAULT 0.5

Parameters automatically generate a menu accessible at:

Main Menu > HDR Settings > Tone Curves > [Shader Name] Parameters

• Float parameters: adjustable with left/right arrow keys
• Integer parameters: increment/decrement or named enum cycling
• Boolean parameters (0/1 range): toggle on/off

Parameter values persist across restarts in shader_params.json.

Tone Mapping Shaders

Shaders with //!CATEGORY hdr/tonemapping integrate into the tone mapping selection:

• They appear as options in Main Menu > HDR Settings > Tone Curves
• Only one tone mapper runs at a time (user shaders are mutually exclusive with built-in algorithms and the Void pipeline)
• Selecting a user shader disables the built-in tone mapper; selecting a built-in algorithm disables the user shader

Pipeline Position

Tone mapping shaders are inserted after the built-in CustomTonemapHook in the pipeline:

EotfInv -> CustomTonemap (disabled) -> [User Shader] -> GamutMap -> Eotf

Non-categorized shaders are appended to the end of the pipeline.