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)
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)