Get a notification whenever the given property changes. You will receive
updates as MPV_EVENT_PROPERTY_CHANGE. Note that this is not very precise:
for some properties, it may not send updates even if the property changed.
This depends on the property, and it's a valid feature request to ask for
better update handling of a specific property. (For some properties, like
`clock`, which shows the wall clock, this mechanism doesn't make too
much sense anyway.)
Property changes are coalesced: the change events are returned only once the
event queue becomes empty (e.g. mpv_wait_event() would block or return
MPV_EVENT_NONE), and then only one event per changed property is returned.
You always get an initial change notification. This is meant to initialize
the user's state to the current value of the property.
Normally, change events are sent only if the property value changes according
to the requested format. mpv_event_property will contain the property value
as data member.
Warning: if a property is unavailable or retrieving it caused an error,
MPV_FORMAT_NONE will be set in mpv_event_property, even if the
format parameter was set to a different value. In this case, the
mpv_event_property.data field is invalid.
If the property is observed with the format parameter set to MPV_FORMAT_NONE,
you get low-level notifications whether the property _may_ have changed, and
the data member in mpv_event_property will be unset. With this mode, you
will have to determine yourself whether the property really changed. On the
other hand, this mechanism can be faster and uses less resources.
Observing a property that doesn't exist is allowed. (Although it may still
cause some sporadic change events.)
Keep in mind that you will get change notifications even if you change a
property yourself. Try to avoid endless feedback loops, which could happen
if you react to the change notifications triggered by your own change.
Only the mpv_handle on which this was called will receive the property
change events, or can unobserve them.
Safe to be called from mpv render API threads.
@param reply_userdata This will be used for the mpv_event.reply_userdata
field for the received MPV_EVENT_PROPERTY_CHANGE
events. (Also see section about asynchronous calls,
although this function is somewhat different from
actual asynchronous calls.)
If you have no use for this, pass 0.
Also see mpv_unobserve_property().
@param name The property name.
@param format see enum mpv_format. Can be MPV_FORMAT_NONE to omit values
from the change events.
@return error code (usually fails only on OOM or unsupported format)
Get a notification whenever the given property changes. You will receive updates as MPV_EVENT_PROPERTY_CHANGE. Note that this is not very precise: for some properties, it may not send updates even if the property changed. This depends on the property, and it's a valid feature request to ask for better update handling of a specific property. (For some properties, like `clock`, which shows the wall clock, this mechanism doesn't make too much sense anyway.)
Property changes are coalesced: the change events are returned only once the event queue becomes empty (e.g. mpv_wait_event() would block or return MPV_EVENT_NONE), and then only one event per changed property is returned.
You always get an initial change notification. This is meant to initialize the user's state to the current value of the property.
Normally, change events are sent only if the property value changes according to the requested format. mpv_event_property will contain the property value as data member.
Warning: if a property is unavailable or retrieving it caused an error, MPV_FORMAT_NONE will be set in mpv_event_property, even if the format parameter was set to a different value. In this case, the mpv_event_property.data field is invalid.
If the property is observed with the format parameter set to MPV_FORMAT_NONE, you get low-level notifications whether the property _may_ have changed, and the data member in mpv_event_property will be unset. With this mode, you will have to determine yourself whether the property really changed. On the other hand, this mechanism can be faster and uses less resources.
Observing a property that doesn't exist is allowed. (Although it may still cause some sporadic change events.)
Keep in mind that you will get change notifications even if you change a property yourself. Try to avoid endless feedback loops, which could happen if you react to the change notifications triggered by your own change.
Only the mpv_handle on which this was called will receive the property change events, or can unobserve them.
Safe to be called from mpv render API threads.
@param reply_userdata This will be used for the mpv_event.reply_userdata field for the received MPV_EVENT_PROPERTY_CHANGE events. (Also see section about asynchronous calls, although this function is somewhat different from actual asynchronous calls.) If you have no use for this, pass 0. Also see mpv_unobserve_property(). @param name The property name. @param format see enum mpv_format. Can be MPV_FORMAT_NONE to omit values from the change events. @return error code (usually fails only on OOM or unsupported format)