Skip to main content
The On-Screen Display (OSD) shows status messages, seek bars, and playback time overlays directly on the video. These options control what is shown, when it appears, and how it looks.

​
Display mode

​
--osd-level
integer (0–3)
default:"1"
Set the initial OSD mode.
LevelBehavior
0OSD completely disabled — only subtitles are rendered
1OSD enabled; messages appear only on user interaction
2OSD enabled; current playback time always visible
3OSD enabled; full status (time, duration, and more) always visible
mpv --osd-level=0 file.mkv   # subtitle-only, no OSD
mpv --osd-level=2 file.mkv   # always show current time
​
--osd-bar
yes|no
default:"yes"
Show the seek bar during seeks. To disable the OSD entirely, use --osd-level=0 instead.
​
--osd-on-seek
no|bar|msg|msg-bar
default:"bar"
What to display on the OSD when the user seeks.
  • no — show nothing
  • bar — show only the seek bar
  • msg — show only the time message
  • msg-bar — show both the message and the bar
​
--osd-fractions
flag
Show OSD timestamps with millisecond precision (HH:MM:SS.mmm). Useful for identifying exact video frame positions.

​
Message duration and content

​
--osd-duration
integer (ms)
default:"1000"
How long OSD messages remain on screen, in milliseconds.
mpv --osd-duration=3000 file.mkv   # keep messages for 3 seconds
​
--osd-msg1
string
Message displayed at OSD level 1 (visible by default). Supports property expansion — for example, ${filename} inserts the current filename.
mpv --osd-msg1='${filename} — ${time-pos}/${duration}' file.mkv
​
--osd-msg2
string
Message displayed at OSD level 2. If empty (the default), shows the current playback time.
​
--osd-msg3
string
Message displayed at OSD level 3, and used by the show-progress command (default binding: P) and when seeking with the msg or msg-bar seek modes. If empty, shows the playback time, duration, and additional status.Supersedes --osd-status-msg.
​
--osd-status-msg
string
Legacy equivalent of --osd-msg3. Implicitly appends ${osd-sym-cc}. Ignored if --osd-msg3 is not empty. Prefer --osd-msg3.
​
--osd-playing-msg
string
Show a message when playback starts. Expands properties.
mpv --osd-playing-msg='Now playing: ${media-title}' file.mkv
​
--osd-playing-msg-duration
integer (ms)
How long --osd-playing-msg stays on screen. Defaults to --osd-duration if unset.

​
Font and text appearance

​
--osd-font
string
default:"sans-serif"
Font family name to use for OSD text.
mpv --osd-font='Noto Sans' file.mkv
mpv --osd-font='Comic Sans MS' file.mkv
​
--osd-font-size
float
default:"30"
Font size in scaled pixels. The actual display size depends on --osd-scale and --osd-scale-by-window.
​
--osd-bold
yes|no
Render OSD text in bold.
​
--osd-italic
yes|no
Render OSD text in italic.
​
--osd-blur
float (0–20)
default:"0"
Apply a Gaussian blur to the OSD font outline. 0 means no blur.

​
Colors

Colors are specified as r/g/b (each component 0.0–1.0), with optional alpha as r/g/b/a, or as #RRGGBB / #AARRGGBB hex values. Alpha 0 is fully transparent, 1.0 is fully opaque.
​
--osd-color
color
default:"#FFFFFF"
Color of OSD text.
mpv --osd-color='#FF0000' file.mkv          # red text
mpv --osd-color='1.0/1.0/1.0/0.8' file.mkv # white with 80% opacity
​
--osd-outline-color
color
Color of the text outline. --osd-border-color is an alias.
mpv --osd-outline-color='#000000' file.mkv   # black outline
​
--osd-back-color
color
Color of the text background (used with --osd-border-style=opaque-box). --osd-shadow-color is an alias.
​
--osd-outline-size
float
default:"1.65"
Size of the OSD text outline in scaled pixels. Set to 0 to disable outlines. --osd-border-size is an alias.
​
--osd-border-style
outline-and-shadow|opaque-box|background-box
default:"outline-and-shadow"
Style used for OSD text borders:
  • outline-and-shadow — standard text with outline and optional shadow
  • opaque-box — solid background box behind each text line
  • background-box — background box spanning all lines of text
​
--osd-shadow-offset
float
default:"0"
Shadow displacement in scaled pixels. 0 disables shadows.

​
Seek bar position and size

​
--osd-bar-align-x
float (-1 to 1)
default:"0"
Horizontal position of the OSD seek bar. -1 is left, 0 is centered, 1 is right.
​
--osd-bar-align-y
float (-1 to 1)
default:"0.5"
Vertical position of the OSD seek bar. -1 is top, 0 is centered, 1 is bottom.
​
--osd-bar-w
float (1–100)
default:"75"
Width of the OSD seek bar as a percentage of the screen width.
​
--osd-bar-h
float (0.1–50)
default:"3.125"
Height of the OSD seek bar as a percentage of the screen height.

​
Scale and position

​
--osd-scale
float
Scale multiplier applied to --osd-font-size. Values above 1 make the OSD larger.
​
--osd-scale-by-window
yes|no
default:"yes"
Scale OSD size with the window size. When disabled, --osd-font-size is interpreted as literal pixels, and resizing the window does not change OSD size.
​
--osd-align-x
left|center|right
default:"left"
Horizontal alignment of OSD text.
​
--osd-align-y
top|center|bottom
default:"top"
Vertical alignment of OSD text.
​
--osd-margin-x
integer (scaled pixels)
default:"16"
Left and right margin for OSD text in scaled pixels. Controls distance from the screen edge and the wrap point for long messages.
​
--osd-margin-y
integer (scaled pixels)
default:"16"
Top and bottom margin for OSD text in scaled pixels.

​
Configuration examples

# No seek bar, just a small time display on interaction
mpv --osd-level=1 --osd-bar=no file.mkv

​
Configuration file

# ~/.config/mpv/mpv.conf

osd-level=1
osd-duration=2000
osd-font=Noto Sans
osd-font-size=32
osd-color=#FFFFFF
osd-outline-color=#000000
osd-outline-size=2
osd-bar-align-y=1
osd-bar-w=90
osd-bar-h=2

Build docs developers (and LLMs) love

Get started for freeTalk to us