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 71EC945C44 for ; Tue, 28 Mar 2023 23:21:53 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 421CF68CD3B; Wed, 29 Mar 2023 02:21:50 +0300 (EEST) Received: from mail-ed1-f41.google.com (mail-ed1-f41.google.com [209.85.208.41]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id C70AE68CCB8 for ; Wed, 29 Mar 2023 02:21:44 +0300 (EEST) Received: by mail-ed1-f41.google.com with SMTP id i5so56456881eda.0 for ; Tue, 28 Mar 2023 16:21:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; t=1680045703; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:to:from:date:from:to:cc:subject :date:message-id:reply-to; bh=qbvVs2sAOO4V0ielSYG9sDdwrQ2FSGFmn7JSPAxSBhw=; b=Flw0CyBFpi1EkC/GfMKUCXePPuZa4RK1qWtf44DaJHMnyxf/EfbXxQySRuVbc/vxs3 CFjwwTj8njfJuwMTO/UzJ3kQDgpoJTuViWJjnQ5oth0TDpr5jH8siWXOpxgXtR1YF14o 6M0JQn1vQEOkgmlsmrokAQAK5jvULZ+UrcM7EWuJpBSso7AWMutv3ioyaIPtnUR4+/vQ wV9wArwcOu8VFU3cszm1nSn7BA4g7ozruOrZSX5f5CqhwV3oBzs6tGmnu2BCt2AIEgIC XBbGh3flvieOSCz/B4DpCrOYYD31dSJW57OuTzFG7zd7q3a7U3KMStGjwTbNpTlkJ2oj kpMA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1680045703; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:to:from:date:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=qbvVs2sAOO4V0ielSYG9sDdwrQ2FSGFmn7JSPAxSBhw=; b=K/vpRe6xKTkcr5sp9a4snUM4tEa+dEQYFhkTqXQRg2NR+e+GUHYp+qx6P2r46jCxYr NJhdJ/a231iAcOs2x0K+iHdvj5fkR0Wzt+6vTqyBQS/DiQ6tAjdwjZz5CrM7P5iXehMi 63cK6TrJ1WtDFPraXrwI5jTrZC69UJmHXnWn4v6YVPVca1yyXFhmVlK/waXPV9vq03zn R+SKfogIDt6Vpqj6cz4cZA+9xYMnAkWLwLMlmqI5COGKYMMRWh5nq9B6ypNHh1Npsoq6 KuWMnQUcA2aEa9xVVpxq00J4mTTcDbvNTzOkbYP98p8fD2rcG/fYx3oQyFzPHiMzIcxz KXaA== X-Gm-Message-State: AAQBX9crUSDg14mImYvbTk1UFnwb2vroWVynS0yTWhXlw9UCrG/VMuw9 4pTe0Pi+3XC7/TxDj3OuKR2D9bNhug9VSZik X-Google-Smtp-Source: AKy350YQocOcFVfP4eyo4xJqpLsb5l+9zDWfhwtrPS3KCUWbFnkzTV9j8PoKh57WN6mUSwcRh9z1Jw== X-Received: by 2002:aa7:c74d:0:b0:4ac:bbaa:867a with SMTP id c13-20020aa7c74d000000b004acbbaa867amr15220366eds.24.1680045703457; Tue, 28 Mar 2023 16:21: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 q18-20020a50c352000000b00501d39f1d2dsm11864462edb.41.2023.03.28.16.21.42 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 28 Mar 2023 16:21:42 -0700 (PDT) Received: by mariano (Postfix, from userid 1000) id E9555BFB73; Wed, 29 Mar 2023 01:21:40 +0200 (CEST) Date: Wed, 29 Mar 2023 01:21:40 +0200 From: Stefano Sabatini To: FFmpeg development discussions and patches Message-ID: <20230328232140.GQ26811@mariano> Mail-Followup-To: FFmpeg development discussions and patches References: <20230327000841.94338-1-stefasab@gmail.com> <9282f389-1307-a3bb-90c5-9b5b05642e5e@gyani.pro> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="PmA2V3Z32TCmWXqI" Content-Disposition: inline In-Reply-To: <9282f389-1307-a3bb-90c5-9b5b05642e5e@gyani.pro> User-Agent: Mutt/1.13.2 (2019-12-18) Subject: Re: [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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: --PmA2V3Z32TCmWXqI Content-Type: text/plain; charset=us-ascii Content-Disposition: inline On date Monday 2023-03-27 10:54:59 +0530, Gyan Doshi wrote: > > > On 2023-03-27 05:38 am, Stefano Sabatini wrote: > > 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 . > > Are they really interactive? Just a return code the other way, not exactly > ChatGPT. > > How about: > > "Some filters allow modification of some or all of their parameters during > execution via commands." Works for me. > > > + > > +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}. > > Should mention ffmpeg.c keyboard interaction. I'd drop this as can be done as a second step (and I don't know ATM how this works). > > +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 > > This note in the general section won't help a user identify which filters > are liable to make such changes via commands. > Such notes are best individually placed in the Commands subsection of > filters which can change AVFrame format midway, > of which there are only a few. I moved this to the scale section, probably we should review what filters are affected by this, but this is out of scope. Thanks. --PmA2V3Z32TCmWXqI Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="0002-doc-filters-extend-section-about-commands-warn-about.patch" >From 6e7a92a01409ce0b283f61ece24cb35c3b3012d4 Mon Sep 17 00:00:00 2001 From: Stefano Sabatini Date: Mon, 27 Mar 2023 02:05:24 +0200 Subject: [PATCH 2/3] doc/filters: extend section about commands, warn about undesirable behaviors of scale options Extend documentation about commands, and add a note to width/height scale commands to warn users that it might fail when the chained filter do not support mid-stream size changes. Fix trac issue: http://trac.ffmpeg.org/ticket/8987 --- doc/filters.texi | 46 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 40 insertions(+), 6 deletions(-) diff --git a/doc/filters.texi b/doc/filters.texi index 120fe6664a..c17faf7a41 100644 --- a/doc/filters.texi +++ b/doc/filters.texi @@ -356,11 +356,33 @@ 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 allow modification of some or all of their parameters during +execution via commands. + +Commands to the filter can be sent to a target 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. @anchor{framesync} @chapter Options for filters with several inputs (framesync) @@ -9532,6 +9554,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 @@ -11450,6 +11473,7 @@ specified file. @end table +@anchor{despill} @section despill Remove unwanted contamination of foreground colors, caused by reflected color of @@ -12735,6 +12759,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. @@ -20074,7 +20099,6 @@ Evaluate expressions for each incoming frame. Default value is @samp{init}. - @item interl Set the interlacing mode. It accepts the following values: @@ -20385,6 +20409,14 @@ The command accepts the same syntax of the corresponding option. If the specified expression is not valid, it is kept at its current value. + +Keep in mind that this command, by changing the output video size, might change +some chained filters configuration causing unexpected behavior. 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. + @end table @section scale_cuda @@ -29084,6 +29116,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. @@ -30830,6 +30863,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 --PmA2V3Z32TCmWXqI Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ 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". --PmA2V3Z32TCmWXqI--