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

[The Wanderer]

Guillaume POIRIER wrote:

> Hi,
> 
> On 10/12/05, Guillaume POIRIER <poirierg at gmail.com> wrote:
> 
>> Hi there,
>> The attached patch documents the different containers supported by
>> MEncoder, as well as a nice example.
>> Please review as I'm keyboard disabled :-).
> 
> Here is an updated patch that features Oded's comment.

...I didn't see any such comment... but oh well, I'll review this patch
anyway.

> +<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...

> +    <entry>lavf</entry>
> +    <entry>Use one of <systemitem class="library">libavformat</systemitem>'s
> +    containers</entry>

I would recommend "One of the containers provided by libavformat",
instead, for parallelism; the other entries are all noun phrases,
whereas this one is a description of what the option tells MEncoder to
do.

As an alternative to "provided", we could say "supported"; it's
different nuance, but grammatically just as fine.

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

I've been long since overruled on most hyphenation issues, but I really
do think that this should be "Audio-Video Interleave". I'll note, also,
that V.E.R.A. lists it as "Audio Video Interleaved" - which I would
disagree with, but I'm not in a position to say much about it.

Also, you say "file" here, but omit the word in almost all other cases.
This should be brought into agreement. The same discrepancy occurs
below, in the list of valid libavformat container types.

> +  <row>
> +    <entry>mpeg</entry>
> +    <entry>MPEG-1 systems and MPEG-2 PS</entry>

Okay, this isn't even parallel within the one entry. Do I correctly
interpret this as meaning that in some cases the resulting container
will be an MPEG-1 system stream and in other cases it will be an MPEG-2
program stream? If so, what determines which? If not, then what the heck
*does* it mean - the "MPEG-1 systems" part especially?

The same line occurs below, in the list of valid libavformat container
types.

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

I'd prefer to say "the one for which", rather than just "for which".

> +  As you saw earlier, other container formats are usable, but you may
> +  experience some problems while using them.

I'd say "As noted above", for the sake of overall tone. I might also
prefer "when" to "while".

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

I would say "a considerable number", rather than "a fair deal", here.

> +  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 encoding file you will obtain.

The usage "the encoding file" is incorrect in this instance. I'm not
quite sure what would be the best way to put it, but either "the file
you will obtain" or "the resulting file" should work well enough.

It might also be desirable to say either "sbould be really paranoid" or
"really should be paranoid" instead of "should really be paranoid"; the
three phrasings do not have *quite* the same meaning, but are close, and
I would probably prefer one of the first two.

> +  Please check if the Audio/Video synchronization is Okay and if it plays
> +  nicely in other players.

It would be better (albeit not necessarily ideal) to say "Please check
to be sure that the audio/video synchronization is okay and that the
file can be played correctly by players other than MPlayer", or
something remotely like that. (I'm not at all satisfied with that
phrasing, but there were a number of notable problems with the original
version - the use of "if" and the capitalization, most specifically.)

> +<para>Example:</para>
> +<para>
> +Creating an Macromedia Flash video suitable to be played on web browser
> +featuring Macromedia Flash plugin:

"Creating an" -> "Creating a"

"on a" or "in a"

"with a" or "with the" rather than "featuring" (which one is better
depends on whether or not there can be considered to be multiple Flash
plugins, rather than just one).

> +<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?

> +-lavcopts vcodec=flv:vbitrate=250:autoaspect:mbd=2:mv0:trell:v4mv:cbp:last_pred=3:predia=2:dia=2:precmp=2:cmp=2:subcmp=2:preme=2 \

Are all of these "dia" and "cmp" options really necessary?

(And, yow! That bitrate! I can see how it might be considered
appropriate for Flash, since the files involved tend to be low-quality
and tiny, but for anything else...)

> +-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>.)

-- 
       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.