From b86bfc907f9ca14fdbfd0cdbca5ba88cfc660fc6 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 1 Feb 2020 18:10:07 +0100 Subject: lua: set package path if loaded from a script directory And document the shit. This uses code from commit bc1c024ae032e5b5c. --- DOCS/man/lua.rst | 44 ++++++++++++++++++++++++++++++++++++++------ DOCS/man/mpv.rst | 9 +++++---- 2 files changed, 43 insertions(+), 10 deletions(-) (limited to 'DOCS') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 0829e8be4b..b7b423a22b 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -1,12 +1,7 @@ LUA SCRIPTING ============= -mpv can load Lua scripts. Scripts passed to the ``--script`` option, or found in -the ``scripts`` subdirectory of the mpv configuration directory (usually -``~/.config/mpv/scripts/``) will be loaded on program start. mpv also appends the -``scripts`` subdirectory to the end of Lua's path so you can import scripts from -there too. Since it's added to the end, don't name scripts you want to import -the same as Lua libraries because they will be overshadowed by them. +mpv can load Lua scripts. (See `Script location`_.) mpv provides the built-in module ``mp``, which contains functions to send commands to the mpv core and to retrieve information about playback state, user @@ -30,6 +25,43 @@ A script which leaves fullscreen mode when the player is paused: mp.observe_property("pause", "bool", on_pause_change) +Script location +--------------- + +Scripts can be passed to the ``--script`` option, and are automatically loaded +from the ``scripts`` subdirectory of the mpv configuration directory (usually +``~/.config/mpv/scripts/``). + +A script can be a single file. The file extension is used to select the +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.) + +Entries with ``.disable`` extension are always ignored. + +If a script is a directory (either if a directory is passed to ``--script``, +or any sub-directories in the script directory, such as for example +``~/.config/mpv/scripts/something/``), then the directory represents a single +script. The player will try to load a file named ``main.x``, where ``x`` is +replaced with the file extension. For example, if ``main.lua`` exists, it is +loaded with the Lua scripting backend. + +You must not put any other files or directories that start with ``main.`` into +the script's top level directory. If the script directory contains for example +both ``main.lua`` and ``main.js``, only one of them will be loaded (and which +one depends on mpv internals that may change any time). Likewise, if there is +for example ``main.foo``, your script will break as soon as mpv adds a backend +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. + +On the other hand, if the script is a single file (directly located in +``~/.config/mpv/scripts/`` and not as sub-directory), the Lua package path +does not include any mpv specific directories. (This was silently changed in +mpv 0.32.0.) + Details on the script initialization and lifecycle -------------------------------------------------- diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index 9cc0726639..286c56392c 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -1242,10 +1242,11 @@ For Windows-specifics, see `FILES ON WINDOWS`_ section. ``~/.config/mpv/scripts/`` All files in this directory are loaded as if they were passed to the - ``--script`` option. They are loaded in alphabetical order. Directory entries - other than files are ignored. Files with unknown extension lead to an - initialization error. Files with ``.disable`` extension are ignored. The - ``--load-scripts=no`` option disables loading these files. + ``--script`` option. They are loaded in alphabetical order. + + The ``--load-scripts=no`` option disables loading these files. + + See `Script location`_ for details. ``~/.config/mpv/watch_later/`` Contains temporary config files needed for resuming playback of files with -- cgit v1.2.3