From 40d6b5ca85e61252871158097e099916376a5dd4 Mon Sep 17 00:00:00 2001 From: wm4 Date: Tue, 21 Oct 2014 00:15:30 +0200 Subject: lua: add convenience function for hooks So the user doesn't have to care about the awkward low-level details. --- DOCS/man/lua.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'DOCS') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 2eddbb8f2f..f35af85079 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -734,3 +734,29 @@ List of events ``chapter-change`` The current chapter possibly changed. + +Extras +------ + +This documents experimental features, or features that are "too special" and +we don't guarantee a stable interface to it. + +``mp.add_hook(type, priority, fn)`` + Add a hook callback for ``type`` (a string identifying a certain kind of + hook). These hooks allow the player to call script functions and wait for + 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. + + Currently existing hooks: + + ``on_load`` + Called when a file is to be opened, before anything is actually done. + For example, you could read and write the ``stream-open-filename`` + property to redirect an URL to something else (consider support for + streaming sites which rarely give the user a direct media URL), or + you could set per-file options with by setting the property + ``file-local-options/