summaryrefslogtreecommitdiffstats
path: root/DOCS/man/lua.rst
Commit message (Collapse)AuthorAgeFilesLines
* lua: add mp.get_script_directory() functionwm42020-02-041-5/+16
| | | | And add some clarifications/suggestions to the manpage.
* lua: set package path if loaded from a script directorywm42020-02-011-6/+38
| | | | | | And document the shit. This uses code from commit bc1c024ae032e5b5c.
* client API, lua: add new API for setting OSD overlayswm42019-12-231-0/+35
| | | | | | | | | | | | | | | | | | | | | | | | | | | Lua scripting has an undocumented mp.set_osd_ass() function, which is used by osc.lua and console.lua. Apparently, 3rd party scripts also use this. It's probably time to make this a public API. The Lua implementation just bypassed the libmpv API. To make it usable by any type of client, turn it into a command, "osd-overlay". There's already a "overlay-add". Ignore it (although the manpage admits guiltiness). I don't really want to deal with that old command. Its main problem is that it uses global IDs, while I'd like to avoid that scripts mess with each others overlays (whether that is accidentally or intentionally). Maybe "overlay-add" can eventually be merged into "osd-overlay", but I'm too lazy to do that now. Scripting now uses the commands. There is a helper to manage OSD overlays. The helper is very "thin"; I only want to force script authors to use the ID allocation, which may help with putting multiple scripts into a single .lua file without causing conflicts (basically, avoiding singletons within a script's environment). The old set_osd_ass() is emulated with the new API. The JS scripting wrapper also provides a set_osd_ass() function, which calls internal mpv API. Comment that part (to keep it compiling), but I'm leaving it to @avih to finish the change.
* lua: change runtime option change behaviorwm42019-12-221-0/+6
| | | | | | | | | | | | As described in the manpage changes. This makes more sense than the previous approach, where options could "unexpectedly" stick. Although this is still a somewhat arbitrary policy (ask many people and you'd get a number of different expectations on what should happen), I think that it reflects what mpv's builtin stuff does. All the copying is annoying, but let's just hope nobody is stupid enough to change these properties per video frame or something equally ridiculous.
* lua: add a helper for runtime script option changeswm42019-12-201-2/+9
| | | | | A script can use this to easily get runtime updates. (Even if script-opts is sort of clunky.)
* manpage: lua: mention what happens on unavailable propertieswm42019-12-191-0/+4
| | | | Kind of as big one if the user unexpectedly gets nil instead of a value.
* lua: make add_key_binding() rotate optional arguments correctlywm42019-11-231-1/+3
| | | | | | | | add_key_binding() makes the name argument optional (in weird Lua fashion), which did not work if there were additional arguments. So there is no way to avoid specifying a name while passing a rp argument. Fix this, declare this way of skipping the argument as deprecated, and allow passing name=nil as the preferred way to skip the name argument.
* input: add text produced by key to script key eventswm42019-11-221-0/+5
| | | | | | | Particularly for "any_unicode" mappings, so they don't have to special-case keys like '#' and ' ', which are normally mapped to symbolic names for input.conf reasons. (Though admittedly, this is a pretty minor thing, since API users could map these manually.)
* manpage: correct "complex" key binding descriptionwm42019-11-221-2/+2
| | | | | | | The key is never nil if it's invoked through the normal input path. The key name could be "" if mp_cmd.key_name==NULL. This should not happen, but there's no strong guarantee in input.c that it cannot happen, so whatever.
* manpage: improve "complex" key binding list of table entrieswm42019-11-221-6/+13
|
* lua: report key name for "complex" key bindingswm42019-11-191-3/+4
| | | | This might make certain use cases less of a mess.
* DOCS: explicitly mention that property observing has an initial eventwm42019-10-081-1/+5
| | | | | This is definitely intended from the start, and it's generally useful, but for some reason it wasn't actually documented.
* manpage: clarify some details about async. commands and "subprocess"wm42019-10-041-0/+2
| | | | | | | | | There's potential confusion about how long a process started with the "subprocess" command is allowed to live. Add some more explanations regarding "subprocess" specifics (such as the playback_only field), and things that apply to asynchronous commands in general. Partially for #7025.
* manpage: fix minor typowm42019-09-191-1/+1
|
* lua: expose mpv_abort_async_command()wm42018-05-241-0/+12
| | | | Also somewhat cleans up mp.command_native_async() error handling.
* lua: reimplement mp.subprocess_detached() by invoking the "run" commandwm42018-05-241-0/+3
| | | | | | | | The "run" command is old. I'm not sure why the separate Lua implementation was added. But maybe it as because the "run" command used to be limited to a small number of arguments. This limit has been removed a while ago. In any case, the old implementation is not needed anymore.
* lua: reimplement mp.subprocess() by invoking the new subprocess commandwm42018-05-241-39/+17
| | | | | | | We keep mp.subprocess() with roughly the same semantics for compatibility with scripts (including the internal ytdl script). Seems to work with rhe ytdl wrapper. Not tested further.
* input: add glue code for named argumentswm42018-05-241-1/+11
| | | | | | | | | | Named arguments should make it easier to have long time compatibility, even if command arguments get added or removed. They're also much nicer for commands with a large number of arguments, especially if many arguments are optional. As of this commit, this can not be used, because there is no command yet which supports them. See the following commit.
* lua: expose async commandswm42018-05-241-0/+9
| | | | Might be useful for some.
* scripting: change when/how player waits for scripts being loadedwm42018-04-181-1/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Fundamentally, scripts are loaded asynchronously, but as a feature, there was code to wait until a script is loaded (for a certain arbitrary definition of "loaded"). This was done in scripting.c with the wait_loaded() function. This called mp_idle(), and since there are commands to load/unload scripts, it meant the player core loop could be entered recursively. I think this is a major complication and has some problems. For example, if you had a script that does 'os.execute("sleep inf")', then every time you ran a command to load an instance of the script would add a new stack frame of mp_idle(). This would lead to some sort of reentrancy horror that is hard to debug. Also misc/dispatch.c contains a somewhat tricky mess to support such recursive invocations. There were also some bugs due to this and due to unforeseen interactions with other messes. This scripting stuff was the only thing making use of that reentrancy, and future commands that have "logical" waiting for something should be implemented differently. So get rid of it. Change the code to wait only in the player initialization phase: the only place where it really has to wait is before playback is started, because scripts might want to set options or hooks that interact with playback initialization. Unloading of builtin scripts (can happen with e.g. "set osc no") is left asynchronous; the unloading wasn't too robust anyway, and this change won't make a difference if someone is trying to break it intentionally. Note that this is not in mp_initialize(), because mpv_initialize() uses this by locking the core, which would have the same problem. In the future, commands which logically wait should use different mechanisms. Originally I thought the current approach (that is removed with this commit) should be used, but it's too much of a mess and can't even be used in some cases. Examples are: - "loadfile" should be made blocking (needs to run the normal player code and manually unblock the thread issuing the command) - "add-sub" should not freeze the player until the URL is opened (needs to run opening on a separate thread) Possibly the current scripting behavior could be restored once new mechanisms exist, and if it turns out that anyone needs it. With this commit there should be no further instances of recursive playloop invocations (other than the case in the following commit), since all mp_idle()/mp_wait_events() calls are done strictly from the main thread (and not commands/properties or libmpv client API that "lock" the main thread).
* config: replace config dir lua-settings/ with dir script-opts/Avi Halachmi (:avih)2018-04-071-1/+1
| | | | lua-settings/ is still supported, with deprecation warning.
* client API: deprecate mpv_get_wakeup_pipe()wm42018-03-261-1/+1
| | | | I don't think anything even uses it.
* lua+js: Implement utils.getpid()sfan52018-02-131-0/+4
| | | | | | | Usable for uniquely identifying mpv instances from subprocesses, controlling mpv with AppleScript, ... Adds a new mp_getpid() wrapper for cross-platform reasons.
* js: implement mp.msg.trace()TheAMM2017-12-161-4/+5
| | | | | | | To match the new Lua helper introduced in 1afdeee1ad8bca1c703e741002fa3b882d162968 Add documentation for both.
* lua+js: implement utils.file_info()TSaaristo2017-12-131-0/+28
| | | | | | | | | | | | | | | This commit introduces mp.utils.file_info() for querying information on file paths, implemented for both Lua and Javascript. The function takes a file path as an argument and returns a Lua table / JS object upon success. The table/object will contain the values: mode, size, atime, mtime, ctime and the convenience booleans is_file, is_dir. On error, the Lua side will return `nil, error` and the Javascript side will return `undefined` (and mark the last error). This feature utilizes the already existing cross-platform `mp_stat()` function.
* manpage: add note about properties not immediately showing upKevin Mitchell2017-12-061-1/+4
| | | | fixes #5134
* manpage: replace gendered pronounsNicolas F2017-04-191-2/+2
|
* lua: allow unregistration of idle handlersOlivier Perret2017-01-151-0/+5
|
* client API: turn mpv_suspend() and mpv_resume() into stubswm42016-11-221-20/+8
| | | | | | | | | | | As threatened by the API changes document. This commit also removes or stubs equivalent calls in IPC and Lua scripting. The stubs are left to maintain ABI compatibility. The semantics of the API functions have been close enough to doing nothing that this probably won't even break existing API users. Probably.
* lua: add API for registering idle handlerswm42016-09-211-0/+7
| | | | | This is only a functionality the Lua event dispatcher provides, rather than the libmpv client API.
* manpage: lua: mention recent deprecationswm42016-09-211-4/+6
| | | | | These are listed in interface-changes.rst, but the documentation in the manpage wasn't updated.
* lua: expose subprocess_detachedrr-2016-09-211-0/+13
|
* manpage: minor fixwm42016-07-101-2/+2
| | | | Also fix some other type in interface-changes.rst.
* man: fix typosJakub Wilk2016-07-091-1/+1
|
* lua: add timer:is_enabled() functionJulian2016-05-141-0/+4
| | | | | Allows to query if some timer is currently running or was stopped/killed.
* manpage: fix some script_message references to preferred namewm42016-05-091-3/+3
|
* lua: don't require key for mp.add_key_binding()wm42016-03-261-1/+2
| | | | | Requested. The intention is that scripts can provide mappable actions for key bindings without setting a default key.
* man: lua: fix typo in script-binding example.torque2016-03-191-1/+1
| | | | This line was added in ae5df9be98e4193342321f30285655fcf88e7e63, and it appears to have been a typo.
* lua: don't suspend core by default during script executionwm42016-03-181-7/+1
| | | | | | | | | This changes behavior somewhat. The old behavior can be restored by running "mp.use_suspend=true". It was originally introduced for the OSC, but I can't reproduce whatever misbehavior I was seeing. (See mp.suspend()/resume() for explanations what the suspend mechanism does.)
* manpage: lua: fix command nameswm42015-12-291-5/+5
| | | | Both variants work, but the ones with "-" are preferred now.
* man: fix grammar issuesMartin Herkt2015-12-191-1/+1
|
* subprocess, lua: export whether the process was killed by uswm42015-06-271-0/+4
| | | | | | | | We want to distinguish actual errors, and just aborting the program intentionally. Also be a bit more careful with handling the wait() exit status: do not called WEXITSTATUS() without checking WIFEXITED() first.
* DOCS/manpage: fix typosrrooij2015-06-171-1/+1
| | | | | | | Fix some errors in the man pages by spell checking them. Most of them were typos. Signed-off-by: wm4 <wm4@nowhere>
* lua: support MPV_END_FILE_REASON_REDIRECTwm42015-06-111-0/+10
| | | | And also add the missing "unknown" entry to the manpage.
* lua: export end-file event fieldswm42015-06-111-0/+17
|
* lua: fix options submodulewm42015-05-291-1/+1
| | | | | | | | | It polluted the global namespace, instead of exporting the function properly. For now, keep it compatible by explicitly keeping the bogus export. Also fix a mistake in the manpage example.
* manpage: lua: clarify OSD differences between mp.command/mp.commandvwm42015-05-161-0/+7
| | | | | | Conflicts: player/audio.c player/video.c
* lua: add utils.format_json() functionwm42015-04-221-0/+8
| | | | Requested. Why not.
* manpage: lua: clarify timer usagewm42015-04-081-0/+17
| | | | | | This seems to come up often. I guess '.' vs. ':' for Lua calls is confusing, and this part of the scripting API is the only one which requires using it.
* DOCS, options: fix exampleChrisK22015-03-051-1/+1
|
* manpage: remove empty line to fix formattingwm42015-03-021-1/+0
| | | | | | The HTML rendering of this page formats the ``timeout`` section differently, and we suspect it's because of this. (Or in other words: wtf rst??)
* manpage: document hook APIwm42015-02-041-14/+3
| | | | | | | This shouldn't exist and for the most part is meant to be used by the ytdl Lua script, but let's document it anyway. Since the Lua API handles all the details, it's considered much more "stable" than the raw API, which is why the raw API wasn't documented.
* command: add on_unload hookwm42015-02-041-0/+4
| | | | Fixes #1552.
* manpage: lua: fix a linkwm42014-12-261-1/+1
|
* manpage: lua: fixes and improvementswm42014-12-251-20/+15
| | | | Some things were outdated, or outright wrong.
* options: deprecate 'lua' based options/dirs for 'script'Avi Halachmi (:avih)2014-12-151-10/+10
| | | | | | | | | | | | - --lua and --lua-opts change to --script and --script-opts - 'lua' default script dirs change to 'scripts' - DOCS updated - 'lua-settings' dir was _not_ modified The old lua-based names/dirs still work, but display a warning. Signed-off-by: wm4 <wm4@nowhere>
* manpage: lua: fix examplewm42014-11-291-2/+2
| | | | Oops.
* manpage: minor fixeswm42014-11-291-6/+5
| | | | | Also update the Lua example. The "pause" event was declared deprecated, so the example should use the newer API.
* lua: add a function that formats Lua values as stringswm42014-11-291-0/+4
| | | | | | | | Yep, Lua is so crappy that the stdlib doesn't provide anything like this. Repurposes the undocumented mp.format_table() function and moves it to mp.utils.
* manpage: lua: fix typo paramater -> parameterAlessandro Ghedini2014-11-261-1/+1
|
* input, lua: redo input handlingwm42014-11-231-7/+18
| | | | | Much of it is the same, but now there's the possibility to distinguish key down/up events in the Lua API.
* manpage: update utils.subprocess() for WindowsJames Ross-Gowan2014-11-221-2/+3
|
* lua: add a way to add repeatable key bindingswm42014-11-211-1/+5
| | | | For these, autorepeat is enabled.
* client API: deprecate some eventswm42014-11-081-22/+3
| | | | | | | | | | | Following the discussion in #1253. The events won't be removed for a while, though. (Or maybe never, unless we run out of bits for the uint64_t event mask.) This is not a real change (the events still work, and the alternative mechanisms were established a few API revisions earlier), but for the sake of notifying API users, update DOCS/client-api-changes.rst.
* lua: add convenience function for hookswm42014-10-211-0/+26
| | | | So the user doesn't have to care about the awkward low-level details.
* lua: expose JSON parserwm42014-10-191-0/+14
| | | | | | | The JSON parser was introduced for the IPC protocol, but I guess it's useful here too. The motivation for this commit is the same as with 8e4fa5fc (again).
* lua: add an utility function for starting processeswm42014-10-191-0/+42
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Because 1) Lua is terrible, and 2) popen() is terrible. Unfortunately, since Unix is also terrible, this turned out more complicated than I hoped. As a consequence and to avoid that this code has to be maintained forever, add a disclaimer that any function in Lua's utils module can disappear any time. The complexity seems a bit ridiculous, especially for a feature so far removed from actual video playback, so if