[MPlayer-DOCS] Re: [PATCH] List container formats and add an example

[The Wanderer]

Guillaume POIRIER wrote:

> Hi,
> 
> On 10/12/05, The Wanderer <inverseparadox at comcast.net> wrote:
> 
>>Guillaume POIRIER wrote:

>>> +<para>
>>> +  Output container formats are selected with the <option>-of</option>
>>> +  option.
>>> +  Type:
>>> +  <screen>mencoder -of help</screen> to list all containers supported
>>> +  by the <application>MEncoder</application> on your machine.
>> 
>> Depending on exactly how the <screen> tag is rendered (I haven't
>> checked, partly because I have no way of knowing whether or not
>> it's going to be the same on all machines), it may or may not be
>> desirable to insert a linebreak (for display purposes) after the
>> literal command. Admittely it would take an *exceptional* idiot to
>> not realize that the "to list all containers" etc. part is not part
>> of the intended command line, but there is always a bigger idiot...
> 
> the tag <screen> introduces a line break.

Okay, that's fine, then.

> I added a line break to the XML source as well.

Good for readability anyway.

>>> +<screen>
>>> +mencoder <replaceable>input.avi</replaceable> -o <replaceable>ouput.flv</replaceable> -of lavf -oac mp3lame -lameopts abr:br=56:q=1 -ovc lavc \
>> 
>> Why mp3lame, rather than lavc? Is lavc's MP3 encoder really that
>> bad?
> 
> if I'm not mistaken, lavc do not feature any mp3 encoder and uses
> 'lame' instead, this it's unnecessary IMHO to make ppl think the
> contrary.

I hadn't thought that that was the case; I'd thought that libavcodec had
its own MP3 encoder, but it didn't necessarily work as well as lame did.
Unfortunately the people who are likely to know better probably aren't
on this mailing list...

>>> +-vf scale=320:240 -srate 22050 -af lavcresample=22050
>>
>> I don't think that the scaling (and, perhaps, rate constraints, and
>> so forth) is necessarily appropriate for an example as generic as
>> this one is described as being; unless the resolution, the sample
>> rate, the bitrate, and the various other things are in fact needed
>> to remain within the limits of the container format, I'd probably
>> prefer that either the example be described more concretely or the
>> extraneous options be omitted. (Or, at the least, marked as
>> [optional] or <replaceable>.)
> 
> I have not played too much with flash video to tell you what are the
> constrains of that format. I dug my archives to get a simpler yet 
> usable example.

I almost certainly know less about Flash than you do, so I can't really
help too much with the details of that - but the current form seems
reasonably okay to my inexperienced eyes.

> Please refer to the attached patch (that also feature a note about
> the fact that the container format of lavf is selected depending on
> the file extension of the output file.
> 
> Is it okay now?

Well... I expected it to mostly be, but found more things on my second
read-through than I'd thought I would. -_-

> +  Type:
> +  <screen>mencoder -ovc help</screen>
> +  for instance to list all video codec supported by the
> +  <application>MEncoder</application> on your machine.

I'd prefer to either drop the "for instance" (which wasn't here last
time, unless I'm blind) or move it to before "type:". (Hmm. Looking at
it again, seems like I *was* blind. Still, the suggestion applies.)

Also, you want "codecs" instead of "codec", and I'd say something like
"supported by your version of MEncoder" (or maybe "your copy" or the
like).

> +  Type:
> +  <screen>mencoder -of help</screen>
> +  to list all containers supported by the <application>MEncoder</application>
> +  on your machine.

Somewhat similarly to the above, I'd say "the version of MEncoder on
your machine" or something along those lines. Whichever phrasing is
chosen should probably be made parallel in both instances.

> +  AVI container is the native container format for
> +  <application>MEncoder</application>, which means that it's the one that
> +  is best handled, and the one for which <application>MEncoder</application>
> +  was designed.

One thing I mised noticing before: either "The AVI container", or just
"AVI".

> +  Provided that you selected <systemitem class="library">libavformat</systemitem>
> +  to do the muxing of the output file (by using the <option>-of lavf</option>,
> +  the appropriate container format is selected depending on the file
> +  extension of the output file.

I'd say "If you selected" ... "format will be determined by the file
extension" etc.

> +  You may force a certain container format with
> +  <systemitem class="library">libavformat</systemitem>'s
> +  <option>format</option> option.

This is minor, but I'd say "particular" instead of "certain".

> +    <entry>avi</entry>
> +    <entry>Audio-Video Interleave file</entry>

You dropped "file" above, but you still have it here.

> +    <entry>flv</entry>
> +    <entry>Macromedia Flash video files</entry>

You also have "files" here...

> +    <entry>au</entry>
> +    <entry>SUN AU format</entry>

...and "format" here...

> +    <entry>nut</entry>
> +    <entry>NUT open container format (experimental and not yet spec-compliant)</entry>

...and here...

> +    <entry>mp4</entry>
> +    <entry>MPEG-4 format</entry>

...and here...

> +    <entry>dv</entry>
> +    <entry>Sony Digital Video container</entry>

...and "container" here (although this one could be justifiable, since
it doesn't sound from the name as if this format is a container). I
think one of the forms - "format", "file", "container", or nothing at
all - should be standardized upon. (As I said, this particular entry
could be an exception, if that last option is chosen.)

> +  As you can see, <systemitem class="library">libavformat</systemitem>
> +  allows <application>MEncoder</application> to mux into a considerable
> +  number of containers.

Here I go, correcting my own suggestion... but this one should be the
last; try "considerable variety" here. (My original form sounded a
little like it was possible to mux into more than one container at a
time, which is certainly not true.)

> +  Unfortunately, as <application>MEncoder</application> was not designed
> +  from the beginning to support other container formats other than AVI,
> +  your should really be paranoid about the resulting file.

Repetition of "other" before and after "container formats". One or the
other should be dropped - it doesn't matter which one.

> +  Please check to be sure that the audio/video synchronization is okay
> +  and that the file can be played correctly by players other than
> +  <application>MPlayer</application>.

I'll note (as I didn't last time) that I'm not 100% happy with this,
since it has three uses of "playe[dr]" in rapid succession, but it's
tolerable.

-- 
       The Wanderer

Warning: Simply because I argue an issue does not mean I agree with any
side of it.

Secrecy is the beginning of tyranny.