= Libmpv =

The full documentation can be found in `/usr/include/mpv/client.h`. The library
treats its own source as documentation. When installing mpv, libmpv is usually
installed as well. Libmpv is a C library.

== Handle ==

MPV provides a `mpv_handle`, which is a client context used by the client API.
Every client has its own private handle.

The handle can be queried with `const char *mpv_client_name(mpv_handle*)` which
returns the handle name. The returned string is read only and valid for the
lifetime of the handle.

The handle has a unique client ID, and can be queried with
`int64_t mpv_client_id(mpv_handle)`. The ID is never reused, and is never 0 or
negative.

A client can be created via `mpv_handle* mpv_create(void)`.
The Client that is created is optimized for embedding by default. This means it
has some defaults not present in the CLI mpv. These include

* `--no-terminal`, which supresses stdin/stdout/stderr and C signal handling
* `--config=no`, loading no default configuration file
* `--idle`, which means the player will idle instead of exiting when it runs
  out of files to play
* Disable input handling

`int mpv_initialize(mpv_handle*)` will init an uninit mpv instance. If the
instance is already running, an error is returned.

Destroy a handle with `void mpv_destroy(mpv_handle*)`.


== Configuration ==

MPV can be configured the same way as the CLI version, via loading a
configuration file or setting config options in individual calls. This
configuration cannot be done during runtime. It *must* be done on an
uninitialized player.

To load traditional config files, call
`int mpv_load_config_file(mpv_handle*, const char* filename)`.