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.
This adds --osd-bar-marker-style option which can be used to
customize OSD bar marker style. In addition to the existing triangle
style, a new style option is added to draw markers as lines.
It is redundant if you're already using the OSC, so only show the
chapter text. Also fix the documented default commands of these buttons
which were outdated.
This adds several script-opts to configure what OSC buttons do when
clicked. It lets you restore the bindings present before they were
changed to call select.lua.
The script-opts are listed one per line in the manual to not make that
section huge.
skip_backward and skip_forward script-opts are omitted to lower the
script-opts number because they are only in box layout and undocumented.
I'm not sure if it's worth adding script-opts for the wheel on the
seekbar.
script-opts for the current and remaining time and fullscreen are not
added to not add more script messages.
Closes#6291 and #11878.
8bf5548 added mouse support to the console's select menu, so open it
from OSC buttons.
Left click on the title opens the playlist selector and showing the
stats is moved to right click.
Right click on chapter buttons opens the chapter selector.
Left click on track buttons opens the track selectors because seeing
which track you're selecting beforehand is useful.
Fixes#10621.
Now that the playlist counter is shown by default there is no use in
showing it again, so repurpose the binding to show the stats page with
file and track info.
It is excessive control to manually configure the terminal height limit
just for stats, if anything this should be added as an option used all
throughout mpv.
Use the property introduced in bf025cd289 to clip the lines of stats.lua
with accurate unicode width detection and considering --msg-module and
--msg-time. This allows removing the term ellipsis functions.
Also use script-opts-append instead of script-opts in the docs so
script-opts in mpv.conf, which could change keybindings, are not
overriden.
When the present extension was originally implemented, nvidia was
specifically blacklisted. The reason was because at the time it would
give bogus values that appeared to be real but actively made playback
worse. So out of an abundance of caution, any nvidia detection at all
(e.g. on a multi-gpu system) would disable the use of the extension.
Well times have changed and actually presentation-time on wayland for
nvidia works now amazingly enough. For xorg, the extension still doesn't
work, but from user testing it does not seem to be harmful anymore. It
just does nothing. So we can remove the blacklist part and just only use
a whitelist. Like before, we only enable the extension for mesa drivers
by default so no practical change for anyone except multi-gpu systems
whom may have this enabled now but should not see any negative behavior
change.
This paragraph is clearly wrong. load-input-conf was recently added, but
even before that the enable-section and disable-section commands could
change key bindings at runtime without scripts.
nanahi
Guido Cella
Kacper Michajłow
Dudemanguy
llyyr
Wertzui123
rkscv