function on_pause_change(name, value)
    if value == true then
        mp.set_property("fullscreen", "no")
    end
end
mp.observe_property("pause", "bool", on_pause_change)

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.

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).

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.

    ``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.

Returns true on success, or ``nil, error`` on error.

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.

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.

Returns a Boolean on success, or ``def, error`` on error.

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.

Returns a value on success, or ``def, error`` on error. Note that ``nil``
might be a possible, valid value too in some corner cases.

Returns true on success, or ``nil, error`` on error.

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.

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.

After calling this function, key presses will cause the function ``fn`` to
be called (unless the user remapped the key with another binding).
However, if the key binding is canceled , the function will not be called,
unless ``complex`` flag is set to ``true``, where the function will be
called with the ``canceled`` entry set to ``true``.

For example, a canceled key binding can happen in the following situations:

- If key A is pressed while key B is being held down, key B is logically
  released ("canceled" by key A), which stops the current autorepeat
  action key B has.
- If key A is pressed while a mouse button is being held down, the mouse
  button is logically released, but the mouse button's action will not be
  called, unless ``complex`` flag is set to ``true``.

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 ``flags`` argument is used for optional parameters. This is a table,
which can have the following entries:

    ``repeatable``
        If set to ``true``, enables key repeat for this specific binding.
        This option only makes sense when ``complex`` is not set to ``true``.

    ``scalable``
        If set to ``true``, enables key scaling for this specific binding.
        This option only makes sense when ``complex`` is set to ``true``.
        Note that this has no effect if the key binding is invoked by
        ``script-binding`` command, where the scalability of the command
        takes precedence.

    ``complex``
        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/repeat can't be
                tracked), which indicates the key's logical state.

            ``is_mouse``
                Boolean: Whether the event was caused by a mouse button.

            ``canceled``
                Boolean: Whether the event was canceled.
                Not all types of cancellations set this flag.

            ``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).

            ``scale``
                The scale of the key, such as the ones produced by ``WHEEL_*``
                keys. The scale is 1 if the key is nonscalable.

            ``arg``
                User-provided string in the ``arg`` argument in the
                ``script-binding`` command if the key binding is invoked
                by that command.

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

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 ``event`` 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.

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``, 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.

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.

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)

.. admonition:: Example

    The script ``/path/to/foo-script.lua`` becomes ``foo_script``.

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.

Used by ``mp.add_key_binding``, so be careful about name collisions.

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.

May return invalid/nonsense values if OSD is not initialized yet.

This can be polyfilled to support mpv versions older than 0.40 with:

::

    if not _G.exit then
        function exit()
            mp.keep_running = false
        end
    end

The parameters after that are all converted to strings. Spaces are inserted
to separate multiple parameters.

You don't need to add newlines.

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).

local options = {
    optionA = "defaultvalueA",
    optionB = -0.5,
    optionC = true,
}

require "mp.options".read_options(options, "myscript")
print(options.optionA)

# comment
optionA=Hello World
optionB=9999
optionC=no

 --script-opts=myscript-optionA=TEST,myscript-optionB=0,myscript-optionC=yes

If the ``filter`` argument is given, it must be one of the following
strings:

    ``files``
        List regular files only. This excludes directories, special files
        (like UNIX device files or FIFOs), and dead symlinks. It includes
        UNIX symlinks to regular files.

    ``dirs``
        List directories only, or symlinks to directories. ``.`` and ``..``
        are not included.

    ``normal``
        Include the results of both ``files`` and ``dirs``. (This is the
        default.)

    ``all``
        List all entries, even device files, dead symlinks, FIFOs, and the
        ``.`` and ``..`` entries.

On error, ``nil, error`` is returned.

    ``mode``
        protection bits (on Windows, always 755 (octal) for directories
        and 644 (octal) for files)
    ``size``
        size in bytes
    ``atime``
        time of last access
    ``mtime``
        time of last modification
    ``ctime``
        time of last metadata change
    ``is_file``
        Whether ``path`` is a regular file (boolean)
    ``is_dir``
        Whether ``path`` is a directory (boolean)

``mode`` and ``size`` are integers.
Timestamps (``atime``, ``mtime`` and ``ctime``) are integer seconds since
the Unix epoch (Unix time).
The booleans ``is_file`` and ``is_dir`` are provided as a convenience;
they can be and are derived from ``mode``.

On error (e.g. path does not exist), ``nil, error`` is returned.

- copy the table ``t``
- rename ``cancellable`` field to ``playback_only``
- rename ``max_size`` to ``capture_size``
- set ``capture_stdout`` field to ``true`` if unset
- set ``name`` field to ``subprocess``
- call ``mp.command_native(copied_t)``
- if the command failed, create a dummy result table
- copy ``error_string`` to ``error`` field if the string is non-empty
- return the result table

It is recommended to use ``mp.command_native`` or ``mp.command_native_async``
directly, instead of calling this legacy wrapper. It is for compatibility
only.

See the ``subprocess`` documentation for semantics and further parameters.

The parameter ``t`` is a table. The function reads the following entries:

    ``args``
        Array of strings of the same semantics as the ``args`` used in the
        ``subprocess`` function.

The function returns ``nil``.

This is a legacy wrapper around calling the ``run`` command with
``mp.commandv`` and other functions.

The returned value uses similar conventions as ``mp.get_property_native()``
to distinguish empty objects and arrays.

If the ``trail`` parameter is ``true`` (or any value equal to ``true``),
then trailing non-whitespace text is tolerated by the function, and the
trailing text is returned as 3rd return value. (The 3rd return value is
always there, but with ``trail`` set, no error is raised.)

The argument value uses similar conventions as ``mp.set_property_native()``
to distinguish empty objects and arrays.

The following entries of ``table`` are read:

``prompt``
    The string to be displayed before the input field.

``submit``
    A callback invoked when the user presses Enter. The first argument is
    the text in the console.

``keep_open``
    Whether to keep the console open on submit, allowing further input.
    Defaults to ``false``.

    If calling ``input.get()`` or ``input.select()`` again from inside the
    ``submit`` callback, setting this option to ``true`` allows a seamless
    transition without the console closing and reopening.

``opened``
    A callback invoked when the console is shown. This can be used to
    override keybinds set by the console with ``mp.add_forced_key_binding()``.

``edited``
    A callback invoked when the text changes. The first argument is the text
    in the console.

``complete``
    A callback invoked when the user edits the text or moves the cursor. The
    first argument is the text before the cursor, and the second argument is
    a response function which can be called to present completion values to
    the user.

    The first argument to the response function is a table of the string
    candidate completion values, and the second argument is the 1-based cursor
    position from which the completion starts. console will show the
    completions that fuzzily match the text between this position and the
    cursor, which the user can select with ``TAB``. The completions will only
    be shown to the user if the text before the cursor has not since changed.
    The response function should be called with an empty table if there are no
    completion values to display.

    The third and optional argument to the response function is a string that
    will be appended to the input line without displaying it in the completions.

``autoselect_completion``
    Whether to automatically select the first completion on submit if one
    wasn't already manually selected. Defaults to ``false``.

``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.

``default_text``
    A string to pre-fill the input field with.

``cursor_position``
    The initial cursor position, starting from 1.

``history_path``
    If specified, the path to save and load the history of the entered
    lines.

``id``
    An identifier that determines which input history and log buffer to use
    among the ones stored for ``input.get()`` calls. Defaults to the calling
    script name with ``prompt`` appended.

``console_opt_overrides``
    A table containing configuration overrides for the console script.
    Can be used to change the visual style of the text input, among other things.
    See `CONSOLE`_ for the full list of options.

``log`` is a table of strings, or tables with ``text``, ``style`` and
``terminal_style`` keys.

Example:

::

    input.set_log({
        "regular text",
        {
            text = "error text",
            style = "{\\c&H7a77f2&}",
            terminal_style = "\027[31m",
        }
    })

The following entries of ``table`` are read:

``prompt``
    The string to be displayed before the input field.

``items``
    The table of the entries to choose from.

``default_item``
    The 1-based integer index of the preselected item.

``submit``
    The callback invoked when the user presses Enter. The first argument is
    the 1-based index of the selected item.

``keep_open``
    Whether to keep the console open on submit, allowing further input.
    Defaults to ``false``.

    If calling ``input.get()`` or ``input.select()`` again from inside the
    ``submit`` callback, setting this option to ``true`` allows a seamless
    transition without the console closing and reopening.

``opened``
    A callback invoked when the console is shown. This can be used to
    override keybinds set by the console with ``mp.add_forced_key_binding()``.

``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.

``default_text``
    A string to pre-fill the input field with.

``cursor_position``
    The initial cursor position, starting from 1.

``console_opt_overrides``
    A table containing configuration overrides for the console script.
    Can be used to change the visual style of the select window, among other things.
    See `CONSOLE`_ for the full list of options.

Example:

    ::

        input.select({
            items = {
                "First playlist entry",
                "Second playlist entry",
            },
            submit = function (id)
                mp.commandv("playlist-play-index", id - 1)
            end,
        })

function my_fn(event)
    print("start of playback!")
end

mp.register_event("file-loaded", my_fn)

``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
function automatically.