diff --git a/README.md b/README.md index 7766089..c4e0b1d 100644 --- a/README.md +++ b/README.md @@ -83,3 +83,6 @@ This project includes third party software from the projects listed below. ### Shaders * [Anime4K](https://github.com/bloc97/Anime4K) v4.0.1 * [FSR.glsl](https://gist.github.com/agyild/82219c545228d70c5604f865ce0b0ce5) v1.0.2 + +### Lua stubs +* [emmylua-stubs](https://github.com/haolian9/emmylua-stubs) based on commit 6d6a51d9f64e30dfe2f57ff104485095361d4a7b diff --git a/meta/mp.lua b/meta/mp.lua new file mode 100644 index 0000000..14a15c6 --- /dev/null +++ b/meta/mp.lua @@ -0,0 +1,489 @@ +-- Source: https://github.com/haolian9/emmylua-stubs/blob/6d6a51d9f64e30dfe2f57ff104485095361d4a7b/mpv/library/mpv.lua +-- MIT License +-- +-- Copyright (c) 2022 高浩亮 +-- +-- Permission is hereby granted, free of charge, to any person obtaining a copy +-- of this software and associated documentation files (the "Software"), to deal +-- in the Software without restriction, including without limitation the rights +-- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +-- copies of the Software, and to permit persons to whom the Software is +-- furnished to do so, subject to the following conditions: +-- +-- The above copyright notice and this permission notice shall be included in all +-- copies or substantial portions of the Software. +-- +-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +-- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +-- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +-- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +-- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +-- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +-- SOFTWARE. + +--The `mp` module is preloaded, although it can be loaded manually with +--require 'mp'. It provides the core client API. +--@class mp +mp = {} + +--Run the given command. This is similar to the commands used in input.conf. +--See `List of Input Commands`_. +--By default, this will show something on the OSD (depending on the command), +--as if it was used in ``input.conf``. See `Input Command Prefixes`_ how +--to influence OSD usage per command. +--Returns ``true`` on success, or ``nil, error`` on error. +function mp.command(string) end + +--Similar to ``mp.command``, but pass each command argument as separate +--parameter. This has the advantage that you don't have to care about +--quoting and escaping in some cases. +--Example: +--:: +-- mp.command("loadfile " .. filename .. " append") +-- mp.commandv("loadfile", filename, "append") +--These two commands are equivalent, except that the first version breaks +--if the filename contains spaces or certain special characters. +--Note that properties are *not* expanded. You can use either ``mp.command``, +--the ``expand-properties`` prefix, or the ``mp.get_property`` family of +--functions. +--Unlike ``mp.command``, this will not use OSD by default either (except +--for some OSD-specific commands). +function mp.commandv(arg1, arg2, ...) end + +--Similar to ``mp.commandv``, but pass the argument list as table. This has +--the advantage that in at least some cases, arguments can be passed as +--native types. It also allows you to use named argument. +--If the table is an array, each array item is like an argument in +--``mp.commandv()`` (but can be a native type instead of a string). +--If the table contains string keys, it's interpreted as command with named +--arguments. This requires at least an entry with the key ``name`` to be +--present, which must be a string, and contains the command name. The special +--entry ``_flags`` is optional, and if present, must be an array of +--`Input Command Prefixes`_ to apply. All other entries are interpreted as +--arguments. +--Returns a result table on success (usually empty), or ``def, error`` on +--error. ``def`` is the second parameter provided to the function, and is +--nil if it's missing. +function mp.command_native(table ,def ) end + +--Like ``mp.command_native()``, but the command is ran asynchronously (as far +--as possible), and upon completion, fn is called. fn has three arguments: +--``fn(success, result, error)``: +-- ``success`` +-- Always a Boolean and is true if the command was successful, +-- otherwise false. +-- ``result`` +-- The result value (can be nil) in case of success, nil otherwise (as +-- returned by ``mp.command_native()``). +-- ``error`` +-- The error string in case of an error, nil otherwise. +--Returns a table with undefined contents, which can be used as argument for +--``mp.abort_async_command``. +--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. +function mp.command_native_async(table ,fn ) end + +--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. +function mp.abort_async_command(t) end + +--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 +--properties. The returned string is formatted similar to ``${=name}`` +--(see `Property Expansion`_). +--Returns the string on success, or ``def, error`` on error. ``def`` is the +--second parameter provided to the function, and is nil if it's missing. +function mp.get_property(name ,def ) end + +--Similar to ``mp.get_property``, but return the property value formatted for +--OSD. This is the same string as printed with ``${name}`` when used in +--input.conf. +--Returns the string on success, or ``def, error`` on error. ``def`` is the +--second parameter provided to the function, and is an empty string if it's +--missing. Unlike ``get_property()``, assigning the return value to a variable +--will always result in a string. +function mp.get_property_osd(name ,def ) end + +--Similar to ``mp.get_property``, but return the property value as Boolean. +--Returns a Boolean on success, or ``def, error`` on error. +function mp.get_property_bool(name ,def ) end + +--Similar to ``mp.get_property``, but return the property value as number. +--Note that while Lua does not distinguish between integers and floats, +--mpv internals do. This function simply request a double float from mpv, +--and mpv will usually convert integer property values to float. +--Returns a number on success, or ``def, error`` on error. +function mp.get_property_number(name ,def ) end + +--Similar to ``mp.get_property``, but return the property value using the best +--Lua type for the property. Most time, this will return a string, Boolean, +--or number. Some properties (for example ``chapter-list``) are returned as +--tables. +--Returns a value on success, or ``def, error`` on error. Note that ``nil`` +--might be a possible, valid value too in some corner cases. +function mp.get_property_native(name ,def ) end + +--Set the given property to the given string value. See ``mp.get_property`` +--and `Properties`_ for more information about properties. +--Returns true on success, or ``nil, error`` on error. +function mp.set_property(name, value) end + +--Similar to ``mp.set_property``, but set the given property to the given +--Boolean value. +function mp.set_property_bool(name, value) end + +--Similar to ``mp.set_property``, but set the given property to the given +--numeric value. +--Note that while Lua does not distinguish between integers and floats, +--mpv internals do. This function will test whether the number can be +--represented as integer, and if so, it will pass an integer value to mpv, +--otherwise a double float. +function mp.set_property_number(name, value) end + +--Similar to ``mp.set_property``, but set the given property using its native +--type. +--Since there are several data types which cannot represented natively in +--Lua, this might not always work as expected. For example, while the Lua +--wrapper can do some guesswork to decide whether a Lua table is an array +--or a map, this would fail with empty tables. Also, there are not many +--properties for which it makes sense to use this, instead of +--``set_property``, ``set_property_bool``, ``set_property_number``. +--For these reasons, this function should probably be avoided for now, except +--for properties that use tables natively. +function mp.set_property_native(name, value) end + +--Return the current mpv internal time in seconds as a number. This is +--basically the system time, with an arbitrary offset. +function mp.get_time() end + +--Register callback to be run on a key binding. The binding will be mapped to +--the given ``key``, which is a string describing the physical key. This uses +--the same key names as in input.conf, and also allows combinations +--(e.g. ``ctrl+a``). If the key is empty or ``nil``, no physical key is +--registered, but the user still can create own bindings (see below). +--After calling this function, key presses will cause the function ``fn`` to +--be called (unless the user remapped the key with another binding). +--The ``name`` argument should be a short symbolic string. It allows the user +--to remap the key binding via input.conf using the ``script-message`` +--command, and the name of the key binding (see below for +--an example). The name should be unique across other bindings in the same +--script - if not, the previous binding with the same name will be +--overwritten. You can omit the name, in which case a random name is generated +--internally. (Omitting works as follows: either pass ``nil`` for ``name``, +--or pass the ``fn`` argument in place of the name. The latter is not +--recommended and is handled for compatibility only.) +--The last argument is used for optional flags. This is a table, which can +--have the following entries: +-- ``repeatable`` +-- If set to ``true``, enables key repeat for this specific binding. +-- ``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): +-- ``event`` +-- Set to one of the strings ``down``, ``repeat``, ``up`` or +-- ``press`` (the latter if key up/down can't be tracked). +-- ``is_mouse`` +-- Boolean Whether the event was caused by a mouse button. +-- ``key_name`` +-- The name of they key that triggered this, or ``nil`` if +-- invoked artificially. If the key name is unknown, it's an +-- empty string. +-- ``key_text`` +-- Text if triggered by a text key, otherwise ``nil``. See +-- description of ``script-binding`` command for details (this +-- field is equivalent to the 5th argument). +--Internally, key bindings are dispatched via the ``script-message-to`` or +--``script-binding`` input commands and ``mp.register_script_message``. +--Trying to map multiple commands to a key will essentially prefer a random +--binding, while the other bindings are not called. It is guaranteed that +--user defined bindings in the central input.conf are preferred over bindings +--added with this function (but see ``mp.add_forced_key_binding``). +--Example: +--:: +-- function something_handler() +-- print("the key was pressed") +-- end +-- mp.add_key_binding("x", "something", something_handler) +--This will print the message ``the key was pressed`` when ``x`` was pressed. +--The user can remap these key bindings. Then the user has to put the +--following into their input.conf to remap the command to the ``y`` key: +--:: +-- y script-binding something +--This will print the message when the key ``y`` is pressed. (``x`` will +--still work, unless the user remaps it.) +--You can also explicitly send a message to a named script only. Assume the +--above script was using the filename ``fooscript.lua``: +--:: +-- y script-binding fooscript/something +function mp.add_key_binding(key, name_or_fn ,fn ,flags ) end + +--This works almost the same as ``mp.add_key_binding``, but registers the +--key binding in a way that will overwrite the user's custom bindings in their +--input.conf. (``mp.add_key_binding`` overwrites default key bindings only, +--but not those by the user's input.conf.) +function mp.add_forced_key_binding(...) end + +--Remove a key binding added with ``mp.add_key_binding`` or +--``mp.add_forced_key_binding``. Use the same name as you used when adding +--the bindings. It's not possible to remove bindings for which you omitted +--the name. +function mp.remove_key_binding(name) end + +--Call a specific function when an event happens. The event name is a string, +--and the function fn is a Lua function value. +--Some events have associated data. This is put into a Lua table and passed +--as argument to fn. The Lua table by default contains a ``name`` field, +--which is a string containing the event name. If the event has an error +--associated, the ``error`` field is set to a string describing the error, +--on success it's not set. +--If multiple functions are registered for the same event, they are run in +--registration order, which the first registered function running before all +--the other ones. +--Returns true if such an event exists, false otherwise. +--See `Events`_ and `List of events`_ for details. +function mp.register_event(name, fn) end + +--Undo ``mp.register_event(..., fn)``. This removes all event handlers that +--are equal to the ``fn`` parameter. This uses normal Lua ``==`` comparison, +--so be careful when dealing with closures. +function mp.unregister_event(fn) end + +--Watch a property for changes. If the property ``name`` is changed, then +--the function ``fn(name)`` will be called. ``type`` can be ``nil``, or be +--set to one of ``none``, ``native``, ``bool``, ``string``, or ``number``. +--``none`` is the same as ``nil``. For all other values, the new value of +--the property will be passed as second argument to ``fn``, using +--``mp.get_property_`` to retrieve it. This means if ``type`` is for +--example ``string``, ``fn`` is roughly called as in +--``fn(name, mp.get_property_string(name))``. +--If possible, change events are coalesced. If a property is changed a bunch +--of times in a row, only the last change triggers the change function. (The +--exact behavior depends on timing and other things.) +--If a property is unavailable, or on error, the value argument to ``fn`` is +--``nil``. (The ``observe_property()`` call always succeeds, even if a +--property does not exist.) +--In some cases the function is not called even if the property changes. +--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. +--You always get an initial change notification. This is meant to initialize +--the user's state to the current value of the property. +function mp.observe_property(name, type, fn) end + +--Undo ``mp.observe_property(..., fn)``. This removes all property handlers +--that are equal to the ``fn`` parameter. This uses normal Lua ``==`` +--comparison, so be careful when dealing with closures. +function mp.unobserve_property(fn) end + +--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. +--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. +function mp.add_timeout(seconds, fn) end + +--Call the given function periodically. This is like ``mp.add_timeout``, but +--the timer is re-added after the function fn is run. +--Returns a timer object. The timer object provides the following methods: +-- ``stop()`` +-- Disable the timer. Does nothing if the timer is already disabled. +-- This will remember the current elapsed time when stopping, so that +-- ``resume()`` essentially unpauses the timer. +-- ``kill()`` +-- Disable the timer. Resets the elapsed time. ``resume()`` will +-- restart the timer. +-- ``resume()`` +-- Restart the timer. If the timer was disabled with ``stop()``, this +-- will resume at the time it was stopped. If the timer was disabled +-- with ``kill()``, or if it's a previously fired one-shot timer (added +-- with ``add_timeout()``), this starts the timer from the beginning, +-- using the initially configured timeout. +-- ``is_enabled()`` +-- Whether the timer is currently enabled or was previously disabled +-- (e.g. by ``stop()`` or ``kill()``). +-- ``timeout`` (RW) +-- This field contains the current timeout period. This value is not +-- updated as time progresses. It's only used to calculate when the +-- timer should fire next when the timer expires. +-- If you write this, you can call ``t:kill() ; t:resume()`` to reset +-- the current timeout to the new one. (``t:stop()`` won't use the +-- new timeout.) +-- ``oneshot`` (RW) +-- Whether the timer is periodic (``false``) or fires just once +-- (``true``). This value is used when the timer expires (but before +-- the timer callback function fn is run). +--Note that these are methods, and you have to call them using ``:`` instead +--of ``.`` (Refer to https://www.lua.org/manual/5.2/manual.html#3.4.9 .) +--Example: +--:: +-- seconds = 0 +-- timer = mp.add_periodic_timer(1, function() +-- print("called every second") +-- # stop it after 10 seconds +-- seconds = seconds + 1 +-- if seconds >= 10 then +-- timer:kill() +-- end +-- end) +function mp.add_periodic_timer(seconds, fn) end + +--Return a setting from the ``--script-opts`` option. It's up to the user and +--the script how this mechanism is used. Currently, all scripts can access +--this equally, so you should be careful about collisions. +function mp.get_opt(key) end + +--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. Any nonalphanumeric characters are replaced with ``_``. +--.. admonition:: Example +-- The script ``/path/to/foo-script.lua`` becomes ``foo_script``. +function mp.get_script_name() end + +--Return the directory if this is a script packaged as directory (see +--`Script location`_ for a description). Return nothing if this is a single +--file script. +function mp.get_script_directory() end + +--Show an OSD message on the screen. ``duration`` is in seconds, and is +--optional (uses ``--osd-duration`` by default). +function mp.osd_message(text ,duration ) end + +--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.) +function mp.get_wakeup_pipe() end + +--Return the relative time in seconds when the next timer (``mp.add_timeout`` +--and similar) expires. If there is no timer, return ``nil``. +function mp.get_next_timeout() end + +--This can be used to run custom event loops. If you want to have direct +--control what the Lua script does (instead of being called by the default +--event loop), you can set the global variable ``mp_event_loop`` to your +--own function running the event loop. From your event loop, you should call +--``mp.dispatch_events()`` to dequeue and dispatch mpv events. +--If the ``allow_wait`` parameter is set to ``true``, the function will block +--until the next event is received or the next timer expires. Otherwise (and +--this is the default behavior), it returns as soon as the event loop is +--emptied. It's strongly recommended to use ``mp.get_next_timeout()`` and +--``mp.get_wakeup_pipe()`` if you're interested in properly working +--notification of new events and working timers. +function mp.dispatch_events( allow_wait ) end + +--Register an event loop idle handler. Idle handlers are called before the +--script goes to sleep after handling all new events. This can be used for +--example to delay processing of property change events: if you're observing +--multiple properties at once, you might not want to act on each property +--change, but only when all change notifications have been received. +function mp.register_idle(fn) end + +--Undo ``mp.register_idle(fn)``. This removes all idle handlers that +--are equal to the ``fn`` parameter. This uses normal Lua ``==`` comparison, +--so be careful when dealing with closures. +function mp.unregister_idle(fn) end + +--Set the minimum log level of which mpv message output to receive. These +--messages are normally printed to the terminal. By calling this function, +--you can set the minimum log level of messages which should be received with +--the ``log-message`` event. See the description of this event for details. +--The level is a string, see ``msg.log`` for allowed log levels. +function mp.enable_messages(level) end + +--This is a helper to dispatch ``script-message`` or ``script-message-to`` +--invocations to Lua functions. ``fn`` is called if ``script-message`` or +--``script-message-to`` (with this script as destination) is run +--with ``name`` as first parameter. The other parameters are passed to ``fn``. +--If a message with the given name is already registered, it's overwritten. +--Used by ``mp.add_key_binding``, so be careful about name collisions. +function mp.register_script_message(name, fn) end + +--Undo a previous registration with ``mp.register_script_message``. Does +--nothing if the ``name`` wasn't registered. +function mp.unregister_script_message(name) end + +--Create an OSD overlay. This is a very thin wrapper around the ``osd-overlay`` +--command. The function returns a table, which mostly contains fields that +--will be passed to ``osd-overlay``. The ``format`` parameter is used to +--initialize the ``format`` field. The ``data`` field contains the text to +--be used as overlay. For details, see the ``osd-overlay`` command. +--In addition, it provides the following methods: +--``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 +-- again. +--Example: +--:: +-- ov = mp.create_osd_overlay("ass-events") +-- ov.data = "{\\an5}{\\b1}hello world!" +-- ov:update() +--The advantage of using this wrapper (as opposed to running ``osd-overlay`` +--directly) is that the ``id`` field is allocated automatically. +function mp.create_osd_overlay(format) end + +--Returns a tuple of ``osd_width, osd_height, osd_par``. The first two give +--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. +function mp.get_osd_size() end + +--This module allows outputting messages to the terminal, and can be loaded +--with ``require 'mp.msg'``. +--@class mp.msg +mp.msg = {} + +--The level parameter is the message priority. It's a string and one of +--``fatal``, ``error``, ``warn``, ``info``, ``v``, ``debug``, ``trace``. The +--user's settings will determine which of these messages will be +--visible. Normally, all messages are visible, except ``v``, ``debug`` and +--``trace``. +--The parameters after that are all converted to strings. Spaces are inserted +--to separate multiple parameters. +--You don't need to add newlines. +function mp.msg.log(level, ...) end + +--All of these are shortcuts and equivalent to the corresponding +--``msg.log(level, ...)`` call. +function mp.msg.fatal(...) end +function mp.msg.error(...) end +function mp.msg.warn(...) end +function mp.msg.info(...) end +function mp.msg.verbose(...) end +function mp.msg.debug(...) end +function mp.msg.trace(...) end + +--mpv comes with a built-in module to manage options from config-files and the +--command-line. All you have to do is to supply a table with default options to +--the read_options function. The function will overwrite the default values +--with values found in the config-file and the command-line (in that order). +--@class mp.options +mp.options = {} + +--A ``table`` with key-value pairs. The type of the default values is +--important for converting the values read from the config file or +--command-line back. Do not use ``nil`` as a default value! +--The ``identifier`` is used to identify the config-file and the command-line +--options. These needs to unique to avoid collisions with other scripts. +--Defaults to ``mp.get_script_name()`` if the parameter is ``nil`` or missing. +--The ``on_update`` parameter enables run-time updates of all matching option +--values via the ``script-opts`` option/property. If any of the matching +--options changes, the values in the ``table`` (which was originally passed to +--the function) are changed, and ``on_update(list)`` is called. ``list`` is +--a table where each updated option has a ``list[option_name] = true`` entry. +--There is no initial ``on_update()`` call. This never re-reads the config file. +--``script-opts`` is always applied on the original config file, ignoring +--previous ``script-opts`` values (for example, if an option is removed from +--``script-opts`` at runtime, the option will have the value in the config +--file). ``table`` entries are only written for option values whose values +--effectively change (this is important if the script changes ``table`` +--entries independently).