It is reasonably stable, so all further changes will be versioned.
Also change how the libmpv version number is generated. Fix the patch
version number to 0; I don't think we have a use for this. In
particular, the version doesn't version mpv, just the client API.
Until now, availability of new log messages (through the mechanism
associated with mpv_request_log_messages()) did not wakeup the client
API properly. Commit 3b7402b5 was basically a hack to improve that
somewhat, but it wasn't a solution.
The main problem is that the client API itself is producing messages, so
the message callback would attempt to lock the client API lock,
resulting in a deadlock. Even if the lock was recursive, we'd run into
lock-order issues.
Solve this by using a separate lock for waiting and wakeup. Also, since
it's a natural addition, avoid redundant wakeups. This means the wakeup
callback as well as the wakeup pipe will be triggered only once until
the next mpv_wait_event() call happens.
This might make the wakeup callback be invoked in a reentrant way for
the first time, for example if a mpv_* function prints to a log. Adjust
the docs accordingly. (Note that non-reentrant beheavior was never
guaranteed - basically the wakeup callback is somewhat dangerous and
inconvenient.)
Also remove some traces of unneeded code. ctx->shutdown for one was
never set, and probably a leftover of an abandoned idea.
A bit verbose, but less misleading. In most cases, the API user probably
actually wants mpv_terminate_destroy() instead, so the less-useful
function shouldn't have a simnpler name anyway.
It wasn't necessarily clear how this works. Especially make clear that
the API user shouldn't expect that there's one byte per readable event
in the wakeup pipe. Actually, the reason why this currently won't work
is because property notifications can generate more events than wakeups.
The limit of 4096 is a more fundamental issue, but the event ringbuffer
is currently limited to 1000 entries anyway.
Also add some important comments to mpv_set_wakeup_callback.
mpv_destroy() should perhaps better be called mpv_detach(), because it
destroys only the handle, not necessarily the player. The player is only
terminated if a quit command is sent.
This function quits automatically, and additionally waits until the
player is completely destroyed. It removes the possibility that the
player core is still uninitializing, while all client handles are
already destroyed. (Although in practice, the difference is usually not
important.)
Now a negative timeout mean an infinite timeout. This is similar to the
poll() system call. Apparently this is more intuitive and less confusing
than specifying a "very high" value as timeout if you want to wait
forever.
For callers that never pass negative timeouts, nothing changes.
Until now, an error was reported only if the command couldn't be parsed.
Attempt to do more fine-grained reporting. This is not necessarily
perfect, but it's an improvement.
This is probably a good idea, because it would make it easier for
software embedding mpv to configure the mpv parts, without requiring the
host program to provide explicit mechanisms for this (other than calling
mpv_load_config_file()).
And slightly adjust the semantics of MPV_EVENT_PAUSE/MPV_EVENT_UNPAUSE.
The real pause state can now be queried with the "core-idle" property,
the user pause state with the "pause" property, whether the player is
paused due to cache with "paused-for-cache", and the keep open event can
be guessed with the "eof-reached" property.
Otherwise, the client API user could not know why playback was stopped.
Regarding the fact that 0 is used both for normal EOF and EOF on error:
this is because mplayer traditionally did not distinguish these, and in
general it's hard to tell the real reason. (There are various weird
corner cases which make it hard.)
This turned out ridiculously complex. I think it will have to be
simplified some day. Main reason for the complexity are:
- filtering properties by forcing clients to observe individual
properties explicitly
(to avoid spamming clients with changes they don't want)
- optional retrieval of property value with the notification
(the basic idea was that this is more user friendly)
- allowing to the client to specify a format in which the value
should be retrieved
(because if a property changes its type, the client API couldn't
convert it properly, and compatibility would break)
I don't know yet which of these are important, and everything could
change. In particular, the interface and semantics should be adjusted
to reduce the implementation complexity.
While I consider the API complete, there could (and probably will) be
bugs left. Also while the implementation is complete, it's inefficient.
The complexity of the property matching is O(a*b*c) with a clients,
b observed properties, and c properties changing at once. I threw away
an earlier implementation using bitmasks, because it was too unwieldy.
Not sure about this... might redo.
At least this provides a case of a broadcasted event, which requires
per-event data allocation.
See github issue #576.
May or may not be useful in some ways.
We require a context parameter for this just to be sure, even if the
internal implementation currently doesn't.
That's one less mpv internal function for the Lua wrapper.
Also mention that NULL isn't valid. Although I'm not sure whether the
implementation strictly follows this (it should, but there are some
wacky corner cases).
This adds declarations for new formats. The implementation will be added
in the following commits. (It still compiles and runs with this commit,
because it adds constants only.)
The obvious new types are MPV_FORMAT_FLAG, MPV_FORMAT_INT64,
MPV_FORMAT_DOUBLE. MPV_FORMAT_FLAG is a boolean, but to avoid nasty ABI
issues or with languages that don't have a bool data type (C89), it uses
int. Thus the format is not named MPV_FORMAT_BOOL, to avoid confusion.
The MPV_FORMAT_NONE type (mpv_node) is a generic structured type, like a
variant or, say, JSON. It can store strings/bools/numbers, as well as
arrays and key/value pairs (with string keys only).
The MPV_FORMAT_NODE_ARRAY and MPV_FORMAT_NODE_MAP types are used
internally by mpv_node only and can't be used with most of the other API
(like mpv_set_property()) directly.
With mpv_set_property(h, "property", MPV_FORMAT_STRING, ptr), ptr now
has to be of type char** instead of char*. This makes it more consistent
with mpv_get_property() and also non-pointer formats, which will be
introduced in the following commits. mpv_set_property() of course does
not change its interface (only its implementation is adjusted to keep
its interface).
This also affects mpv_set_option(), but again not
mpv_set_option_string().
This is allowed in C99 and C++11, but apparently not in C89 and C++98.
Make it conform to the older standards, since we want the client API
header to be highly portable.
Add a client API, which is intended to be a stable API to get some rough
control over the player. Basically, it reflects what can be done with
input.conf commands or the old slavemode. It will replace the old
slavemode (and enable the implementation of a new slave protocol).
wm4
Alessandro Ghedini
xylosper