From d223a63bc5de423bca7337795fe165678cf6d236 Mon Sep 17 00:00:00 2001 From: "Avi Halachmi (:avih)" Date: Sat, 13 Dec 2014 18:27:47 +0200 Subject: js: add javascript scripting support using MuJS Implements JS with almost identical API to the Lua support. Key differences from Lua: - The global mp, mp.msg and mp.utils are always available. - Instead of returning x, error, return x and expose mp.last_error(). - Timers are JS standard set/clear Timeout/Interval. - Supports CommonJS modules/require. - Added at mp.utils: getenv, read_file, write_file and few more. - Global print and dump (expand objects) functions. - mp.options currently not supported. See DOCS/man/javascript.rst for more details. --- DOCS/man/javascript.rst | 336 ++++++++++++++++++++++++++++++++++++++++++++++++ DOCS/man/mpv.rst | 2 + 2 files changed, 338 insertions(+) create mode 100644 DOCS/man/javascript.rst (limited to 'DOCS/man') diff --git a/DOCS/man/javascript.rst b/DOCS/man/javascript.rst new file mode 100644 index 0000000000..0c099cad0a --- /dev/null +++ b/DOCS/man/javascript.rst @@ -0,0 +1,336 @@ +JavaScript +========== + +JavaScript support in mpv is near identical to its Lua support. Use this section +as reference on differences and availability of APIs, but otherwise you should +refer to the Lua documentation for API details and general scripting in mpv. + +Example +------- + +JavaScript code which leaves fullscreen mode when the player is paused: + +:: + + function on_pause_change(name, value) { + if (value == true) + mp.set_property("fullscreen", "no"); + } + mp.observe_property("pause", "bool", on_pause_change); + + +Similarities with Lua +--------------------- + +mpv tries to load a script file as JavaScript if it has a ``.js`` extension, but +otherwise, the documented Lua options, script directories, loading, etc apply to +JavaScript files too. + +Script initialization and lifecycle is the same as with Lua, and most of the Lua +functions at the modules ``mp``, ``mp.utils`` and ``mp.msg`` are available to +JavaScript with identical APIs - including running commands, getting/setting +properties, registering events/key-bindings/property-changes/hooks, etc. + +Differences from Lua +-------------------- + +No need to load modules. ``mp``, ``mp.utils`` and ``mp.msg`` are preloaded, and +you can use e.g. ``var cwd = mp.utils.getcwd();`` without prior setup. +``mp.options`` is currently not implemented, but ``mp.get_opt(...)`` is. + +Errors are slightly different. Where the Lua APIs return ``nil`` for error, +the JavaScript ones return ``undefined``. Where Lua returns ``something, error`` +JavaScript returns only ``something`` - and makes ``error`` available via +``mp.last_error()``. Note that only some of the functions have this additional +``error`` value - typically the same ones which have it in Lua. + +Standard APIs are preferred. For instance ``setTimeout`` and ``JSON.stringify`` +are available, but ``mp.add_timeout`` and ``mp.utils.format_json`` are not. + +No standard library. This means that interaction with anything outside of mpv is +limited to the available APIs, typically via ``mp.utils``. However, some file +functions were added, and CommonJS ``require`` is available too - where the +loaded modules have the same privileges as normal scripts. + +Language features - ECMAScript 5 +-------------------------------- + +The scripting backend which mpv currently uses is MuJS - a compatible minimal +ES5 interpreter. As such, ``String.substring`` is implemented for instance, +while the common but non-standard ``String.substr`` is not. Please consult the +MuJS pages on language features and platform support - http://mujs.com . + +Unsupported Lua APIs and their JS alternatives +---------------------------------------------- + +``mp.add_timeout(seconds, fn)`` JS: ``id = setTimeout(fn, ms)`` + +``mp.add_periodic_timer(seconds, fn)`` JS: ``id = setInterval(fn, ms)`` + +``mp.register_idle(fn)`` JS: ``id = setTimeout(fn)`` + +``mp.unregister_idle(fn)`` JS: ``clearTimeout(id)`` + +``utils.parse_json(str [, trail])`` JS: ``JSON.parse(str)`` + +``utils.format_json(v)`` JS: ``JSON.stringify(v)`` + +``utils.to_string(v)`` see ``dump`` below. + +``mp.suspend()`` JS: none (deprecated). + +``mp.resume()`` JS: none (deprecated). + +``mp.resume_all()`` JS: none (deprecated). + +``mp.get_next_timeout()`` see event loop below. + +``mp.dispatch_events([allow_wait])`` see event loop below. + +``mp.options`` module is not implemented currently for JS. + +Scripting APIs - identical to Lua +--------------------------------- + +(LE) - Last-Error, indicates that ``mp.last_error()`` can be used after the +call to test for success (empty string) or failure (non empty reason string). +Otherwise, where the Lua APIs return ``nil`` on error, JS returns ``undefined``. + +``mp.command(string)`` (LE) + +``mp.commandv(arg1, arg2, ...)`` (LE) + +``mp.command_native(table [,def])`` (LE) + +``mp.get_property(name [,def])`` (LE) + +``mp.get_property_osd(name [,def])`` (LE) + +``mp.get_property_bool(name [,def])`` (LE) + +``mp.get_property_number(name [,def])`` (LE) + +``mp.get_property_native(name [,def])`` (LE) + +``mp.set_property(name, value)`` (LE) + +``mp.set_property_bool(name, value)`` (LE) + +``mp.set_property_number(name, value)`` (LE) + +``mp.set_property_native(name, value)`` (LE) + +``mp.get_time()`` + +``mp.add_key_binding(key, name|fn [,fn [,flags]])`` + +``mp.add_forced_key_binding(...)`` + +``mp.remove_key_binding(name)`` + +``mp.register_event(name, fn)`` + +``mp.unregister_event(fn)`` + +``mp.observe_property(name, type, fn)`` + +``mp.unobserve_property(fn)`` + +``mp.get_opt(key)`` + +``mp.get_script_name()`` + +``mp.osd_message(text [,duration])`` + +``mp.get_wakeup_pipe()`` + +``mp.enable_messages(level)`` + +``mp.register_script_message(name, fn)`` + +``mp.unregister_script_message(name)`` + +``mp.msg.log(level, ...)`` + +``mp.msg.fatal(...)`` + +``mp.msg.error(...)`` + +``mp.msg.warn(...)`` + +``mp.msg.info(...)`` + +``mp.msg.verbose(...)`` + +``mp.msg.debug(...)`` + +``mp.utils.getcwd()`` (LE) + +``mp.utils.readdir(path [, filter])`` (LE) + +``mp.utils.split_path(path)`` + +``mp.utils.join_path(p1, p2)`` + +``mp.utils.subprocess(t)`` + +``mp.utils.subprocess_detached(t)`` + +``mp.add_hook(type, priority, fn)`` + +Additional utilities +-------------------- + +``mp.last_error()`` + If used after an API call which updates last error, returns an empty string + if the API call succeeded, or a non-empty error reason string otherwise. + +``Error.stack`` (string) + When using ``try { ... } catch(e) { ... }``, then ``e.stack`` is the stack + trace of the error - if it was created using the ``Error(...)`` constructor. + +``print`` (global) + A convenient alias to ``mp.msg.info``. + +``dump`` (global) + Like ``print`` but also expands objects and arrays recursively. + +``mp.utils.getenv(name)`` + Returns the value of the host environment variable ``name``, or empty str. + +``mp.utils.get_user_path(path)`` + Expands (mpv) meta paths like ``~/x``, ``~~/y``, ``~~desktop/z`` etc. + ``read_file``, ``write_file`` and ``require`` already use this internaly. + +``mp.utils.read_file(fname [,max])`` + Returns the content of file ``fname`` as string. If ``max`` is provided and + not negative, limit the read to ``max`` bytes. + +``mp.utils.write_file(fname, str)`` + (Over)write file ``fname`` with text content ``str``. ``fname`` must be + prefixed with ``file://`` as simple protection against accidental arguments + switch, e.g. ``mp.utils.write_file("file://~/abc.txt", "hello world")``. + +Note: ``read_file`` and ``write_file`` throw on errors, allow text content only. + +``mp.get_time_ms()`` + Same as ``mp.get_time()`` but in ms instead of seconds. + +``mp.get_script_file()`` + Returns the file name of the current script. + +``exit()`` (global) + Make the script exit at the end of the current event loop iteration. + Note: please reomve added key bindings before calling ``exit()``. + +``mp.utils.compile_js(fname, content_str)`` + Compiles the JS code ``content_str`` as file name ``fname`` (without loading + anything from the filesystem), and returns it as a function. Very similar + to a ``Function`` constructor, but shows at stack traces as ``fname``. + +Timers (global) +--------------- + +The standard HTML/node.js timers are available: + +``id = setTimeout(fn [,duration [,arg1 [,arg2...]]])`` + +``id = setTimeout(code_string [,duration])`` + +``clearTimeout(id)`` + +``id = setInterval(fn [,duration [,arg1 [,arg2...]]])`` + +``id = setInterval(code_string [,duration])`` + +``clearInterval(id)`` + +``setTimeout`` and ``setInterval`` return id, and later call ``fn`` (or execute +``code_string``) after ``duration`` ms. Interval also repeat every ``duration``. + +``duration`` has a minimum and default value of 0, ``code_string`` is +a plain string which is evaluated as JS code, and ``[,arg1 [,arg2..]]`` are used +as arguments (if provided) when calling back ``fn``. + +The ``clear...(id)`` functions cancel timer ``id``, and are irreversible. + +Note: timers always call back asynchronously, e.g. ``setTimeout(fn)`` will never +call ``fn`` before returning. ``fn`` will be called either at the end of this +event loop iteration or at a later event loop iteration. This is true also for +intervals - which also never call back twice at the same event loop iteration. + +Additionally, timers are processed after the event queue is empty, so it's valid +to use ``setTimeout(fn)`` instead of Lua's ``mp.register_idle(fn)``. + +CommonJS modules and ``require(id)`` +------------------------------------ + +CommonJS Modules are a standard system where scripts can export common functions +for use by other scripts. A module is a script which adds properties (functions, +etc) to its invisible ``exports`` object, which another script can access by +loading it with ``require(module-id)`` - which returns that ``exports`` object. + +Modules and ``require`` are supported, standard compliant, and generally similar +to node.js. However, most node.js modules won't run due to missing modules such +as ``fs``, ``process``, etc, but some node.js modules with minimal dependencies +do work. In general, this is for mpv modules and not a node.js replacement. + +A ``.js`` file extension is always added to ``id``, e.g. ``require("./foo")`` +will load the file ``./foo.js`` and return its ``exports`` object. + +An id is relative (to the script which ``require``'d it) if it starts with +``./`` or ``../``. Otherwise, it's considered a "top-level id" (CommonJS term). + +Top level id is evaluated as absolute filesystem path if possible (e.g. ``/x/y`` +or ``~/x``). Otherwise, it's searched at ``scripts/modules.js/`` in mpv config +dirs - in normal config search order. E.g. ``require("x")`` is searched as file +``x.js`` at those dirs, and id ``foo/x`` is searched as file ``foo/x.js``. + +No ``global`` variable, but a module's ``this`` at its top lexical scope is the +global object - also in strict mode. If you have a module which needs ``global`` +as the global object, you could do ``this.global = this;`` before ``require``. + +Functions and variables declared at a module don't pollute the global object. + +The event loop +-------------- + +The event loop poll/dispatch mpv events as long as the queue is not empty, then +processes the timers, then waits for the next event, and repeats this forever. + +You could put this code at your script to replace the built-in event loop, and +also print every event which mpv sends to your script: + +:: + + function mp_event_loop() { + var wait = 0; + do { + var e = mp.wait_event(wait); + dump(e); // there could be a lot of prints... + if (e.event != "none") { + mp.dispatch_event(e); + wait = 0; + } else { + wait = mp.process_timers() / 1000; + } + } while (mp.keep_running); + } + + +``mp_event_loop`` is a name which mpv tries to call after the script loads. +The internal implementation is similar to this (without ``dump`` though..). + +``e = mp.wait_event(wait)`` returns when the next mpv event arrives, or after +``wait`` seconds if positive and no mpv events arrived. ``wait`` value of 0 +returns immediately (with ``e.event == "none"`` if the queue is empty). + +``mp.dispatch_event(e)`` calls back the handlers registered for ``e.event``, +if there are such (event handlers, property observers, script messages, etc). + +``mp.process_timers()`` calls back the already-added, non-canceled due timers, +and returns the duration in ms till the next due timer (possibly 0), or -1 if +there are no pending timers. Must not be called recursively. + +Note: ``exit()`` is also registered for the ``shutdown`` event, and its +implementation is a simple ``mp.keep_running = false``. diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index 13f9395b4c..3ca135439d 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -847,6 +847,8 @@ works like in older mpv releases. The profiles are currently defined as follows: .. include:: lua.rst +.. include:: javascript.rst + .. include:: ipc.rst .. include:: changes.rst -- cgit v1.2.3