diff options
Diffstat (limited to 'DOCS/man')
-rw-r--r-- | DOCS/man/en/changes.rst | 53 | ||||
-rw-r--r-- | DOCS/man/en/input.rst | 308 | ||||
-rw-r--r-- | DOCS/man/en/mpv.rst | 2 | ||||
-rw-r--r-- | DOCS/man/en/options.rst | 72 | ||||
-rw-r--r-- | DOCS/man/en/vo.rst | 2 |
5 files changed, 404 insertions, 33 deletions
diff --git a/DOCS/man/en/changes.rst b/DOCS/man/en/changes.rst index 5b1c3ea4a6..402bdbd336 100644 --- a/DOCS/man/en/changes.rst +++ b/DOCS/man/en/changes.rst @@ -84,7 +84,7 @@ Command line switches ``-no-opt``, or better ``--no-opt``. * Per-file options are not the default anymore. You can explicitly specify file local options. See ``Usage`` section. -* Table of renamed switches: +* Table of renamed/replaced switches: =================================== =================================== Old New @@ -92,20 +92,53 @@ Command line switches -nosound --no-audio -use-filename-title --title="${filename}" -loop 0 --loop=inf + -hardframedrop --framedrop=hard + -osdlevel --osd-level + -delay --audio-delay + -subdelay --sub-delay + -subpos --sub-pos + -forcedsubsonly --sub-forced-only =================================== =================================== input.conf and slave commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Table of renamed slave commands: - - =================================== =================================== - Old New - =================================== =================================== - pt_step 1 b playlist_next b - pt_step -1 b playlist_prev b - pt_clear playlist_clear - =================================== =================================== +* Table of renamed input commands: + + This lists only commands that are not always gracefully handled by the + internal legacy translation layer. If an input.conf contains any legacy + commands, they will be displayed with ``-v`` when it is loaded, and show + and the replacement commands. + + Properties containing ``_`` to separate words use ``-`` instead. + + +--------------------------------+----------------------------------------+ + | Old | New | + +================================+========================================+ + | pt_step 1 [0|1] | playlist_next [weak|force] | + | | (translation layer can't deal with | + | | whitespace) | + +--------------------------------+----------------------------------------+ + | pt_step -1 [0|1] | playlist_prev [weak|force] (same) | + +--------------------------------+----------------------------------------+ + | switch_ratio [<ratio>] | set aspect <ratio> | + | | set aspect 0 (to reset aspect) | + +--------------------------------+----------------------------------------+ + | step_property_osd <prop> <step>| cycle <prop> <step> (wraps), | + | <dir> | add <prop> <step> (clamps). | + | | <dir> parameter unsupported. Use | + | | a negative step instead. | + +--------------------------------+----------------------------------------+ + | step_property <prop> <step> | Prefix cycle or add with no-osd: | + | <dur> | no-osd cycle <prop> <step> | + +--------------------------------+----------------------------------------+ + | osd_show_property_text <text> | show_text <text> | + | | The property expansion format string | + | | syntax slightly changed. | + +--------------------------------+----------------------------------------+ + | osd_show_text | Now does the same as | + | | osd_show_property_text. | + +--------------------------------+----------------------------------------+ Other ~~~~~ diff --git a/DOCS/man/en/input.rst b/DOCS/man/en/input.rst new file mode 100644 index 0000000000..58565f0267 --- /dev/null +++ b/DOCS/man/en/input.rst @@ -0,0 +1,308 @@ +.. _input: + +INPUT.CONF +========== + +The input.conf file consists of a list of key bindings, for example: + +| s screenshot # take a screenshot with the s key + +Each line maps a key to an input command. Keys are specified with their literal +value (upper case if combined with ``Shift``), or a name for special keys. For +example, ``a`` maps to the ``a`` key without shift, and ``A`` maps to ``a`` +with shift. + +A list of special keys can be obtained with + +| **mplayer** --input=keylist + +In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``: + +| ctrl+q quit + +General input command syntax +---------------------------- + +`[Shift+][Ctrl+][Alt+][Meta+]<key> [<prefix>] <command> (<argument>)*` + +Newlines always start a new binding. ``#`` starts a comment (outside of quoted +string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used. + +<key> is either the literal character the key produces (ASCII or unicode +character), or a symbol name. + +Arguments are separated by whitespace. This applies even to string arguments. +For this reason, string arguments should be quoted with ``"``. Inside quotes, +C style escaping can be used. + +Optional arguments can be skipped with ``-``. + +List of input commands +---------------------- + +ignore + Use this to "block" keys that should be unbound, and do nothing. Useful for + disabling default bindings, without disabling all bindings with + ``--input=default-bindings=no``. + +seek <seconds> [relative|absolute|absolute-percent] [default-precise|exact|keyframes] + Change the playback position. By default, seeks by a relative amount of + seconds. + + The second argument sets the seek mode: + + relative (default) + Seek relative to current position (a negative value seeks backwards). + absolute + Seek to a given time. + absolute-percent + Seek to agiven percent position. + + The third argument defines how exact the seek is: + + default-precise (default) + Follow the default behavior as set by ``--hr-seek``, which by default + does imprecise seeks (like ``keyframes``). + exact + Always do exact/hr/precise seeks (slow). + keyframes + Always restart playback at keyframe boundaries (fast). + +frame_step + Basically seek forward by one frame. Actually this plays one frame, then + pauses again. + +set <property> "<value>" + Set the given property to the given value. + +add <property> [<value>] + Add the given value to the property. On overflow or underflow, clamp the + property to the maximum. If <value> is omitted, assume ``1``. + +cycle <property> [up|down] + Cycle the given property. ``up`` and ``down`` set the cycle direction. On + overflow, set the property back to the minimum, on underflow set it to the + maximum. If ``up`` or ``down`` is omitted, assume ``up``. + +speed_mult <value> + Multiply the ``speed`` property by the given value. + +screenshot [single|each-frame] [video|window] + Take a screenshot. + + First argument: + + <single> (default) + Take a single screenshot. + <each-frame> + Take a screenshot each frame. Issue this command again to stop taking + screenshots. + + Second argument: + + <video> (default) + Save the video image, in its original resolution. Typically without + OSD or subtitles, but the exact behavior depends on the selected video + output. + <window> + Save the contents of the mplayer window. Typically scaled, with OSD and + subtitles. The exact behavior depends on the selected video output, and + if not support is available, this will act like ``video``. + +playlist_next [weak|force] + Go to the next entry on the playlist. + + weak (default) + If the last file on the playlist is currently played, do nothing. + force + Terminate playback if there are no more files on the playlist. + +playlist_prev [weak|force] + Go to the previous entry on the playlist. + + weak (default) + If the first file on the playlist is currently played, do nothing. + force + Terminate playback if the first file is being played. + +loadfile "<file>" [replace|append] + Load the given file and play it. + + Second argument: + + <replace> (default) + Stop playback of the current file, and play the new file immediately. + <append> + Append the file to the playlist. + +loadlist "<playlist>" [replace|append] + Load the given playlist file (like ``--playlist``). + +playlist_clear + Clear the playlist, except the currently played file. + +run "<command>" + Run the given command with ``/bin/sh -c``. The string is expanded like in + ``--playing-msg`` before + +quit [<code>] + Exit the player using the given exit code. + +sub_load "<file>" + Load the given subtitle file. It's not selected as current subtitle after + loading. + +sub_step <skip> + Change subtitle timing such, that the subtitle event after the next <skip> + subtitle events is displayed. <skip> can be negative to step back. + +osd [<level>] + Toggle OSD level. If <level> is specified, set the OSD mode + (see ``--osd-level`` for valid values). + +print_text "<string>" + Print text to stdout. The string can contain properties, which are expanded + like in ``--playing-msg``. + +show_text "<string>" [<duration>] [<level>] + Show text on the OSD. The string can contain properties, which are expanded + like in ``--playing-msg``. This can be used to show playback time, filename, + and so on. + + <duration> is the time in ms to show the message. By default, it uses the + same value as ``--osd-duration``. + + <level> is the minimum OSD level to show the text (see ``--osd-level``). + +show_progress + Show the progress bar, the elapsed time and the total duration of the file + on the OSD. + +show_chapters + Show a list of chapters on the OSD. + +show_tracks + Show a list of video/audio/subtitle tracks on the OSD. + + + +Undocumented properties: tv_start_scan, tv_step_channel, tv_step_norm, +tv_step_chanlist, tv_set_channel, tv_last_channel, tv_set_freq, tv_step_freq, +tv_set_norm, dvb_set_channel, radio_step_channel, radio_set_channel, +radio_set_freq, radio_step_freq (all of these should be replaced by properties), +edl_mark, stop (questionable use), get_property (?), af_switch, af_add, af_del, +af_clr, af_cmdline, vo_cmdline (experimental). + +Input command prefixes +---------------------- + +osd-auto (default) + Use the default behavior for this command. +no-osd + Do not use any OSD for this command. +osd-bar + If possible, show a bar with this command. Seek commands will show the + progress bar, property changing commands may show the newly set value. +osd-msg + If possible, show an OSD message with this command. The seek command shows + the current playback time (like ``show_progress``), property changing + commands show the newly set value as text. +osd-msg-bar + Combine osd-bar and osd-msg. + + + +All of these are still overridden by the global ``--osd-level`` settings. + +Undocumented prefixes: pausing, pausing_keep, pausing_toggle, +pausing_keep_force. (Should these be made official?) + +Properties +---------- + +Properties are used to set mplayer options during runtime, or to query arbitrary +information. They can be manipulated with the ``set``/``add``/``cycle`` +commands, and retrieved with ``show_text``, or anything else that uses property +expansion. (See ``--playing-msg`` how properties are expanded.) + +``W`` indicates whether the property is generally writeable. If an option +is referenced, the property should take/return exactly the same values as the +option. + +=========================== = ================================================== +Name W Comment +=========================== = ================================================== +osd-level x see ``--osd-level`` +loop x see ``--loop`` +speed x see ``--speed`` +filename currently played file (path stripped) +path currently played file (full path) +demuxer +stream-pos x byte position in source stream +stream-start start byte offset in source stream +stream-end end position in bytes in source stream +stream-length length in bytes (${stream-end} - ${stream-start}) +stream-time-pos x time position in source stream (also see time-pos) +length length of the current file in seconds +percent-pos x position in current file (0-100) +time-pos x position in current file in seconds +chapter x current chapter number +edition x current MKV edition number +titles number of DVD titles +chapters number of chapters +editions number of MKV editions +angle current DVD angle +metadata metadata key/value pairs +metadata/<key> value of metedata entry <key> +pause x pause status (bool) +pts-association-mode x see ``--pts-association-mode`` +hr-seek x see ``--hr-seek`` +volume x current volume (0-100) +mute x current mute status (bool) +audio-delay x see ``--audio-delay`` +audio-format audio format (codec tag) +audio-codec audio codec selected for decoding +audio-bitrate audio bitrate +samplerate audio samplerate +channels number of audio channels +audio x current audio track (similar to ``--aid``) +balance x audio channel balance +fullscreen x see ``--fullscreen`` +deinterlace x deinterlacing, if available (bool) +colormatrix x see ``--colormatrix`` +colormatrix-input-range x see ``--colormatrix-input-range`` +colormatrix-output-range x see ``--colormatrix-output-range`` +ontop x see ``--ontop`` +rootwin x see ``--rootwin`` +border x see ``--border`` +framedrop x see ``--framedrop`` +gamma x see ``--gamma`` +brightness x see ``--brightness`` +contrast x see ``--contrast`` +saturation x see ``--saturation`` +hue x see ``--hue`` +panscan x see ``--panscan`` +vsync x see ``--vsync`` +video-format video format (integer FourCC) +video-codec video codec selected for decoding +video-bitrate video bitrate +width video width +height video height +fps FPS (may contain bogus values) +aspect x video aspect +video x current video track (similar to ``--vid``) +program x switch TS program (write-only) +sub x current subttitle track (similar to ``--sid``) +sub-delay x see ``--sub-delay`` +sub-pos x see ``--sub-pos`` +sub-visibility x whether current subtitle is rendered +sub-forced-only x see ``--sub-forced-only`` +sub-scale x subtitle font size multiplicator +ass-use-margins x see ``--ass-use-margins`` +ass-vsfilter-aspect-compat x see ``--ass-vsfilter-aspect-compat`` +ass-style-override x see ``--ass-style-override`` +tv-brightness +tv-contrast +tv-saturation +tv-hue +=========================== = ================================================== diff --git a/DOCS/man/en/mpv.rst b/DOCS/man/en/mpv.rst index 2cca30c383..6de386fdf9 100644 --- a/DOCS/man/en/mpv.rst +++ b/DOCS/man/en/mpv.rst @@ -409,6 +409,8 @@ OPTIONS .. include:: encode.rst +.. include:: input.rst + Taking screenshots ================== diff --git a/DOCS/man/en/options.rst b/DOCS/man/en/options.rst index dbac793fa9..c825cd58d6 100644 --- a/DOCS/man/en/options.rst +++ b/DOCS/man/en/options.rst @@ -176,6 +176,14 @@ rendering text subtitles. The syntax of the file is exactly like the ``[V4 Styles]`` / ``[V4+ Styles]`` section of SSA/ASS. +--ass-style-override=<yes|no> + Control whether user style overrides should be applied. + + :yes: Apply all the ``--ass-*`` style override options. Changing the default + for any of these options can lead to incorrect subtitle rendering. + (Default.) + :no: Render subtitles as forced by subtitle scripts. + --ass-top-margin=<value> Adds a black band at the top of the frame. The SSA/ASS renderer can place toptitles there (with ``--ass-use-margins``). @@ -472,7 +480,7 @@ will stay hidden. Supported by video output drivers which use X11 or OS X Cocoa. ---delay=<sec> +--audio-delay=<sec> audio delay in seconds (positive or negative float value). Negative values delay the audio, and positive values delay the video. @@ -624,7 +632,7 @@ there is a change in video parameters, video stream or file. This used to be the default behavior. Currently only affects X11 VOs. ---forcedsubsonly +--sub-forced-only Display only forced subtitles for the DVD subtitle stream selected by e.g. ``--slang``. @@ -643,11 +651,14 @@ --fps=<float> Override video framerate. Useful if the original value is wrong or missing. ---framedrop +--framedrop=<no|yes|hard> Skip displaying some frames to maintain A/V sync on slow systems. Video filters are not applied to such frames. For B-frames even decoding is - skipped completely. May produce unwatchably choppy output. See also - ``--hardframedrop``. + skipped completely. May produce unwatchably choppy output. With ``hard``, + decoding and output of any frame can be skipped, and will lead to an even + worse playback experience. + + Practical use of this feature is questionable. Disabled by default. --frames=<number> Play/convert only first <number> frames, then quit. @@ -656,6 +667,7 @@ Specifies the character set that will be passed to FriBiDi when decoding non-UTF-8 subtitles (default: ISO8859-8). +--fullscreen --fs Fullscreen playback (centers movie, and paints black bands around it). @@ -753,9 +765,6 @@ ``--no-grabpointer`` tells the player to not grab the mouse pointer after a video mode change (``--vm``). Useful for multihead setups. ---hardframedrop - More intense frame dropping (breaks decoding). Leads to image distortion! - --heartbeat-cmd Command that is executed every 30 seconds during playback via *system()* - i.e. using the shell. @@ -1294,7 +1303,7 @@ --osd-fractions Show OSD times with fractions of seconds. ---osdlevel=<0-3> +--osd-level=<0-3> Specifies which mode the OSD should start in. :0: subtitles only @@ -1312,9 +1321,6 @@ controls how much of the image is cropped. May not work with all video output drivers. - *NOTE*: Values between -1 and 0 are allowed as well, but highly - experimental and may crash or worse. Use at your own risk! - --panscanrange=<-19.0-99.0> (experimental) Change the range of the pan-and-scan functionality (default: 1). Positive @@ -1328,15 +1334,37 @@ See also ``--user``. --playing-msg=<string> - Print out a string before starting playback. The following expansions are - supported: + Print out a string before starting playback. The string is expanded for + properties, e.g. ``--playing-msg=file: ${filename}`` will print the string + ``file: `` followed by the currently played filename. + + The following expansions are supported: ${NAME} - Expand to the value of the property ``NAME``. - ?(NAME:TEXT) - Expand ``TEXT`` only if the property ``NAME`` is available. - ?(!NAME:TEXT) - Expand ``TEXT`` only if the property ``NAME`` is not available. + Expands to the value of the property ``NAME``. If ``NAME`` starts with + ``=``, use the raw value of the property. If retrieving the property + fails, expand to an error string. (Use ``${NAME:}`` with a trailing + ``:`` to expand to an empty string instead.) + ${NAME:STR} + Expands to the value of the property ``NAME``, or ``STR`` if the + property can't be retrieved. ``STR`` is expanded recursively. + ${!NAME:STR} + Expands to ``STR`` (recursively) if the property ``NAME`` can't be + retrieved. + ${?NAME:STR} + Expands to ``STR`` (recursively) if the property ``NAME`` is available. + $$ + Expands to ``$``. + $} + Expands to ``}``. (To produce this character inside rexursive + expansion.) + $> + Disable property expansion and special handling of ``$`` for the rest + of the string. + +--status-msg=<string> + Print out a custom string during playback instead of the standard status + line. Expands properties. See ``--playing-msg``. --playlist=<filename> Play files according to a playlist file (ASX, Winamp, SMIL, or @@ -1892,7 +1920,7 @@ - ``--subcp=enca:pl:cp1250`` guess the encoding for Polish, fall back on cp1250. ---subdelay=<sec> +--sub-delay=<sec> Delays subtitles by <sec> seconds. Can be negative. --subfile=<filename> @@ -1939,7 +1967,7 @@ *NOTE*: <rate> > movie fps speeds the subtitles up for frame-based subtitle files and slows them down for time-based ones. ---subpos=<0-100> +--sub-pos=<0-100> Specify the position of subtitles on the screen. The value is the vertical position of the subtitle in % of the screen height. Can be useful with ``--vf=expand``. @@ -1980,7 +2008,7 @@ the line used for the OSD and clear it (default: ``^[[A\r^[[K``). --title - Set the window title. The string can contain property names. + Set the window title. Properties are expanded (see ``--playing-msg``). --tv=<option1:option2:...> This option tunes various properties of the TV capture module. For diff --git a/DOCS/man/en/vo.rst b/DOCS/man/en/vo.rst index dd5b0f72ef..f7346a55f5 100644 --- a/DOCS/man/en/vo.rst +++ b/DOCS/man/en/vo.rst @@ -635,7 +635,7 @@ opengl-old (no-)osd Enable or disable support for OSD rendering via OpenGL (default: enabled). This option is for testing; to disable the OSD use - ``--osdlevel=0`` instead. + ``--osd-level=0`` instead. sw Continue even if a software renderer is detected. |