libmpv2

https://github.com/stremio/libmpv2-rs
Admin
libmpv2 is a Rust abstraction for libmpv that provides easy-to-use video and audio playback with...
Tokens:67,109
Snippets:403
Trust Score:8.3
License:LGPL-2.1
Update:2 days ago
Show doc for...
Tokens:
Raw
### Mpv::set_property usage examples

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Examples of setting properties with different types: i64, bool, String/&str, and f64. Each call returns Result<()>.

```rust
mpv.set_property("volume", 15)?;       // i64
mpv.set_property("pause", true)?;      // bool
mpv.set_property("vo", "null")?;       // String / &str
mpv.set_property("sub-gauss", 0.6)?;   // f64
```

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

### Usage example for Mpv::with_initializer

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Sets pre-initialization options like vo, config-dir, and config before creating the Mpv instance.

```rust
use libmpv2::Mpv;

let mpv = Mpv::with_initializer(|init| {
    init.set_property("vo", "libmpv")?;
    init.set_property("config-dir", "test-data")?;
    init.set_property("config", "mpv.conf")?;
    Ok(())
})?;
```

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

### Mpv::get_property usage examples

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Examples of reading properties with different types: i64, bool, and MpvStr. The returned buffer for String/MpvStr is freed with mpv_free.

```rust
let volume: i64 = mpv.get_property("volume")?;
let muted: bool = mpv.get_property("mute")?;
let title: MpvStr = mpv.get_property("media-title")?;
println!("now playing: {title}");
```

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

### MpvInitializer::load_config usage example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

Loads the config file at /etc/mpv/mpv.conf inside the initializer closure.

```rust
Mpv::with_initializer(|init| {
    init.load_config("/etc/mpv/mpv.conf")?;
    Ok(())
})?;
```

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

### Using Mpv::new and set_property

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Example usage of Mpv::new to create an instance and set a property. The ? operator propagates errors from Result<Mpv>.

```rust
use libmpv2::Mpv;

let mpv = Mpv::new()?;
mpv.set_property("volume", 50)?;
```

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

### Error handling example for Mpv::with_initializer

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Handles errors from with_initializer by printing the error and exiting the process.

```rust
match Mpv::with_initializer(|_| Ok(())) {
    Ok(mpv) => mpv,
    Err(e) => {
        eprintln!("failed to create mpv context: {e:?}");
        std::process::exit(1);
    }
}
```

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

### RenderContext::render usage example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Renders the video into the current backbuffer (fbo=0) with the window's drawable size and flip=true. Must be called on the render thread; the example is inside a redraw callback.

```rust
// inside a redraw callback: must run on the render thread
let (width, height) = window.drawable_size();
render_ctx
    .render::<sdl2::VideoSubsystem>(0, width as i32, height as i32, true)
    .expect("failed to draw");
window.gl_swap_window();
```

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

### MpvInitializer::load_config error handling example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

Used by the crate's own test 'config_file' in src/tests.rs. Loads a relative path 'mpv.conf', prints any error, and then asserts the volume property is 50 after initialization.

```rust
let mpv = Mpv::with_initializer(|init| {
    init.load_config("mpv.conf").map_err(|e| {
        eprintln!("failed to load config: {e:?}");
        e
    })?;
    Ok(())
})?;
assert_eq!(mpv.get_property::<i64>("volume")?, 50);
```

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

### RenderContext::new usage example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Initializes an Mpv instance with the 'vo' property set to 'libmpv', then creates a RenderContext with OpenGL init params. The raw handle is obtained via mpv.ctx.as_mut().

```rust
let mut mpv = Mpv::with_initializer(|init| {
    init.set_property("vo", "libmpv")?;
    Ok(())
})?;

let mut render_ctx = RenderContext::new(
    unsafe { mpv.ctx.as_mut() },
    vec![
        RenderParam::ApiType(RenderParamApiType::OpenGl),
        RenderParam::InitParams(OpenGLInitParams {
            get_proc_address,
            ctx: video_subsystem,
        }),
    ],
)?;
```

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

### MpvInitializer::set_option usage example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

Sets the 'config' option to "no" and 'config-dir' to "/nonexistent" inside the initializer closure.

```rust
Mpv::with_initializer(|init| {
    init.set_option("config", "no")?;
    init.set_option("config-dir", "/nonexistent")?;
    Ok(())
})?;
```

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

### Protocol::register usage example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/protocol.md

Shows how to handle the result of register: on success, load a file using the protocol; on error, print a message indicating likely duplicate registration.

```rust
match protocol.register() {
    Ok(()) => mpv.command("loadfile", &["filereader://x.mp4", "append-play"])?,
    Err(e) => eprintln!("registration failed: {e:?}"), // likely already registered
}
```

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

### MpvStr usage in crate tests

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/data-traits.md

Example from the crate's own tests demonstrating MpvStr usage with get_property and type inference.

```rust
let vo: MpvStr = mpv.get_property("vo").unwrap();
assert_eq!("null", &*vo);

let subg: f64 = mpv.get_property("sub-gauss").unwrap();
let volume: i64 = mpv.get_property("volume").unwrap();
```

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

### RenderContext::get_info

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Gets render context info. Returns an error on raw mpv errors; panics on unsupported-info success and unknown flag values.

```APIDOC
## RenderContext::get_info

### Description
Gets render context info. Returns an error on raw mpv errors; panics on unsupported-info success and unknown flag values.

### Method
Method

### Endpoint
`RenderContext::get_info`

### Error Conditions
- `Raw(res)`
- **Panics** on unsupported-info success and on unknown flag values

### Error Type
`Err` (with panic cases)
```

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

### Convenient catch-alls for libmpv2 errors

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Shows three ways to handle errors without full pattern matching: ignore errors with let _, match only the raw code using Error::Raw and mpv_error::PropertyUnavailable, or get a human-readable string via libmpv2_sys::mpv_error_str.

```rust
// ignore errors wholesale
let _ = mpv.set_property("volume", 10);

// match only the raw code, ignore the wrapping
if let Error::Raw(code) = mpv.get_property::<f64>("time-pos") {
    if code == mpv_error::PropertyUnavailable {
        println!("no file playing");
    }
}

// or use the sys helper for a human-readable string
let msg = libmpv2_sys::mpv_error_str(mpv_error::PropertyUnavailable);
println!("{msg}");
```

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

### MpvInitializer::set_property usage example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

Sets the 'osc' property to true and 'volume' to 30 inside the initializer closure. Must be used before mpv_initialize() runs.

```rust
Mpv::with_initializer(|init| {
    init.set_property("osc", true)?;
    init.set_property("volume", 30)?;
    Ok(())
})?;
```

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

### RenderContext::get_info usage example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Queries the next frame info and computes the time until the next frame is available. The match arm is unreachable because get_info always returns the NextFrameInfo variant on success.

```rust
let info = match render_ctx.get_info(RenderParam::NextFrameInfo(RenderFrameInfo {
    flags: RenderFrameInfoFlag::Present,
    target_time: 0,
}))? {
    RenderParam::NextFrameInfo(info) => info,
    _ => unreachable!(),
};
let available_in: i64 = info.target_time - mpv.get_time_us();
```

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

### Mpv::get_property

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Gets a property from the mpv instance. Returns an error on NUL, invalid UTF-8, or raw mpv errors.

```APIDOC
## Mpv::get_property

### Description
Gets a property from the mpv instance. Returns an error on NUL, invalid UTF-8, or raw mpv errors.

### Method
Method

### Endpoint
`Mpv::get_property`

### Error Conditions
- NUL → `Error::Null`
- Invalid UTF-8 → `Error::InvalidUtf8`
- Raw mpv errors → `Raw(PropertyNotFound/PropertyFormat/PropertyUnavailable/PropertyError/...)`

### Error Type
`Err`
```

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

### RenderContext::set_parameter

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Sets a parameter at runtime (mpv_render_context_set_parameter). For example, ICCProfile, AmbientLight, AdvancedControl. Returns Result<()>.

```APIDOC
## RenderContext::set_parameter

### Description
Sets a parameter at runtime (mpv_render_context_set_parameter). For example, ICCProfile, AmbientLight, AdvancedControl. Returns Result<()>.

### Method
Method

### Parameters
- `param` (`RenderParam<C>`) - Required - One parameter

### Returns
`Result<()>`

### Errors
`Error::Raw` — e.g. `MpvError::InvalidParameter` when the parameter is already set or wrong for the backend.

### Example
```rust
render_ctx.set_parameter(RenderParam::ICCProfile(vec![]))?; // reset profile
```
```

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

### RenderContext::set_parameter usage example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Resets the ICC profile by passing an empty vector. This is a runtime parameter change.

```rust
render_ctx.set_parameter(RenderParam::ICCProfile(vec![]))?; // reset profile
```

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

### Protocol::new usage example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/protocol.md

Shows how to create and register a custom protocol named 'filereader' that reads local files. The open, close, read, seek, and size functions are defined to operate on std::fs::File. After registration, loadfile can use the protocol URI.

```rust
use libmpv2::{Mpv, protocol::Protocol};

let mpv = Mpv::new()?;
let protocol = unsafe {
    Protocol::new(
        &mpv,
        "filereader".into(),
        (),
        open, close, read, Some(seek), Some(size),
    )
};
protocol.register()?;
mpv.command("loadfile", &["filereader://data/movie.mp4", "append-play"])?;

fn open(_: &mut (), uri: &str) -> std::fs::File {
    std::fs::File::open(&uri[13..]).unwrap()
}
fn close(file: Box<std::fs::File>) { drop(file); }
fn read(file: &mut std::fs::File, buf: &mut [i8]) -> i64 {
    file.read(unsafe { std::mem::transmute::<&mut [i8], &mut [u8]>(buf) })
        .unwrap() as i64
}
fn seek(file: &mut std::fs::File, offset: i64) -> i64 {
    file.seek(SeekFrom::Start(offset as u64)).unwrap() as i64
}
fn size(file: &mut std::fs::File) -> i64 {
    file.metadata().unwrap().len() as i64
}
```

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

### set_wakeup_callback usage example

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/events.md

Shows how to use set_wakeup_callback with an mpsc channel to wake a loop and process events. The callback sends a signal on the channel; the loop waits with recv_timeout and drains events using wait_event(0.0) until None.

```rust
let (tx, rx) = std::sync::mpsc::channel();
mpv.set_wakeup_callback(move || { let _ = tx.send(()); });

loop {
    match rx.recv_timeout(Duration::from_millis(100)) {
        Ok(()) => while let Some(ev) = mpv.wait_event(0.0) {
            /* handle ev */
        },
        Err(_) => continue,
    }
}
```

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

### Using MpvStr to avoid allocation

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/data-traits.md

Shows how to use MpvStr instead of String to avoid extra allocation when getting properties. The Deref implementation allows direct use as &str.

```rust
let title: MpvStr = mpv.get_property("media-title")?;
println!("title: {title}"); // Deref to &str

let volume: i64 = mpv.get_property("volume")?;
assert_eq!(volume, 100);
```

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

### Mpv::get_time_ns signature

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Returns the internal time in nanoseconds via mpv_get_time_ns. The start offset is arbitrary but the value never wraps or goes backwards. This is real time, not playback status; use the time-pos property for playback. Callable at any time, even inside wakeup callbacks or from mpv render-API threads. Returns a raw i64, not a Result.

```rust
// src/mpv.rs:442
pub fn get_time_ns(&self) -> i64
```

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

### Mpv::get_time_ns

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Returns the internal time in nanoseconds (mpv_get_time_ns). The start offset is arbitrary but the value never wraps or goes backwards. This is real time — use the time-pos property for playback status. Unlike other APIs this is callable at any time (even inside wakeup callbacks or from mpv render-API threads). Note: raw result, not Result.

```APIDOC
## `Mpv::get_time_ns`

### Description
Returns the internal time in nanoseconds (`mpv_get_time_ns`). The start offset is arbitrary but the value never wraps or goes backwards. This is real time — use the `time-pos` property for playback status. Unlike other APIs this is callable at any time (even inside wakeup callbacks or from mpv render-API threads). Note: `raw` result, not `Result`.

### Method
`pub fn get_time_ns(&self) -> i64`

### Parameters
None

### Return Value
- `i64` - The current time in nanoseconds.

### Example
```rust
let start = mpv.get_time_ns();
// ... render loop ...
let elapsed = mpv.get_time_ns() - start;
```
```

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

### Mpv::new / Mpv::with_initializer

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Creates a new Mpv instance. Returns an error on version mismatch, null pointer from mpv_create, initializer failure, or mpv_initialize failure.

```APIDOC
## Mpv::new / Mpv::with_initializer

### Description
Creates a new Mpv instance. Returns an error on version mismatch, null pointer from mpv_create, initializer failure, or mpv_initialize failure.

### Method
Constructor

### Endpoint
`Mpv::new` / `Mpv::with_initializer`

### Error Conditions
- Version mismatch
- `mpv_create` returns null
- Initializer failure
- `mpv_initialize` failure

### Error Type
`Err` (specific error type not specified)
```

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

### MpvInitializer::load_config

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

Loads and parses a config file (wraps `mpv_load_config_file`), setting every entry in the file's default section as if `set_option` had been called for each. `path` should be an absolute path; if not, the actual path used is unspecified.

```APIDOC
## load_config

### Description
Loads and parses a config file (wraps `mpv_load_config_file`), setting every entry in the file's default section as if `MpvInitializer::set_option` had been called for each.

### Method
`pub fn load_config(&self, path: &str) -> Result<()>`

### Parameters
- **path** (`&str`) - Required - Absolute path to a config file

### Returns
`Result<()>`

### Errors
- `Error::Null` - NUL byte
- `Error::Raw(e)` - File not found or fatal error while parsing config file

### Example
```rust
Mpv::with_initializer(|init| {
    init.load_config("/etc/mpv/mpv.conf")?;
    Ok(())
})?;
```
```

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

### Mpv::with_initializer

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Creates a new Mpv instance after running an initializer closure to set pre-initialization options. The function checks API version compatibility, allocates the core, runs the initializer, and initializes the context, returning an error if any step fails.

```APIDOC
## Mpv::with_initializer

### Description
Creates a new `Mpv` after letting `initializer` set options/properties that can only be set *before* initialization. Two steps happen inside:

1. `mpv_client_api_version()` is compared against the compile-time `MPV_CLIENT_API_MAJOR`; on mismatch the function returns `Error::VersionMismatch { linked, loaded }`.
2. `mpv_create()` allocates the core; if it returns null, `Error::Null` is returned. `initializer(MpvInitializer { ctx })` runs, then `mpv_initialize(ctx)` is called. If initialization fails, `ctx` is terminated with `mpv_terminate_destroy` and the error is returned.

Options that can be set here but *not* after initialization:

- options only read at init time: `config`, `config-dir`, `input-conf`, `load-scripts`, `script`, `player-operation-mode`, `input-app-events` (OSX)
- all encoding-mode options

### Method
Function call (Rust)

### Signature
```rust
pub fn with_initializer<F: FnOnce(MpvInitializer) -> Result<()>>(
    initializer: F,
) -> Result<Mpv>
```

### Parameters
- `initializer` (F: FnOnce(MpvInitializer) -> Result<()>) - Required - Closure receiving an `MpvInitializer` used to set pre-init options

### Returns
`Result<Mpv>`

### Errors
- `Error::VersionMismatch` (linked/loaded API major mismatch)
- `Error::Null` (mpv_create returned null)
- any error propagated from `initializer`
- raw init errors (`Error::Raw`)

### Example
```rust
use libmpv2::Mpv;

let mpv = Mpv::with_initializer(|init| {
    init.set_property("vo", "libmpv")?;
    init.set_property("config-dir", "test-data")?;
    init.set_property("config", "mpv.conf")?;
    Ok(())
})?;
```

Error handling:

```rust
match Mpv::with_initializer(|_| Ok(())) {
    Ok(mpv) => mpv,
    Err(e) => {
        eprintln!("failed to create mpv context: {e:?}");
        std::process::exit(1);
    }
}
```
```

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

### StreamSize<T>

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/protocol.md

Callback type for getting the total size of a custom stream. Returns the total size in bytes; panic on error. Optional.

```APIDOC
## StreamSize<T>

### Description
Callback type for getting the total size of a custom stream. Returns the total size in bytes; panic on error. Optional.

### Signature
`fn(&mut T) -> i64`

### Parameters
- **cookie** (`&mut T`) - The per-stream cookie.

### Returns
- **i64** - Total size of the stream in bytes.

### Errors
Panics on error.
```

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

### RenderContext::new

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Creates a new render context. Returns an error from mpv_render_context_create.

```APIDOC
## RenderContext::new

### Description
Creates a new render context. Returns an error from mpv_render_context_create.

### Method
Constructor

### Endpoint
`RenderContext::new`

### Error Conditions
- `Raw` from `mpv_render_context_create`

### Error Type
`Err`
```

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

### Mpv::new signature (src/mpv.rs:310)

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Creates and initializes a new Mpv instance with default options. Equivalent to Mpv::with_initializer(|_| Ok(())). The instance never accesses stdin/stdout/stderr or the terminal, loads no config files, enables idle mode, disables parts of input handling, and is strictly isolated from the command-line player's configuration. Returns Err if out of memory or LC_NUMERIC is not set to "C".

```rust
// src/mpv.rs:310
pub fn new() -> Result<Mpv>
```

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

### MpvInitializer::load_config signature

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

Loads and parses a config file, wrapping mpv_load_config_file. Sets every entry in the file's default section as if set_option had been called for each. Path should be absolute; if not, the actual path used is unspecified.

```rust
// src/mpv.rs:232
pub fn load_config(&self, path: &str) -> Result<()>
```

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

### Mpv::create_client

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Creates a new client handle on the same mpv core via mpv_create_client. Each client has its own event queue. The name parameter is the client name shown in mpv's client list, or None for an automatically generated name.

```APIDOC
## `Mpv::create_client`

### Description
Creates a new client handle on the same mpv core via `mpv_create_client`. Each client has its own event queue. `name` is the client name shown in mpv's client list (pass `None` for an automatically generated name).

### Method
Rust function call

### Signature
```rust
pub fn create_client(&self, name: Option<&str>) -> Result<Mpv>
```

### Parameters
- `name` (Option<&str>) - Required - Client name, or `None` for the default

### Returns
Returns a new independent `Mpv` bound to the same core.

### Errors
- `Error::Null` if `name` contains a NUL byte (`From<NulError>` maps to `Error::Null`)
- Errors from `mpv_create_client` are not checked (the returned handle is wrapped with `NonNull::new_unchecked` unconditionally)

### Example
```rust
let mpv = Mpv::new()?;
let client = mpv.create_client(Some("event-consumer"))?;
client.observe_property("volume", Format::Int64, 0)?;
```
```

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

### Mpv::with_initializer function signature

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Creates a new Mpv after running an initializer closure. Checks API version compatibility and initializes the core, returning errors on failure.

```rust
// src/mpv.rs:330
pub fn with_initializer<F: FnOnce(MpvInitializer) -> Result<()>>(
    initializer: F,
) -> Result<Mpv>
```

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

### Mpv::new

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Creates and initializes a new Mpv instance with default options. The instance is isolated from the command-line player and does not load config files or access the terminal.

```APIDOC
## Mpv::new

### Description
Creates and initializes a new `Mpv` instance with default options. Equivalent to `Mpv::with_initializer(|_| Ok(()))`. The created instance never accesses stdin/stdout/stderr or the terminal, loads no config files, enables idle mode, disables parts of input handling, and is strictly isolated from the command-line player's configuration.

### Method
Constructor

### Signature
```rust
pub fn new() -> Result<Mpv>
```

### Parameters
None

### Returns
`Result<Mpv>` (`libmpv2::Result<Mpv>`)

### Errors
Returns `Err` if out of memory or `LC_NUMERIC` is not set to `"C"` (`Error::Null` or a raw error).

### Example
```rust
use libmpv2::Mpv;

let mpv = Mpv::new()?;
mpv.set_property("volume", 50)?;
```
```

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

### Pattern-match on Error variants and MpvError payload

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Use this loop to catch errors from mpv events. It matches on Error::Raw(MpvError::LoadingFailed) to detect a failed file load, and also handles InvalidUtf8, Null, VersionMismatch, and Loadfile variants. The example loads a missing file with mpv.command and waits for events.

```rust
use libmpv2::{Error, MpvError, mpv_error, Mpv};

let mpv = Mpv::new()?;
mpv.command("loadfile", &["missing-file.mp4", "append-play"])?;

loop {
    match mpv.wait_event(1.0) {
        Some(Ok(_)) => {}
        Some(Err(e)) => {
            match e {
                Error::Raw(MpvError::LoadingFailed) => {
                    eprintln!("file failed to load");
                    break;
                }
                Error::InvalidUtf8 => eprintln!("bad utf-8 from player"),
                Error::Null => eprintln!("nul byte / null handle"),
                Error::VersionMismatch { linked, loaded } => {
                    eprintln!("linked {linked:#x} vs loaded {loaded:#x}");
                }
                Error::Loadfile { error } => eprintln!("load failure: {error:?}"),
                other => eprintln!("unexpected: {other:?}"),
            }
        }
        None => {}
    }
}
```

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

### MpvInitializer::set_option signature

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

Sets the value of an option, wrapping mpv_set_option. Options are static configuration that generally cannot change at runtime once the core is initialized. Correct method for options only read at initialization time.

```rust
// src/mpv.rs:214
pub fn set_option<T: SetData>(&self, name: &str, data: T) -> Result<()>
```

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

### Create a new client handle with Mpv::create_client

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Creates an independent Mpv handle on the same core via mpv_create_client. Each client has its own event queue; pass None for an automatically generated name. Returns Error::Null if name contains a NUL byte; errors from mpv_create_client are not checked.

```rust
// src/mpv.rs:360
pub fn create_client(&self, name: Option<&str>) -> Result<Mpv>
```

```rust
let mpv = Mpv::new()?;
let client = mpv.create_client(Some("event-consumer"))?;
client.observe_property("volume", Format::Int64, 0)?;
```

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

### MpvInitializer::set_option / load_config

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Sets an option or loads a config file. Returns an error on NUL or raw mpv errors.

```APIDOC
## MpvInitializer::set_option / load_config

### Description
Sets an option or loads a config file. Returns an error on NUL or raw mpv errors.

### Method
Method

### Endpoint
`MpvInitializer::set_option` / `MpvInitializer::load_config`

### Error Conditions
- NUL → `Error::Null`
- Raw mpv errors → `Raw(OptionNotFound/OptionFormat/OptionError)` for set_option; config-file errors for load_config

### Error Type
`Err`
```

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

### RenderContext::new

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Creates a new RenderContext with the given parameters. The parameters must include ApiType(OpenGl) and InitParams(...). Returns a Result<RenderContext>.

```APIDOC
## RenderContext::new

### Description
Creates a new RenderContext with the given parameters. The parameters must include ApiType(OpenGl) and InitParams(...). Returns a Result<RenderContext>.

### Method
Constructor

### Parameters
- `mpv` (`&mut libmpv2_sys::mpv_handle`) - Required - The raw handle from `mpv.ctx.as_mut()`
- `params` (`impl IntoIterator<Item = RenderParam<C>>`) - Required - Params; must include `ApiType(OpenGl)` and `InitParams(...)`; array is auto-terminated with type 0

### Returns
`Result<RenderContext>`

### Errors
`Error::Raw(e)` from `mpv_render_context_create` on failure (e.g. `MpvError::InvalidParameter` for missing/duplicate required params).

### Example
```rust
let mut mpv = Mpv::with_initializer(|init| {
    init.set_property("vo", "libmpv")?;
    Ok(())
})?;

let mut render_ctx = RenderContext::new(
    unsafe { mpv.ctx.as_mut() },
    vec![
        RenderParam::ApiType(RenderParamApiType::OpenGl),
        RenderParam::InitParams(OpenGLInitParams {
            get_proc_address,
            ctx: video_subsystem,
        }),
    ],
)?;
```
```

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

### OpenGLInitParams<GLContext>

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Parameters for initializing the OpenGL render backend. Provides a callback to resolve OpenGL function pointers and a context cookie passed to that callback.

```APIDOC
## OpenGLInitParams<GLContext>

### Description
Parameters for initializing the OpenGL render backend. Provides a callback to resolve OpenGL function pointers and a context cookie passed to that callback.

### Fields
- **get_proc_address** (`fn(ctx: &GLContext, name: &str) -> *mut c_void`) - Required - Resolves one GL function by name; returns null for unknown names.
- **ctx** (`GLContext`) - Required - Cookie passed as the `ctx` parameter to the callback.

### Usage
Used for `RenderParam::InitParams`. The `GLContext` value is boxed and kept alive by the render context until a later `mpv_render_param::from` for `InitParams` frees it through the `free_init_params` deleter.
```

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

### MpvInitializer::set_property

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

Sets a property to a given value before initialization. Wraps mpv_set_property on the raw handle. Properties not backed by options generally cannot be set before init and will return an error.

```APIDOC
## set_property

### Description
Sets a property to a given value (wraps `mpv_set_property`). Properties are variables that can be queried or set at runtime. Properties not backed by options generally cannot be set before init.

### Method
`pub fn set_property<T: SetData>(&self, name: &str, data: T) -> Result<()>`

### Parameters
- **name** (`&str`) - Required - Property name, e.g. `"volume"`, `"osc"`
- **data** (`T: SetData`) - Required - Value (`f64` | `i64` | `bool` | `String` | `&str`)

### Returns
`Result<()>`

### Errors
- `Error::Null` - NUL byte in `name`
- `Error::Raw(e)` - Format mismatch / property error

### Example
```rust
Mpv::with_initializer(|init| {
    init.set_property("osc", true)?;
    init.set_property("volume", 30)?;
    Ok(())
})?;
```
```

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

### MpvInitializer::set_option

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

Sets the value of an option (wraps `mpv_set_option`). Options are static configuration and generally cannot change at runtime once the core is initialized. This is the correct method for options read only at initialization time.

```APIDOC
## set_option

### Description
Sets the value of an option (wraps `mpv_set_option`). Options are static configuration; unlike properties they generally cannot change at runtime once the core is initialized.

### Method
`pub fn set_option<T: SetData>(&self, name: &str, data: T) -> Result<()>`

### Parameters
- **name** (`&str`) - Required - Option name, e.g. `"config"`, `"config-dir"`
- **data** (`T: SetData`) - Required - Value (`f64` | `i64` | `bool` | `String` | `&str`)

### Returns
`Result<()>`

### Errors
- `Error::Null` - NUL byte
- `Error::Raw(e)` - e.g. `MpvError::OptionNotFound`, `MpvError::OptionFormat`, `MpvError::OptionError`

### Example
```rust
Mpv::with_initializer(|init| {
    init.set_option("config", "no")?;
    init.set_option("config-dir", "/nonexistent")?;
    Ok(())
})?;
```
```

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

### Module-level constants

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Re-exported at crate root (`use libmpv2::MPV_CLIENT_API_VERSION`). The compile-time version the crate was built against; used by `with_initializer` for the `Error::VersionMismatch` check against the loaded library's `mpv_client_api_version()`. libmpv 2.0 (mpv 0.35.0) is the minimum required version.

```APIDOC
## Module-level constants

### Description
Re-exported at crate root (`use libmpv2::MPV_CLIENT_API_VERSION`). The compile-time version the crate was built against; used by `with_initializer` for the `Error::VersionMismatch` check against the loaded library's `mpv_client_api_version()`. libmpv 2.0 (mpv 0.35.0) is the minimum required version.

### Constants
- `MPV_CLIENT_API_MAJOR` (`ctype::c_ulong`) - Major version number (2).
- `MPV_CLIENT_API_MINOR` (`ctype::c_ulong`) - Minor version number (2).
- `MPV_CLIENT_API_VERSION` (`ctype::c_ulong`) - Combined version (major << 16 | minor).

### Example
```rust
pub const MPV_CLIENT_API_MAJOR: ctype::c_ulong = 2;
pub const MPV_CLIENT_API_MINOR: ctype::c_ulong = 2;
pub const MPV_CLIENT_API_VERSION: ctype::c_ulong =
    MPV_CLIENT_API_MAJOR << 16 | MPV_CLIENT_API_MINOR;
```
```

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

### RenderContext::get_info

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Queries renderer info (mpv_render_context_get_info). Only RenderParam::NextFrameInfo(_) is supported. Returns Result<RenderParam<C>>.

```APIDOC
## RenderContext::get_info

### Description
Queries renderer info (mpv_render_context_get_info). Only RenderParam::NextFrameInfo(_) is supported. Returns Result<RenderParam<C>>.

### Method
Method

### Parameters
- `param` (`RenderParam<C>`) - Required - Must be `NextFrameInfo`

### Returns
`Result<RenderParam<C>>` — always the `NextFrameInfo` variant on success.

### Errors
`Error::Raw(res)` from mpv; **panics** ("I don't know how to handle this info type.") if a non-`NextFrameInfo` param returns success, and `From<u64>` for `flags` panics on unknown flag values.

### Example
```rust
let info = match render_ctx.get_info(RenderParam::NextFrameInfo(RenderFrameInfo {
    flags: RenderFrameInfoFlag::Present,
    target_time: 0,
}))? {
    RenderParam::NextFrameInfo(info) => info,
    _ => unreachable!(),
};
let available_in: i64 = info.target_time - mpv.get_time_us();
```
```

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

### Mpv::command

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Sends a command to the player via mpv_command. Commands are the same as those used in input.conf (e.g. loadfile, seek, playlist-next). The name parameter is the command name and args are the command arguments.

```APIDOC
## `Mpv::command`

### Description
Sends a command to the player via `mpv_command`. Commands are the same as those used in `input.conf` (e.g. `loadfile`, `seek`, `playlist-next`). `name` is the command name; `args` are the command arguments. Both are converted to C strings (NUL bytes produce `Error::Null`).

### Method
Rust function call

### Signature
```rust
pub fn command(&self, name: &str, args: &[&str]) -> Result<()>
```

### Parameters
- `name` (&str) - Required - Command name, e.g. `"loadfile"`
- `args` (&[&str]) - Required - Command arguments

### Returns
Returns `Result<()>`.

### Errors
- `Error::Null` on embedded NUL
- `Error::Raw(e)` with e.g. `MpvError::Command`, `MpvError::NothingToPlay`, `MpvError::LoadingFailed` depending on the command
- `Error::InvalidUtf8` is not produced here

### Example
```rust
mpv.command("loadfile", &["test-data/jellyfish.mp4", "append-play"])?;
mpv.command("seek", &["15"])?;
mpv.command("playlist-next", &["force"])?;
```
```

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

### RenderContext::set_parameter / render

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Sets a parameter or renders. Returns an error from mpv.

```APIDOC
## RenderContext::set_parameter / render

### Description
Sets a parameter or renders. Returns an error from mpv.

### Method
Method

### Endpoint
`RenderContext::set_parameter` / `RenderContext::render`

### Error Conditions
- `Raw` from mpv

### Error Type
`Err`
```

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

### Cargo features in Cargo.toml

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/configuration.md

Defines the default and optional Cargo features for the crate. The `render` feature is enabled by default and compiles the `libmpv2::render` module. The `build_libmpv` feature is off by default and activates build.rs logic to build libmpv from source, requiring the `MPV_SOURCE` environment variable.

```toml
[features]
default = ["render"]
render = []          # Enable custom rendering
build_libmpv = []    # build libmpv automatically, provided MPV_SOURCE is set
```

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

### Mpv::create_client

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Creates a new client handle. Returns an error if the client name contains a NUL byte.

```APIDOC
## Mpv::create_client

### Description
Creates a new client handle. Returns an error if the client name contains a NUL byte.

### Method
Method

### Endpoint
`Mpv::create_client`

### Error Conditions
- Client name contains NUL → `Error::Null`

### Error Type
`Err`
```

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

### RenderContext::new signature

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Creates a RenderContext from a raw mpv_handle and render parameters. Params must include ApiType(OpenGl) and InitParams(...); the array is auto-terminated with type 0. Returns Result<RenderContext>.

```rust
// src/mpv/render.rs:204
pub fn new<C>(
    mpv: &mut libmpv2_sys::mpv_handle,
    params: impl IntoIterator<Item = RenderParam<C>>,
) -> Result<Self>
```

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

### MpvInitializer::set_property signature

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

Sets a property to a given value, wrapping mpv_set_property on the raw handle. Properties are runtime variables (e.g. pause). Returns Err if the format T doesn't match the property's internal format or when setting properties not backed by options.

```rust
// src/mpv.rs:203
pub fn set_property<T: SetData>(&self, name: &str, data: T) -> Result<()>
```

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

### report_swap: Report frame flip after GL swap

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Reports that a frame was flipped via mpv_render_context_report_swap. Optional but improves timing; calling it at least once informs libmpv you'll use it. Ignored while no video is initialized. No return value.

```rust
// src/mpv/render.rs:370
pub fn report_swap(&self)
```

```rust
render_ctx.render::<GL>(0, w, h, true)?;

// after the GL swap / vsync
render_ctx.report_swap();
```

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

### Send commands with Mpv::command

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Sends a command to the player via mpv_command, using the same commands as input.conf (e.g. loadfile, seek, playlist-next). Both name and args are converted to C strings; embedded NUL bytes produce Error::Null. Returns Error::Raw with MpvError variants like Command, NothingToPlay, or LoadingFailed depending on the command.

```rust
// src/mpv.rs:382
pub fn command(&self, name: &str, args: &[&str]) -> Result<()>
```

```rust
mpv.command("loadfile", &["test-data/jellyfish.mp4", "append-play"])?;
mpv.command("seek", &["15"])?;
mpv.command("playlist-next", &["force"])?;
```

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

### OpenGLInitParams struct definition

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Defines the OpenGL initialization parameters for RenderParam::InitParams. get_proc_address resolves GL function pointers; ctx is passed to the callback on every call.

```rust
// src/mpv/render.rs:15
pub struct OpenGLInitParams<GLContext> {
    pub get_proc_address: fn(ctx: &GLContext, name: &str) -> *mut c_void,
    pub ctx: GLContext,
}
```

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

### RenderContext::update

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Updates the render context. Returns an error if the update flag bitset fails conversion.

```APIDOC
## RenderContext::update

### Description
Updates the render context. Returns an error if the update flag bitset fails conversion.

### Method
Method

### Endpoint
`RenderContext::update`

### Error Conditions
- `Err(Raw(Generic))` if the update flag bitset fails `try_into` conversion

### Error Type
`Err`
```

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

### RenderContext::get_info signature

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Queries renderer info via mpv_render_context_get_info. Only RenderParam::NextFrameInfo is supported; the C-level function returns 0 and the raw mpv_render_frame_info is converted to RenderParam::NextFrameInfo.

```rust
// src/mpv/render.rs:271
pub fn get_info<C>(&self, param: RenderParam<C>) -> Result<RenderParam<C>>
```

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

### Module-level MPV client API constants

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Constants defining the compile-time libmpv client API version the crate was built against. Re-exported at crate root as MPV_CLIENT_API_VERSION. Used by with_initializer for the Error::VersionMismatch check against the loaded library's mpv_client_api_version(). libmpv 2.0 (mpv 0.35.0) is the minimum required version.

```rust
pub const MPV_CLIENT_API_MAJOR: ctype::c_ulong = 2;
pub const MPV_CLIENT_API_MINOR: ctype::c_ulong = 2;
pub const MPV_CLIENT_API_VERSION: ctype::c_ulong =
    MPV_CLIENT_API_MAJOR << 16 | MPV_CLIENT_API_MINOR;
```

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

### MpvInitializer struct definition

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv-initializer.md

The context passed to the initializer closure of Mpv::with_initializer. Wraps the un-initialized raw mpv_handle and is consumed by Mpv::with_initializer. Not Send/Sync and owns no memory.

```rust
// src/mpv.rs:191
pub struct MpvInitializer {
    ctx: *mut libmpv2_sys::mpv_handle,
}
```

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

### Mpv::command

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/errors.md

Executes a command on the mpv instance. Returns an error on NUL in name/args or C command failure.

```APIDOC
## Mpv::command

### Description
Executes a command on the mpv instance. Returns an error on NUL in name/args or C command failure.

### Method
Method

### Endpoint
`Mpv::command`

### Error Conditions
- NUL in name/args → `Error::Null`
- C command failure → `Raw(Command | NothingToPlay | LoadingFailed | ...)`

### Error Type
`Err`
```

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

### Using get_time_ns to measure elapsed time

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/mpv.md

Shows how to measure elapsed time between two calls to get_time_ns, typically around a render loop. The difference is in nanoseconds.

```rust
let start = mpv.get_time_ns();
// ... render loop ...
let elapsed = mpv.get_time_ns() - start;
```

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

### RenderContext::report_swap

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Reports that a frame was flipped, improving timing. Optional but recommended; calling it at least once informs libmpv that you will use it. No return value.

```APIDOC
## `RenderContext::report_swap`

### Description
Reports that a frame was flipped (`mpv_render_context_report_swap`); optional but improves timing. Calling it at least once informs libmpv you'll use it — using it inconsistently gives bad playback. Ignored while no video is initialized. No return value.

### Method
`report_swap`

### Parameters
None

### Return Value
None

### Example
```rust
render_ctx.render::<GL>(0, w, h, true)?;

// after the GL swap / vsync
render_ctx.report_swap();
```
```

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

### set_update_callback: Set redraw notification callback

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/render.md

Sets the callback that fires when a new frame is available or video display configuration changed (mpv_render_context_set_update_callback). Same restrictions as Mpv::set_wakeup_callback: no mpv API calls inside, no long blocking, no exceptions; wake another thread instead. Callable from any thread except an update callback itself, and from no OpenGL context/state access. Calling this raises an update immediately; replacing the callback runs the previous cleanup; Drop runs it too.

```rust
// src/mpv/render.rs:383
pub fn set_update_callback<F: Fn() + Send + 'static>(&mut self, callback: F)
```

```rust
let (tx, rx) = std::sync::mpsc::channel();
render_ctx.set_update_callback(move || {
    let _ = tx.send(RenderSignal::RedrawRequested);
});
```

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

### Protocol::new unsafe constructor

Source: https://github.com/stremio/libmpv2-rs/blob/master/_autodocs/api-reference/protocol.md

Creates a new Protocol with the given callbacks and user_data. Does not register the protocol; call register after. Safety: do not call any libmpv function inside the supplied functions. Panics are caught and converted to generic errors.

```rust
// src/mpv/protocol.rs:193
pub unsafe fn new(
    mpv: &'parent Mpv,
    name: String,
    user_data: U,
    open_fn: StreamOpen<T, U>,
    close_fn: StreamClose<T>,
    read_fn: StreamRead<T>,
    seek_fn: Option<StreamSeek<T>>,
    size_fn: Option<StreamSize<T>>,
) -> Protocol<'parent, T, U>
```
Tokens:
Raw