RepoMirrors
/
mpv
mirror of https://github.com/mpv-player/mpv
1
0
Fork 0
Code Issues Releases Wiki Activity
mpv/DOCS/man/stats.rst

299 lines
8.2 KiB
ReStructuredText
Raw Normal View History

stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
STATS
=====
This builtin script displays information and statistics for the currently
played file. It is enabled by default if mpv was compiled with Lua support.
It can be disabled entirely using the ``--load-stats-overlay=no`` option.
Usage
-----
The following key bindings are active by default unless something else is
already bound to them:
==== ==============================================
i Show stats for a fixed duration
I Toggle stats (shown until toggled again)
input.conf: bind ? to show key bindings This should help new users to view mpv's key bindings as it's easier to discover than shift+i and 4, because many other websites and terminal applications show key bindings upon pressing ?.
2024-10-14 18:30:31 +00:00
? Toggle displaying the key bindings
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
==== ==============================================
While the stats are visible on screen the following key bindings are active,
regardless of existing bindings. They allow you to switch between *pages* of
stats:
==== ==================
1 Show usual stats
stats: UP/DOWN scrolling on page 2 (frame stats) Code contributed by @avih with only minor modifications to comments by me. Fixes #7727.
2020-05-17 11:55:38 +00:00
2 Show frame timings (scroll)
manpage: document stats page 3
2019-10-26 20:24:57 +00:00
3 Input cache stats
stats.lua: add page 4: active key-bindings list This is a scrollable page which also works nicely with the terminal OSD. Typically there are more than 100 bound keys. It groups the binding using fuzzy property/command/script name after simple analysis of the command string, and then further sorts the binding in each group according to the "complexity" of the key itself (plain keys -> keys with modifiers, alphabetically, etc). The alignment/grouping style is heavily inspired by @medhefgo's #8924 but otherwise it's an independent implementation.
2021-07-16 08:17:50 +00:00
4 Active key bindings (scroll)
stats.lua: add page 5 for currently selected tracks information
2024-06-08 16:19:00 +00:00
5 Selected Tracks Info (scroll)
stats.lua: move internal performance from page 4 to page 0 This allows adding more pages without the internal performance page getting stuck at the middle of the list.
2021-07-16 07:33:46 +00:00
0 Internal stuff (scroll)
stats: support UP/DOWN to scroll at page 4 (perf) Keys and lines-to-scroll are configurabe, and the scroll keys are only bound on pages which support scrolling (currently only page 4) - also during oneshot (like the page-switching keys). Scroll offset is reset for all pages on any key - except scroll keys, so that entering or switching to a page resets the scroll, as well as when "re-entering" the same page or "re-activating" the stats oneshot view. TODO: print_page(..) is highly associated with extending the oneshot timer if required. The timer handling can probably move into print_page and removed from all the places which boilerplate its management.
2020-04-10 22:20:02 +00:00
==== ==================
stats.lua: exit with ESC if being toggled If not opened in oneshot mode, close the stats with ESC. Especially now that ? toggles showing key bindings by default, this provides an intuitive way to close the stats. Also do some minor reformatting of key binding documentation.
2024-10-17 07:20:04 +00:00
If stats were displayed by toggling, these key bindings are also active:
==== ==================
ESC Close the stats
==== ==================
stats: support UP/DOWN to scroll at page 4 (perf) Keys and lines-to-scroll are configurabe, and the scroll keys are only bound on pages which support scrolling (currently only page 4) - also during oneshot (like the page-switching keys). Scroll offset is reset for all pages on any key - except scroll keys, so that entering or switching to a page resets the scroll, as well as when "re-entering" the same page or "re-activating" the stats oneshot view. TODO: print_page(..) is highly associated with extending the oneshot timer if required. The timer handling can probably move into print_page and removed from all the places which boilerplate its management.
2020-04-10 22:20:02 +00:00
On pages which support scroll, these key bindings are also active:
==== ==================
stats.lua: exit with ESC if being toggled If not opened in oneshot mode, close the stats with ESC. Especially now that ? toggles showing key bindings by default, this provides an intuitive way to close the stats. Also do some minor reformatting of key binding documentation.
2024-10-17 07:20:04 +00:00
UP Scroll one line up
DOWN Scroll one line down
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
==== ==================
stats.lua: exit with ESC if being toggled If not opened in oneshot mode, close the stats with ESC. Especially now that ? toggles showing key bindings by default, this provides an intuitive way to close the stats. Also do some minor reformatting of key binding documentation.
2024-10-17 07:20:04 +00:00
On page 4, these key bindings are also active:
==== ==================
/ Search key bindings
==== ==================
stats.lua: filter input bindings by typing them This lets you press / in page 4 of the stats and type a keybinding or part of its command to filter it by using mp.input. This works badly without a VO because both stats.lua and console.lua use show-text and only one can be displayed at a time, but it's still better than not having the search available at all.
2024-03-21 19:09:22 +00:00
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
Configuration
-------------
config: replace config dir lua-settings/ with dir script-opts/ lua-settings/ is still supported, with deprecation warning.
2017-12-13 17:37:42 +00:00
This script can be customized through a config file ``script-opts/stats.conf``
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
placed in mpv's user directory and through the ``--script-opts`` command-line
DOCS/man: refer to "mp.options functions" for script config docs Currently they refer to the OSC documentation. However, the "mp.options functions" already documents that, is more detailed, and does not contain false statements like "there may be no spaces around the ``=`` or anywhere else" (the primitive parser does not care about them, so starting a string option value with spaces is perfectly fine). Change them to refer to "mp.options functions" and remove the redundant section in the OSC documentation.
2024-04-20 14:16:53 +00:00
option. The configuration syntax is described in `mp.options functions`_.
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
Configurable Options
~~~~~~~~~~~~~~~~~~~~
``key_page_1``
Default: 1
``key_page_2``
Default: 2
manpage: document stats page 3
2019-10-26 20:24:57 +00:00
``key_page_3``
Default: 3
stats.lua: add page 4: active key-bindings list This is a scrollable page which also works nicely with the terminal OSD. Typically there are more than 100 bound keys. It groups the binding using fuzzy property/command/script name after simple analysis of the command string, and then further sorts the binding in each group according to the "complexity" of the key itself (plain keys -> keys with modifiers, alphabetically, etc). The alignment/grouping style is heavily inspired by @medhefgo's #8924 but otherwise it's an independent implementation.
2021-07-16 08:17:50 +00:00
``key_page_4``
Default: 4
stats.lua: add page 5 for currently selected tracks information
2024-06-08 16:19:00 +00:00
``key_page_5``
Default: 5
stats.lua: move internal performance from page 4 to page 0 This allows adding more pages without the internal performance page getting stuck at the middle of the list.
2021-07-16 07:33:46 +00:00
``key_page_0``
Default: 0
stats.lua: exit with ESC if being toggled If not opened in oneshot mode, close the stats with ESC. Especially now that ? toggles showing key bindings by default, this provides an intuitive way to close the stats. Also do some minor reformatting of key binding documentation.
2024-10-17 07:20:04 +00:00
``key_exit``
Default: ESC
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
Key bindings for page switching while stats are displayed.
stats: support UP/DOWN to scroll at page 4 (perf) Keys and lines-to-scroll are configurabe, and the scroll keys are only bound on pages which support scrolling (currently only page 4) - also during oneshot (like the page-switching keys). Scroll offset is reset for all pages on any key - except scroll keys, so that entering or switching to a page resets the scroll, as well as when "re-entering" the same page or "re-activating" the stats oneshot view. TODO: print_page(..) is highly associated with extending the oneshot timer if required. The timer handling can probably move into print_page and removed from all the places which boilerplate its management.
2020-04-10 22:20:02 +00:00
``key_scroll_up``
Default: UP
``key_scroll_down``
Default: DOWN
stats.lua: filter input bindings by typing them This lets you press / in page 4 of the stats and type a keybinding or part of its command to filter it by using mp.input. This works badly without a VO because both stats.lua and console.lua use show-text and only one can be displayed at a time, but it's still better than not having the search available at all.
2024-03-21 19:09:22 +00:00
``key_scroll_search``
Default: /
stats: support UP/DOWN to scroll at page 4 (perf) Keys and lines-to-scroll are configurabe, and the scroll keys are only bound on pages which support scrolling (currently only page 4) - also during oneshot (like the page-switching keys). Scroll offset is reset for all pages on any key - except scroll keys, so that entering or switching to a page resets the scroll, as well as when "re-entering" the same page or "re-activating" the stats oneshot view. TODO: print_page(..) is highly associated with extending the oneshot timer if required. The timer handling can probably move into print_page and removed from all the places which boilerplate its management.
2020-04-10 22:20:02 +00:00
``scroll_lines``
Default: 1
Scroll key bindings and number of lines to scroll on pages which support it.
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
``duration``
Default: 4
How long the stats are shown in seconds (oneshot).
``redraw_delay``
Default: 1
How long it takes to refresh the displayed stats in seconds (toggling).
``persistent_overlay``
stats: clarify documentation Change true/false to yes/no because lua script configs only take these values for booleans.
2017-10-12 19:28:24 +00:00
Default: no
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
stats: clarify documentation Change true/false to yes/no because lua script configs only take these values for booleans.
2017-10-12 19:28:24 +00:00
When `no`, other scripts printing text to the screen can overwrite the
displayed stats. When `yes`, displayed stats are persistently shown for the
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
respective duration. This can result in overlapping text when multiple
scripts decide to print text at the same time.
stats.lua: display file tags This adds file tags to display along with the title, including album/artist etc. for music, and series etc. for some videos. The list of tags to display is identical to the tags printed to the terminal and is controlled by the --display-tags option. To filter out overlength tags (such as long comments and lyrics) and files with too many tags, add file_tag_max_length and file_tag_max_count options so that tags longer than this length are not displayed, and only the first few tags are displayed. Also makes tags show on page 5 only.
2024-04-17 10:27:04 +00:00
``file_tag_max_length``
Default: 128
Only show file tags shorter than this length, in bytes.
``file_tag_max_count``
Default: 16
Only show the first specified amount of file tags.
stats.lua: clip lines with ${term-clip-cc} 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.
2024-10-17 22:00:22 +00:00
``term_clip``
Default: yes
stats.lua: truncate long lines for the terminal The terminal is assumed to be 80x24 in size, the new options `term_width_limit` and `term_height_limit` can be used to overwrite that. Lines longer then the terminal width cause problems with scrolling pages and need to be shortened. The algorithm used for shortening can deal with tabs and escape sequences, has rudimentary support for UTF-8 and runs in O(n). avih helped in the creation of the term_ellipsis() function and split() is also from him.
2023-08-28 21:39:34 +00:00
stats.lua: clip lines with ${term-clip-cc} 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.
2024-10-17 22:00:22 +00:00
Whether to clip lines to the terminal width.
stats.lua: truncate long lines for the terminal The terminal is assumed to be 80x24 in size, the new options `term_width_limit` and `term_height_limit` can be used to overwrite that. Lines longer then the terminal width cause problems with scrolling pages and need to be shortened. The algorithm used for shortening can deal with tabs and escape sequences, has rudimentary support for UTF-8 and runs in O(n). avih helped in the creation of the term_ellipsis() function and split() is also from him.
2023-08-28 21:39:34 +00:00
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
``plot_perfdata``
stats: clarify documentation Change true/false to yes/no because lua script configs only take these values for booleans.
2017-10-12 19:28:24 +00:00
Default: yes
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
Show graphs for performance data (page 2).
``plot_vsync_ratio``
stats: clarify documentation Change true/false to yes/no because lua script configs only take these values for booleans.
2017-10-12 19:28:24 +00:00
Default: yes
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
``plot_vsync_jitter``
stats: clarify documentation Change true/false to yes/no because lua script configs only take these values for booleans.
2017-10-12 19:28:24 +00:00
Default: yes
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
Show graphs for vsync and jitter values (page 1). Only when toggled.
stats.lua: enable --tone-mapping-visualize while stats shown Except in oneshot mode. Controllable via new option.
2023-08-30 13:09:51 +00:00
``plot_tonemapping_lut``
stats.lua: disable tonemapping plot by default Nobody except a chosen few (I'm not one of them) even knows what it means. Multiple people thought it was actually some kind of rendering bug. Just disable it by default. Closes #12671.
2023-10-22 04:13:52 +00:00
Default: no
stats.lua: enable --tone-mapping-visualize while stats shown Except in oneshot mode. Controllable via new option.
2023-08-30 13:09:51 +00:00
Enable tone-mapping LUT visualization automatically. Only when toggled.
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
``flush_graph_data``
stats: clarify documentation Change true/false to yes/no because lua script configs only take these values for booleans.
2017-10-12 19:28:24 +00:00
Default: yes
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
Clear data buffers used for drawing graphs when toggling.
``font``
stats.lua: inherit OSD styles Avoid having to configure both the OSD and the stats script opts when you change the OSD options, in particular avoid having to convert colors to BGR. Also document the shadow options. font_size, border_size and shadow offset defaults are kept because the same values look much bigger in the stats than in the corresponding OSD options. osd-back-color is now respected without extra checks until you explicitly set a shadow_color.
2023-11-13 07:46:29 +00:00
Default: same as ``osd-font``
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
Font name. Should support as many font weights as possible for optimal
visual experience.
``font_mono``
stats.lua: set sans-serif as default font sans is deprecated and unsupported on some platforms.
2023-07-09 09:05:23 +00:00
Default: monospace
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
Font name for parts where monospaced characters are necessary to align
text. Currently, monospaced digits are sufficient.
``font_size``
Default: 8
Font size used to render text.
``font_color``
stats.lua: inherit OSD styles Avoid having to configure both the OSD and the stats script opts when you change the OSD options, in particular avoid having to convert colors to BGR. Also document the shadow options. font_size, border_size and shadow offset defaults are kept because the same values look much bigger in the stats than in the corresponding OSD options. osd-back-color is now respected without extra checks until you explicitly set a shadow_color.
2023-11-13 07:46:29 +00:00
Default: same as ``osd-color``
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
stats.lua: inherit OSD styles Avoid having to configure both the OSD and the stats script opts when you change the OSD options, in particular avoid having to convert colors to BGR. Also document the shadow options. font_size, border_size and shadow offset defaults are kept because the same values look much bigger in the stats than in the corresponding OSD options. osd-back-color is now respected without extra checks until you explicitly set a shadow_color.
2023-11-13 07:46:29 +00:00
Color of the text.
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
``border_size``
Default: 0.8
Size of border drawn around the font.
``border_color``
stats.lua: inherit OSD styles Avoid having to configure both the OSD and the stats script opts when you change the OSD options, in particular avoid having to convert colors to BGR. Also document the shadow options. font_size, border_size and shadow offset defaults are kept because the same values look much bigger in the stats than in the corresponding OSD options. osd-back-color is now respected without extra checks until you explicitly set a shadow_color.
2023-11-13 07:46:29 +00:00
Default: same as ``osd-border-color``
Color of the text border.
``shadow_x_offset``
Default: 0
The horizontal distance from the text to position the shadow at.
``shadow_y_offset``
Default: 0
The vertical distance from the text to position the shadow at.
``shadow_color``
Default: same as ``osd-shadow-color``
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
stats.lua: inherit OSD styles Avoid having to configure both the OSD and the stats script opts when you change the OSD options, in particular avoid having to convert colors to BGR. Also document the shadow options. font_size, border_size and shadow offset defaults are kept because the same values look much bigger in the stats than in the corresponding OSD options. osd-back-color is now respected without extra checks until you explicitly set a shadow_color.
2023-11-13 07:46:29 +00:00
Color of the text shadow.
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
``alpha``
Default: 11
stats.lua: inherit OSD styles Avoid having to configure both the OSD and the stats script opts when you change the OSD options, in particular avoid having to convert colors to BGR. Also document the shadow options. font_size, border_size and shadow offset defaults are kept because the same values look much bigger in the stats than in the corresponding OSD options. osd-back-color is now respected without extra checks until you explicitly set a shadow_color.
2023-11-13 07:46:29 +00:00
Transparency of text when ``font_color`` is specified, of text borders when
``border_color`` is specified, and of text shadows when ``shadow_color`` is
specified.
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
``plot_bg_border_color``
Default: 0000FF
Border color used for drawing graphs.
stats.lua: add option to control plot border width This adds a new configuration option plot_bg_border_width, which controls the border width of plots.
2024-04-15 04:45:18 +00:00
``plot_bg_border_width``
Default: 0.5
Border width used for drawing graphs.
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
``plot_bg_color``
Default: 262626
Background color used for drawing graphs.
``plot_color``
Default: FFFFFF
Color used for drawing graphs.
stats.lua: add option to disable scale with video size This adds a new configuration option vidscale, which controls whether stats display is scaled with video, similar to the option for OSC.lua.
2024-04-15 04:43:17 +00:00
``vidscale``
{stats,osc}.lua: respect --osd-scale-by-window by default This lets these scripts scale the elements with OSD by default.
2024-05-16 14:56:46 +00:00
Default: auto
stats.lua: add option to disable scale with video size This adds a new configuration option vidscale, which controls whether stats display is scaled with video, similar to the option for OSC.lua.
2024-04-15 04:43:17 +00:00
Scale the text and graphs with the video.
``no`` tries to keep the sizes constant.
stats.lua: add add auto value to vidscale option This adds auto to vidscale script option, which lets the scale be inherited from OSD --osd-scale-by-window option.
2024-05-16 14:08:06 +00:00
``auto`` scales the text and graphs with the OSD, which is scaled with the
window or kept at a constant size, depending on the ``--osd-scale-by-window`` option.
stats.lua: add option to disable scale with video size This adds a new configuration option vidscale, which controls whether stats display is scaled with video, similar to the option for OSC.lua.
2024-04-15 04:43:17 +00:00
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
Note: colors are given as hexadecimal values and use ASS tag order: BBGGRR
(blue green red).
Different key bindings
~~~~~~~~~~~~~~~~~~~~~~
stats.lua: remove script-opts for the main keys (i/I) Unlike the page switching/scrolling keys which are bound at runtime and therefore we need to know which (configured) keys to bind, the main keys (i/I by default) are static and can be bound via input.conf. And indeed, the builtin bindings at etc/input.conf have them already.
2021-07-21 06:13:23 +00:00
Additional keys can be configured in ``input.conf`` to display the stats::
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
e script-binding stats/display-stats
E script-binding stats/display-stats-toggle
stats.lua: remove script-opts for the main keys (i/I) Unlike the page switching/scrolling keys which are bound at runtime and therefore we need to know which (configured) keys to bind, the main keys (i/I by default) are static and can be bound via input.conf. And indeed, the builtin bindings at etc/input.conf have them already.
2021-07-21 06:13:23 +00:00
And to display a certain page directly::
stats: add documentation stats.rst is heavily based on osc.rst
2017-10-09 15:30:41 +00:00
i script-binding stats/display-page-1
stats.lua: allow keybindings to toggle the display of a specific page This lets you define bindings like h script-binding stats/display-page-4-toggle. Requested in #14966.
2024-10-01 19:47:48 +00:00
h script-binding stats/display-page-4-toggle
stats: some more performance graphs Add an infrastructure for collecting performance-related data, use it in some places. Add rendering of them to stats.lua. There were two main goals: minimal impact on the normal code and normal playback. So all these stats_* function calls either happen only during initialization, or return immediately if no stats collection is going on. That's why it does this lazily adding of stats entries etc. (a first iteration made each stats entry an API thing, instead of just a single stats_ctx, but I thought that was getting too intrusive in the "normal" code, even if everything gets worse inside of stats.c). You could get most of this information from various profilers (including the extremely primitive --dump-stats thing in mpv), but this makes it easier to see the most important information at once (at least in theory), partially because we know best about the context of various things. Not very happy with this. It's all pretty primitive and dumb. At this point I just wanted to get over with it, without necessarily having to revisit it later, but with having my stupid statistics. Somehow the code feels terrible. There are a lot of meh decisions in there that could be better or worse (but mostly could be better), and it just sucks but it's also trivial and uninteresting and does the job. I guess I hate programming. It's so tedious and the result is always shit. Anyway, enjoy.
2020-04-08 22:27:54 +00:00
stats.lua: add page 4: active key-bindings list This is a scrollable page which also works nicely with the terminal OSD. Typically there are more than 100 bound keys. It groups the binding using fuzzy property/command/script name after simple analysis of the command string, and then further sorts the binding in each group according to the "complexity" of the key itself (plain keys -> keys with modifiers, alphabetically, etc). The alignment/grouping style is heavily inspired by @medhefgo's #8924 but otherwise it's an independent implementation.
2021-07-16 08:17:50 +00:00
Active key bindings page
~~~~~~~~~~~~~~~~~~~~~~~~
Lists the active key bindings and the commands they're bound to, excluding the
DOCS: fix manual compiling warnings This fix the warnings shown below when compiling the manual for any of its three common formats: ``` DOCS/man/mpv.rst:46: (ERROR/3) Unknown target name: "--input-test". DOCS/man/stats.rst:183: (ERROR/3) Unknown target name: "--input-test". ```
2021-07-22 19:00:44 +00:00
interactive keys of the stats script itself. See also ``--input-test`` for more
stats.lua: add page 4: active key-bindings list This is a scrollable page which also works nicely with the terminal OSD. Typically there are more than 100 bound keys. It groups the binding using fuzzy property/command/script name after simple analysis of the command string, and then further sorts the binding in each group according to the "complexity" of the key itself (plain keys -> keys with modifiers, alphabetically, etc). The alignment/grouping style is heavily inspired by @medhefgo's #8924 but otherwise it's an independent implementation.
2021-07-16 08:17:50 +00:00
detailed view of each binding.
The keys are grouped automatically using a simple analysis of the command
string, and one should not expect documentation-level grouping accuracy,
however, it should still be reasonably useful.
DOCS/man/stats: bindlist: use --script-opts-append Use --script-opts-append=bindlist instead of --script-opts to not overwrite script-opts in mpv.conf, which may set different key bindings.
2024-10-21 10:49:17 +00:00
Using ``--idle --script-opts-append=stats-bindlist=yes`` will print the list to
stats.lua: clip lines with ${term-clip-cc} 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.
2024-10-17 22:00:22 +00:00
the terminal and quit immediately. Long lines are clipped to the terminal width
unless this is disabled with ``--script-opts-append=stats-term_clip=no``. Escape
sequences can be disabled by adding ``-`` before ``yes``, i.e.
``--script-opts-append=stats-bindlist=-yes``.
stats.lua: page 4 (keys): support help-like terminal printout While --input-test is useful, and so is page 4 of stats, until now there was no way to simply print the list in a help-like fashion. This commit adds such printout, invoked by the script opt stats-bindlist=yes, which uses the existing page 4 code. This prints the list on startup and quits immediately - like any help page. It's awkward to invoke compared to other help pages, and it does require the stats page to be enabled (it is by default), however it is a script-generated output, and currently there's no other method to print a help page generated by a script. The printout itself is performed using lua's io.write. While reliable, it's not the standard way for mpv to print to the terminal. Other possible printout methods are mp.msg.info - which also prints "[stats]" prefix on each line (ugly), or forcing term-osd and setting an osd-message which mpv will then print at the terminal - however that's printed to stderr, and could also be subject to timing concerns since we quit right afterwards. In the future we can consider changing/integrating the invocation so that mpv itself could print a help page generated by a script, thus solving both the awkward invocation and printout-method issues.
2021-07-16 09:06:20 +00:00
stats.lua: add page 4: active key-bindings list This is a scrollable page which also works nicely with the terminal OSD. Typically there are more than 100 bound keys. It groups the binding using fuzzy property/command/script name after simple analysis of the command string, and then further sorts the binding in each group according to the "complexity" of the key itself (plain keys -> keys with modifiers, alphabetically, etc). The alignment/grouping style is heavily inspired by @medhefgo's #8924 but otherwise it's an independent implementation.
2021-07-16 08:17:50 +00:00
Like with ``--input-test``, the list includes bindings from ``input.conf`` and
DOCS/stats.rst: fix quoting
2021-08-09 20:57:04 +00:00
from user scripts. Use ``--no-config`` to list only built-in bindings.
stats.lua: add page 4: active key-bindings list This is a scrollable page which also works nicely with the terminal OSD. Typically there are more than 100 bound keys. It groups the binding using fuzzy property/command/script name after simple analysis of the command string, and then further sorts the binding in each group according to the "complexity" of the key itself (plain keys -> keys with modifiers, alphabetically, etc). The alignment/grouping style is heavily inspired by @medhefgo's #8924 but otherwise it's an independent implementation.
2021-07-16 08:17:50 +00:00
stats: some more performance graphs Add an infrastructure for collecting performance-related data, use it in some places. Add rendering of them to stats.lua. There were two main goals: minimal impact on the normal code and normal playback. So all these stats_* function calls either happen only during initialization, or return immediately if no stats collection is going on. That's why it does this lazily adding of stats entries etc. (a first iteration made each stats entry an API thing, instead of just a single stats_ctx, but I thought that was getting too intrusive in the "normal" code, even if everything gets worse inside of stats.c). You could get most of this information from various profilers (including the extremely primitive --dump-stats thing in mpv), but this makes it easier to see the most important information at once (at least in theory), partially because we know best about the context of various things. Not very happy with this. It's all pretty primitive and dumb. At this point I just wanted to get over with it, without necessarily having to revisit it later, but with having my stupid statistics. Somehow the code feels terrible. There are a lot of meh decisions in there that could be better or worse (but mostly could be better), and it just sucks but it's also trivial and uninteresting and does the job. I guess I hate programming. It's so tedious and the result is always shit. Anyway, enjoy.
2020-04-08 22:27:54 +00:00
Internal stuff page
~~~~~~~~~~~~~~~~~~~
Most entries shown on this page have rather vague meaning. Likely none of this
is useful for you. Don't attempt to use it. Forget its existence.
Selecting this for the first time will start collecting some internal
performance data. That means performance will be slightly lower than normal for
the rest of the time the player is running (even if the stats page is closed).
manpage: finish a sentence
2020-04-08 23:07:12 +00:00
Note that the stats page itself uses a lot of CPU and even GPU resources, and
may have a heavy impact on performance.
stats: some more performance graphs Add an infrastructure for collecting performance-related data, use it in some places. Add rendering of them to stats.lua. There were two main goals: minimal impact on the normal code and normal playback. So all these stats_* function calls either happen only during initialization, or return immediately if no stats collection is going on. That's why it does this lazily adding of stats entries etc. (a first iteration made each stats entry an API thing, instead of just a single stats_ctx, but I thought that was getting too intrusive in the "normal" code, even if everything gets worse inside of stats.c). You could get most of this information from various profilers (including the extremely primitive --dump-stats thing in mpv), but this makes it easier to see the most important information at once (at least in theory), partially because we know best about the context of various things. Not very happy with this. It's all pretty primitive and dumb. At this point I just wanted to get over with it, without necessarily having to revisit it later, but with having my stupid statistics. Somehow the code feels terrible. There are a lot of meh decisions in there that could be better or worse (but mostly could be better), and it just sucks but it's also trivial and uninteresting and does the job. I guess I hate programming. It's so tedious and the result is always shit. Anyway, enjoy.
2020-04-08 22:27:54 +00:00
The displayed information is accumulated over the redraw delay (shown as
``poll-time`` field).
This adds entries for each Lua script. If there are too many scripts running,
stats: support UP/DOWN to scroll at page 4 (perf) Keys and lines-to-scroll are configurabe, and the scroll keys are only bound on pages which support scrolling (currently only page 4) - also during oneshot (like the page-switching keys). Scroll offset is reset for all pages on any key - except scroll keys, so that entering or switching to a page resets the scroll, as well as when "re-entering" the same page or "re-activating" the stats oneshot view. TODO: print_page(..) is highly associated with extending the oneshot timer if required. The timer handling can probably move into print_page and removed from all the places which boilerplate its management.
2020-04-10 22:20:02 +00:00
parts of the list will simply be out of the screen, but it can be scrolled.
stats: some more performance graphs Add an infrastructure for collecting performance-related data, use it in some places. Add rendering of them to stats.lua. There were two main goals: minimal impact on the normal code and normal playback. So all these stats_* function calls either happen only during initialization, or return immediately if no stats collection is going on. That's why it does this lazily adding of stats entries etc. (a first iteration made each stats entry an API thing, instead of just a single stats_ctx, but I thought that was getting too intrusive in the "normal" code, even if everything gets worse inside of stats.c). You could get most of this information from various profilers (including the extremely primitive --dump-stats thing in mpv), but this makes it easier to see the most important information at once (at least in theory), partially because we know best about the context of various things. Not very happy with this. It's all pretty primitive and dumb. At this point I just wanted to get over with it, without necessarily having to revisit it later, but with having my stupid statistics. Somehow the code feels terrible. There are a lot of meh decisions in there that could be better or worse (but mostly could be better), and it just sucks but it's also trivial and uninteresting and does the job. I guess I hate programming. It's so tedious and the result is always shit. Anyway, enjoy.
2020-04-08 22:27:54 +00:00
If the underlying platform does not support pthread per thread times, the
displayed times will be 0 or something random (I suspect that at time of this
writing, only Linux provides the correct via pthread APIs for per thread times).
Most entries are added lazily and only during data collection, which is why
entries may pop up randomly after some time. It's also why the memory usage
entries for scripts that have been inactive since the start of data collection
are missing.
Memory usage is approximate and does not reflect internal fragmentation.
js: report scripts CPU/memory usage statistics This can be viewed at page 4 of the internal stats display (i or I). CPU time report is the same as at lua.c, but untested - doesn't seem to work on windows - also not for lua. TL;DR: Set env MPV_LEAK_REPORT=1 to enable js memory reporting stats. This also almost doubles the memory usage by js scripts. For memory reporting, we don't have enough info by default, because even when using a custom allocator, mujs doesn't report the old size (on free or realloc) because it doesn't track this value, and as a result we can't track the overall size. Our option are either to track the size of each allocation on our own, or use talloc which tracks this value. However, using talloc for mujs allocations adds a considerable overhead, and almost doubles(!) the overall memory used, because each individual allocation includes a considerable talloc header, and mujs does many small allocations. So our solution is that by default we behave like previously - not using a custom allocator with mujs, and stats does not display memory usage for js scripts. However, if the env var MPV_LEAK_REPORT is set to 1, then we use a custom allocator with talloc and track/report memory usage. We can't switch allocator at runtime, so an mpv instance either tracks or doesn't track js scripts memory usage, according to the env var. (we could use a property and apply it whenever a new script starts, so that it could change for newly launched scripts, but we don't).
2020-04-11 00:56:12 +00:00
JS scripts memory reporting is disabled by default because collecting the data
javascript: use --js-memory-report option instead of MPV_LEAK_REPORT The MPV_LEAK_REPORT environment variable was previously read in order to determine whether or not to enable memory reporting for javascript scripts. This is kind of weird and deviates from the norm of exposing an option to the user. So let's just add --js-memory-report and disable it by default instead.
2023-10-25 23:17:25 +00:00
at the JS side has an overhead and will increase memory usage. It can be
enabled by setting the ``--js-memory-report`` option before starting mpv.
js: report scripts CPU/memory usage statistics This can be viewed at page 4 of the internal stats display (i or I). CPU time report is the same as at lua.c, but untested - doesn't seem to work on windows - also not for lua. TL;DR: Set env MPV_LEAK_REPORT=1 to enable js memory reporting stats. This also almost doubles the memory usage by js scripts. For memory reporting, we don't have enough info by default, because even when using a custom allocator, mujs doesn't report the old size (on free or realloc) because it doesn't track this value, and as a result we can't track the overall size. Our option are either to track the size of each allocation on our own, or use talloc which tracks this value. However, using talloc for mujs allocations adds a considerable overhead, and almost doubles(!) the overall memory used, because each individual allocation includes a considerable talloc header, and mujs does many small allocations. So our solution is that by default we behave like previously - not using a custom allocator with mujs, and stats does not display memory usage for js scripts. However, if the env var MPV_LEAK_REPORT is set to 1, then we use a custom allocator with talloc and track/report memory usage. We can't switch allocator at runtime, so an mpv instance either tracks or doesn't track js scripts memory usage, according to the env var. (we could use a property and apply it whenever a new script starts, so that it could change for newly launched scripts, but we don't).
2020-04-11 00:56:12 +00:00
stats: some more performance graphs Add an infrastructure for collecting performance-related data, use it in some places. Add rendering of them to stats.lua. There were two main goals: minimal impact on the normal code and normal playback. So all these stats_* function calls either happen only during initialization, or return immediately if no stats collection is going on. That's why it does this lazily adding of stats entries etc. (a first iteration made each stats entry an API thing, instead of just a single stats_ctx, but I thought that was getting too intrusive in the "normal" code, even if everything gets worse inside of stats.c). You could get most of this information from various profilers (including the extremely primitive --dump-stats thing in mpv), but this makes it easier to see the most important information at once (at least in theory), partially because we know best about the context of various things. Not very happy with this. It's all pretty primitive and dumb. At this point I just wanted to get over with it, without necessarily having to revisit it later, but with having my stupid statistics. Somehow the code feels terrible. There are a lot of meh decisions in there that could be better or worse (but mostly could be better), and it just sucks but it's also trivial and uninteresting and does the job. I guess I hate programming. It's so tedious and the result is always shit. Anyway, enjoy.
2020-04-08 22:27:54 +00:00
If entries have ``/time`` and ``/cpu`` variants, the former gives the real time
(monotonic clock), while the latter the thread CPU time (only if the
corresponding pthread API works and is supported).