diff options
author | Dan Oscarsson <DanOscarsson@users.noreply.github.com> | 2016-10-02 17:08:14 +0200 |
---|---|---|
committer | wm4 <wm4@nowhere> | 2016-10-03 16:57:04 +0200 |
commit | 7debdde9b91833e63b800181d8d3aaf3099bdfaa (patch) | |
tree | 94aa175e2826178afe84e5a07dddca949abea395 /DOCS | |
parent | 81d125efd8f66f560ee5e169bfd641daf64be1db (diff) | |
download | mpv-7debdde9b91833e63b800181d8d3aaf3099bdfaa.tar.bz2 mpv-7debdde9b91833e63b800181d8d3aaf3099bdfaa.tar.xz |
options: rename subtitle options
Rename the text subtitle options from --sub-text- to --sub-
and --ass- options to --sub-ass-.
The intention is to common sub options to prefixed --sub-
and special ASS option be seen as a special version of sub options.
The OSD options that work like the --sub- options are still named
--osd-.
Man page updated including a short note about renamed --sub-text-*
and --ass-* options to --sub-* and --sub-ass-*.
Diffstat (limited to 'DOCS')
-rw-r--r-- | DOCS/interface-changes.rst | 2 | ||||
-rw-r--r-- | DOCS/man/mpv.rst | 4 | ||||
-rw-r--r-- | DOCS/man/options.rst | 297 | ||||
-rw-r--r-- | DOCS/mplayer-changes.rst | 5 |
4 files changed, 200 insertions, 108 deletions
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst index 53e6ee016e..1e27edfe03 100644 --- a/DOCS/interface-changes.rst +++ b/DOCS/interface-changes.rst @@ -66,6 +66,8 @@ Interface changes - deprecate --playlist-pos option, renamed to --playlist-start - deprecate the --chapter option, as it is redundant with --start/--end, and conflicts with the semantics of the "chapter" property + - rename --sub-text-* to --sub-* and --ass-* to --sub-ass-* (old options + deprecated) - incompatible change to cdda:// protocol options: the part after cdda:// now always sets the device, not the span or speed to be played. No separating extra "/" is needed. The hidden --cdda-device options is also diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index 8b4d7c6065..f4876ac00e 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -143,11 +143,11 @@ Ctrl + and Ctrl - u Switch between applying no style overrides to SSA/ASS subtitles, and overriding them almost completely with the normal subtitle style. See - ``--ass-style-override`` for more info. + ``--sub-ass-style-override`` for more info. V Toggle subtitle VSFilter aspect compatibility mode. See - ``--ass-vsfilter-aspect-compat`` for more info. + ``--sub-ass-vsfilter-aspect-compat`` for more info. r and t Move subtitles up/down. diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index 04d178764a..acd031b624 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -1434,7 +1434,12 @@ Subtitles Changing styling and position does not work with all subtitles. Image-based subtitles (DVD, Bluray/PGS, DVB) cannot changed for fundamental reasons. Subtitles in ASS format are normally not changed intentionally, but - overriding them can be controlled with ``--ass-style-override``. + overriding them can be controlled with ``--sub-ass-style-override``. + + Previously some options working on text subtitles were called + ``--sub-text-*``, they are now named ``--sub-*``, and those specifically + for ASS have been renamed from ``--ass-*`` to ``--sub-ass-*``. + They are now all in this section. ``--sub-demuxer=<[+]name>`` Force subtitle demuxer type for ``--sub-file``. Give the demuxer name as @@ -1485,7 +1490,7 @@ Subtitles .. note:: This affects ASS subtitles as well, and may lead to incorrect subtitle - rendering. Use with care, or use ``--sub-text-font-size`` instead. + rendering. Use with care, or use ``--sub-font-size`` instead. ``--sub-scale-by-window=<yes|no>`` Whether to scale subtitles with the window size (default: yes). If this is @@ -1506,10 +1511,10 @@ Subtitles scales with the approximate window size, while the other option disables this scaling. - Affects plain text subtitles only (or ASS if ``--ass-style-override`` is + Affects plain text subtitles only (or ASS if ``--sub-ass-style-override`` is set high enough). -``--ass-scale-with-window=<yes|no>`` +``--sub-ass-scale-with-window=<yes|no>`` Like ``--sub-scale-with-window``, but affects subtitles in ASS format only. Like ``--sub-scale``, this can break ASS subtitles. @@ -1526,7 +1531,7 @@ Subtitles .. note:: This affects ASS subtitles as well, and may lead to incorrect subtitle - rendering. Use with care, or use ``--sub-text-margin-y`` instead. + rendering. Use with care, or use ``--sub-margin-y`` instead. ``--sub-speed=<0.1-10.0>`` Multiply the subtitle event timestamps with the given value. Can be used @@ -1538,19 +1543,19 @@ Subtitles `--sub-speed=25/23.976`` plays frame based subtitles which have been loaded assuming a framerate of 23.976 at 25 FPS. -``--ass-force-style=<[Style.]Param=Value[,...]>`` +``--sub-ass-force-style=<[Style.]Param=Value[,...]>`` Override some style or script info parameters. .. admonition:: Examples - - ``--ass-force-style=FontName=Arial,Default.Bold=1`` - - ``--ass-force-style=PlayResY=768`` + - ``--sub-ass-force-style=FontName=Arial,Default.Bold=1`` + - ``--sub-ass-force-style=PlayResY=768`` .. note:: Using this option may lead to incorrect subtitle rendering. -``--ass-hinting=<none|light|normal|native>`` +``--sub-ass-hinting=<none|light|normal|native>`` Set font hinting type. <type> can be: :none: no hinting (default) @@ -1565,10 +1570,10 @@ Subtitles of animations with some badly authored ASS scripts. It is recommended to not use this option, unless really needed. -``--ass-line-spacing=<value>`` +``--sub-ass-line-spacing=<value>`` Set line spacing value for SSA/ASS renderer. -``--ass-shaper=<simple|complex>`` +``--sub-ass-shaper=<simple|complex>`` Set the text layout engine used by libass. :simple: uses Fribidi only, fast, doesn't render some languages correctly @@ -1577,7 +1582,7 @@ Subtitles ``complex`` is the default. If libass hasn't been compiled against HarfBuzz, libass silently reverts to ``simple``. -``--ass-styles=<filename>`` +``--sub-ass-styles=<filename>`` Load all SSA/ASS styles found in the specified file and use them for rendering text subtitles. The syntax of the file is exactly like the ``[V4 Styles]`` / ``[V4+ Styles]`` section of SSA/ASS. @@ -1586,20 +1591,20 @@ Subtitles Using this option may lead to incorrect subtitle rendering. -``--ass-style-override=<yes|no|force|signfs|strip>`` +``--sub-ass-style-override=<yes|no|force|signfs|strip>`` Control whether user style overrides should be applied. - :yes: Apply all the ``--ass-*`` style override options. Changing the default + :yes: Apply all the ``--sub-ass-*`` style override options. Changing the default for any of these options can lead to incorrect subtitle rendering (default). :signfs: like ``yes``, but apply ``--sub-scale`` only to signs :no: Render subtitles as forced by subtitle scripts. - :force: Try to force the font style as defined by the ``--sub-text-*`` + :force: Try to force the font style as defined by the ``--sub-*`` options. Can break rendering easily. :strip: Radically strip all ASS tags and styles from the subtitle. This is equivalent to the old ``--no-ass`` / ``--no-sub-ass`` options. -``--ass-force-margins`` +``--sub-ass-force-margins`` Enables placing toptitles and subtitles in black borders when they are available, if the subtitles are in the ASS format. @@ -1608,14 +1613,14 @@ Subtitles ``--sub-use-margins`` Enables placing toptitles and subtitles in black borders when they are available, if the subtitles are in a plain text format (or ASS if - ``--ass-style-override`` is set high enough). + ``--sub-ass-style-override`` is set high enough). Default: yes. - Renamed from ``--ass-use-margins``. To place ASS subtitles in the borders - too (like the old option did), also add ``--ass-force-margins``. + Renamed from ``--sub-ass-use-margins``. To place ASS subtitles in the borders + too (like the old option did), also add ``--sub-ass-force-margins``. -``--ass-vsfilter-aspect-compat=<yes|no>`` +``--sub-ass-vsfilter-aspect-compat=<yes|no>`` Stretch SSA/ASS subtitles when playing anamorphic videos for compatibility with traditional VSFilter behavior. This switch has no effect when the video is stored with square pixels. @@ -1632,7 +1637,7 @@ Subtitles Enabled by default. -``--ass-vsfilter-blur-compat=<yes|no>`` +``--sub-ass-vsfilter-blur-compat=<yes|no>`` Scale ``\blur`` tags by video resolution instead of script resolution (enabled by default). This is bug in VSFilter, which according to some, can't be fixed anymore in the name of compatibility. @@ -1641,7 +1646,7 @@ Subtitles offset scale factor, not what the video filter chain or the video output use. -``--ass-vsfilter-color-compat=<basic|full|force-601|no>`` +``--sub-ass-vsfilter-color-compat=<basic|full|force-601|no>`` Mangle colors like (xy-)vsfilter do (default: basic). Historically, VSFilter was not color space aware. This was no problem as long as the color space used for SD video (BT.601) was used. But when everything switched to HD @@ -1663,7 +1668,7 @@ Subtitles Choosing anything other than ``no`` will make the subtitle color depend on the video color space, and it's for example in theory not possible to reuse - a subtitle script with another video file. The ``--ass-style-override`` + a subtitle script with another video file. The ``--sub-ass-style-override`` option doesn't affect how this option is interpreted. ``--stretch-dvd-subs=<yes|no>`` @@ -1696,14 +1701,14 @@ Subtitles .. note:: - This has been deprecated by ``--ass-style-override=strip``. You also + This has been deprecated by ``--sub-ass-style-override=strip``. You also may need ``--embeddedfonts=no`` to get the same behavior. Also, - using ``--ass-style-override=force`` should give better results + using ``--sub-ass-style-override=force`` should give better results without breaking subtitles too much. If ``--no-sub-ass`` is specified, all tags and style declarations are stripped and ignored on display. The subtitle renderer uses the font style - as specified by the ``--sub-text-`` options instead. + as specified by the ``--sub-`` options instead. .. note:: @@ -1854,6 +1859,132 @@ Subtitles This works for ``dvb_teletext`` subtitle streams, and if FFmpeg has been compiled with support for it. +``--sub-font=<name>`` + Specify font to use for subtitles that do not themselves + specify a particular font. The default is ``sans-serif``. + + .. admonition:: Examples + + - ``--sub-font='Bitstream Vera Sans'`` + - ``--sub-font='MS Comic Sans'`` + + .. note:: + + The ``--sub-font`` option (and many other style related ``--sub-`` + options) are ignored when ASS-subtitles are rendered, unless the + ``--no-sub-ass`` option is specified. + + This used to support fontconfig patterns. Starting with libass 0.13.0, + this stopped working. + +``--sub-font-size=<size>`` + Specify the sub font size. The unit is the size in scaled pixels at a + window height of 720. The actual pixel size is scaled with the window + height: if the window height is larger or smaller than 720, the actual size + of the text increases or decreases as well. + + Default: 55. + +``--sub-back-color=<color>`` + See ``--sub-color``. Color used for sub text background. + +``--sub-blur=<0..20.0>`` + Gaussian blur factor. 0 means no blur applied (default). + +``--sub-bold=<yes|no>`` + Format text on bold. + +``--sub-italic=<yes|no>`` + Format text on italic. + +``--sub-border-color=<color>`` + See ``--sub-color``. Color used for the sub font border. + + .. note:: + + ignored when ``--sub-back-color`` is + specified (or more exactly: when that option is not set to completely + transparent). + +``--sub-border-size=<size>`` + Size of the sub font border in scaled pixels (see ``--sub-font-size`` + for details). A value of 0 disables borders. + + Default: 3. + +``--sub-color=<color>`` + Specify the color used for unstyled text subtitles. + + The color is specified in the form ``r/g/b``, where each color component + is specified as number in the range 0.0 to 1.0. It's also possible to + specify the transparency by using ``r/g/b/a``, where the alpha value 0 + means fully transparent, and 1.0 means opaque. If the alpha component is + not given, the color is 100% opaque. + + Passing a single number to the option sets the sub to gray, and the form + ``gray/a`` lets you specify alpha additionally. + + .. admonition:: Examples + + - ``--sub-color=1.0/0.0/0.0`` set sub to opaque red + - ``--sub-color=1.0/0.0/0.0/0.75`` set sub to opaque red with 75% alpha + - ``--sub-color=0.5/0.75`` set sub to 50% gray with 75% alpha + + Alternatively, the color can be specified as a RGB hex triplet in the form + ``#RRGGBB``, where each 2-digit group expresses a color value in the + range 0 (``00``) to 255 (``FF``). For example, ``#FF0000`` is red. + This is similar to web colors. Alpha is given with ``#AARRGGBB``. + + .. admonition:: Examples + + - ``--sub-color='#FF0000'`` set sub to opaque red + - ``--sub-color='#C0808080'`` set sub to 50% gray with 75% alpha + +``--sub-margin-x=<size>`` + Left and right screen margin for the subs in scaled pixels (see + ``--sub-font-size`` for details). + + This option specifies the distance of the sub to the left, as well as at + which distance from the right border long sub text will be broken. + + Default: 25. + +``--sub-margin-y=<size>`` + Top and bottom screen margin for the subs in scaled pixels (see + ``--sub-font-size`` for details). + + This option specifies the vertical margins of unstyled text subtitles. + If you just want to raise the vertical subtitle position, use ``--sub-pos``. + + Default: 22. + +``--sub-align-x=<left|center|right>`` + Control to which corner of the screen text subtitles should be + aligned to (default: ``center``). + + Never applied to ASS subtitles, except in ``--no-sub-ass`` mode. Likewise, + this does not apply to image subtitles. + +``--sub-align-y=<top|center|bottom>`` + Vertical position (default: ``bottom``). + Details see ``--sub-align-x``. + +``--sub-shadow-color=<color> + See ``--sub-color``. Color used for sub text shadow. + +``--sub-shadow-offset=<size>`` + Displacement of the sub text shadow in scaled pixels (see + ``--sub-font-size`` for details). A value of 0 disables shadows. + + Default: 0. + +``--sub-spacing=<size>`` + Horizontal sub font spacing in scaled pixels (see ``--sub-font-size`` + for details). This value is added to the normal letter spacing. Negative + values are allowed. + + Default: 0. + Window ------ @@ -2747,29 +2878,16 @@ OSD ``--osd-duration=<time>`` Set the duration of the OSD messages in ms (default: 1000). -``--osd-font=<name>``, ``--sub-text-font=<name>`` - Specify font to use for OSD and for subtitles that do not themselves - specify a particular font. The default is ``sans-serif``. +``--osd-font=<name>`` + Specify font to use for OSD. The default is ``sans-serif``. .. admonition:: Examples - ``--osd-font='Bitstream Vera Sans'`` - ``--osd-font='MS Comic Sans'`` - .. note:: - - The ``--sub-text-font`` option (and most other ``--sub-text-`` - options) are ignored when ASS-subtitles are rendered, unless the - ``--no-sub-ass`` option is specified. - - This used to support fontconfig patterns. Starting with libass 0.13.0, - this stopped working. - -``--osd-font-size=<size>``, ``--sub-text-font-size=<size>`` - Specify the OSD/sub font size. The unit is the size in scaled pixels at a - window height of 720. The actual pixel size is scaled with the window - height: if the window height is larger or smaller than 720, the actual size - of the text increases or decreases as well. +``--osd-font-size=<size>`` + Specify the OSD font size. See ``--sub-font-size`` for details. Default: 55. @@ -2826,60 +2944,36 @@ OSD ``--osd-bar-h=<0.1-50>`` Height of the OSD bar, in percentage of the screen height (default: 3.125). -``--osd-back-color=<color>``, ``--sub-text-back-color=<color>`` - See ``--osd-color``. Color used for OSD/sub text background. +``--osd-back-color=<color>`` + See ``--osd-color``. Color used for OSD text background. -``--osd-blur=<0..20.0>``, ``--sub-text-blur=<0..20.0>`` +``--osd-blur=<0..20.0>`` Gaussian blur factor. 0 means no blur applied (default). -``--osd-bold=<yes|no>``, ``--sub-text-bold=<yes|no>`` +``--osd-bold=<yes|no>`` Format text on bold. -``--osd-italic=<yes|no>``, ``--sub-text-italic=<yes|no>`` +``--osd-italic=<yes|no>`` Format text on italic. -``--osd-border-color=<color>``, ``--sub-text-border-color=<color>`` - See ``--osd-color``. Color used for the OSD/sub font border. +``--osd-border-color=<color>`` + See ``--osd-color``. Color used for the OSD font border. .. note:: - ignored when ``--osd-back-color``/``--sub-text-back-color`` is + ignored when ``--osd-back-color`` is specified (or more exactly: when that option is not set to completely transparent). -``--osd-border-size=<size>``, ``--sub-text-border-size=<size>`` - Size of the OSD/sub font border in scaled pixels (see ``--osd-font-size`` +``--osd-border-size=<size>`` + Size of the OSD font border in scaled pixels (see ``--sub-font-size`` for details). A value of 0 disables borders. Default: 3. -``--osd-color=<color>``, ``--sub-text-color=<color>`` - Specify the color used for OSD/unstyled text subtitles. - - The color is specified in the form ``r/g/b``, where each color component - is specified as number in the range 0.0 to 1.0. It's also possible to - specify the transparency by using ``r/g/b/a``, where the alpha value 0 - means fully transparent, and 1.0 means opaque. If the alpha component is - not given, the color is 100% opaque. - - Passing a single number to the option sets the OSD to gray, and the form - ``gray/a`` lets you specify alpha additionally. - - .. admonition:: Examples - - - ``--osd-color=1.0/0.0/0.0`` set OSD to opaque red - - ``--osd-color=1.0/0.0/0.0/0.75`` set OSD to opaque red with 75% alpha - - ``--osd-color=0.5/0.75`` set OSD to 50% gray with 75% alpha - - Alternatively, the color can be specified as a RGB hex triplet in the form - ``#RRGGBB``, where each 2-digit group expresses a color value in the - range 0 (``00``) to 255 (``FF``). For example, ``#FF0000`` is red. - This is similar to web colors. Alpha is given with ``#AARRGGBB``. - - .. admonition:: Examples - - - ``--osd-color='#FF0000'`` set OSD to opaque red - - ``--osd-color='#C0808080'`` set OSD to 50% gray with 75% alpha +``--osd-color=<color>`` + Specify the color used for OSD. + See ``--sub-color`` for details. ``--osd-fractions`` Show OSD times with fractions of seconds (in millisecond precision). Useful @@ -2893,34 +2987,29 @@ OSD :2: enabled + current time visible by default :3: enabled + ``--osd-status-msg`` (current time and status by default) -``--osd-margin-x=<size>, --sub-text-margin-x=<size>`` - Left and right screen margin for the OSD/subs in scaled pixels (see - ``--osd-font-size`` for details). +``--osd-margin-x=<size>`` + Left and right screen margin for the OSD in scaled pixels (see + ``--sub-font-size`` for details). This option specifies the distance of the OSD to the left, as well as at which distance from the right border long OSD text will be broken. Default: 25. -``--osd-margin-y=<size>, --sub-text-margin-y=<size>`` - Top and bottom screen margin for the OSD/subs in scaled pixels (see - ``--osd-font-size`` for details). +``--osd-margin-y=<size>`` + Top and bottom screen margin for the OSD in scaled pixels (see + ``--sub-font-size`` for details). - This option specifies the vertical margins of the OSD. This is also used - for unstyled text subtitles. If you just want to raise the vertical - subtitle position, use ``--sub-pos``. + This option specifies the vertical margins of the OSD. Default: 22. -``--osd-align-x=<left|center|right>``, ``--sub-text-align-x=...`` - Control to which corner of the screen OSD or text subtitles should be - aligned to (default: ``center`` for subs, ``left`` for OSD). - - Never applied to ASS subtitles, except in ``--no-sub-ass`` mode. Likewise, - this does not apply to image subtitles. +``--osd-align-x=<left|center|right>`` + Control to which corner of the screen OSD should be + aligned to (default: ``left``). -``--osd-align-y=<top|center|bottom>`` ``--sub-text-align-y=...`` - Vertical position (default: ``bottom`` for subs, ``top`` for OSD). +``--osd-align-y=<top|center|bottom>`` + Vertical position (default: ``top``). Details see ``--osd-align-x``. ``--osd-scale=<factor>`` @@ -2932,17 +3021,17 @@ OSD are always in actual pixels. The effect is that changing the window size won't change the OSD font size. -``--osd-shadow-color=<color>, --sub-text-shadow-color=<color>`` - See ``--osd-color``. Color used for OSD/sub text shadow. +``--osd-shadow-color=<color>`` + See ``--sub-color``. Color used for OSD shadow. -``--osd-shadow-offset=<size>, --sub-text-shadow-offset=<size>`` - Displacement of the OSD/sub text shadow in scaled pixels (see - ``--osd-font-size`` for details). A value of 0 disables shadows. +``--osd-shadow-offset=<size>`` + Displacement of the OSD shadow in scaled pixels (see + ``--sub-font-size`` for details). A value of 0 disables shadows. Default: 0. -``--osd-spacing=<size>, --sub-text-spacing=<size>`` - Horizontal OSD/sub font spacing in scaled pixels (see ``--osd-font-size`` +``--osd-spacing=<size>`` + Horizontal OSD/sub font spacing in scaled pixels (see ``--sub-font-size`` for details). This value is added to the normal letter spacing. Negative values are allowed. diff --git a/DOCS/mplayer-changes.rst b/DOCS/mplayer-changes.rst index 6e9e5f20e3..397bb47c9e 100644 --- a/DOCS/mplayer-changes.rst +++ b/DOCS/mplayer-changes.rst @@ -262,13 +262,14 @@ Command Line Switches ``-ssf <sub>`` ``--sws-...`` ``-stop-xscreensaver`` ``--stop-screensaver`` ``-sub-fuzziness`` ``--sub-auto`` + ``-sub-text-*`` ``--sub-*`` ``-sub`` ``--sub-file`` ``-subcp`` ``--sub-codepage`` ``-subdelay`` ``--sub-delay`` ``-subfile`` ``--sub-file`` - ``-subfont-*`` ``--sub-text-*``, ``--osd-*`` + ``-subfont-*`` ``--sub-*``, ``--osd-*`` ``-subfont-text-scale`` ``--sub-scale`` - ``-subfont`` ``--sub-text-font`` + ``-subfont`` ``--sub-font`` ``-subfps`` ``--sub-fps`` ``-subpos`` ``--sub-pos`` ``-sws`` ``--sws-scaler`` |