This script aims to create a common API that other scripts can use to request text input from the user via the OSD. This script was built from mpv's console.lua. The logging, commands, and tab completion have been removed, leaving just the text input and history code. As a result this script's text input has almost identical behaviour to console.lua.
Around the original code is a system to recieve input requests via script messages, and respond with the users input, and an error message if the request was somehow terminated. The script utilises a queue system to handle multiple requests at once, and there are various option flags to control how to handle multiple requests from the same source.
Usage of this API requires that standard interface functions be used to request and cancel input requests, these functions are packaged into user-input-module.lua, which can be loaded as a module, or simply pasted into another script.
If a script does choose to load the module, then I recommend it be loaded from ~~/script-modules rather than ~~/scripts.
The aim of this script is that it be seamless enough that it could be added to mpv player officially.
For versions of mpv ≤ v0.36 see the mpv-v0.36 branch.
If you've been directed here by another script that requires this API follow these instructions unless told otherwise.
Place user-input.lua inside the ~~/scripts/ directory, and place user-input-module.lua inside the ~~/script-modules/ directory.
Create these directories if they do not exist. ~~/ represents the mpv config directory.
What is important is that user-input.lua is loaded as a script my mpv, which can be done from anywhere using the --script option.
Meanwhile, user-input-module.lua needs to be in one of the lua package paths; scripts that use this API are recommended to use ~~/script-modules/, but you can set any directory using the LUA_PATH environment variable.
If you use the recommended ~~/script-modules/ directory then load this addon with the following code:
package.path = mp.command_native({"expand-path", "~~/script-modules/?.lua;"})..package.path
local input = require "user-input-module"Note: this API is still in its early stages, so these functions may change.
Requests input from the user and returns a request table.
input.get_user_input(print) -- prints the user input plus the error codefn is called when user-input sends a response, the first argument will be the input string the user entered,
the second argument will be an error string if the input is nil.
Any additional arguments sent after the options table will be sent to fn as additional arguments after the error string.
The following error codes currently exist:
exited the user closed the input instead of pressing Enter
already_queued a request with the specified id was already in the queue
cancelled the request was cancelled
replaced request was replacedIf the request throws an error for whatever reason then that Lua error message will be returned instead. Those error messages are undefined and could change at any time.
Options is an optional table of values and flags which can be used to control the behaviour of user-input. The function will preset some options if they are left blank. The following options are currently available:
| name | type | default | description |
|---|---|---|---|
| id | string | mp.get_script_name()../ |
used for storing input history and detecting duplicate requests |
| source | string | mp.get_script_name() | used to show the source of the request in square brackets |
| request_text | string | requesting user input: |
printed above the input box - use it to describe the input request |
| default_input | string | text to pre-enter into the input | |
| cursor_pos | number | 1 | the numerical position to place the cursor - for use with the default_input field |
| queueable | boolean | false | allows requests to be queued even if there is already one queued with the same id |
| replace | boolean | false | replace the queued request with the same id with the new request |
The function prepends the script name to any id to avoid conflicts between
different scripts.
Do not use both the queuable and replace flags for input requests with the same ID, the behaviour is undefined and may change at any time.
Here is an example for printing only a sucessful input:
input.get_user_input(function(line, err)
if line then print(line) end
end, { request_text = "print text:" })The request table returned by get_user_input can be used to modify the behaviour of an existing request.
The defined fields are:
| name | type | description |
|---|---|---|
| callback | function | the callback function - same as fn passed to get_user_input() - can be set to a different function to modify the callback |
| passthrough_args | table | an array of extra arguments to pass to the callback - cannot be nil |
| pending | boolean | true if the request is still pending, false if the request is completed |
| cancel | method | cancels the request - unlike cancel_user_input() this does not cancel all requests with a matching id |
| update | method | takes an options table and updates the request - maintains the original request unlike the replace flag - not all options can be changed |
A method is referring to a function that is called with Lua's method syntax:
local request = input.get_user_input(print)
request:update{
request_text = "hello world:"
}
request:cancel()Removes all input requests with a matching string id.
If no id is provided, then the default id for get_user_input() will be used.
The cancellation happens asynchronously.
This is a wrapper function around get_user_input() that uses coroutines
to make the input request behave synchronously. It returns line, err, as would
normally be passed to the callback function.
This function will yield the current coroutine and resume once the input
response has been received. If the coroutine is forcibly resumed by the user then
it will send a cancellation request to user-input and will return nil, 'cancelled'.
The request object is passed to the yield function.
local function main()
local line, err = input.get_user_input_co({ request_text = 'test input:' })
if line then print(line) end
end
local co = coroutine.create(main)
local success, request = coroutine.resume(co)If a function is passed as co_resume then custom resume behaviour can be setup instead
of the default coroutine.resume. This can be useful if you want to define what happens when an error is thrown.
This function is the equivalent of the usual callback function, except it's purpose is to resume
the yielded coroutine and that it has three agruments:
uid, line, err where uid is a unique variable that needs to be
passed to coroutine.resume(). The functions created by coroutine.wrap() can be passed into here.
The following examples show how this can be used to propogate errors using coroutine.wrap(),
and how to safely catch and print errors using a custom error handler.
-- if an error is thrown the script will crash instead of the error being caught
local driver
driver = coroutine.wrap(function()
local line, err = input.get_user_input_co({ request_text = 'test input:' }, driver)
if line then print(line) end
end)
local request = driver()-- if the coroutine throws an error it is caught and a stack trace is printed
-- note that the error handler shown here is actually what is used by default when `co_resume` is nil
function coroutine_resume_err(uid, line, err)
local co = coroutine.running()
local success, err = coroutine.resume(co, uid, line, err)
if not success then
msg.warn( debug.traceback(co) )
msg.error(err)
end
end
local function main()
local line, err = input.get_user_input_co({ request_text = 'test input:' }, coroutine_resume_err)
if line then print(line) end
end
local co = coroutine.create(main)
local success, request = coroutine.resume(co)The examples folder contains some scripts that make user of the API.
You can find more examples in the wiki page.