Struct mpv_client::Handle

pub struct Handle(_);

Client context used by the client API. Every client has its own private handle.

Implementations

impl Handle

pub fn from_ptr(ptr: RawHandle) -> Self

Wrap a raw mpv_handle The pointer must not be null

pub fn wait_event(&self, timeout: f64) -> Event

Wait for the next event, or until the timeout expires, or if another thread makes a call to mpv_wakeup(). Passing 0 as timeout will never wait, and is suitable for polling.

The internal event queue has a limited size (per client handle). If you don’t empty the event queue quickly enough with Handle::wait_event, it will overflow and silently discard further events. If this happens, making asynchronous requests will fail as well (with MPV_ERROR_EVENT_QUEUE_FULL).

Only one thread is allowed to call this on the same Handle at a time. The API won’t complain if more than one thread calls this, but it will cause race conditions in the client when accessing the shared mpv_event struct. Note that most other API functions are not restricted by this, and no API function internally calls mpv_wait_event(). Additionally, concurrent calls to different handles are always safe.

As long as the timeout is 0, this is safe to be called from mpv render API threads.

pub fn client_name(&self) -> &str

Return the name of this client handle. Every client has its own unique name, which is mostly used for user interface purposes.

pub fn command<I, S>(&self, args: I) -> Result<(), Error>where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,

Send a command to the player. Commands are the same as those used in input.conf, except that this function takes parameters in a pre-split form.

pub fn command_async<I, S>(
    &self,
    reply_userdata: u64,
    args: I
) -> Result<(), Error>where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,

Same as Handle::command, but run the command asynchronously.

Commands are executed asynchronously. You will receive a CommandReply event. This event will also have an error code set if running the command failed. For commands that return data, the data is put into mpv_event_command.result.

The only case when you do not receive an event is when the function call itself fails. This happens only if parsing the command itself (or otherwise validating it) fails, i.e. the return code of the API call is not 0 or positive.

Safe to be called from mpv render API threads.

pub fn osd_message<S: AsRef<str>>(
    &self,
    text: S,
    duration: Duration
) -> Result<(), Error>

Display a message on the screen. See Handle::command

pub fn osd_message_async<S: AsRef<str>>(
    &self,
    reply_userdata: u64,
    text: S,
    duration: Duration
) -> Result<(), Error>

Same as Handle::osd_command, but run the command asynchronously. See Handle::command_async

pub fn set_property<T: Format>(&self, name: &str, data: T) -> Result<(), Error>

pub fn get_property<T: Format>(&self, name: &str) -> Result<T, Error>

Read the value of the given property.

If the format doesn’t match with the internal format of the property, access usually will fail with MPV_ERROR_PROPERTY_FORMAT. In some cases, the data is automatically converted and access succeeds. For example, i64 is always converted to f64, and access using String usually invokes a string formatter.

pub fn observe_property<T: Format>(
    &self,
    reply_userdata: u64,
    name: &str
) -> Result<(), Error>

pub fn unobserve_property(
    &self,
    registered_reply_userdata: u64
) -> Result<(), Error>

Undo Handle::observe_property. This will remove all observed properties for which the given number was passed as reply_userdata to Handle::observe_property.

Safe to be called from mpv render API threads.

pub fn hook_add(
    &self,
    reply_userdata: u64,
    name: &str,
    priority: i32
) -> Result<(), Error>

pub fn hook_continue(&self, id: u64) -> Result<(), Error>