From patchwork Sat Sep 11 06:03:13 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Soft Works X-Patchwork-Id: 30115 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6602:2a4a:0:0:0:0 with SMTP id k10csp2168961iov; Fri, 10 Sep 2021 23:06:22 -0700 (PDT) X-Google-Smtp-Source: ABdhPJxY/gLuYJKb2Vv70HxyUZJPBMn10+cXl/UVmTc1Gsqua92B9hATAZUxB25DBdVRhqZc0OIf X-Received: by 2002:a17:906:4c8c:: with SMTP id q12mr1421581eju.254.1631340382504; Fri, 10 Sep 2021 23:06:22 -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 eb20si979745ejc.641.2021.09.10.23.06.22; Fri, 10 Sep 2021 23:06:22 -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=oX8ejbVT; 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 31E2A68A818; Sat, 11 Sep 2021 09:03:18 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from NAM11-DM6-obe.outbound.protection.outlook.com (mail-dm6nam11olkn2040.outbound.protection.outlook.com [40.92.19.40]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 61D4668A64A for ; Sat, 11 Sep 2021 09:03:16 +0300 (EEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=dYIRBDK85rvox0bM4RLZXD1K6UNzIWhWplyxq7ww/a7afAMac4W6RbZVYNWbuskZaaStIDE5is6O2Vic+8xb8yHQ+YQuiwQDoiB6xEzOvQJyn58D3GXwkGjLz/JmDqdl8xne2MQSEsqblIk2fXsrTou8Z9OY8W0ulrlaNYEMYHvsAYJZh+QLENpDVcvaevTrTnW5ahH7Fm3B542KjdbERginSC0jEYeiFzuHs14Xb0sl7GQI6HsX9RVTPJeVR2iQMoF4ELzqdFWGP4L8DEZfqyD1sn8icY5rtzMghfZTP1Jo3G5rBzhkTNxQYCO+8C7nNPgUwJAd4MQXlgpZb5LF6g== 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=GMug1pvV/7WWohefrh3tsnHy2hg5tf8ZJHyOwWGCq6di96Q8lYq9AQa/F8lDaXBLKl/eKV217x6z6+u56OcaDysw0B3HlgeN/ssoEzTdvAEB63WCehl1IvhPzpmwS+cIv/UHt4Cl/lY4Iakf6dX5W2uFM32evvLtpNVyYCRp7P01LFSAp/l/NoNCnswXduvlM3QGaBBEeHgf6Q1RlQph93gq12YmapXO858ScXodjCEjFpCh8/+5cFgsi+XHyokIORjOMYWJLTvkXkCfsvaNngubgwhYfFYZwlQYEM69Bo+hsOglxfFB/kMU2VVZ00ovrlO+SJ346qCMYXDiqZUW0w== 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=oX8ejbVTYhN6hb1GRQLTwtyF5ELPVEY27NxUYDx5RZ7w2xmCVKTsQNWcYG/yZDqklMl762xpZdddD3yuEiFEi3Ki86sfow511gCz3ULV8ZvTgPl3pqbC9pG3Tv60P6z/LvvxmTd93bAnivMdfvBS+hjYTC6GVJyNfU2WyDUQsfaCmWjy673VlQZdy/PQWLMijHjkdgzbeaI62KAKqysMajBqIETjhtK974458e7Wn9I1+I2wYO29DQPb7V31/s9XGeOrVsy4IhJ292bv2HC7RXPfgZKnysofB+C4+/yq0aDiI9blYzZBFS209/UaiPSVtKwBxxFugmkHu2+3bQTRjA== Received: from MN2PR04MB5981.namprd04.prod.outlook.com (2603:10b6:208:da::10) by MN2PR04MB5776.namprd04.prod.outlook.com (2603:10b6:208:a2::15) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4500.16; Sat, 11 Sep 2021 06:03:14 +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 06:03:14 +0000 From: Soft Works To: "ffmpeg-devel@ffmpeg.org" Thread-Topic: [PATCH v3 17/18] docs/filters: Add documentation for all new subtitle filters Thread-Index: AdemxYTy5en4+uQySsWHLm5t8FNccQ== Date: Sat, 11 Sep 2021 06:03:13 +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: [PKWm+zyTNZbIOelvEWo7tIy0I954wy4xkXZA/H9UTpM=] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 1544cef7-13f0-4d34-025f-08d974e9d76d x-ms-traffictypediagnostic: MN2PR04MB5776: x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: Uv8X2W81ccEWEtfz56t2DmDqU829GLTllXtzf7wJjIYuOAAs0c38+QVaC1E8etwyTaX0h18EUZ1ZMxGqyNnVLNiC/pzEJK3/bdlFHFh6CNHX7JDnBgtn+Yu4K4VBxZaKIdD+K2JT0pqe7Jqu7AO9PErQQnCLTm3Hj8z1OxY/374EX9QxQJKc+8MaRkug4SeAeQhH58bJPCsj/ivZYIrfDsbpNmofM+zyxb4Ow+OYC/5lXDi22KFpfqC3A72oSCHZC9nce7Y4jhO7g2R9RXJ9bXcCfofvnNpKt2GdrdgNr8kWbMXZ/HCvxh67/t2axT5fSVHDK7GbQTY7bycmiWNiqGfNoSk4fqdBQLOUfjrle9juzEfsoJCLA3LyphIyfW9So7LMu7rdyrESJQfw8VllAjys2O0b76AGfs1kiV1AhayC26s3fT4SIJEFWuhbuQxRCFeMP2uCaY/FOd8PJYQhDP1TTldetDZFH8rd7MoKjb0= x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: LdSaSa1zyKUOxZ9o3D7ROmTq/ht0Omw6ComYN2bgzpvxsd5BQBcLEi1sGyhNyWPNAnpmSPR6b3sfMJop4oE4qP39xls31+3+qdkZJ7r/69dYo2xYAhqOkGTH68RdIJZroQuQGJA55d3YtQgSNOQ9MQ== 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: 1544cef7-13f0-4d34-025f-08d974e9d76d X-MS-Exchange-CrossTenant-originalarrivaltime: 11 Sep 2021 06:03:13.8913 (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: MN2PR04MB5776 Subject: [FFmpeg-devel] [PATCH v3 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: uLnlHfcGOidp 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