diff options
Diffstat (limited to 'DOCS')
| -rw-r--r-- | DOCS/client-api-changes.rst | 1 | ||||
| -rw-r--r-- | DOCS/interface-changes.rst | 2 | ||||
| -rw-r--r-- | DOCS/man/input.rst | 144 | ||||
| -rw-r--r-- | DOCS/man/lua.rst | 111 |
4 files changed, 148 insertions, 110 deletions
diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst index 9a224c9f5b..2ccbc24e76 100644 --- a/DOCS/client-api-changes.rst +++ b/DOCS/client-api-changes.rst @@ -35,6 +35,7 @@ API changes --- mpv 0.33.0 --- 1.108 - Deprecate MPV_EVENT_IDLE - add mpv_event_start_file, mpv_event_end_file.playlist_entry_id + - add mpv_event_to_node() 1.107 - Remove the deprecated qthelper.hpp. This was obviously not part of the libmpv API, only an "additionally" provided helper, thus this is not considered an API change. If you are maintaining a project that relies diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst index 15be443190..d35164f718 100644 --- a/DOCS/interface-changes.rst +++ b/DOCS/interface-changes.rst @@ -54,6 +54,8 @@ Interface changes Using the "playlist-play-index" command is recommended instead. - add "playlist-play-index" command - add playlist-current-pos, playlist-playing-pos properties + - Lua end-file events do not set the "error" field anymore, use "file_error" + instead. --- mpv 0.32.0 --- - change behavior when using legacy option syntax with options that start with two dashes (``--`` instead of a ``-``). Now, using the recommended diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 60e024ebc9..a4567be3aa 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -1275,6 +1275,150 @@ Input Commands that are Possibly Subject to Change Undocumented commands: ``ao-reload`` (experimental/internal). +List of events +~~~~~~~~~~~~~~ + +This is a partial list of events. This section describes what +``mpv_event_to_node()`` returns, and which is what scripting APIs and the JSON +IPC sees. Note that the C API has separate C-level declarations with +``mpv_event``, which may be slightly different. + +All events can have the following fields: + +``event`` + Name as the event (as returned by ``mpv_event_name()``). + +``error`` + Set to an error string (as returned by ``mpv_error_string()``). This field + is missing if no error happened, or the event type does not report error. + Most events leave this unset. + +This list uses the event name field value, and the C API symbol in brackets: + +``start-file`` (``MPV_EVENT_START_FILE``) + Happens right before a new file is loaded. When you receive this, the + player is loading the file (or possibly already done with it). + + This has the following fields: + + ``playlist_entry_id`` + Playlist entry ID of the file being loaded now. + +``end-file`` (``MPV_EVENT_END_FILE``) + Happens after a file was unloaded. Typically, the player will load the + next file right away, or quit if this was the last file. + + The event has the following fields: + + ``reason`` + Has one of these values: + + ``eof`` + The file has ended. This can (but doesn't have to) include + incomplete files or broken network connections under + circumstances. + + ``stop`` + Playback was ended by a command. + + ``quit`` + Playback was ended by sending the quit command. + + ``error`` + An error happened. In this case, an ``error`` field is present with + the error string. + + ``redirect`` + Happens with playlists and similar. Details see + ``MPV_END_FILE_REASON_REDIRECT`` in the C API. + + ``unknown`` + Unknown. Normally doesn't happen, unless the Lua API is out of sync + with the C API. (Likewise, it could happen that your script gets + reason strings that did not exist yet at the time your script was + written.) + + ``playlist_entry_id`` + Playlist entry ID of the file that was being played or attempted to be + played. This has the same value as the ``playlist_entry_id`` field in the + corresponding ``start-file`` event. + + ``file_error`` + Set to mpv error string describing the approximate reason why playback + failed. Unset if no error known. (In Lua scripting, this value was set + on the ``error`` field directly before mpv 0.33.0. Now the ``error`` + field always indicates success, i.e. is not set.) + +``file-loaded`` (``MPV_EVENT_FILE_LOADED``) + Happens after a file was loaded and begins playback. + +``seek`` (``MPV_EVENT_SEEK``) + Happens on seeking. (This might include cases when the player seeks + internally, even without user interaction. This includes e.g. segment + changes when playing ordered chapters Matroska files.) + +``playback-restart`` (``MPV_EVENT_PLAYBACK_RESTART``) + Start of playback after seek or after file was loaded. + +``shutdown`` (``MPV_EVENT_SHUTDOWN``) + Sent when the player quits, and the script should terminate. Normally + handled automatically. See `Details on the script initialization and lifecycle`_. + +``log-message`` (``MPV_EVENT_LOG_MESSAGE``) + Receives messages enabled with ``mpv_request_log_messages()`` (Lua: + ``mp.enable_messages``). + + This contains, in addition to the default event fields, the following + fields: + + ``prefix`` + The module prefix, identifies the sender of the message. This is what + the terminal player puts in front of the message text when using the + ``--v`` option, and is also what is used for ``--msg-level``. + + ``level`` + The log level as string. See ``msg.log`` for possible log level names. + Note that later versions of mpv might add new levels or remove + (undocumented) existing ones. + + ``text`` + The log message. The text will end with a newline character. Sometimes + it can contain multiple lines. + + Keep in mind that these messages are meant to be hints for humans. You + should not parse them, and prefix/level/text of messages might change + any time. + +``hook`` + The event has the following fields: + + ``hook_id`` + ID to pass to ``mpv_hook_continue()``. The Lua scripting wrapper + provides a better API around this with ``mp.add_hook()``. + +``get-property-reply`` (``MPV_EVENT_GET_PROPERTY_REPLY``) + Undocumented. + +``set-property-reply`` (``MPV_EVENT_SET_PROPERTY_REPLY``) + Undocumented. + +``command-reply`` (``MPV_EVENT_COMMAND_REPLY``) + Undocumented. + +``client-message`` (``MPV_EVENT_CLIENT_MESSAGE``) + Undocumented. + +``video-reconfig`` (``MPV_EVENT_VIDEO_RECONFIG``) + Happens on video output or filter reconfig. + +``audio-reconfig`` (``MPV_EVENT_AUDIO_RECONFIG``) + Happens on audio output or filter reconfig. + +The following events also happen, but are deprecated: ``tracks-changed``, +``track-switched``, ``pause``, ``unpause``, ``metadata-update``, ``idle``, +``tick``, ``chapter-change``. Use ``mpv_observe_property()`` +(Lua: ``mp.observe_property()``) instead. + Hooks ~~~~~ diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 339ec60dd1..b256d7bf2d 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -871,116 +871,7 @@ Example: mp.register_event("file-loaded", my_fn) - - -List of events --------------- - -``start-file`` - Happens right before a new file is loaded. When you receive this, the - player is loading the file (or possibly already done with it). - -``end-file`` - Happens after a file was unloaded. Typically, the player will load the - next file right away, or quit if this was the last file. - - The event has the ``reason`` field, which takes one of these values: - - ``eof`` - The file has ended. This can (but doesn't have to) include - incomplete files or broken network connections under - circumstances. - - ``stop`` - Playback was ended by a command. - - ``quit`` - Playback was ended by sending the quit command. - - ``error`` - An error happened. In this case, an ``error`` field is present with - the error string. - - ``redirect`` - Happens with playlists and similar. Details see - ``MPV_END_FILE_REASON_REDIRECT`` in the C API. - - ``unknown`` - Unknown. Normally doesn't happen, unless the Lua API is out of sync - with the C API. (Likewise, it could happen that your script gets - reason strings that did not exist yet at the time your script was - written.) - -``file-loaded`` - Happens after a file was loaded and begins playback. - -``seek`` - Happens on seeking. (This might include cases when the player seeks - internally, even without user interaction. This includes e.g. segment - changes when playing ordered chapters Matroska files.) - -``playback-restart`` - Start of playback after seek or after file was loaded. - -``idle`` - Idle mode is entered. This happens when playback ended, and the player was - started with ``--idle`` or ``--force-window``. This mode is implicitly ended - when the ``start-file`` or ``shutdown`` events happen. - -``tick`` - Called after a video frame was displayed. This is a hack, and you should - avoid using it. Use timers instead and maybe watch pausing/unpausing events - to avoid wasting CPU when the player is paused. This is deprecated. - -``shutdown`` - Sent when the player quits, and the script should terminate. Normally - handled automatically. See `Details on the script initialization and lifecycle`_. - -``log-message`` - Receives messages enabled with ``mp.enable_messages``. The message data - is contained in the table passed as first parameter to the event handler. - The table contains, in addition to the default event fields, the following - fields: - - ``prefix`` - The module prefix, identifies the sender of the message. This is what - the terminal player puts in front of the message text when using the - ``--v`` option, and is also what is used for ``--msg-level``. - - ``level`` - The log level as string. See ``msg.log`` for possible log level names. - Note that later versions of mpv might add new levels or remove - (undocumented) existing ones. - - ``text`` - The log message. The text will end with a newline character. Sometimes - it can contain multiple lines. - - Keep in mind that these messages are meant to be hints for humans. You - should not parse them, and prefix/level/text of messages might change - any time. - -``get-property-reply`` - Undocumented (not useful for Lua scripts). - -``set-property-reply`` - Undocumented (not useful for Lua scripts). - -``command-reply`` - Undocumented (not useful for Lua scripts). - -``client-message`` - Undocumented (used internally). - -``video-reconfig`` - Happens on video output or filter reconfig. - -``audio-reconfig`` - Happens on audio output or filter reconfig. - -The following events also happen, but are deprecated: ``tracks-changed``, -``track-switched``, ``pause``, ``unpause``, ``metadata-update``, -``chapter-change``. Use ``mp.observe_property()`` instead. +For the existing event types, see `List of events`_. Extras ------ |