[FFmpeg-devel] [PATCH v4 17/18] docs/filters: Add documentation for all new subtitle filters

[Soft Works]

Signed-off-by: softworkz <softworkz at hotmail.com>
---
 doc/filters.texi | 263 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 263 insertions(+)

diff --git a/doc/filters.texi b/doc/filters.texi
index 9ad6031d23..a7b80acada 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -25016,6 +25016,269 @@ tools.
 
 @c man end VIDEO SINKS
 
+ at chapter Subtitle Filters
+ at c man begin SUBTITLE FILTERS
+
+When you configure your FFmpeg build, you can disable any of the
+existing filters using @code{--disable-filters}.
+
+Below is a description of the currently available subtitle filters.
+
+ at section stripstyles
+
+Remove all inline styles from subtitle events.
+
+It accepts the following parameters:
+
+ at table @option
+ at item remove_animated
+Also remove text which is subject to animation (default: true)
+Usually, animated text elements are used used in addition to static subtitle lines for creating effects, so in most cases it is safe to remove the animation content.
+If subtitle text is missing, try setting this to false.
+
+ at end table
+
+ at subsection Examples
+
+ at itemize
+ at item
+Change all characters to upper case while keeping all styles and animations:
+ at example
+ffmpeg -i "https://streams.videolan.org/samples/sub/SSA/subtitle_testing_complex.mkv" -filter_complex "[0:1]stripstyles" -map 0 output.mkv
+ at end example
+ at end itemize
+
+ at section textmod
+
+Modify subtitle text in a number of ways.
+
+It accepts the following parameters:
+
+ at table @option
+ at item mode
+The kind of text modification to apply
+
+Supported operation modes are:
+
+ at table @var
+ at item 0, leet
+Convert subtitle text to 'leet speak'. It's primarily useful for testing as the modification will be visible with almost all text lines.
+ at item 1, to_upper
+Change all text to upper case. Might improve readability.
+ at item 2, to_lower
+Change all text to lower case.
+ at item 3, replace_chars
+Replace one or more characters. Requires the find and replace parameters to be specified. 
+Both need to be equal in length.
+The first char in find is replaced by the first char in replace, same for all subsequent chars.
+ at item 4, remove_chars
+Remove certain characters. Requires the find parameter to be specified. 
+All chars in the find parameter string will be removed from all subtitle text.
+ at item 5, replace_words
+Replace one or more words. Requires the find and replace parameters to be specified. Multiple words must be separated by the delimiter char specified vie the separator parameter (default: ','). 
+The number of words in the find and replace parameters needs to be equal.
+The first word in find is replaced by the first word in replace, same for all subsequent words
+ at item 6, remove_words
+Remove certain words. Requires the find parameter to be specified. Multiple words must be separated by the delimiter char specified vie the separator parameter (default: ','). 
+All words in the find parameter string will be removed from all subtitle text.
+ at end table
+
+ at item find
+Required for replace_chars, remove_chars, replace_words and remove_words.
+
+ at item replace
+Required for replace_chars and replace_words.
+
+ at item separator
+Delimiter character for words. Used with replace_words and remove_words- Must be a single character.
+The default is '.'.
+
+ at end table
+
+ at subsection Examples
+
+ at itemize
+ at item
+Change all characters to upper case while keeping all styles and animations:
+ at example
+ffmpeg -i "https://streams.videolan.org/ffmpeg/mkv_subtitles.mkv" -filter_complex "[0:s]textmod=mode=to_upper" -map 0 -y out.mkv
+ at end example
+ at item
+Mark the 100-pixel-wide region on the left edge of the frame as very
+uninteresting (to be encoded at much lower quality than the rest of
+the frame).
+ at example
+addroi=0:0:100:ih:+1/5
+ at end example
+ at end itemize
+
+ at section graphicsub2video
+
+Renders graphic subtitles as video frames. 
+
+This filter replaces the previous "sub2video" hack which did the conversion implicitly and up-front as subtitle filtering wasn't possible at that time.
+To retain compatibility with earlier sub2video command lines, this filter is being auto-inserted in those cases.
+
+For overlaying graphicsal subtitles it is recommended to use the 'overlay_graphicsubs' filter which is more efficient and takes less processing resources.
+
+This filter is still useful in cases where the overlay is done with hardware acceleration (e.g. overlay_qsv, overlay_vaapi, overlay_cuda) for preparing the overlay frames.
+
+It accepts the following parameters:
+
+ at table @option
+ at item size, s
+Set the size of the output video frame.
+
+ at end table
+
+ at subsection Examples
+
+ at itemize
+ at item
+Overlay PGS subtitles
+(not recommended - better use overlay_graphicsubs)
+ at example
+ffmpeg -i "https://streams.videolan.org/samples/sub/PGS/Girl_With_The_Dragon_Tattoo_2%3A23%3A56.mkv" -filter_complex "[0:1]graphicsub2video[subs];[0:0][subs]overlay" output.mp4
+ at end example
+
+ at item
+Overlay PGS subtitles implicitly 
+The graphicsub2video is inserted automatically for compatibility with legacy command lines. 
+ at example
+ffmpeg -i "https://streams.videolan.org/samples/sub/PGS/Girl_With_The_Dragon_Tattoo_2%3A23%3A56.mkv" -filter_complex "[0:0][0:1]overlay" output.mp4
+ at end example
+ at end itemize
+
+
+ at section overlay_graphicsubs
+
+Overlay graphic subtitles onto a video stream.
+
+This filter can blend graphical subtitles on a video stream directly, i.e. without creating full-size alpha images first.
+The blending operation is limited to the area of the subtitle rectangles, which also means that no processing is done at times where no subtitles are to be displayed.
+
+
+It accepts the following parameters:
+
+ at table @option
+ at item x
+ at item y
+Set the expression for the x and y coordinates of the overlaid video
+on the main video. Default value is "0" for both expressions. In case
+the expression is invalid, it is set to a huge value (meaning that the
+overlay will not be displayed within the output visible area).
+
+ at item eof_action
+See @ref{framesync}.
+
+ at item eval
+Set when the expressions for @option{x}, and @option{y} are evaluated.
+
+It accepts the following values:
+ at table @samp
+ at item init
+only evaluate expressions once during the filter initialization or
+when a command is processed
+
+ at item frame
+evaluate expressions for each incoming frame
+ at end table
+
+Default value is @samp{frame}.
+
+ at item shortest
+See @ref{framesync}.
+
+ at end table
+
+ at subsection Examples
+
+ at itemize
+ at item
+Overlay PGS subtitles
+ at example
+ffmpeg -i "https://streams.videolan.org/samples/sub/PGS/Girl_With_The_Dragon_Tattoo_2%3A23%3A56.mkv" -filter_complex "[0:1]graphicsub2video[subs];[0:0][subs]overlay" output.mp4
+ at end example
+
+ at item
+Overlay PGS subtitles implicitly 
+The graphicsub2video is inserted automatically for compatibility with legacy command lines. 
+ at example
+ffmpeg -i "https://streams.videolan.org/samples/sub/PGS/Girl_With_The_Dragon_Tattoo_2%3A23%3A56.mkv" -filter_complex "[0:0][0:1]overlay" output.mp4
+ at end example
+ at end itemize
+
+ at section overlay_textsubs
+
+Overlay text subtitles onto a video stream.
+
+This filter supersedes the classic @ref{subtitles} filter opposed to which it does no longer require to open and access the source stream separately, which is often causing problems or doesn't even work for non-local or slow sources.
+
+Inputs:
+- 0: Video [YUV420P, YUV422P, YUV444P, ARGB, RGBA, ABGR, BGRA, RGB24, BGR24]
+- 1: Subtitles [text]
+
+Outputs:
+- 0: Video (same as input)
+
+It accepts the following parameters:
+
+ at table @option
+
+ at item alpha
+Process alpha channel, by default alpha channel is untouched.
+
+ at item fonts_dir
+Set a directory path containing fonts that can be used by the filter.
+These fonts will be used in addition to whatever the font provider uses.
+
+ at item force_style
+Override default style or script info parameters of the subtitles. It accepts a
+string containing ASS style format @code{KEY=VALUE} couples separated by ",".
+
+ at end table
+
+ at section textsub2video
+
+Converts text subtitles to video frames.
+
+For overlaying text subtitles onto video frames it is recommended to use the overlay_textsubs filter.
+The textsub2video is useful for for creating transparent text-frames when overlay is done via hw acceleration 
+
+Inputs:
+- 0: Subtitles [text]
+
+Outputs:
+- 0: Video [ARGB, RGBA, ABGR, BGRA]
+
+It accepts the following parameters:
+
+ at table @option
+
+ at item rate, r
+Set the framerate for updating overlay frames.
+Normally, overlay frames will only be updated each time when the subtitles to display are changing.
+In cases where subtitles include advanced features (like animation), this parameter determines the frequency by which the overlay frames should be updated.
+
+ at item size, s
+Set the output frame size.
+Allows to override the size of output video frames.
+
+ at item alpha
+Process alpha channel, by default alpha channel is untouched.
+
+ at item fonts_dir
+Set a directory path containing fonts that can be used by the filter.
+These fonts will be used in addition to whatever the font provider uses.
+
+ at item force_style
+Override default style or script info parameters of the subtitles. It accepts a
+string containing ASS style format @code{KEY=VALUE} couples separated by ",".
+
+ at end table
+
+ at c man end SUBTITLE FILTERS
+
 @chapter Multimedia Filters
 @c man begin MULTIMEDIA FILTERS
 
-- 
2.30.2.windows.1