client API: clarify pause/unpause events, modify core-idle property

Whether you consider the semantics weird or not depends on your use
case, but I suppose it's a bit confusing anyway. At this point, we keep
MPV_EVENT_PAUSE/UNPAUSE for compatibility only.

Make the "core-idle" property somewhat more useful in this context.

DOCS/client-api-changes.rst

@@ -25,6 +25,8 @@ API changes
 
 ::
 
+ 1.6    - modify "core-idle" property behavior
+ --- mpv 0.6.0 is released ---
  1.5    - change in X11 and "--wid" behavior again. The previous change didn't
           work as expected, and now the behavior can be explicitly controlled
           with the "input-x11-keyboard" option. This is only a temporary

DOCS/man/input.rst

@@ -828,6 +828,10 @@ Property list
     be different ``pause`` in special situations, such as when the player
     pauses itself due to low network cache.
 
+    This also returns ``yes`` if playback is restarting or if nothing is
+    playing at all. In other words, it's only ``no`` if there's actually
+    video playing. (Behavior since mpv 0.7.0.)
+
 ``cache``
     Network cache fill state (0-100.0).
 

libmpv/client.h

@@ -162,7 +162,7 @@ extern "C" {
  * relational operators (<, >, <=, >=).
  */
 #define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL)
-#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 5)
+#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 6)
 
 /**
  * Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.
@@ -892,10 +892,21 @@ typedef enum mpv_event_id {
      */
     MPV_EVENT_IDLE              = 11,
     /**
-     * Playback was paused. This indicates the logical pause state (like the
-     * property "pause" as opposed to the "core-idle" propetty). This event
-     * is sent whenever any pause state changes, not only the logical state,
-     * so you might get multiple MPV_EVENT_PAUSE events in a row.
+     * Playback was paused. This indicates the user pause state.
+     *
+     * The user pause state is the state the user requested (changed with the
+     * "pause" property). There is an internal pause state too, which is entered
+     * if e.g. the network is too slow (the "core-idle" property generally
+     * indicates whether the core is playing or waiting).
+     *
+     * This event is sent whenever any pause states change, not only the user
+     * state. You might get multiple events in a row while these states change
+     * independently. But the event ID sent always indicates the user pause
+     * state.
+     *
+     * If you don't want to deal with this, use mpv_observe_property() on the
+     * "pause" property and ignore MPV_EVENT_PAUSE/UNPAUSE. Likewise, the
+     * "core-idle" property tells you whether video is actually playing or not.
      */
     MPV_EVENT_PAUSE             = 12,
     /**

player/command.c

@@ -1020,7 +1020,8 @@ static int mp_property_core_idle(void *ctx, struct m_property *prop,
                                  int action, void *arg)
 {
     MPContext *mpctx = ctx;
-    return m_property_flag_ro(action, arg, mpctx->paused);
+    bool idle = mpctx->paused || !mpctx->restart_complete || !mpctx->playing;
+    return m_property_flag_ro(action, arg, idle);
 }
 
 static int mp_property_eof_reached(void *ctx, struct m_property *prop,