This documents the scalable keys (currently WHEEL_*) and notes
how the keys work with scalable commands. Mention touch pad
as a common source of scalable input source.
For complex key bindings, the table now contains a new member
of the current key scale. mp.add_key_binding() now accepts the
scalable flag to make the binding scalable.
script-binding command is currently not scalable, so script
registered key bindings also cannot be scalable, unlink input.conf
bindings.
This makes script-binding command scalable so that it's possible to
define scalable key bindings in scripts. It now calls script-message
command with an extra argument with the scale of the key.
This has been happening for a while now apparently, so change it to
accurately reflect reality. I chose the next release as the point to
formally make this change, because I was under the impression that we
didn't have to list new options so I never did it and there may be
others like that too.
Instead of printing circles in show-text ${playlist}, ${chapter-list}
and ${edition-list}, introduce --osd-selected-color and
--osd-selected-outline-color to reduce clutter, make the selected item
easier to differentiate, and have visual consistency with select.lua.
The defaults are taken from the style of the selected item in the
console. These new options are also used there, replacing the hardcoded
styles. Due to being user-configurable, selected item styles are changed
to take priority over default item styles.
The default selected style is yellow and bold. The bold (hardcoded)
allows differentiating the selected item with color blindness. There is
also a separate --osd-selected-outline-color option defaulting to black,
since without it if the user changes --osd-outline-color yellow text
becomes unreadable without a black border. --osd-selected-back-color is
omitted for now.
Text and background colors are inverted for the selected item in the
terminal. This is hardcoded, adding an option is overkill.
A disadvantage of this commit is that if you run print-text ${playlist}
with a VO, the selected style ASS is printed to the terminal (but ASS
printed in the console is interpreted). This commit avoids printing the
reset ASS sequence for non-selected items to reduce clutter in this
case.
The previous documentation was pretty scary and misleading, and was
also outdated in several sections.
It was also difficult to understand some of the paragraphs.
The path documentation has now been overhauled to be much easier
to understand and to document the latest mpv behavior.
Show available completion suggestions as you type without having to
press Tab.
This is fast even on a 2011 CPU, so we can get away with doing this in
the same thread that draws the console. The one case where it could make
the console hang is file completion of network drives, but in general it
is convenient for loadfile.
mp.input.get clients also get a request to complete on each character
typed, but those run in a different thread so performance is always
fine, and completions were already rejected if the input line or cursor
changed after the request. If I ever make running mpv commands an
mp.input client in the future, command completion will also benefit from
running in a different thread.
mpv has too many commands and they are unorganized in the
documentation, making it difficult to navigate.
This commit completely reorganizes the commands into several
categories to make the documentation easier to navigate.
The following categories are defined:
- Playback Control: Seeking and stepping.
- Property Manipulation: Changing property values.
- Playlist Manipulation: Playlist navigation and editing.
- Track Manipulation: Track navigation and editing.
- Text Manipulation: Text printing, expansion, escaping.
- Configuration: General configuration and related files.
- OSD: Displaying contents as OSD.
- Input and Keybind: Input configuration and key bindings.
- Execution: Execution of mpv and subprocesses.
- Scripting: Script loading and communication.
- Screenshot: Taking screenshots.
- Filter: Changing filters.
- Miscellaneous: Other commands.
The current OSD font size is excessively large, causing most
messages—except for very short ones to overflow horizontally.
I conducted testing across multiple devices of varying screen sizes and
under different scenarios. The adjusted font size strikes a good balance
for readability on non-high-DPI displays, while high-DPI displays should
utilize DPI scaling as needed.
Additionally, I compared the font sizes of subtitles and UI elements
across various VOD platforms, which generally use smaller font in most
cases.
The current sub font size was significantly larger than even PGS
subtitles, which are quite large on their own. Now, they are comparable.
The subtitle font size was chosen based on recommendations from the BBC
Subtitle Guidelines. It is set to 8% of the video height with a
recommended scaling factor of 0.67. Therefore, at 720p (the reference
size for mpv font scaling), the calculation is 8% * 0.67 * 720 = 38.592,
rounded down to 38. This value falls within the recommended scaling
range of x0.5–x1 for desktop PCs/Laptops and TVs (32"–42"). For more
information, see
https://www.bbc.co.uk/accessibility/forproducts/guides/subtitles/#Presentation-font-size.
OSD font size is smaller than font as those elements shouldn't be
distractful and only noticable when the user wants to look at them.
Outline size is set to 5.5% of font size.
Most of the commands list here are several years old and we will
probably never change them. And it is already stated in the description
of individual commands if they are deprecated or subject to change.
Furthermore, it is easy to add new commands at the end of this section
by accident. I added load-config-file and load-input-conf here without
realizing it's a separate section, and I assume this was also the case
for begin-vo-dragging.
Disabled by default because it breaks sub-seek and playback in cases
where the user changes play-dir from + to - during runtime and past
"seen" events need to be re-rendered.
Available since dcc9eb722e
Scripts can terminate execution by setting mp.keep_running = false. Add
an exit() function to wrap setting mp.keep_running and properly expose
this feature. It can be used e.g. by a thumbnail script to spawn workers
with load-script and then let them quit.
It is not added to the mp namespace as mp.exit because that would make
it look like it terminates mpv.
This mirrors the exit() function which already exists in js.
The note in javascript.rst about having to remove key bindings before
exit is not kept because they are actually removed automatically since
bf385e1140 (though it was accurate when the JS backend was developed
before upstreaming it).
It comes up often in IRC and issues that users don't understand why the
path property is initially unavailable, so link the section that
mentions it from the Properties section, and expand on how to get these
properties.
Because it is a bit shorter than calling
utils.join_path(working_directory, path), it gives you a canonical path,
and it doesn't concate working-directory before URLs.
Currently --script-opt=stats-font_size=n is much bigger than
--osd-font-size=n, which can confuse users, so calculate sizes the same
way.
The \fs value to replicate --osd-font-size is
${osd-font-size} * 288 / 720 with --osd-scale-by-window, and
\fs${osd-font-size} * 288 / ${osd-height}
with --osd-scale-by-window=no. This is because
sub/osd_libass.c:update_playres() sets
track->PlayResY = ass->res_y ? ass->res_y : MP_ASS_FONT_PLAYRESY,
where MP_ASS_FONT_PLAYRESY is 288.
This also works with persistent_overlay=yes.
{\fscx100}{\fscy100} would also replicate --osd-font-size with show-text
and with osd-verlay + --osd-scale-by-window, but not with osd-overlay +
--osd-scale-by-window=no.
The default sizes are multiplied by 720/288 = 2.5 to keep them the same
as before.
In the select menu there are no completions to align in a grid, so the
better looking proportional font of --osd-font can be used by default.
It is also easier to read for the visually impaired.
The text width calculation is no longer performed if the console is only
opened through select, it is only performed the first time something is
completed. This avoids having to pass an argument to get_font() to make
it use the monospace font regardless of selectable_items.
Fixes#15176.
