From 81cf58c8c47430cc3308ff9b33ea3fe5c83c221c Mon Sep 17 00:00:00 2001 From: Julian Date: Mon, 9 Oct 2017 17:30:41 +0200 Subject: stats: add documentation stats.rst is heavily based on osc.rst --- DOCS/man/mpv.rst | 2 + DOCS/man/stats.rst | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++ wscript_build.py | 2 +- 3 files changed, 165 insertions(+), 1 deletion(-) create mode 100644 DOCS/man/stats.rst diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index a307cc2ff2..e9c6db31e3 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -877,6 +877,8 @@ works like in older mpv releases. The profiles are currently defined as follows: .. include:: osc.rst +.. include:: stats.rst + .. include:: lua.rst .. include:: javascript.rst diff --git a/DOCS/man/stats.rst b/DOCS/man/stats.rst new file mode 100644 index 0000000000..eb4c2afaff --- /dev/null +++ b/DOCS/man/stats.rst @@ -0,0 +1,162 @@ +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) +==== ============================================== + +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 +2 Show frame timings +==== ================== + +Font +~~~~ + +For optimal visual experience, a font with support for many font weights and +monospaced digits is recommended. By default, the open source font +`Source Sans Pro `_ is used. + +Configuration +------------- + +This script can be customized through a config file ``lua-settings/stats.conf`` +placed in mpv's user directory and through the ``--script-opts`` command-line +option. The configuration syntax is described in `ON SCREEN CONTROLLER`_. + +Configurable Options +~~~~~~~~~~~~~~~~~~~~ + +``key_oneshot`` + Default: i +``key_toggle`` + Default: I + + Key bindings to display stats. + +``key_page_1`` + Default: 1 +``key_page_2`` + Default: 2 + + Key bindings for page switching while stats are displayed. + +``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`` + Default: false + + When false, other scripts printing text to the screen can overwrite the + displayed stats. When true, displayed stats are persistently shown for the + respective duration. This can result in overlapping text when multiple + scripts decide to print text at the same time. + +``plot_perfdata`` + Default: true + + Show graphs for performance data (page 2). + +``plot_vsync_ratio`` + Default: true +``plot_vsync_jitter`` + Default: true + + Show graphs for vsync and jitter values (page 1). Only when toggled. + +``flush_graph_data`` + Default: true + + Clear data buffers used for drawing graphs when toggling. + +``font`` + Default: Source Sans Pro + + Font name. Should support as many font weights as possible for optimal + visual experience. + +``font_mono`` + Default: Source Sans Pro + + 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`` + Default: FFFFFF + + Font color. + +``border_size`` + Default: 0.8 + + Size of border drawn around the font. + +``border_color`` + Default: 262626 + + Color of drawn border. + +``alpha`` + Default: 11 + + Transparency for drawn text. + +``plot_bg_border_color`` + Default: 0000FF + + Border color used for drawing graphs. + +``plot_bg_color`` + Default: 262626 + + Background color used for drawing graphs. + +``plot_color`` + Default: FFFFFF + + Color used for drawing graphs. + +Note: colors are given as hexadecimal values and use ASS tag order: BBGGRR +(blue green red). + +Different key bindings +~~~~~~~~~~~~~~~~~~~~~~ + +A different key binding can be defined with the aforementioned options +``key_oneshot`` and ``key_toggle`` but also with commands in ``input.conf``, +for example:: + + e script-binding stats/display-stats + E script-binding stats/display-stats-toggle + +Using ``input.conf``, it is also possible to directly display a certain page:: + + i script-binding stats/display-page-1 + e script-binding stats/display-page-2 diff --git a/wscript_build.py b/wscript_build.py index cb66fbec40..7f0991f13a 100644 --- a/wscript_build.py +++ b/wscript_build.py @@ -4,7 +4,7 @@ import os def _add_rst_manual_dependencies(ctx): manpage_sources_basenames = """ options.rst ao.rst vo.rst af.rst vf.rst encode.rst - input.rst osc.rst lua.rst ipc.rst changes.rst""".split() + input.rst osc.rst stats.rst lua.rst ipc.rst changes.rst""".split() manpage_sources = ['DOCS/man/'+x for x in manpage_sources_basenames] -- cgit v1.2.3