diff options
Diffstat (limited to 'DOCS/man/osc.rst')
| -rw-r--r-- | DOCS/man/osc.rst | 456 |
1 files changed, 456 insertions, 0 deletions
diff --git a/DOCS/man/osc.rst b/DOCS/man/osc.rst new file mode 100644 index 0000000..c791d75 --- /dev/null +++ b/DOCS/man/osc.rst @@ -0,0 +1,456 @@ +ON SCREEN CONTROLLER +==================== + +The On Screen Controller (short: OSC) is a minimal GUI integrated with mpv to +offer basic mouse-controllability. It is intended to make interaction easier +for new users and to enable precise and direct seeking. + +The OSC is enabled by default if mpv was compiled with Lua support. It can be +disabled entirely using the ``--osc=no`` option. + +Using the OSC +------------- + +By default, the OSC will show up whenever the mouse is moved inside the +player window and will hide if the mouse is not moved outside the OSC for +0.5 seconds or if the mouse leaves the window. + +The Interface +~~~~~~~~~~~~~ + +:: + + +---------+----------+------------------------------------------+----------+ + | pl prev | pl next | title | cache | + +------+--+---+------+---------+-----------+------+-------+-----+-----+----+ + | play | skip | skip | time | seekbar | time | audio | sub | vol | fs | + | | back | frwd | elapsed | | left | | | | | + +------+------+------+---------+-----------+------+-------+-----+-----+----+ + + +pl prev + ============= ================================================ + left-click play previous file in playlist + right-click show playlist + shift+L-click show playlist + ============= ================================================ + +pl next + ============= ================================================ + left-click play next file in playlist + right-click show playlist + shift+L-click show playlist + ============= ================================================ + +title + | Displays current media-title, filename, custom title, or target chapter + name while hovering the seekbar. + + ============= ================================================ + left-click show playlist position and length and full title + right-click show filename + ============= ================================================ + +cache + | Shows current cache fill status + +play + ============= ================================================ + left-click toggle play/pause + ============= ================================================ + +skip back + ============= ================================================ + left-click go to beginning of chapter / previous chapter + right-click show chapters + shift+L-click show chapters + ============= ================================================ + +skip frwd + ============= ================================================ + left-click go to next chapter + right-click show chapters + shift+L-click show chapters + ============= ================================================ + +time elapsed + | Shows current playback position timestamp + + ============= ================================================ + left-click toggle displaying timecodes with milliseconds + ============= ================================================ + +seekbar + | Indicates current playback position and position of chapters + + ============= ================================================ + left-click seek to position + mouse wheel seek forward/backward + ============= ================================================ + +time left + | Shows remaining playback time timestamp + + ============= ================================================ + left-click toggle between total and remaining time + ============= ================================================ + +audio and sub + | Displays selected track and amount of available tracks + + ============= ================================================ + left-click cycle audio/sub tracks forward + right-click cycle audio/sub tracks backwards + shift+L-click show available audio/sub tracks + mouse wheel cycle audio/sub tracks forward/backwards + ============= ================================================ + +vol + ============= ================================================ + left-click toggle mute + mouse wheel volume up/down + ============= ================================================ + +fs + ============= ================================================ + left-click toggle fullscreen + ============= ================================================ + +Key Bindings +~~~~~~~~~~~~ + +These key bindings are active by default if nothing else is already bound to +these keys. In case of collision, the function needs to be bound to a +different key. See the `Script Commands`_ section. + +============= ================================================ +del Cycles visibility between never / auto (mouse-move) / always +============= ================================================ + +Configuration +------------- + +The OSC offers limited configuration through a config file +``script-opts/osc.conf`` placed in mpv's user dir and through the +``--script-opts`` command-line option. Options provided through the command-line +will override those from the config file. + +Config Syntax +~~~~~~~~~~~~~ + +The config file must exactly follow the following syntax:: + + # this is a comment + optionA=value1 + optionB=value2 + +``#`` can only be used at the beginning of a line and there may be no +spaces around the ``=`` or anywhere else. + +Command-line Syntax +~~~~~~~~~~~~~~~~~~~ + +To avoid collisions with other scripts, all options need to be prefixed with +``osc-``. + +Example:: + + --script-opts=osc-optionA=value1,osc-optionB=value2 + + +Configurable Options +~~~~~~~~~~~~~~~~~~~~ + +``layout`` + Default: bottombar + + The layout for the OSC. Currently available are: box, slimbox, + bottombar and topbar. Default pre-0.21.0 was 'box'. + +``seekbarstyle`` + Default: bar + + Sets the style of the playback position marker and overall shape + of the seekbar: ``bar``, ``diamond`` or ``knob``. + +``seekbarhandlesize`` + Default: 0.6 + + Size ratio of the seek handle if ``seekbarstyle`` is set to ``diamond`` + or ``knob``. This is relative to the full height of the seekbar. + +``seekbarkeyframes`` + Default: yes + + Controls the mode used to seek when dragging the seekbar. If set to ``yes``, + default seeking mode is used (usually keyframes, but player defaults and + heuristics can change it to exact). If set to ``no``, exact seeking on + mouse drags will be used instead. Keyframes are preferred, but exact seeks + may be useful in cases where keyframes cannot be found. Note that using + exact seeks can potentially make mouse dragging much slower. + +``seekrangestyle`` + Default: inverted + + Display seekable ranges on the seekbar. ``bar`` shows them on the full + height of the bar, ``line`` as a thick line and ``inverted`` as a thin + line that is inverted over playback position markers. ``none`` will hide + them. Additionally, ``slider`` will show a permanent handle inside the seekbar + with cached ranges marked inside. Note that these will look differently + based on the seekbarstyle option. Also, ``slider`` does not work with + ``seekbarstyle`` set to ``bar``. + +``seekrangeseparate`` + Default: yes + + Controls whether to show line-style seekable ranges on top of the + seekbar or separately if ``seekbarstyle`` is set to ``bar``. + +``seekrangealpha`` + Default: 200 + + Alpha of the seekable ranges, 0 (opaque) to 255 (fully transparent). + +``deadzonesize`` + Default: 0.5 + + Size of the deadzone. The deadzone is an area that makes the mouse act + like leaving the window. Movement there won't make the OSC show up and + it will hide immediately if the mouse enters it. The deadzone starts + at the window border opposite to the OSC and the size controls how much + of the window it will span. Values between 0.0 and 1.0, where 0 means the + OSC will always popup with mouse movement in the window, and 1 means the + OSC will only show up when the mouse hovers it. Default pre-0.21.0 was 0. + +``minmousemove`` + Default: 0 + + Minimum amount of pixels the mouse has to move between ticks to make + the OSC show up. Default pre-0.21.0 was 3. + +``showwindowed`` + Default: yes + + Enable the OSC when windowed + +``showfullscreen`` + Default: yes + + Enable the OSC when fullscreen + +``idlescreen`` + Default: yes + + Show the mpv logo and message when idle + +``scalewindowed`` + Default: 1.0 + + Scale factor of the OSC when windowed. + +``scalefullscreen`` + Default: 1.0 + + Scale factor of the OSC when fullscreen + +``scaleforcedwindow`` + Default: 2.0 + + Scale factor of the OSC when rendered on a forced (dummy) window + +``vidscale`` + Default: yes + + Scale the OSC with the video + ``no`` tries to keep the OSC size constant as much as the window size allows + +``valign`` + Default: 0.8 + + Vertical alignment, -1 (top) to 1 (bottom) + +``halign`` + Default: 0.0 + + Horizontal alignment, -1 (left) to 1 (right) + +``barmargin`` + Default: 0 + + Margin from bottom (bottombar) or top (topbar), in pixels + +``boxalpha`` + Default: 80 + + Alpha of the background box, 0 (opaque) to 255 (fully transparent) + +``hidetimeout`` + Default: 500 + + Duration in ms until the OSC hides if no mouse movement, must not be + negative + +``fadeduration`` + Default: 200 + + Duration of fade out in ms, 0 = no fade + +``title`` + Default: ${media-title} + + String that supports property expansion that will be displayed as + OSC title. + ASS tags are escaped, and newlines and trailing slashes are stripped. + +``tooltipborder`` + Default: 1 + + Size of the tooltip outline when using bottombar or topbar layouts + +``timetotal`` + Default: no + + Show total time instead of time remaining + +``remaining_playtime`` + Default: yes + + Whether the time-remaining display takes speed into account. + ``yes`` - how much playback time remains at the current speed. + ``no`` - how much video-time remains. + +``timems`` + Default: no + + Display timecodes with milliseconds + +``tcspace`` + Default: 100 (allowed: 50-200) + + Adjust space reserved for timecodes (current time and time remaining) in + the ``bottombar`` and ``topbar`` layouts. The timecode width depends on the + font, and with some fonts the spacing near the timecodes becomes too small. + Use values above 100 to increase that spacing, or below 100 to decrease it. + +``visibility`` + Default: auto (auto hide/show on mouse move) + + Also supports ``never`` and ``always`` + +``boxmaxchars`` + Default: 80 + + Max chars for the osc title at the box layout. mpv does not measure the + text width on screen and so it needs to limit it by number of chars. The + default is conservative to allow wide fonts to be used without overflow. + However, with many common fonts a bigger number can be used. YMMV. + +``boxvideo`` + Default: no + + Whether to overlay the osc over the video (``no``), or to box the video + within the areas not covered by the osc (``yes``). If this option is set, + the osc may overwrite the ``--video-margin-ratio-*`` options, even if the + user has set them. (It will not overwrite them if all of them are set to + default values.) Additionally, ``visibility`` must be set to ``always``. + Otherwise, this option does nothing. + + Currently, this is supported for the ``bottombar`` and ``topbar`` layout + only. The other layouts do not change if this option is set. Separately, + if window controls are present (see below), they will be affected + regardless of which osc layout is in use. + + The border is static and appears even if the OSC is configured to appear + only on mouse interaction. If the OSC is invisible, the border is simply + filled with the background color (black by default). + + This currently still makes the OSC overlap with subtitles (if the + ``--sub-use-margins`` option is set to ``yes``, the default). This may be + fixed later. + + This does not work correctly with video outputs like ``--vo=xv``, which + render OSD into the unscaled video. + +``windowcontrols`` + Default: auto (Show window controls if there is no window border) + + Whether to show window management controls over the video, and if so, + which side of the window to place them. This may be desirable when the + window has no decorations, either because they have been explicitly + disabled (``border=no``) or because the current platform doesn't support + them (eg: gnome-shell with wayland). + + The set of window controls is fixed, offering ``minimize``, ``maximize``, + and ``quit``. Not all platforms implement ``minimize`` and ``maximize``, + but ``quit`` will always work. + +``windowcontrols_alignment`` + Default: right + + If window controls are shown, indicates which side should they be aligned + to. + + Supports ``left`` and ``right`` which will place the controls on those + respective sides. + +``greenandgrumpy`` + Default: no + + Set to ``yes`` to reduce festivity (i.e. disable santa hat in December.) + +``livemarkers`` + Default: yes + + Update chapter markers positions on duration changes, e.g. live streams. + The updates are unoptimized - consider disabling it on very low-end systems. + +``chapters_osd``, ``playlist_osd`` + Default: yes + + Whether to display the chapters/playlist at the OSD when left-clicking the + next/previous OSC buttons, respectively. + +``chapter_fmt`` + Default: ``Chapter: %s`` + + Template for the chapter-name display when hovering the seekbar. + Use ``no`` to disable chapter display on hover. Otherwise it's a lua + ``string.format`` template and ``%s`` is replaced with the actual name. + +``unicodeminus`` + Default: no + + Use a Unicode minus sign instead of an ASCII hyphen when displaying + the remaining playback time. + + +Script Commands +~~~~~~~~~~~~~~~ + +The OSC script listens to certain script commands. These commands can bound +in ``input.conf``, or sent by other scripts. + +``osc-message`` + Show a message on screen using the OSC. First argument is the message, + second the duration in seconds. + +``osc-visibility`` + Controls visibility mode ``never`` / ``auto`` (on mouse move) / ``always`` + and also ``cycle`` to cycle between the modes + +Example + +You could put this into ``input.conf`` to hide the OSC with the ``a`` key and +to set auto mode (the default) with ``b``:: + + a script-message osc-visibility never + b script-message osc-visibility auto + +``osc-idlescreen`` + Controls the visibility of the mpv logo on idle. Valid arguments are ``yes``, + ``no``, and ``cycle`` to toggle between yes and no. + +``osc-playlist``, ``osc-chapterlist``, ``osc-tracklist`` + Shows a limited view of the respective type of list using the OSC. First + argument is duration in seconds. + |