From 7debdde9b91833e63b800181d8d3aaf3099bdfaa Mon Sep 17 00:00:00 2001 From: Dan Oscarsson Date: Sun, 2 Oct 2016 17:08:14 +0200 Subject: 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-*. --- DOCS/interface-changes.rst | 2 + DOCS/man/mpv.rst | 4 +- DOCS/man/options.rst | 297 +++++++++++++++++++++++++++++---------------- DOCS/mplayer-changes.rst | 5 +- options/options.c | 51 ++++++-- options/options.h | 2 +- sub/sd_ass.c | 8 +- 7 files changed, 244 insertions(+), 125 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=`` 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=`` +``--sub-ass-scale-with-window=`` 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=`` +``--sub-ass-hinting=`` Set font hinting 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=`` +``--sub-ass-line-spacing=`` Set line spacing value for SSA/ASS renderer. -``--ass-shaper=`` +``--sub-ass-shaper=`` 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=`` +``--sub-ass-styles=`` 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=`` +``--sub-ass-style-override=`` 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=`` +``--sub-ass-vsfilter-aspect-compat=`` 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=`` +``--sub-ass-vsfilter-blur-compat=`` 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=`` +``--sub-ass-vsfilter-color-compat=`` 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=`` @@ -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=`` + 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=`` + 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=`` + 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=`` + Format text on bold. + +``--sub-italic=`` + Format text on italic. + +``--sub-border-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 of the sub font border in scaled pixels (see ``--sub-font-size`` + for details). A value of 0 disables borders. + + Default: 3. + +``--sub-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=`` + 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=`` + 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=`` + 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=`` + Vertical position (default: ``bottom``). + Details see ``--sub-align-x``. + +``--sub-shadow-color= + See ``--sub-color``. Color used for sub text shadow. + +``--sub-shadow-offset=`` + 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=`` + 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=