From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id 61F6B4373E for ; Mon, 27 Mar 2023 00:08:53 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 601BE68C6A0; Mon, 27 Mar 2023 03:08:51 +0300 (EEST) Received: from mail-ed1-f42.google.com (mail-ed1-f42.google.com [209.85.208.42]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id B690F68C473 for ; Mon, 27 Mar 2023 03:08:44 +0300 (EEST) Received: by mail-ed1-f42.google.com with SMTP id r11so29131615edd.5 for ; Sun, 26 Mar 2023 17:08:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; t=1679875723; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=ZsOkhkYgPlHv1P7XRIS8bt/WsmziOxClkx0QoA7F/H0=; b=m1xx45Xeux28ck12fY/eIVH3+VOMDgoFbNWXCzDzCI4B44qCONBs3c+ivDM9mUZEES 5IX0i08RKcHGikIxuuTVsvZDaUGOJwJC7MF0ZmiPn7rkbyVo0mrhRBKuVoanwfPdtJpl wJbPYtMIqRZCKBdg7j9VuEvVyoFdvZCZpi9gCiToPiwXTsGdzL30fIIZIgIQkqtWUsZo 3Rx2sNy3GF1Ur2Q4DeWTwWpDN50bUmEQJXLELH00F3qVz2y+EwQ8m/CMJhVzoDREnBli nPTF+0DTLf31eEH8jbiGvctXcIWA4Dil9Mv36slQGOygWM/zQ5FPat9yncO8+Lj2SJo1 tdrg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1679875723; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=ZsOkhkYgPlHv1P7XRIS8bt/WsmziOxClkx0QoA7F/H0=; b=lkatAeiX3Lh7qrrmoOojFXrEH7swfNFE+wGBCHT0yqCn+AWih0aqrHBRSn0xz/hUca 5AcE0xVAA9tKwgMeBdKI56bB571OVEOKtTjD94wIyOCAtbAVsmtui1kGXvXgtt6ZkAb0 8QnGcdR4MYtDpWcHxOfvuNggBTvZ2TpXh/WcdufWQJigAVXEJOff0ykprBsCSIn17Zwg CkL4COK2vayh5UKsHnjhUBK+lVIjE+riXhrBm1JT4V9bXck/5axkeLlT1EIzD08g+G3V NYaN/ucxW4UzT1yDMIcO7iBa6V51XO3PJF03uEFQgf5ZcyroYVweyiifAS95sQsc0fpY 62BQ== X-Gm-Message-State: AAQBX9fjnXHPMh7wzkbup3AQDEi3HvLV5KXFclRTpTLZZZo7gaOoFJS1 yK81UK/FfFZhyONSCdbDUKs4gQazJqs= X-Google-Smtp-Source: AKy350adOQLdmr1FUDpj4r5Fh58umI306XxHbX6k69SegD97qdBp2p+WJ/1hPuxxf0iBzGHxbG6u8Q== X-Received: by 2002:a17:906:1c19:b0:92b:f118:ef32 with SMTP id k25-20020a1709061c1900b0092bf118ef32mr10369356ejg.48.1679875723166; Sun, 26 Mar 2023 17:08:43 -0700 (PDT) Received: from mariano (dynamic-adsl-62-10-98-143.clienti.tiscali.it. [62.10.98.143]) by smtp.gmail.com with ESMTPSA id jz15-20020a17090775ef00b009334edaed98sm11187275ejc.50.2023.03.26.17.08.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 26 Mar 2023 17:08:42 -0700 (PDT) Received: by mariano (Postfix, from userid 1000) id A26A4BFB73; Mon, 27 Mar 2023 02:08:41 +0200 (CEST) From: Stefano Sabatini To: FFmpeg development discussions and patches Date: Mon, 27 Mar 2023 02:08:41 +0200 Message-Id: <20230327000841.94338-1-stefasab@gmail.com> X-Mailer: git-send-email 2.25.1 MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH] doc/filters: extend section about command, warn about undesirable behaviors 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 Cc: Stefano Sabatini Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: Extend documentation about commands, and add a note to warn users in case of commands which might fail in special cases, based on a report by Michael Koch. Fix trac issue: http://trac.ffmpeg.org/ticket/8987 --- doc/filters.texi | 45 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 40 insertions(+), 5 deletions(-) diff --git a/doc/filters.texi b/doc/filters.texi index 4449998ba4..3db7280bb5 100644 --- a/doc/filters.texi +++ b/doc/filters.texi @@ -327,11 +327,41 @@ See @code{ffmpeg -filters} to view which filters have timeline support. @anchor{commands} @chapter Changing options at runtime with a command -Some options can be changed during the operation of the filter using -a command. These options are marked 'T' on the output of -@command{ffmpeg} @option{-h filter=}. -The name of the command is the name of the option and the argument is -the new value. +Some filters accepts interactive commands which can be sent to filters to +interactively change their behavior . + +When a filter supports commands, it is possible to send a command to the filter, +either programmatically through the @code{avfilter_process_command()} function +defined in @file{avfilter.h}, or through dedicated filters such as @ref{sendcmd} +or @ref{zmq}. + +A command can be sent to a filtergraph by specifying the following parameters: +@table @option + +@item target +a filter target, is specified as the unique filter name in the filterchain, or +as the filter class name followed by "@@@var{id}", where @var{id} is the unique +filter identifier assigned to the filter in the filtergraph specification + +@item command +the name of the command defined in the filter + +@item arg +an optional argument specifying the option to set through the command +@end table + +Commands are shown as options and marked with the @code{T} flag on the output of +@command{ffmpeg} @option{-h filter=}. The name of the +corresponding option is the name of the command and the argument is the value +set through the command. + +Keep in mind that some commands might change some filters configuration causing +unexpected behavior. For example, it is possible to send the @command{width} +command to the @ref{scale} filter for changing the size of a video stream. But +changing the size mid-stream is not supported by many other filters (for example +@ref{eq}, @ref{colorkey} and @ref{despill}). In some cases it works (for example +the output of @ref{scale} can be used as the second input of @ref{overlay}), but +in most other cases it would fail. @anchor{framesync} @chapter Options for filters with several inputs (framesync) @@ -9503,6 +9533,7 @@ Allowed range is from 0.0 to 1.0. This filter supports the all above options as @ref{commands}. +@anchor{colorkey} @section colorkey RGB colorspace color keying. This filter operates on 8-bit RGB format frames by setting the alpha component of each pixel @@ -11421,6 +11452,7 @@ specified file. @end table +@anchor{despill} @section despill Remove unwanted contamination of foreground colors, caused by reflected color of @@ -12704,6 +12736,7 @@ Set the scaling dimension: @code{2} for @code{2xEPX}, @code{3} for Default is @code{3}. @end table +@anchor{eq} @section eq Set brightness, contrast, saturation and approximate gamma adjustment. @@ -29016,6 +29049,7 @@ ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=co @end example @end itemize +@anchor{sendcmd} @section sendcmd, asendcmd Send commands to filters in the filtergraph. @@ -30762,6 +30796,7 @@ ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT @end example @end itemize +@anchor{zmq} @section zmq, azmq Receive commands sent through a libzmq client, and forward them to -- 2.25.1 _______________________________________________ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org https://ffmpeg.org/mailman/listinfo/ffmpeg-devel To unsubscribe, visit link above, or email ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".