[FFmpeg-devel] Add FAQs about running in background (rev 2)

Add two FAQs about running FFmpeg in the background.
The first explains the use of the -nostdin option in
a straightforward way. Text revised based on review.

The second FAQ starts from a confusing error message,
and leads to the solution, use of the -nostdin option.
The purpose of the second FAQ is to attract web searches
from people having the problem, and offer them a solution.

Add an anchor to the Main Options section of the ffmpeg
documentation, so that the FAQs can link directly there.
---
 doc/faq.texi    | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/ffmpeg.texi |  1 +
 2 files changed, 66 insertions(+)

Ping. This patch responds to review comments, and there have been no 
further comments for a week. Could someone commit it please?

Thanks,
       —Jim DeLaHunt


On 2017-11-15 00:43, Jim DeLaHunt wrote:
> Add two FAQs about running FFmpeg in the background.
> The first explains the use of the -nostdin option in
> a straightforward way. Text revised based on review.
>
> The second FAQ starts from a confusing error message,
> and leads to the solution, use of the -nostdin option.
> The purpose of the second FAQ is to attract web searches
> from people having the problem, and offer them a solution.
>
> Add an anchor to the Main Options section of the ffmpeg
> documentation, so that the FAQs can link directly there.
> ---
>   doc/faq.texi    | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>   doc/ffmpeg.texi |  1 +
>   2 files changed, 66 insertions(+)
>
> diff --git a/doc/faq.texi b/doc/faq.texi
> index dcaf89c6d2..73624c647e 100644
> --- a/doc/faq.texi
> +++ b/doc/faq.texi
> @@ -501,6 +501,71 @@ ffmpeg -i ega_screen.nut -vf setdar=4/3 ega_screen_anamorphic.nut
>   ffmpeg -i ega_screen.nut -aspect 4/3 -c copy ega_screen_overridden.nut
>   @end example
>   
> +@anchor{background task}
> +@section How do I run ffmpeg as a background task?
> +
> +ffmpeg normally checks the console input, for entries like "q" to stop
> +and "?" to give help, while performing operations. ffmpeg does not have a way of
> +detecting when it is running as a background task.
> +When it checks the console input, that can cause the process running ffmpeg
> +in the background to suspend.
> +
> +To prevent those input checks, allowing ffmpeg to run as a background task,
> +use the @url{ffmpeg.html#stdin-option, @code{-nostdin} option}
> +in the ffmpeg invocation. This is effective whether you run ffmpeg in a shell
> +or invoke ffmpeg in its own process via an operating system API.
> +
> +As an alternative, when you are running ffmpeg in a shell, you can redirect
> +standard input to @code{/dev/null} (on Linux and Mac OS)
> +or @code{NUL} (on Windows). You can do this redirect either
> +on the ffmpeg invocation, or from a shell script which calls ffmpeg.
> +
> +For example:
> +
> +@example
> +ffmpeg -nostdin -i INPUT OUTPUT
> +@end example
> +
> +or (on Linux, Mac OS, and other UNIX-like shells):
> +
> +@example
> +ffmpeg -i INPUT OUTPUT </dev/null
> +@end example
> +
> +or (on Windows):
> +
> +@example
> +ffmpeg -i INPUT OUTPUT <NUL
> +@end example
> +
> +@section How do I prevent ffmpeg from suspending with a message like @emph{suspended (tty output)}?
> +
> +If you run ffmpeg in the background, you may find that its process suspends.
> +There may be a message like @emph{suspended (tty output)}. The question is how
> +to prevent the process from being suspended.
> +
> +For example:
> +
> +@example
> +% ffmpeg -i INPUT OUTPUT &> ~/tmp/log.txt &
> +[1] 93352
> +%
> +[1]  + suspended (tty output)  ffmpeg -i INPUT OUTPUT &>
> +@end example
> +
> +The message "tty output" notwithstanding, the problem here is that
> +ffmpeg normally checks the console input when it runs. The operating system
> +detects this, and suspends the process until you can bring it to the
> +foreground and attend to it.
> +
> +The solution is to use the right techniques to tell ffmpeg not to consult
> +console input. You can use the
> +@url{ffmpeg.html#stdin-option, @code{-nostdin} option},
> +or redirect standard input with @code{< /dev/null}.
> +See FAQ
> +@ref{background task, @emph{How do I run ffmpeg as a background task?}}
> +for details.
> +
>   @chapter Development
>   
>   @section Are there examples illustrating how to use the FFmpeg libraries, particularly libavcodec and libavformat?
> diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
> index 7db80ebf6a..2bcad75973 100644
> --- a/doc/ffmpeg.texi
> +++ b/doc/ffmpeg.texi
> @@ -470,6 +470,7 @@ the encoding process. It is made of "@var{key}=@var{value}" lines. @var{key}
>   consists of only alphanumeric characters. The last key of a sequence of
>   progress information is always "progress".
>   
> +@anchor{stdin option}
>   @item -stdin
>   Enable interaction on standard input. On by default unless standard input is
>   used as an input. To explicitly disable interaction you need to specify

On Wed, Nov 15, 2017 at 12:43:30AM -0800, Jim DeLaHunt wrote:
> Add two FAQs about running FFmpeg in the background.
> The first explains the use of the -nostdin option in
> a straightforward way. Text revised based on review.
> 
> The second FAQ starts from a confusing error message,
> and leads to the solution, use of the -nostdin option.
> The purpose of the second FAQ is to attract web searches
> from people having the problem, and offer them a solution.
> 
> Add an anchor to the Main Options section of the ffmpeg
> documentation, so that the FAQs can link directly there.
> ---
>  doc/faq.texi    | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  doc/ffmpeg.texi |  1 +
>  2 files changed, 66 insertions(+)

will apply

thanks

[...]

On 2017-11-22 08:54, Michael Niedermayer wrote:

> On Wed, Nov 15, 2017 at 12:43:30AM -0800, Jim DeLaHunt wrote:
>> Add two FAQs about running FFmpeg in the background.
>> The first explains the use of the -nostdin option in
>> a straightforward way. Text revised based on review.
>>
>> The second FAQ starts from a confusing error message,
>> and leads to the solution, use of the -nostdin option.
>> The purpose of the second FAQ is to attract web searches
>> from people having the problem, and offer them a solution.
>>
>> Add an anchor to the Main Options section of the ffmpeg
>> documentation, so that the FAQs can link directly there.
>> ---
>>   doc/faq.texi    | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>   doc/ffmpeg.texi |  1 +
>>   2 files changed, 66 insertions(+)
> will apply
>
> thanks
>
> [...]
And there it is: 
<http://ffmpeg.org/faq.html#How-do-I-run-ffmpeg-as-a-background-task_003f>. 
Thank you!

     --Jim DeLaHunt, jdlh@jdlh.com     http://blog.jdlh.com/ (http://jdlh.com/)
       multilingual websites consultant

       355-1027 Davie St, Vancouver BC V6E 4L2, Canada
          Canada mobile +1-604-376-8953