summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2020-03-21 19:31:58 +0100
committerwm4 <wm4@nowhere>2020-03-21 19:33:48 +0100
commit218d6643e940dde2a01260cf8def70efc100cd43 (patch)
treef7ce9e059456eeaa3e33b08d8fa96512573c6a99 /DOCS
parent7e885a3bc3af4df93681b6e760a34e59e2f47ef7 (diff)
downloadmpv-218d6643e940dde2a01260cf8def70efc100cd43.tar.bz2
mpv-218d6643e940dde2a01260cf8def70efc100cd43.tar.xz
client API, lua, ipc: unify event struct return
Both Lua and the JSON IPC code need to convert the mpv_event struct (and everything it points to) to Lua tables or JSON. I was getting sick of having to make the same changes to Lua and IPC. Do what has been done everywhere else, and let the core handle this by going through mpv_node (which is supposed to serve both Lua tables and JSON, and potentially other scripting language backends). Expose it as new libmpv API function. The new API is still a bit "rough" and support for other event types might be added in the future. This silently adds support for the playlist_entry_id fields to both Lua and JSON IPC. There is a small API change for Lua; I don't think this matters, so I didn't care about compatibility. The new code in client.c is mashed up from the Lua and the IPC code. The manpage additions are moved from the Lua docs, and made slightly more "general". Some danger for unintended regressions both in Lua and IPC. Also damn these node functions suck, expect crashes due to UB. Not sure why this became more code instead of less compared to before (according to the diff stat), even though some code duplication across Lua and IPC was removed. Software development sucks.
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/client-api-changes.rst1
-rw-r--r--DOCS/interface-changes.rst2
-rw-r--r--DOCS/man/input.rst144
-rw-r--r--DOCS/man/lua.rst111
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
------