From patchwork Mon Mar 27 00:08:41 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefano Sabatini X-Patchwork-Id: 40852 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:7a30:b0:df:834d:2c1a with SMTP id t48csp924454pzh; Sun, 26 Mar 2023 17:08:56 -0700 (PDT) X-Google-Smtp-Source: AKy350ZkAlFqM8c7xP+ItAND9n46DeWDy7VylWXG+SPDrzk93WOE5+ubyjVvDfs/T6CnWYJD6ZLQ X-Received: by 2002:a05:6402:45:b0:4ea:a9b0:a511 with SMTP id f5-20020a056402004500b004eaa9b0a511mr10257146edu.37.1679875736105; Sun, 26 Mar 2023 17:08:56 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1679875736; cv=none; d=google.com; s=arc-20160816; b=PJ7ocpElzds8Ay35t/QYlJv8HRnVRPiXjkvCluxxJkdxnqtdm/IUfOMEF4bOTexkbA hw7JCf3KkEGL73GqxaZu75vf2jNlASKNYw1X0YHFI1SvGWLofG2M/0PHcMzkH01teoPo qCL8qIALAp08Pz/kavsh3E1KexNxk+3xmf+MaUykrUBiVVRT3e1lHc6C1RiVNl1ivDEL fkpYUY0PLSBeOS15vZS+3DkbdEGeChGioCfhb/rprMeyeejsEr27lTPb6J4szWVpJG9H 08OE+nNjYmlCedZm1U207YNcwBEhLT5Ggi3+5iLrxDVUPb/OlnWbjWoK1cEtvKlQKd3Y 67cA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:mime-version:message-id:date:to:from :dkim-signature:delivered-to; bh=pchoZfho0ID885p92h8qYu5mCjk52mRYqWEO5/Ik75E=; b=cHAa+L8dqjamVRRdMqbaHXjDiUUSq9f4o7yTixKEO3++CMQImQeC2p/KDOr2eXqqRi eR+Za4sGnloaRnAr87Yno7dhCl/EmODhYODFyMGanFeAp7tbWFoRfg45FAUNW53atC2u UkgiyfD9+pS4bB+cu/8LFTzkIivCEUld9i54NNQklqk5P7flieJBQGD4G1AnJTStEajU +y8B8OD2c97LZokBw4nehjKP6Zof4wjVyUON3iSAW3N8w9pK7DBtNVl1+7TT+qWo1ODJ p+JF1N+1Vl1ySoxZ8+NOTJZJa4A003ln4RSLZUhi6q6FLrqL+kARNM+pY2+Iu+06dEoq aKeA== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20210112 header.b=m1xx45Xe; 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=QUARANTINE dis=NONE) header.from=gmail.com Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id u2-20020aa7d882000000b004acef3d53b7si26825225edq.269.2023.03.26.17.08.55; Sun, 26 Mar 2023 17:08:56 -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=@gmail.com header.s=20210112 header.b=m1xx45Xe; 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=QUARANTINE dis=NONE) header.from=gmail.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id A18C368C6A1; Mon, 27 Mar 2023 03:08:51 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org 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-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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: Wh/Imu0nLoos 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