diff options
Diffstat (limited to 'DOCS/man/lua.rst')
| -rw-r--r-- | DOCS/man/lua.rst | 279 |
1 files changed, 142 insertions, 137 deletions
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index a9fc02ed44..73776964d5 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -37,6 +37,12 @@ scripting backend to use for it. For Lua, it is ``.lua``. If the extension is not recognized, an error is printed. (If an error happens, the extension is either mistyped, or the backend was not compiled into your mpv binary.) +mpv internally loads the script's name by stripping the ``.lua`` extension and +replacing all nonalphanumeric characters with ``_``. E.g., ``my-tools.lua`` +becomes ``my_tools``. If there are several scripts with the same name, it is +made unique by appending a number. This is the name returned by +``mp.get_script_name()``. + Entries with ``.disable`` extension are always ignored. If a script is a directory (either if a directory is passed to ``--script``, @@ -56,15 +62,15 @@ that uses the ``.foo`` file extension. mpv also appends the top level directory of the script to the start of Lua's package path so you can import scripts from there too. Be aware that this will shadow Lua libraries that use the same package path. (Single file scripts do not -include mpv specific directory the Lua package path. This was silently changed -in mpv 0.32.0.) +include mpv specific directories in the Lua package path. This was silently +changed in mpv 0.32.0.) Using a script directory is the recommended way to package a script that consists of multiple source files, or requires other files (you can use ``mp.get_script_directory()`` to get the location and e.g. load data files). Making a script a git repository, basically a repository which contains a -``main.lua``` file in the root directory, makes scripts easily updateable +``main.lua`` file in the root directory, makes scripts easily updateable (without the dangers of auto-updates). Another suggestion is to use git submodules to share common files or libraries. @@ -185,12 +191,20 @@ The ``mp`` module is preloaded, although it can be loaded manually with If starting the command failed for some reason, ``nil, error`` is returned, and ``fn`` is called indicating failure, using the same error value. + ``fn`` is always called asynchronously, even if the command failed to start. + ``mp.abort_async_command(t)`` Abort a ``mp.command_native_async`` call. The argument is the return value of that command (which starts asynchronous execution of the command). Whether this works and how long it takes depends on the command and the situation. The abort call itself is asynchronous. Does not return anything. +``mp.del_property(name)`` + Delete the given property. See ``mp.get_property`` and `Properties`_ for more + information about properties. Most properties cannot be deleted. + + Returns true on success, or ``nil, error`` on error. + ``mp.get_property(name [,def])`` Return the value of the given property as string. These are the same properties as used in input.conf. See `Properties`_ for a list of @@ -294,16 +308,17 @@ The ``mp`` module is preloaded, although it can be loaded manually with ``repeatable`` If set to ``true``, enables key repeat for this specific binding. + This option only makes sense when ``complex`` is not set to ``true``. ``complex`` - If set to ``true``, then ``fn`` is called on both key up and down - events (as well as key repeat, if enabled), with the first - argument being a table. This table has the following entries (and - may contain undocumented ones): + If set to ``true``, then ``fn`` is called on key down, repeat and up + events, with the first argument being a table. This table has the + following entries (and may contain undocumented ones): ``event`` Set to one of the strings ``down``, ``repeat``, ``up`` or - ``press`` (the latter if key up/down can't be tracked). + ``press`` (the latter if key up/down/repeat can't be + tracked). ``is_mouse`` Boolean Whether the event was caused by a mouse button. @@ -412,9 +427,9 @@ The ``mp`` module is preloaded, although it can be loaded manually with This depends on the property, and it's a valid feature request to ask for better update handling of a specific property. - If the ``type`` is ``none`` or ``nil``, sporadic property change events are - possible. This means the change function ``fn`` can be called even if the - property doesn't actually change. + If the ``type`` is ``none`` or ``nil``, the change function ``fn`` will be + called sporadically even if the property doesn't actually change. You should + therefore avoid using these types. You always get an initial change notification. This is meant to initialize the user's state to the current value of the property. @@ -424,17 +439,21 @@ The ``mp`` module is preloaded, although it can be loaded manually with that are equal to the ``fn`` parameter. This uses normal Lua ``==`` comparison, so be careful when dealing with closures. -``mp.add_timeout(seconds, fn)`` +``mp.add_timeout(seconds, fn [, disabled])`` Call the given function fn when the given number of seconds has elapsed. Note that the number of seconds can be fractional. For now, the timer's resolution may be as low as 50 ms, although this will be improved in the future. + If the ``disabled`` argument is set to ``true`` or a truthy value, the + timer will wait to be manually started with a call to its ``resume()`` + method. + This is a one-shot timer: it will be removed when it's fired. Returns a timer object. See ``mp.add_periodic_timer`` for details. -``mp.add_periodic_timer(seconds, fn)`` +``mp.add_periodic_timer(seconds, fn [, disabled])`` Call the given function periodically. This is like ``mp.add_timeout``, but the timer is re-added after the function fn is run. @@ -474,7 +493,7 @@ The ``mp`` module is preloaded, although it can be loaded manually with the timer callback function fn is run). Note that these are methods, and you have to call them using ``:`` instead - of ``.`` (Refer to http://www.lua.org/manual/5.2/manual.html#3.4.9 .) + of ``.`` (Refer to https://www.lua.org/manual/5.2/manual.html#3.4.9 .) Example: @@ -500,11 +519,11 @@ The ``mp`` module is preloaded, although it can be loaded manually with Return the name of the current script. The name is usually made of the filename of the script, with directory and file extension removed. If there are several scripts which would have the same name, it's made unique - by appending a number. + by appending a number. Any nonalphanumeric characters are replaced with ``_``. .. admonition:: Example - The script ``/path/to/fooscript.lua`` becomes ``fooscript``. + The script ``/path/to/foo-script.lua`` becomes ``foo_script``. ``mp.get_script_directory()`` Return the directory if this is a script packaged as directory (see @@ -521,18 +540,6 @@ Advanced mp functions These also live in the ``mp`` module, but are documented separately as they are useful only in special situations. -``mp.suspend()`` - This function has been deprecated in mpv 0.21.0 and does nothing starting - with mpv 0.23.0 (no replacement). - -``mp.resume()`` - This function has been deprecated in mpv 0.21.0 and does nothing starting - with mpv 0.23.0 (no replacement). - -``mp.resume_all()`` - This function has been deprecated in mpv 0.21.0 and does nothing starting - with mpv 0.23.0 (no replacement). - ``mp.get_wakeup_pipe()`` Calls ``mpv_get_wakeup_pipe()`` and returns the read end of the wakeup pipe. This is deprecated, but still works. (See ``client.h`` for details.) @@ -599,6 +606,7 @@ are useful only in special situations. ``update()`` Commit the OSD overlay to the screen, or in other words, run the ``osd-overlay`` command with the current fields of the overlay table. + Returns the result of the ``osd-overlay`` command itself. ``remove()`` Remove the overlay from the screen. A ``update()`` call will add it @@ -617,7 +625,7 @@ are useful only in special situations. ``mp.get_osd_size()`` Returns a tuple of ``osd_width, osd_height, osd_par``. The first two give - the size of the OSD in pixels (for video ouputs like ``--vo=xv``, this may + the size of the OSD in pixels (for video outputs like ``--vo=xv``, this may be "scaled" pixels). The third is the display pixel aspect ratio. May return invalid/nonsense values if OSD is not initialized yet. @@ -677,13 +685,13 @@ with values found in the config-file and the command-line (in that order). Example implementation:: - require 'mp.options' local options = { optionA = "defaultvalueA", optionB = -0.5, optionC = true, } - read_options(options, "myscript") + + require "mp.options".read_options(options, "myscript") print(options.optionA) @@ -762,7 +770,7 @@ strictly part of the guaranteed API. ``mtime`` time of last modification ``ctime`` - time of last metadata change (Linux) / time of creation (Windows) + time of last metadata change ``is_file`` Whether ``path`` is a regular file (boolean) ``is_dir`` @@ -774,7 +782,7 @@ strictly part of the guaranteed API. The booleans ``is_file`` and ``is_dir`` are provided as a convenience; they can be and are derived from ``mode``. - On error (eg. path does not exist), ``nil, error`` is returned. + On error (e.g. path does not exist), ``nil, error`` is returned. ``utils.split_path(path)`` Split a path into directory component and filename component, and return @@ -783,7 +791,7 @@ strictly part of the guaranteed API. ``utils.join_path(p1, p2)`` Return the concatenation of the 2 paths. Tries to be clever. For example, - if ```p2`` is an absolute path, p2 is returned without change. + if ``p2`` is an absolute path, ``p2`` is returned without change. ``utils.subprocess(t)`` Runs an external process and waits until it exits. Returns process status @@ -825,6 +833,10 @@ strictly part of the guaranteed API. Returns the process ID of the running mpv process. This can be used to identify the calling mpv when launching (detached) subprocesses. +``utils.get_env_list()`` + Returns the C environment as a list of strings. (Do not confuse this with + the Lua "environment", which is an unrelated concept.) + ``utils.parse_json(str [, trail])`` Parses the given string argument as JSON, and returns it as a Lua table. On error, returns ``nil, error``. (Currently, ``error`` is just a string @@ -851,135 +863,114 @@ strictly part of the guaranteed API. Turn the given value into a string. Formats tables and their contents. This doesn't do anything special; it is only needed because Lua is terrible. -Events ------- - -Events are notifications from player core to scripts. You can register an -event handler with ``mp.register_event``. - -Note that all scripts (and other parts of the player) receive events equally, -and there's no such thing as blocking other scripts from receiving events. - -Example: - -:: - - function my_fn(event) - print("start of playback!") - end - - mp.register_event("file-loaded", my_fn) - - +mp.input functions +-------------------- -List of events --------------- +This module lets scripts get textual input from the user using the console +REPL. -``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). +``input.get(table)`` + Show the console to let the user enter text. -``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 following entries of ``table`` are read: - The event has the ``reason`` field, which takes one of these values: + ``prompt`` + The string to be displayed before the input field. - ``eof`` - The file has ended. This can (but doesn't have to) include - incomplete files or broken network connections under - circumstances. + ``submit`` + A callback invoked when the user presses Enter. The first argument is + the text in the console. You can close the console from within the + callback by calling ``input.terminate()``. If you don't, the console + stays open and the user can input more text. - ``stop`` - Playback was ended by a command. + ``opened`` + A callback invoked when the console is shown. This can be used to + present a list of options with ``input.set_log()``. - ``quit`` - Playback was ended by sending the quit command. + ``edited`` + A callback invoked when the text changes. This can be used to filter a + list of options based on what the user typed with ``input.set_log()``, + like dmenu does. The first argument is the text in the console. - ``error`` - An error happened. In this case, an ``error`` field is present with - the error string. + ``complete`` + A callback invoked when the user presses TAB. The first argument is the + text before the cursor. The callback should return a table of the string + candidate completion values and the 1-based cursor position from which + the completion starts. console.lua will filter the suggestions beginning + with the the text between this position and the cursor, sort them + alphabetically, insert their longest common prefix, and show them when + there are multiple ones. - ``redirect`` - Happens with playlists and similar. Details see - ``MPV_END_FILE_REASON_REDIRECT`` in the C API. + ``closed`` + A callback invoked when the console is hidden, either because + ``input.terminate()`` was invoked from the other callbacks, or because + the user closed it with a key binding. The first argument is the text in + the console, and the second argument is the cursor position. - ``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.) + ``default_text`` + A string to pre-fill the input field with. -``file-loaded`` - Happens after a file was loaded and begins playback. + ``cursor_position`` + The initial cursor position, starting from 1. -``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.) + ``id`` + An identifier that determines which input history and log buffer to use + among the ones stored for ``input.get()`` calls. The input histories + and logs are stored in memory and do not persist across different mpv + invocations. Defaults to the calling script name with ``prompt`` + appended. -``playback-restart`` - Start of playback after seek or after file was loaded. +``input.terminate()`` + Close the console. -``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. +``input.log(message, style, terminal_style)`` + Add a line to the log buffer. ``style`` can contain additional ASS tags to + apply to ``message``, and ``terminal_style`` can contain escape sequences + that are used when the console is displayed in the terminal. -``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. +``input.log_error(message)`` + Helper to add a line to the log buffer with the same color as the one the + console uses for errors. Useful when the user submits invalid input. -``shutdown`` - Sent when the player quits, and the script should terminate. Normally - handled automatically. See `Details on the script initialization and lifecycle`_. +``input.set_log(log)`` + Replace the entire log buffer. -``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: + ``log`` is a table of strings, or tables with ``text``, ``style`` and + ``terminal_style`` keys. - ``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``. + Example: - ``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. + input.set_log({ + "regular text", + { + text = "error text", + style = "{\\c&H7a77f2&}", + terminal_style = "\027[31m", + } + }) - 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. +Events +------ -``get-property-reply`` - Undocumented (not useful for Lua scripts). +Events are notifications from player core to scripts. You can register an +event handler with ``mp.register_event``. -``set-property-reply`` - Undocumented (not useful for Lua scripts). +Note that all scripts (and other parts of the player) receive events equally, +and there's no such thing as blocking other scripts from receiving events. -``command-reply`` - Undocumented (not useful for Lua scripts). +Example: -``client-message`` - Undocumented (used internally). +:: -``video-reconfig`` - Happens on video output or filter reconfig. + function my_fn(event) + print("start of playback!") + end -``audio-reconfig`` - Happens on audio output or filter reconfig. + mp.register_event("file-loaded", my_fn) -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 ------ @@ -993,8 +984,22 @@ guarantee a stable interface. their result (normally, the Lua scripting interface is asynchronous from the point of view of the player core). ``priority`` is an arbitrary integer that allows ordering among hooks of the same kind. Using the value 50 is - recommended as neutral default value. ``fn`` is the function that will be - called during execution of the hook. + recommended as neutral default value. + + ``fn(hook)`` is the function that will be called during execution of the + hook. The parameter passed to it (``hook``) is a Lua object that can control + further aspects about the currently invoked hook. It provides the following + methods: + + ``defer()`` + Returning from the hook function should not automatically continue + the hook. Instead, the API user wants to call ``hook:cont()`` on its + own at a later point in time (before or after the function has + returned). + + ``cont()`` + Continue the hook. Doesn't need to be called unless ``defer()`` was + called. See `Hooks`_ for currently existing hooks and what they do - only the hook list is interesting; handling hook execution is done by the Lua script |