mpv_create method

Pointer<mpv_handle> mpv_create()

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.

Some API functions will return MPV_ERROR_UNINITIALIZED in the uninitialized state. You can call mpv_set_property() (or mpv_set_property_string() and other variants, and before mpv 0.21.0 mpv_set_option() etc.) to set initial options. After this, call mpv_initialize() to start the player, and then use e.g. mpv_command() to start playback of a file.

The point of separating handle creation and actual initialization is that you can configure things which can't be changed during runtime.

Unlike the command line player, this will have initial settings suitable for embedding in applications. The following settings are different:

  • stdin/stdout/stderr and the terminal will never be accessed. This is equivalent to setting the --no-terminal option. (Technically, this also suppresses C signal handling.)
  • No config files will be loaded. This is roughly equivalent to using --config=no. Since libmpv 1.15, you can actually re-enable this option, which will make libmpv load config files during mpv_initialize(). If you do this, you are strongly encouraged to set the "config-dir" option too. (Otherwise it will load the mpv command line player's config.) For example: mpv_set_option_string(mpv, "config-dir", "/my/path"); // set config root mpv_set_option_string(mpv, "config", "yes"); // enable config loading (call mpv_initialize() after this)
  • Idle mode is enabled, which means the playback core will enter idle mode if there are no more files to play on the internal playlist, instead of exiting. This is equivalent to the --idle option.
  • Disable parts of input handling.
  • Most of the different settings can be viewed with the command line player by running "mpv --show-profile=libmpv".

All this assumes that API users want a mpv instance that is strictly isolated from the command line player's configuration, user settings, and so on. You can re-enable disabled features by setting the appropriate options.

The mpv command line parser is not available through this API, but you can set individual options with mpv_set_property(). Files for playback must be loaded with mpv_command() or others.

Note that you should avoid doing concurrent accesses on the uninitialized client handle. (Whether concurrent access is definitely allowed or not has yet to be decided.)

@return a new mpv client API handle. Returns NULL on error. Currently, this can happen in the following situations:

  • out of memory
  • LC_NUMERIC is not set to "C" (see general remarks)

Implementation

ffi.Pointer<mpv_handle> mpv_create() {
  return _mpv_create();
}