Stats overlay

Display real-time playback statistics and performance information

The stats overlay is a built-in Lua script that displays detailed playback statistics and performance information directly on the OSD. It is enabled by default in all mpv builds with Lua support.

Enabling and disabling

The stats overlay is loaded automatically. To disable it:

mpv --load-stats-overlay=no file.mkv

Or in your config file:

# ~/.config/mpv/mpv.conf
load-stats-overlay=no

Basic usage

1. Show stats briefly

   Press i to display stats for a fixed duration (default: 4 seconds), then they disappear automatically.

2. Toggle stats permanently

   Press I (capital i) to keep stats visible until toggled off again. Press I again or ESC to hide them.

3. Show key bindings

   Press ? to toggle the display of active key bindings.

Default key bindings

Activation

Key	Action
i	Show stats for a fixed duration
I	Toggle stats (stay until toggled off)
?	Toggle key bindings display

Page navigation (while stats are visible)

Key	Page
1	Playback info (video, audio, timing)
2	Frame timings (scrollable)
3	Input cache stats (scrollable)
4	Active key bindings (scrollable)
5	Selected tracks info (scrollable)
0	Internal performance data (scrollable)

Scroll controls (on scrollable pages)

Key	Action
UP	Scroll one line up
DOWN	Scroll one line down

Key bindings page (page 4)

Key	Action
/	Search key bindings

When stats are toggled on

Key	Action
ESC	Close the stats overlay

Pages overview

Page 1 — Playback info

The default page. Shows:

• Video codec, format, resolution, framerate, bitrate
• Audio codec, sample rate, channels, bitrate
• Current A/V sync offset
• Dropped frame count
• Cache fill status and buffer duration
• Optional graphs for vsync ratio and jitter (when toggled, if plot_vsync_ratio / plot_vsync_jitter are enabled)

Page 2 — Frame timings

Shows per-frame timing data including decoder, filter, and display times. Supports scrolling for long lists. Optionally shows graphs for performance data (plot_perfdata=yes).

Page 3 — Input cache stats

Shows the demuxer cache status, including bytes in cache, cache ranges, and timestamps. Optionally shows a cache fill graph (plot_cache=yes in toggled mode).

Page 4 — Active key bindings

Lists all active key bindings and the commands they run, grouped by command type. Excludes stats script internal keys.

You can also print this list to the terminal and quit immediately:

mpv --idle --script-opt=stats-bindlist=yes

Disable escape sequences in the output:

mpv --idle --script-opt=stats-bindlist=-yes

Limit to built-in bindings only:

mpv --no-config --idle --script-opt=stats-bindlist=yes

Page 5 — Track info

Detailed information about selected tracks (or all tracks, depending on track_info_selected_only): codec, format, bitrate, language, metadata.

Page 0 — Internal data

Internal performance counters including CPU/thread time per subsystem and per Lua script. Selecting this page for the first time enables data collection, which has a small ongoing performance impact.

The internal data page can itself use significant CPU and GPU resources. Treat it as a debugging tool only.

Configuration

Configure the stats script through ~/.config/mpv/script-opts/stats.conf or via --script-opts on the command line (prefix options with stats-):

mpv --script-opts=stats-duration=8,stats-font_size=18 file.mkv

Timing options

duration · integer (seconds) · default: "4"

How long the stats display stays on screen when triggered with i (oneshot mode).

redraw_delay · integer (seconds) · default: "1"

How frequently the stats display refreshes when in toggled mode (I).

Key binding options

key_page_1 · default: "1"

Key to show page 1.

key_page_2 · default: "2"

Key to show page 2.

key_page_3 · default: "3"

Key to show page 3.

key_page_4 · default: "4"

Key to show page 4.

key_page_5 · default: "5"

Key to show page 5.

key_page_0 · default: "0"

Key to show page 0 (internal data).

key_exit · default: "ESC"

Key to close the stats when in toggled mode.

key_scroll_up · default: "UP"

Scroll up on scrollable pages.

key_scroll_down · default: "DOWN"

Scroll down on scrollable pages.

key_scroll_search · default: "/"

Search key bindings on page 4.

scroll_lines · integer · default: "1"

Number of lines to scroll per key press on scrollable pages.

Display options

persistent_overlay · yes|no · default: "no"

When yes, stats text is not overwritten by other scripts printing to the OSD. When no, any script writing to the OSD can overwrite the stats. Enabling this can cause overlapping text if multiple scripts write simultaneously.

track_info_selected_only · yes|no · default: "yes"

When yes, page 5 shows only selected tracks. When no, all tracks in the file are listed.

File tag limits

file_tag_max_length · integer (bytes) · default: "128"

Hide file metadata tags longer than this many bytes.

file_tag_max_count · integer · default: "16"

Show at most this many file metadata tags.

term_clip · yes|no · default: "yes"

Clip lines to the terminal width when printing to the terminal (used with bindlist).

Graph options

plot_perfdata · yes|no · default: "no"

Show performance graphs on page 2.

plot_vsync_ratio · yes|no · default: "no"

Show a vsync ratio graph on page 1 (toggled mode only).

plot_vsync_jitter · yes|no · default: "no"

Show a vsync jitter graph on page 1 (toggled mode only).

plot_cache · yes|no · default: "yes"

Show a cache fill graph on page 3 (toggled mode only).

plot_tonemapping_lut · yes|no · default: "no"

Enable tone-mapping LUT visualization automatically (toggled mode only).

flush_graph_data · yes|no · default: "yes"

Clear graph data buffers when toggling stats off and on.

Appearance options

font · string · default: "same as osd-font"

Font family for stats text. Should support multiple weights for best appearance.

font_mono · string · default: "monospace"

Monospaced font for aligned columns. Monospaced digits are sufficient.

font_size · integer · default: "20"

Font size for stats text in scaled pixels.

font_color · color (BBGGRR hex) · default: "same as osd-color"

Text color. Note: unlike most mpv color options, stats colors use ASS tag order: BBGGRR (blue-green-red), not RRGGBB.

border_size · float · default: "1.65"

Outline size drawn around stats text.

border_color · color (BBGGRR hex) · default: "same as osd-border-color"

Text outline color (BBGGRR order).

shadow_x_offset · float · default: "same as --osd-shadow-offset"

Horizontal shadow offset in scaled pixels.

shadow_y_offset · float · default: "same as --osd-shadow-offset"

Vertical shadow offset in scaled pixels.

shadow_color · color (BBGGRR hex) · default: "same as osd-shadow-color"

Shadow color (BBGGRR order).

alpha · integer (0–255) · default: "11"

Transparency of text, borders, and shadows when their respective colors are specified. 0 is fully opaque, 255 is fully transparent.

vidscale · auto|yes|no · default: "auto"

Scale stats text with the video/window:

• auto — scale with OSD (respects --osd-scale-by-window)
• no — fixed size regardless of window dimensions

Graph colors

Graph colors use BBGGRR hex order (not RRGGBB).

plot_bg_border_color · color (BBGGRR) · default: "0000FF"

Border color for graph backgrounds.

plot_bg_border_width · float · default: "1.25"

Border width for graph backgrounds.

plot_bg_color · color (BBGGRR) · default: "262626"

Background color for graphs.

plot_color · color (BBGGRR) · default: "FFFFFF"

Foreground color for graph data lines.

Custom key bindings

You can add extra bindings in input.conf to trigger specific stats pages:

# input.conf

e script-binding stats/display-stats
E script-binding stats/display-stats-toggle

i script-binding stats/display-page-1
h script-binding stats/display-page-4-toggle

Example configuration

# ~/.config/mpv/script-opts/stats.conf

duration=6
redraw_delay=1
font_size=18
persistent_overlay=no
track_info_selected_only=yes
plot_cache=yes
plot_perfdata=no
plot_vsync_ratio=no
vidscale=auto