Crate libmpv_sys
source ·Re-exports
pub use self::mpv_render_update_flag as mpv_render_context_flag;Structs
(see mpv_node)
Since API version 1.108.
Generic data storage.
(see mpv_node)
For MPV_RENDER_PARAM_DRM_DRAW_SURFACE_SIZE.
Deprecated. For MPV_RENDER_PARAM_DRM_DISPLAY.
For MPV_RENDER_PARAM_DRM_DISPLAY_V2.
For MPV_RENDER_PARAM_OPENGL_FBO.
For initializing the mpv OpenGL state via MPV_RENDER_PARAM_OPENGL_INIT_PARAMS.
Information about the next video frame that will be rendered. Can be
retrieved with MPV_RENDER_PARAM_NEXT_FRAME_INFO.
Used to pass arbitrary parameters to some mpv_render_* functions. The
meaning of the data parameter is determined by the type, and each
MPV_RENDER_PARAM_* documents what type the value must point to.
See mpv_stream_cb_open_ro_fn callback.
Constants
The end of file was reached. Sometimes this may also happen on
incomplete or corrupted files, or if the network connection was
interrupted when playing a remote file. It also happens if the
playback range was restricted with –end or –frames or similar.
Some kind of error happened that lead to playback abort. Does not
necessarily happen on incomplete or broken files (in these cases, both
MPV_END_FILE_REASON_ERROR or MPV_END_FILE_REASON_EOF are possible).
Playback was stopped by the quit command or player shutdown.
The file was a playlist or similar. When the playlist is read, its
entries will be appended to the playlist after the entry of the current
file, the entry of the current file is removed, and a MPV_EVENT_END_FILE
event is sent with reason set to MPV_END_FILE_REASON_REDIRECT. Then
playback continues with the playlist contents.
Since API version 1.18.
Playback was stopped by an external action (e.g. playlist controls).
Initializing the audio output failed.
General error when running a command with mpv_command and similar.
The event ringbuffer is full. This means the client is choked, and can’t
receive any events. This can happen when too many asynchronous requests
have been made, but not answered. Probably never happens in practice,
unless the mpv core is frozen for some reason, and the client keeps
making asynchronous requests. (Bugs in the client API implementation
could also trigger this, e.g. if events become “lost”.)
Unspecified error.
Generic catch-all error if a parameter is set to an invalid or
unsupported value. This is used if there is no better error code.
Generic error on loading (usually used with mpv_event_end_file.error).
Memory allocation failed.
There was no audio or video data to play. This also happens if the
file was recognized, but did not contain any audio or video streams,
or no streams were selected.
The API function which was called is a stub only.
Setting the option failed. Typically this happens if the provided option
value could not be parsed.
Trying to set an option using an unsupported MPV_FORMAT.
Trying to set an option that doesn’t exist.
Error setting or getting a property.
Trying to set or get a property using an unsupported MPV_FORMAT.
The accessed property doesn’t exist.
The property exists, but is not available. This usually happens when the
associated subsystem is not active, e.g. querying audio parameters while
audio is disabled.
No error happened (used to signal successful operation).
Keep in mind that many API functions returning error codes can also
return positive values, which also indicate success. API users can
hardcode the fact that “>= 0” means success.
The mpv core wasn’t configured and initialized yet. See the notes in
mpv_create().
When trying to load the file, the file format could not be determined,
or the file was too broken to open it.
Generic error for signaling that certain system requirements are not
fulfilled.
Initializing the video output failed.
Similar to MPV_EVENT_VIDEO_RECONFIG. This is relatively uninteresting,
because there is no such thing as audio output embedding.
Triggered by the script-message input command. The command uses the
first argument of the command as client name (see mpv_client_name()) to
dispatch the message, and passes along all arguments starting from the
second argument as strings.
See also mpv_event and mpv_event_client_message.
Reply to a mpv_command_async() or mpv_command_node_async() request.
See also mpv_event and mpv_event_command.
Notification after playback end (after the file was unloaded).
See also mpv_event and mpv_event_end_file.
Notification when the file has been loaded (headers were read etc.), and
decoding starts.
Reply to a mpv_get_property_async() request.
See also mpv_event and mpv_event_property.
Triggered if a hook handler was registered with mpv_hook_add(), and the
hook is invoked. If you receive this, you must handle it, and continue
the hook with mpv_hook_continue().
See also mpv_event and mpv_event_hook.
Idle mode was entered. In this mode, no file is played, and the playback
core waits for new commands. (The command line player normally quits
instead of entering idle mode, unless –idle was specified. If mpv
was started with mpv_create(), idle mode is enabled by default.)
See mpv_request_log_messages().
Nothing happened. Happens on timeouts or sporadic wakeups.
There was a discontinuity of some sort (like a seek), and playback
was reinitialized. Usually happens on start of playback and after
seeking. The main purpose is allowing the client to detect when a seek
request is finished.
Event sent due to mpv_observe_property().
See also mpv_event and mpv_event_property.
Happens if the internal per-mpv_handle ringbuffer overflows, and at
least 1 event had to be dropped. This can happen if the client doesn’t
read the event queue quickly enough with mpv_wait_event(), or if the
client makes a very large number of asynchronous calls at once.
Happens when a seek was initiated. Playback stops. Usually it will
resume with MPV_EVENT_PLAYBACK_RESTART as soon as the seek is finished.
Reply to a mpv_set_property_async() request.
(Unlike MPV_EVENT_GET_PROPERTY, mpv_event_property is not used.)
Happens when the player quits. The player enters a state where it tries
to disconnect all clients. Most requests to the player will fail, and
the client should react to this and quit with mpv_destroy() as soon as
possible.
Notification before playback start of a file (before the file is loaded).
See also mpv_event and mpv_event_start_file.
Sent every time after a video frame is displayed. Note that currently,
this will be sent in lower frequency if there is no video, or playback
is paused - but that will be removed in the future, and it will be
restricted to video frames only.
Happens after video changed in some way. This can happen on resolution
changes, pixel format changes, or video filter changes. The event is
sent after the video filters and the VO are reconfigured. Applications
embedding a mpv window should listen to this event in order to resize
the window if needed.
Note that this event can happen sporadically, and you should check
yourself whether the video parameters really changed before doing
something expensive.
A raw, untyped byte array. Only used only with mpv_node, and only in
some very specific situations. (Some commands use it.)
The basic type is double.
The basic type is int. The only allowed values are 0 (“no”)
and 1 (“yes”).
The basic type is int64_t.
The type is mpv_node.
Used with mpv_node only. Can usually not be used directly.
See MPV_FORMAT_NODE_ARRAY.
Invalid. Sometimes used for empty values. This is always defined to 0,
so a normal 0-init of mpv_format (or e.g. mpv_node) is guaranteed to set
this it to MPV_FORMAT_NONE (which makes some things saner as consequence).
The basic type is char*. It returns the OSD property string, like
using ${property} in input.conf (see input.rst). In many cases, this
is the same as the raw string, but in other cases it’s formatted for
display on OSD. It’s intended to be human readable. Do not attempt to
parse these strings.
The basic type is char*. It returns the raw property string, like
using ${=property} in input.conf (see input.rst).
“v” - noisy informational message
“fatal” - critical/aborting errors
“no” - disable absolutely all messages
“warn” - possible problems
“debug” - very noisy technical information
“info” - informational message
“error” - simple errors
If set, the player timing code expects that the user thread blocks on
vsync (by either delaying the render call, or by making a call to
mpv_render_context_report_swap() at vsync time).
Set if there is actually a next frame. If unset, there is no next frame
yet, and other flags and fields that require a frame to be queued will
be unset.
If set, the frame is not an actual new video frame, but a redraw request.
For example if the video is paused, and an option that affects video
rendering was changed (or any other reason), an update request can be
issued and this flag will be set.
If set, this is supposed to reproduce the previous frame perfectly. This
is usually used for certain “video-sync” options (“display-…” modes).
Typically the renderer will blit the video from a FBO. Unset otherwise.
Better control about rendering and enabling some advanced features. Valid
for mpv_render_context_create().
Ambient light in lux. Valid for mpv_render_context_set_parameter().
Type: int*
This can be used for automatic gamma correction.
The render API to use. Valid for mpv_render_context_create().
Enable or disable video timing. Valid for mpv_render_context_render().
Control surface depth. Valid for mpv_render_context_render().
Type: int*
This implies the depth of the surface passed to the render function in
bits per channel. If omitted or set to 0, the renderer will assume 8.
Typically used to control dithering.
Deprecated. Not supported. Use MPV_RENDER_PARAM_DRM_DISPLAY_V2 instead.
Type : struct mpv_opengl_drm_params*
DRM display, contains drm display handles.
Valid for mpv_render_context_create().
Type : struct mpv_opengl_drm_params_v2*
DRM draw surface size, contains draw surface dimensions.
Valid for mpv_render_context_create().
Type : struct mpv_opengl_drm_draw_surface_size*
Control flipped rendering. Valid for mpv_render_context_render().
Type: int*
If the value is set to 0, render normally. Otherwise, render it flipped,
which is needed e.g. when rendering to an OpenGL default framebuffer
(which has a flipped coordinate system).
ICC profile blob. Valid for mpv_render_context_set_parameter().
Type: mpv_byte_array*
Set an ICC profile for use with the “icc-profile-auto” option. (If the
option is not enabled, the ICC data will not be used.)
Not a valid value, but also used to terminate a params array. Its value
is always guaranteed to be 0 (even if the ABI changes in the future).
Return information about the next frame to render. Valid for
mpv_render_context_get_info().
Describes a GL render target. Valid for mpv_render_context_render().
Type: mpv_opengl_fbo*
Required parameters for initializing the OpenGL renderer. Valid for
mpv_render_context_create().
Type: mpv_opengl_init_params*
Use to skip rendering in mpv_render_context_render().
MPV_RENDER_API_TYPE_SW only: rendering target surface pixel format,
mandatory.
Valid for MPV_RENDER_API_TYPE_SW & mpv_render_context_render().
Type: char* (e.g.: char *f = “rgb0”; param.data = f;)
MPV_RENDER_API_TYPE_SW only: rendering target surface bytes per line,
mandatory.
Valid for MPV_RENDER_API_TYPE_SW & mpv_render_context_render().
Type: size_t*
MPV_RENDER_API_TYPE_SW only: rendering target surface size, mandatory.
Valid for MPV_RENDER_API_TYPE_SW & mpv_render_context_render().
Type: int[2] (e.g.: int s[2] = {w, h}; param.data = &s[0];)
MPV_RENDER_API_TYPE_SW only: rendering target surface bytes per line,
mandatory.
Valid for MPV_RENDER_API_TYPE_SW & mpv_render_context_render().
Type: size_t*
Wayland display, sometimes used for hwdec. Valid for
mpv_render_context_create(). The wl_display must stay valid for the
lifetime of the mpv_render_context.
Type: struct wl_display*
X11 Display, sometimes used for hwdec. Valid for
mpv_render_context_create(). The Display must stay valid for the lifetime
of the mpv_render_context.
Type: Display*
A new video frame must be rendered. mpv_render_context_render() must be
called.
Functions
Signal to all async requests with the matching ID to abort. This affects
the following API calls:
Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.
Return the ID of this client handle. Every client has its own unique ID. This
ID is never reused by the core, even if the mpv_handle at hand gets destroyed
and new handles get allocated.
Return the name of this client handle. Every client has its own unique
name, which is mostly used for user interface purposes.
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.
Same as mpv_command, but run the command asynchronously.
Same as mpv_command(), but allows passing structured data in any format.
In particular, calling mpv_command() is exactly like calling
mpv_command_node() with the format set to MPV_FORMAT_NODE_ARRAY, and
every arg passed in order as MPV_FORMAT_STRING.
Same as mpv_command_node(), but run it asynchronously. Basically, this
function is to mpv_command_node() what mpv_command_async() is to
mpv_command().
This is essentially identical to mpv_command() but it also returns a result.
Same as mpv_command, but use input.conf parsing for splitting arguments.
This is slightly simpler, but also more error prone, since arguments may
need quoting/escaping.
Create a new mpv instance and an associated client API handle to control
the mpv instance. This instance is in a pre-initialized state,
and needs to be initialized to be actually used with most other API
functions.
Create a new client handle connected to the same player core as ctx. This
context has its own event queue, its own mpv_request_event() state, its own
mpv_request_log_messages() state, its own set of observed properties, and
its own state for asynchronous operations. Otherwise, everything is shared.
This is the same as mpv_create_client(), but the created mpv_handle is
treated as a weak reference. If all mpv_handles referencing a core are
weak references, the core is automatically destroyed. (This still goes
through normal uninit of course. Effectively, if the last non-weak mpv_handle
is destroyed, then the weak mpv_handles receive MPV_EVENT_SHUTDOWN and are
asked to terminate as well.)
Disconnect and destroy the mpv_handle. ctx will be deallocated with this
API call.
Returns the associated error string.
Return a string describing the error. For unknown errors, the string
“unknown error” is returned.
Return a string describing the event. For unknown events, NULL is returned.
Convert the given src event to a mpv_node, and set *dst to the result. dst
is set to a MPV_FORMAT_NODE_MAP, with fields for corresponding mpv_event and
mpv_event.data/mpv_event_ fields.
General function to deallocate memory returned by some of the API functions.
Call this only if it’s explicitly documented as allowed. Calling this on
mpv memory not owned by the caller will lead to undefined behavior.
Frees any data referenced by the node. It doesn’t free the node itself.
Call this only if the mpv client API set the node. If you constructed the
node yourself (manually), you have to free it yourself.
Read the value of the given property.
Get a property asynchronously. You will receive the result of the operation
as well as the property data with the MPV_EVENT_GET_PROPERTY_REPLY event.
You should check the mpv_event.error field on the reply event.
Return the property as “OSD” formatted string. This is the same as
mpv_get_property_string, but using MPV_FORMAT_OSD_STRING.
Return the value of the property with the given name as string. This is
equivalent to mpv_get_property() with MPV_FORMAT_STRING.
Return the internal time in microseconds. This has an arbitrary start offset,
but will never wrap or go backwards.
Return a UNIX file descriptor referring to the read end of a pipe. This
pipe can be used to wake up a poll() based processing loop. The purpose of
this function is very similar to mpv_set_wakeup_callback(), and provides
a primitive mechanism to handle coordinating a foreign event loop and the
libmpv event loop. The pipe is non-blocking. It’s closed when the mpv_handle
is destroyed. This function always returns the same value (on success).
A hook is like a synchronous event that blocks the player. You register
a hook handler with this function. You will get an event, which you need
to handle, and once things are ready, you can let the player continue with
mpv_hook_continue().
Respond to a MPV_EVENT_HOOK event. You must call this after you have handled
the event. There is no way to “cancel” or “stop” the hook.
Initialize an uninitialized mpv instance. If the mpv instance is already
running, an error is returned.
Load a config file. This loads and parses the file, and sets every entry in
the config file’s default section as if mpv_set_option_string() is called.
Get a notification whenever the given property changes. You will receive
updates as MPV_EVENT_PROPERTY_CHANGE. Note that this is not very precise:
for some properties, it may not send updates even if the property changed.
This depends on the property, and it’s a valid feature request to ask for
better update handling of a specific property. (For some properties, like
clock, which shows the wall clock, this mechanism doesn’t make too
much sense anyway.)Initialize the renderer state. Depending on the backend used, this will
access the underlying GPU API and initialize its own objects.
Destroy the mpv renderer state.
Retrieve information from the render context. This is NOT a counterpart to
mpv_render_context_set_parameter(), because you generally can’t read
parameters set with it, and this function is not meant for this purpose.
Instead, this is for communicating information from the renderer back to the
user. See mpv_render_param_type; entries which support this function
explicitly mention it, and for other entries you can assume it will fail.
Render video.
Tell the renderer that a frame was flipped at the given time. This is
optional, but can help the player to achieve better timing.
Attempt to change a single parameter. Not all backends and parameter types
support all kinds of changes.
Set the callback that notifies you when a new video frame is available, or
if the video display configuration somehow changed and requires a redraw.
Similar to mpv_set_wakeup_callback(), you must not call any mpv API from
the callback, and all the other listed restrictions apply (such as not
exiting the callback by throwing exceptions).
The API user is supposed to call this when the update callback was invoked
(like all mpv_render_* functions, this has to happen on the render thread,
and not from the update callback itself).
Enable or disable the given event.
Enable or disable receiving of log messages. These are the messages the
command line player prints to the terminal. This call sets the minimum
required log level for a message to be received with MPV_EVENT_LOG_MESSAGE.
Set an option. Note that you can’t normally set options during runtime. It
works in uninitialized state (see mpv_create()), and in some cases in at
runtime.
Convenience function to set an option to a string value. This is like
calling mpv_set_option() with MPV_FORMAT_STRING.
Set a property to a given value. Properties are essentially variables which
can be queried or set at runtime. For example, writing to the pause property
will actually pause or unpause playback.
Set a property asynchronously. You will receive the result of the operation
as MPV_EVENT_SET_PROPERTY_REPLY event. The mpv_event.error field will contain
the result status of the operation. Otherwise, this function is similar to
mpv_set_property().
Convenience function to set a property to a string value.
Set a custom function that should be called when there are new events. Use
this if blocking in mpv_wait_event() to wait for new events is not feasible.
Add a custom stream protocol. This will register a protocol handler under
the given protocol prefix, and invoke the given callbacks if an URI with the
matching protocol prefix is opened.
Similar to mpv_destroy(), but brings the player and all clients down
as well, and waits until all of them are destroyed. This function blocks. The
advantage over mpv_destroy() is that while mpv_destroy() merely
detaches the client handle from the player, this function quits the player,
waits until all other clients are destroyed (i.e. all mpv_handles are
detached), and also waits for the final termination of the player.
Undo mpv_observe_property(). This will remove all observed properties for
which the given number was passed as reply_userdata to mpv_observe_property.
Block until all asynchronous requests are done. This affects functions like
mpv_command_async(), which return immediately and return their result as
events.
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.
Interrupt the current mpv_wait_event() call. This will wake up the thread
currently waiting in mpv_wait_event(). If no thread is waiting, the next
mpv_wait_event() call will return immediately (this is to avoid lost
wakeups).
Type Definitions
Since API version 1.9.
List of error codes than can be returned by API functions. 0 and positive
return values always mean success, negative values are always errors.
Data format for options and properties. The API functions to get/set
properties and options support multiple formats, and this enum describes
them.
Numeric log levels. The lower the number, the more important the message is.
MPV_LOG_LEVEL_NONE is never used when receiving messages. The string in
the comment after the value is the name of the log level as used for the
mpv_request_log_messages() function.
Unused numeric values are unused, but reserved for future use.
Flags used in mpv_render_frame_info.flags. Each value represents a bit in it.
Parameters for mpv_render_param (which is used in a few places such as
mpv_render_context_create().
Flags returned by mpv_render_context_update(). Each value represents a bit
in the function’s return value.
Cancel callback used to implement a custom stream.
Close callback used to implement a custom stream.
Open callback used to implement a custom read-only (ro) stream. The user
must set the callback fields in the passed info struct. The cookie field
also can be set to store state associated to the stream instance.
Read callback used to implement a custom stream. The semantics of the
callback match read(2) in blocking mode. Short reads are allowed (you can
return less bytes than requested, and libmpv will retry reading the rest
with another call). If no data can be immediately read, the callback must
block until there is new data. A return of 0 will be interpreted as final
EOF, although libmpv might retry the read, or seek to a different position.
Seek callback used to implement a custom stream.
Size callback used to implement a custom stream.