libmpv API

// Create a new mpv instance (pre-initialized, not yet started)
mpv_handle *mpv_create(void);

// Initialize a created instance; must be called before most API use
int mpv_initialize(mpv_handle *ctx);

// Detach the handle; destroys the core if this was the last handle
void mpv_destroy(mpv_handle *ctx);

// Quit the player, wait for all handles to be destroyed, then return
void mpv_terminate_destroy(mpv_handle *ctx);

// Create an additional client handle connected to the same core
mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name);

// Like mpv_create_client(), but the handle is a weak reference
mpv_handle *mpv_create_weak_client(mpv_handle *ctx, const char *name);

// Return the name of this client handle
const char *mpv_client_name(mpv_handle *ctx);

// Return the unique numeric ID of this client handle
int64_t mpv_client_id(mpv_handle *ctx);

// Return the compiled API version
unsigned long mpv_client_api_version(void);

// Send a command as a NULL-terminated string array
int mpv_command(mpv_handle *ctx, const char **args);

// Send a command using input.conf parsing (enables OSD and string expansion)
int mpv_command_string(mpv_handle *ctx, const char *args);

// Send a command as a structured mpv_node
int mpv_command_node(mpv_handle *ctx, mpv_node *args, mpv_node *result);

// Like mpv_command(), but also returns result data
int mpv_command_ret(mpv_handle *ctx, const char **args, mpv_node *result);

// Send a command asynchronously; result is delivered as MPV_EVENT_COMMAND_REPLY
int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata,
                      const char **args);

// Async version of mpv_command_node()
int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata,
                           mpv_node *args);

// Signal async requests with the matching ID to abort
void mpv_abort_async_command(mpv_handle *ctx, uint64_t reply_userdata);

// Set a property (supports all mpv_format types)
int mpv_set_property(mpv_handle *ctx, const char *name,
                     mpv_format format, void *data);

// Set a property to a string value
int mpv_set_property_string(mpv_handle *ctx, const char *name,
                             const char *data);

// Delete a property (equivalent to "del [name]" command)
int mpv_del_property(mpv_handle *ctx, const char *name);

// Set a property asynchronously; result: MPV_EVENT_SET_PROPERTY_REPLY
int mpv_set_property_async(mpv_handle *ctx, uint64_t reply_userdata,
                            const char *name, mpv_format format, void *data);

// Read a property value
int mpv_get_property(mpv_handle *ctx, const char *name,
                     mpv_format format, void *data);

// Read a property value as a string (caller must mpv_free() the result)
char *mpv_get_property_string(mpv_handle *ctx, const char *name);

// Read a property value formatted for OSD display
char *mpv_get_property_osd_string(mpv_handle *ctx, const char *name);

// Read a property asynchronously; result: MPV_EVENT_GET_PROPERTY_REPLY
int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata,
                            const char *name, mpv_format format);

// Watch a property; changes are reported as MPV_EVENT_PROPERTY_CHANGE
int mpv_observe_property(mpv_handle *mpv, uint64_t reply_userdata,
                          const char *name, mpv_format format);

// Stop watching a property registered with the given reply_userdata
int mpv_unobserve_property(mpv_handle *mpv,
                            uint64_t registered_reply_userdata);

// Load a config file (parses it as if mpv_set_option_string() was called)
int mpv_load_config_file(mpv_handle *ctx, const char *filename);

// Set an option before mpv_initialize() (semi-deprecated; prefer mpv_set_property())
int mpv_set_option(mpv_handle *ctx, const char *name,
                   mpv_format format, void *data);

// Set an option to a string value
int mpv_set_option_string(mpv_handle *ctx, const char *name, const char *data);

// Block until an event is available, timeout expires, or mpv_wakeup() is called
// Pass timeout=-1 to wait indefinitely; timeout=0 to poll without blocking
mpv_event *mpv_wait_event(mpv_handle *ctx, double timeout);

// Wake up a blocked mpv_wait_event() call from another thread
void mpv_wakeup(mpv_handle *ctx);

// Set a callback invoked when new events are available (do not call API from it)
void mpv_set_wakeup_callback(mpv_handle *ctx, void (*cb)(void *d), void *d);

// Block until all pending async requests have completed
void mpv_wait_async_requests(mpv_handle *ctx);

// Enable or disable a specific event type
int mpv_request_event(mpv_handle *ctx, mpv_event_id event, int enable);

// Enable log message delivery at the specified minimum level
int mpv_request_log_messages(mpv_handle *ctx, const char *min_level);

// Convert an mpv_event to an mpv_node map representation
int mpv_event_to_node(mpv_node *dst, mpv_event *src);

// Register a hook handler (priority 0 is neutral; lower priority runs first)
int mpv_hook_add(mpv_handle *ctx, uint64_t reply_userdata,
                 const char *name, int priority);

// Signal that hook handling is complete and the player may continue
int mpv_hook_continue(mpv_handle *ctx, uint64_t id);

// Internal time in nanoseconds (not related to playback position)
int64_t mpv_get_time_ns(mpv_handle *ctx);

// Same, in microseconds
int64_t mpv_get_time_us(mpv_handle *ctx);

// Free memory allocated by the API (e.g. strings from mpv_get_property_string)
void mpv_free(void *data);

// Free data referenced by an mpv_node (does not free the node itself)
void mpv_free_node_contents(mpv_node *node);

// Reading a double property
double pos;
mpv_get_property(mpv, "time-pos", MPV_FORMAT_DOUBLE, &pos);

// Reading a flag property
int paused;
mpv_get_property(mpv, "pause", MPV_FORMAT_FLAG, &paused);

// Reading a string property (must be freed)
char *path = mpv_get_property_string(mpv, "path");
printf("Playing: %s\n", path);
mpv_free(path);

const char *mpv_error_string(int error);

#include <stdio.h>
#include <mpv/client.h>

int main(void) {
    mpv_handle *mpv = mpv_create();
    if (!mpv) return 1;

    // Optional: suppress terminal output (enabled by default in libmpv mode)
    mpv_set_property_string(mpv, "terminal", "no");

    if (mpv_initialize(mpv) < 0) return 1;

    const char *cmd[] = {"loadfile", "myvideo.mkv", NULL};
    mpv_command(mpv, cmd);

    while (1) {
        mpv_event *event = mpv_wait_event(mpv, -1);
        if (event->event_id == MPV_EVENT_SHUTDOWN)
            break;
        if (event->event_id == MPV_EVENT_END_FILE) {
            mpv_event_end_file *ef = event->data;
            if (ef->reason == MPV_END_FILE_REASON_EOF)
                printf("Playback ended.\n");
        }
    }

    mpv_terminate_destroy(mpv);
    return 0;
}

gcc -o player player.c $(pkg-config --libs --cflags mpv)

// Create a render context (call before playback starts)
int mpv_render_context_create(mpv_render_context **res, mpv_handle *mpv,
                               mpv_render_param *params);

// Set a callback invoked when a new frame is ready to render
void mpv_render_context_set_update_callback(mpv_render_context *ctx,
                                             mpv_render_update_fn callback,
                                             void *callback_ctx);

// Query what should happen next (returns mpv_render_update_flag bitmask)
uint64_t mpv_render_context_update(mpv_render_context *ctx);

// Render the current video frame to the target surface
int mpv_render_context_render(mpv_render_context *ctx, mpv_render_param *params);

// Notify mpv that a frame was displayed (helps with A/V sync)
void mpv_render_context_report_swap(mpv_render_context *ctx);

// Destroy the render context
void mpv_render_context_free(mpv_render_context *ctx);

#include <mpv/render_gl.h>

static void *get_proc_address(void *ctx, const char *name) {
    // e.g. return SDL_GL_GetProcAddress(name);
    return your_gl_get_proc_address(name);
}

// Create OpenGL render context
mpv_opengl_init_params gl_params = {
    .get_proc_address = get_proc_address,
    .get_proc_address_ctx = NULL,
};

mpv_render_param params[] = {
    {MPV_RENDER_PARAM_API_TYPE,          (void *)MPV_RENDER_API_TYPE_OPENGL},
    {MPV_RENDER_PARAM_OPENGL_INIT_PARAMS, &gl_params},
    {MPV_RENDER_PARAM_ADVANCED_CONTROL,  &(int){1}},
    {0},
};

mpv_render_context *render_ctx;
mpv_render_context_create(&render_ctx, mpv, params);

// Render a frame to FBO 0 at 1920x1080
mpv_opengl_fbo fbo = {.fbo = 0, .w = 1920, .h = 1080};
int flip_y = 1; // OpenGL default framebuffer is y-flipped
mpv_render_param render_params[] = {
    {MPV_RENDER_PARAM_OPENGL_FBO, &fbo},
    {MPV_RENDER_PARAM_FLIP_Y,     &flip_y},
    {0},
};
mpv_render_context_render(render_ctx, render_params);

#include <mpv/stream_cb.h>

// Register a protocol prefix (e.g. "mystream://")
int mpv_stream_cb_add_ro(mpv_handle *ctx, const char *protocol,
                          void *user_data,
                          mpv_stream_cb_open_ro_fn open_fn);