[FFmpeg-devel] [PATCH] Clearer wording of audio channel maping limitations

[Tim Nicholson]

Clément Bœsch wrote


>On Wed, Dec 21, 2011 at 03:23:26PM +0000, Tim Nicholson wrote:
>> Since I and others have been caught out by the channel mapping limitations and the documentation
>> is not clear about those limitations with regard to  stream mapping from a single file. I offer the attached patch
>> in the hope it clarifies things.

>> From 2ce04ac3c8fccda673cc08eed94cb57990161f69 Mon Sep 17 00:00:00 2001
>> From: Tim Nicholson <tim.nicholson at bbc.co.uk>
>> Date: Wed, 21 Dec 2011 15:11:04 +0000
>> Subject: [PATCH] Clearer explanation of audio channel mapping restrictions
>> 
>> ---
>>  doc/ffmpeg.texi |    7 ++++---
>>  1 files changed, 4 insertions(+), 3 deletions(-)
>> 
>> diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
>> index 553d759..ace4b29 100644
>> --- a/doc/ffmpeg.texi
>> +++ b/doc/ffmpeg.texi
>> @@ -825,9 +825,10 @@ The following example split the channels of a stereo input into streams:
>>  ffmpeg -i stereo.wav -map 0:0 -map 0:0 -map_channel 0.0.0:0.0 -map_channel 0.0.1:0.1 -y out.ogg
>>  @end example
>>  
>> -Note that "-map_channel" is currently limited to the scope of one input for
>> -each output; you can't for example use it to pick multiple input audio files
>> -and mix them into one single output.
>> +Note that "-map_channel" is currently limited to the scope of one input stream for
>> +each output stream;
>
>Adding "stream" is indeed a good idea. I'd actually even reword it
>emphasis that "one output stream is associated with one single input
>stream"; I think it's easier to visualize that the output stream can't be
>composed of multiple inputs. It enlightens the fact that -map_channel is
>(currently) limited to filtering and reordering.

OK then, a bolder rewording......

Should I keep them as separate patch stages, or should I have merged them?

I tried a rebase but nothing happened....

>
>>                      you can't, for example, use it to pick multiple input audio channels
>> +contained in different streams (from the same or different files) and mix them into one single
>> +output stream in order to turn two separate mono streams into a single stereo stream.
>>  
>
>You start that part of the sentence with an "abstraction" ("pick multiple
>input audio channels contained in different streams") and end up with a
>very specific example; I think it would be better split.
>

Interesting observation, as originally I had it split, but then tried to reduce/simplify it...

>Also, could you keep the 80 columns wrapping?

Sorry, I was relying on keeping within other, existing, lines that were over 80 ;(
-- 
Tim


From 2ce04ac3c8fccda673cc08eed94cb57990161f69 Mon Sep 17 00:00:00 2001
From: Tim Nicholson <tim.nicholson at bbc.co.uk>
Date: Wed, 21 Dec 2011 15:11:04 +0000
Subject: [PATCH 1/2] Clearer explanation of audio channel mapping
 restrictions

---
 doc/ffmpeg.texi |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index 553d759..ace4b29 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -825,9 +825,10 @@ The following example split the channels of a stereo input into streams:
 ffmpeg -i stereo.wav -map 0:0 -map 0:0 -map_channel 0.0.0:0.0 -map_channel 0.0.1:0.1 -y out.ogg
 @end example
 
-Note that "-map_channel" is currently limited to the scope of one input for
-each output; you can't for example use it to pick multiple input audio files
-and mix them into one single output.
+Note that "-map_channel" is currently limited to the scope of one input stream for
+each output stream; you can't, for example, use it to pick multiple input audio channels
+contained in different streams (from the same or different files) and mix them into one single
+output stream in order to turn two separate mono streams into a single stereo stream.
 
 @item -map_metadata[:@var{metadata_type}][:@var{index}] @var{infile}[:@var{metadata_type}][:@var{index}] (@emph{output,per-metadata})
 Set metadata information of the next output file from @var{infile}. Note that
-- 
1.7.7

From 8db7cd8383c741a27db3c971d0dca3f5779ec44a Mon Sep 17 00:00:00 2001
From: Tim Nicholson <tim.nicholson at bbc.co.uk>
Date: Wed, 21 Dec 2011 16:04:44 +0000
Subject: [PATCH 2/2] Clearer explanation of audio channel mapping
 restrictions

With emphasis on the output streams limitation of a single source stream
---
 doc/ffmpeg.texi |   11 +++++++----
 1 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index ace4b29..83a45a8 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -825,10 +825,13 @@ The following example split the channels of a stereo input into streams:
 ffmpeg -i stereo.wav -map 0:0 -map 0:0 -map_channel 0.0.0:0.0 -map_channel 0.0.1:0.1 -y out.ogg
 @end example
 
-Note that "-map_channel" is currently limited to the scope of one input stream for
-each output stream; you can't, for example, use it to pick multiple input audio channels
-contained in different streams (from the same or different files) and mix them into one single
-output stream in order to turn two separate mono streams into a single stereo stream.
+Note that currently each output stream can only contain channels from a single
+input stream; you can't for example use "-map_channel" to pick multiple input
+audio channels contained in different streams (from the same or different files)
+and merge them into a single output stream. It is therefore not currently
+possible, for example, to turn two separate mono streams into a single stereo
+stream. However spliting a stereo stream into two single channel mono streams
+is possible.
 
 @item -map_metadata[:@var{metadata_type}][:@var{index}] @var{infile}[:@var{metadata_type}][:@var{index}] (@emph{output,per-metadata})
 Set metadata information of the next output file from @var{infile}. Note that
-- 
1.7.7