summaryrefslogtreecommitdiffstats
path: root/DOCS/man/lua.rst
Commit message (Collapse)AuthorAgeFilesLines
* DOCS/lua: clarify `repeatable` and `complex` for `add_key_binding`gaesa2024-02-151-5/+6
| | | | | | | | | | | | | | | | The current documentation lacks clarity regarding the interaction between the `repeatable` and `complex` options. Through an analysis of the source code (`player/lua/defaults.lua` and `player/js/defaults.js`), it was observed that the `repeatable` option is only meaningful when the `complex` option is not enabled. Additionally, the `complex` option in the existing documentation is confusing, actually `fn` can be called on key repeat when `complex` is `true` and `repeatable` is not `true`. To address these issues, the documentation for the `repeatable` option was updated to specify that it only applies when the `complex` option is not set to `true`. Furthermore, the description of the `complex` and `event` were revised to acknowledge the occurrence of key repeat events.
* scripting: don't observe properties with type nilGuido Cella2024-01-201-3/+3
| | | | | | | | | | | | | | | | | | | | | | | | mp.observe_property('foo', nil, ...) calls the handler at least 2 times on each playlist change even when the property doesn't change. This is dangerous because if you haven't read observe_property's documentation in a long time this is easy to forget, and you can end up using it for handlers that are computationally expensive or that cause unintended side effects. Therefore, this commit discourages its use more explicitly in the documentation, and replaces its usages in scripts. For console.lua, observing focused with type nil leads to calling mp.osd_message('') when changing file while playing in the terminal with the console disabled. I don't notice issues from this, but it's safer to avoid it. For playlist and track-list this doesn't really matter since they trigger multiple changes on each new file anyway, but changing it can avoid encouraging people to imitate the code. One usage of none in stats.lua is kept because according to b9084dfd47 it is a hack to replicate the deprecated tick event.
* console.lua: style log lines in the terminalGuido Cella2024-01-141-4/+10
| | | | | | | | | | When running the console in the terminal, style log lines with the same escape sequences as msg.c. mp.input can also specify terminal escape sequences, e.g. a script to select a playlist entry can invert the color of the selection. Also add a missing newline to help's error message.
* scripting: add mp.inputGuido Cella2024-01-131-0/+82
| | | | This lets scripts get textual input from the user using console.lua.
* defaults.lua: add a disabled parameter to timer constructorsMike Will2023-10-111-2/+6
| | | | | | | | Added to the functions `mp.add_timeout` and `mp.add_periodic_timer`. 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.
* DOCS/lua: update read_options exampleGuido Cella2023-10-101-2/+2
| | | | | This still shows the old way of calling read_options even though it was deprecated 8 years in ago 327b091909e.
* DOCS/lua: remove superfluous parameterChristoph Heinrich2023-09-301-1/+1
| | | | This seems to have been a leftover from copying the entry below it.
* DOCS/lua.rst: fix typoGuido Cella2023-09-091-2/+2
|
* DOCS/lua: fix typoAmeer Taweel2023-03-211-1/+1
|
* lua/js: remove user-data helpersAvi Halachmi (:avih)2023-01-291-28/+0
| | | | | | | | | | | | | | | This reverts: 3fb4140c lua/defaults: add user_data helpers 68a20e7a javascript/defaults: add user_data helpers 00510379 lua/js: fix user_data_del util function As well as the lua/js parts of: 3ec2a098 docs: document new user-data property user-data and its sub-properties can be set/get/observed/deleted via the standard properties interface, so there's no need for additional helpers specific to user-data, which only added maintenance burden.
* doc: correct spelling of user-data/user_data JS/lua helpersrcombs2023-01-281-12/+12
|
* docs: document new user-data propertyrcombs2023-01-281-0/+28
|
* lua: add mp.del_property()rcombs2023-01-281-0/+6
|
* lua: command_native_async: always callback a-syncCogentRedTester2022-06-221-0/+2
| | | | | | | | | | | | | | | | | Previously if the raw command_native_async returned an error then the callback function was run directly. This meant that script writers potentially had to account for both synchronous and asynchronous logic in the callback, which can happen even with seemingly 'safe' commands if the mpv event queue is full. This was at odds with the Javascript implementation of the function, which always runs the callback asynchronously. Now the mp.add_timeout function is used to run the callback asynchronously on error, replicating the Javascript implementation. This provides consistency for developers in how the callback is handled in Lua, and increases consistency between the Lua and Javascript APIs.
* lua: remove mp.suspend, resume and resume_allsfan52021-12-151-12/+0
| | | | | | These functions were deprecated in v0.21.0 and no-ops since v0.23.0. The matching client API functions were removed in the previous commit.
* DOCS: fix spellinga13460542021-08-241-2/+2
|
* DOCS: convert 3rd party http links to httpsLaserEyess2021-08-171-1/+1
| | | | | | | | | | Discovered with: find . -type f \( -name '*.md' -o -name '*.rst' \) -exec grep -n 'http://' {} + All real, i.e. non-example, links found were moved to https. There are some dead links and websites with no https available which were not converted.
* DOCS/lua.rst: fix docs for utils.file_infoAvi Halachmi (:avih)2021-05-031-1/+1
| | | | | | | | | | | | | | The ctime member on Windows uses FILE_BASIC_INFO.ChangeTime, which is pretty much the same as st_ctime on POSIX. See https://devblogs.microsoft.com/oldnewthing/20100709-00/?p=13463 : ... The Last­Write­Time covers writes to the file’s data stream (which you accomplish via the Write­File function). On the other hand, the Change­Time also includes changes to the file metadata, such as changing its file attributes ... Fixes #8801
* DOCS: clarify how client/script names workDudemanguy2021-04-291-2/+8
| | | | | This isn't really clearly stated anywhere and could understandably lead to some confusion.
* lua: make hook processing more flexiblewm42020-08-051-2/+16
| | | | | | | This can now opt to not continue a hook after the hook callback returns. This makes it easier for scripts, and may make it unnecessary to run reentrant event loops etc. for scripts that want to wait before continuing while still running the event loop.
* lua: add mp.get_env_list() functionwm42020-07-201-0/+4
| | | | | Because Lua is too stupid to provide this directly, and I sort of need it.
* documentation: fix some ReST syntax mistakes in lua.rstEmanuele Torre2020-05-011-1/+1
|
* client API, lua, ipc: unify event struct returnwm42020-03-211-110/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | Both Lua and the JSON IPC code need to convert the mpv_event struct (and everything it points to) to Lua tables or JSON. I was getting sick of having to make the same changes to Lua and IPC. Do what has been done everywhere else, and let the core handle this by going through mpv_node (which is supposed to serve both Lua tables and JSON, and potentially other scripting language backends). Expose it as new libmpv API function. The new API is still a bit "rough" and support for other event types might be added in the future. This silently adds support for the playlist_entry_id fields to both Lua and JSON IPC. There is a small API change for Lua; I don't think this matters, so I didn't care about compatibility. The new code in client.c is mashed up from the Lua and the IPC code. The manpage additions are moved from the Lua docs, and made slightly more "general". Some danger for unintended regressions both in Lua and IPC. Also damn these node functions suck, expect crashes due to UB. Not sure why this became more code instead of less compared to before (according to the diff stat), even though some code duplication across Lua and IPC was removed. Software development sucks.
* manpage: explicitly mention "tick" event as deprecatedwm42020-03-071-1/+1
| | | | Just. Don't. Use. It.
* command: extend osd-overlay command with bounds reportingwm42020-03-061-0/+1
| | | | | | | | | | | | | | | | | | | | This is more or less a minimal hack to make _some_ text measurement functionality available to scripts. Since libass does not support such a thing, this simply uses the bounding box of the rendered text. This is far from ideal. Problems include: - using a bitmap bounding box - additional memory waste and/or flushing caches - dependency on window size - odd small deviations with different window sizes (run osd-test.lua and resize the window after each timer update; the bounding boxes aren't adjusted in an overly useful way) - inability to query the size _after_ actual rendering But I guess it's a start. Since I'm aware that it's crap, add a threat to the manpage that this may be changed/removed again. For now, I'm interested whether anyone will have use for it in its current form, as it's an often requested feature.
* manpage: improve command_native_async descriptionwm42020-02-161-6/+13
|
* manpage: fix a case of broken indentationwm42020-02-151-15/+16
| | | | | | This renders incorrectly in the html output. I suspect you need one more level here. Increase the indentation level. No other changes, other than re-breaking some lines.
* 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
|