Skip to main content
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

KeyAction
iShow stats for a fixed duration
IToggle stats (stay until toggled off)
?Toggle key bindings display

​
Page navigation (while stats are visible)

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

​
Scroll controls (on scrollable pages)

KeyAction
UPScroll one line up
DOWNScroll one line down

​
Key bindings page (page 4)

KeyAction
/Search key bindings

​
When stats are toggled on

KeyAction
ESCClose the stats overlay

​
Pages overview

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)
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).
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).
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
Detailed information about selected tracks (or all tracks, depending on track_info_selected_only): codec, format, bitrate, language, metadata.
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

Build docs developers (and LLMs) love

Get started for freeTalk to us