From patchwork Sat Sep 11 08:47:44 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Soft Works X-Patchwork-Id: 30145 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6602:2a4a:0:0:0:0 with SMTP id k10csp2252236iov; Sat, 11 Sep 2021 01:47:57 -0700 (PDT) X-Google-Smtp-Source: ABdhPJxrfM1eOBZOXKZ+y5mwoOe85dEwz1ijiBY5ZD2VEH0oNyY4KEAoF44shqZiSScuLVISVNdq X-Received: by 2002:a17:906:3798:: with SMTP id n24mr1919175ejc.116.1631350077362; Sat, 11 Sep 2021 01:47:57 -0700 (PDT) Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id h15si1363189ede.550.2021.09.11.01.47.56; Sat, 11 Sep 2021 01:47:57 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@hotmail.com header.s=selector1 header.b="PRSe/dLa"; arc=fail (body hash mismatch); spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=hotmail.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id B828868A82C; Sat, 11 Sep 2021 11:47:53 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from NAM10-BN7-obe.outbound.protection.outlook.com (mail-bn7nam10olkn2034.outbound.protection.outlook.com [40.92.40.34]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id BB62768A603 for ; Sat, 11 Sep 2021 11:47:46 +0300 (EEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=YfLIRHFH7Iutnzbv0ssL3mtebDRcCnGh5ypOJzhJD5/IFyWH9AY1Ui9ovD/oLOA/XNNPuNLVJ9xwleWx8IjshvmJFjFSFIyaIqc+VEx4vpYHwGyt377AW6x1Cz9OVDvUEh6DJM7Vjq4H3AZWe/IMgE4XDdOvloBUh0am3i+vlWM9QmrPhDPqzzy9wz8GKF0TrxaujTBYKssoIUXicsQURmMUAByjk4h6hv9sZr7GcCQTPbNBrtAar7uYlvcyQWNnTxHhvK+ih/wRNEauN93gokQJ1ejvK6lEIyDVhhl7MmECecIkKLDsNvT7tZAf8cs3kB7Y/OYk+7rgEvfaRH6ulg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=GMvaQA1bLDhc9+gg4WxqGG3PjhZiL7s8i4X/k1lEVQI=; b=T9/Hb4hBhSMUxuHossxhJ63h4ntNG3kAnrQw4POFw20b4irZKciQUvSkCtm+8fR6bdrtRd/AjZn5N7tkYoFQS0xtQc22F7+bpZv5Y1ZL9kfJg2tYj7NHPXo9lMOV7R7VaUBuJGRrNwepKxnoNbBycwGHEe6sg0fI5PvusG6uHabG3NadG4SJ7Um0NpypsUbEW/yROk9dbwsq748BoLDjWeWPKXK7R+LzyZwrgmZW2/NCFj4L4QW8VekbM+qE8Uvf0AEqYwEYmeLosAkrKHhsc73hrcbH6o1KfBKc4eCFUaKqfgSyNP/waNvNF6Axcq11E4IQYlwimHQ43g6opY580Q== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=none; dmarc=none; dkim=none; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=hotmail.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=GMvaQA1bLDhc9+gg4WxqGG3PjhZiL7s8i4X/k1lEVQI=; b=PRSe/dLaIZX6N4x4opXAdPBHVD4xqqUO4t0Ws9Cdyw9WpgbB1WsuY/6bM2hHPe/oCTjM2FQj2Se9BnxGE7BvcPH5p1p8PYmhP1TXgjE7qjHND5/HtjwOVSVYrcZgaLw0uaIc8ZeWuEuhW5zXDd8N7DJFCs2Rt7xxsOkO/sQE6+RCvdUG4m+QhN7SJJccx4YlOAWCWzQKZIOvR6wGQJk0k6kg/isyH+Z9MF5sT44RxSyyunL4Fx4LN4cIdmYhByaAt4ruEIROaNe+JhqEKRT1B7o0pngzivKMS3HSIY7suGDp9JJsgdxzOTh9Gs9jA8Mv70A/K4kej0/nYrsmhs1/aA== Received: from MN2PR04MB5981.namprd04.prod.outlook.com (2603:10b6:208:da::10) by MN2PR04MB5853.namprd04.prod.outlook.com (2603:10b6:208:a6::10) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4500.15; Sat, 11 Sep 2021 08:47:44 +0000 Received: from MN2PR04MB5981.namprd04.prod.outlook.com ([fe80::ecfe:2528:2012:22cb]) by MN2PR04MB5981.namprd04.prod.outlook.com ([fe80::ecfe:2528:2012:22cb%5]) with mapi id 15.20.4500.018; Sat, 11 Sep 2021 08:47:44 +0000 From: Soft Works To: "ffmpeg-devel@ffmpeg.org" Thread-Topic: [PATCH v4 17/18] docs/filters: Add documentation for all new subtitle filters Thread-Index: AdemxYTyUryyFADDSw2PGZBwFaMVMA== Date: Sat, 11 Sep 2021 08:47:44 +0000 Message-ID: Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-ms-exchange-messagesentrepresentingtype: 1 x-tmn: [tfD0fHaoA/2gk7RKLt4ZDKQL6j6W6MxRtGC9C3uY8VU=] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: bbc958a9-77e5-40b5-892c-08d97500d2a5 x-ms-traffictypediagnostic: MN2PR04MB5853: x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: uwbgC4N+89lvIkkC0oKllv9RAYSLoPI14x97nmxnJ0vtv8SG0yprHVSzC7pgqDiAyhQDmf8eMpblVh5ftJmnLKchqjVURNytoNZf5GMBCJxTUIieZVRvTkChOs9mp/geS9UUkrjEn/fVdQcGz/cGv2QLMI0/N3xW1yC/y91A1sXBd1+KsyzbShmbugEemk3fCzXCItXZjzqmCGdq4/8p0vqtrs/wT8OMDRDSB5jk4K8TgpwxIIsT1BQleXbbkCPAbgfQ7lQFXzxkkBryzvFlbXjDKwaBsHOhUf2Xunybhuoz32psIclnma6G8FenNTJNaT56s3wc02ourPiMGslZqZlyD2cwNR1g2gy65xPc9bl01pfOjVM05s7oWHPCUN1OKx0D1TXf9Z7Mt/weE4oXmvwoyYf+jCPI/PwdpocpfoVLrL+V3zVwXn79L/LQa4E86GAfGoB7HaKWudBXcSa7lLbLErRFZEOSRbrdWtMuhx4= x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: R9NyJd6nNlme2pnhiKbvXqgqLWupME8Ww9f3kLd5942wf/g6QgtNfHm24CS2QimCLNE1BrNg0Y2U0iA6Qo8sRcMC1wNp5rt77asDXTia7Fekgi0NMWtqUJHJLE/wMltvk+Jo71fe4qg8x67Lo0ORlQ== x-ms-exchange-transport-forked: True MIME-Version: 1.0 X-OriginatorOrg: sct-15-20-3174-20-msonline-outlook-529c7.templateTenant X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: MN2PR04MB5981.namprd04.prod.outlook.com X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-CrossTenant-Network-Message-Id: bbc958a9-77e5-40b5-892c-08d97500d2a5 X-MS-Exchange-CrossTenant-originalarrivaltime: 11 Sep 2021 08:47:44.3230 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-CrossTenant-rms-persistedconsumerorg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR04MB5853 Subject: [FFmpeg-devel] [PATCH v4 17/18] docs/filters: Add documentation for all new subtitle filters X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: W9J5fwGr3/+B Signed-off-by: softworkz --- 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 +@chapter Subtitle Filters +@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. + +@section stripstyles + +Remove all inline styles from subtitle events. + +It accepts the following parameters: + +@table @option +@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. + +@end table + +@subsection Examples + +@itemize +@item +Change all characters to upper case while keeping all styles and animations: +@example +ffmpeg -i "https://streams.videolan.org/samples/sub/SSA/subtitle_testing_complex.mkv" -filter_complex "[0:1]stripstyles" -map 0 output.mkv +@end example +@end itemize + +@section textmod + +Modify subtitle text in a number of ways. + +It accepts the following parameters: + +@table @option +@item mode +The kind of text modification to apply + +Supported operation modes are: + +@table @var +@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. +@item 1, to_upper +Change all text to upper case. Might improve readability. +@item 2, to_lower +Change all text to lower case. +@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. +@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. +@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 +@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. +@end table + +@item find +Required for replace_chars, remove_chars, replace_words and remove_words. + +@item replace +Required for replace_chars and replace_words. + +@item separator +Delimiter character for words. Used with replace_words and remove_words- Must be a single character. +The default is '.'. + +@end table + +@subsection Examples + +@itemize +@item +Change all characters to upper case while keeping all styles and animations: +@example +ffmpeg -i "https://streams.videolan.org/ffmpeg/mkv_subtitles.mkv" -filter_complex "[0:s]textmod=mode=to_upper" -map 0 -y out.mkv +@end example +@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). +@example +addroi=0:0:100:ih:+1/5 +@end example +@end itemize + +@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: + +@table @option +@item size, s +Set the size of the output video frame. + +@end table + +@subsection Examples + +@itemize +@item +Overlay PGS subtitles +(not recommended - better use overlay_graphicsubs) +@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 +@end example + +@item +Overlay PGS subtitles implicitly +The graphicsub2video is inserted automatically for compatibility with legacy command lines. +@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 +@end example +@end itemize + + +@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: + +@table @option +@item x +@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). + +@item eof_action +See @ref{framesync}. + +@item eval +Set when the expressions for @option{x}, and @option{y} are evaluated. + +It accepts the following values: +@table @samp +@item init +only evaluate expressions once during the filter initialization or +when a command is processed + +@item frame +evaluate expressions for each incoming frame +@end table + +Default value is @samp{frame}. + +@item shortest +See @ref{framesync}. + +@end table + +@subsection Examples + +@itemize +@item +Overlay PGS subtitles +@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 +@end example + +@item +Overlay PGS subtitles implicitly +The graphicsub2video is inserted automatically for compatibility with legacy command lines. +@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 +@end example +@end itemize + +@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: + +@table @option + +@item alpha +Process alpha channel, by default alpha channel is untouched. + +@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. + +@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 ",". + +@end table + +@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: + +@table @option + +@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. + +@item size, s +Set the output frame size. +Allows to override the size of output video frames. + +@item alpha +Process alpha channel, by default alpha channel is untouched. + +@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. + +@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 ",". + +@end table + +@c man end SUBTITLE FILTERS + @chapter Multimedia Filters @c man begin MULTIMEDIA FILTERS