[MPlayer-DOCS] [PATCH] mplayer advanced audio usage guide

[The Wanderer]

Corey Hickey wrote:

> All right folks, here it is. Please:
> 
> * Check for technical accuracy. Most of what is written here I
> determined by experimentation and there are some rather complicated
> examples I might have messed up. I don't even actually have a
> surround sound system so it's difficult to test.

You have a much better idea of how the entire system works than I do -
I'd never touched any of the mentioned options before - so I can't
really do much for that.

> * Check my xmlification. I usually miss some things.

I don't know XML more than vaguely, but I did have one comment despite
that.

> * Proofread. :)

You asked for it.

> * See if I explained af_channels and af_pan well enough. The list of
> suboptions can easily grow quite long. I tried to strike a good
> balance between keeping the explanations reasonably short and not
> assuming the reader knows how the filters work.

I think you did a fairly good job of it; I had no clue how they worked,
before, and now I think that if need be I could use them fairly
confidently.

> * Suggest anything else fun or important that I ought to include.

Not sure if it's advanced enough to be worth considering, but it might
be nice to have an explanation - and, more importantly, a few examples -
of the use of "-softvol-max" and related options somewhere; I'm not sure
it's sufficiently comprehensible for the ordinary user (I had some
difficulty getting it clear myself, when the options were first
implemented).

(Then again, if it's *that* important (and would belong anywhere near
here), the onus would presumably be on me to write the addition... we'll
see if I wind up being too lazy or not.)

> +Most DVDs and many other files include surround sound.
> +<application>MPlayer</application> supports surround playback but does not
> +enable it by default because stereo equipment is by far more common. To play a
> +file that has more than 2-channel audio use <option>-channel</option>. For
> +example, to play a DVD with 5.1 audio:

I'm not 100% happy with the commas (or rather, lack thereof) in the
second sentence, but it's not nearly as bad as many things I've let go
by for lack of better solutions in the past.

"more than two audio channels", perhaps? I understand and accept
"2-channel audio" as a noun to itself, but since the word "more" is here
being applied to the "2", I don't think that the number can be
reasonably integrated into the noun phrase.

"-channels"

> +Note that despite the name "5.1" there are actually six discrete channels.
> +If you have surround sound equipment it is safe to put the channels option in
> +your <application>MPlayer</application> configuration file

The word 'channels' in this sentence probably ought to be set out in
some way - enclosed in <option> tags, or in quotes, or just prepended
with the usual hyphen (although I can certainly see why it wasn't used
in this case).

> +<para>
> +<application>MPlayer</application> does not duplicate any channels by default,
> +and nor do most audio drivers. If you want to do that manually:

"and nor" is not really appropriate - it's the negative parallel of
"or", and you certainly would never say "and or" (unless either you
meant "and (or, alternately, or)", which is usually written "and/or", or
you were being silly - in which see Monty Python).

Anyway, either "nor" or "and neither" would work.

> +DVDs usually have surround audio encoded in AC3 (Dolby Digital) or DTS
> +(Digital Theater System) format. Some modern audio equipment is capable of
> +decoding these formats internally. In this case
> +<application>MPlayer</application> sends out the original, undecoded audio data.
> +This will only work if you have a S/PDIF (Sony/Philips Digital Interface) jack
> +in your sound card.
> +</para>

I'm not entirely happy with "In this case" vs. "sends" here, but I'm not
sure quite what the problem is or how to fix it. It's not intolerable,
it's just not ideal.

I'm not sure I wouldn't use "on" instead of "in" in that last line - or
jsut "if your sound card has an S/PDIF", et cetera. (Speaking of which,
unless that term is in fact pronounced beginning with the teeth-together
"sss" sound, the preceding indefinite article should be "an".)

> +If your audio equipment can decode both AC3 and DTS, you can enable passthrough
> +for both formats. Otherwise, you can specify either one.

Sure you don't mean "just one" or "only one"? Saying "either" makes it
sound like you can pick whichever one you want, which is certainly not
the case unless your hardware is *really* weird.

<pedant> Technically, the user *can* enable passthrough for both anyway,
it just won't work. I might say "should" instead in the latter case, and
'it is safe to" in the former case. </pedant>

> +<itemizedlist>
> +<title>To enable passthrough on the command line:</title>
> +<listitem><para>
> +For AC3 only, use <option>-ac hwac3</option>
> +</para></listitem>
> +<listitem><para>
> +For DTS only, use <option>-ac hwdts</option>
> +</para></listitem>
> +<listitem><para>
> +For both AC3 and DTS, use <option>-afm hwac3</option>
> +</para></listitem>
> +</itemizedlist>

These list entries don't seem to be full sentences, so I'm not sure they
should be capitalized - but I'm also not sure they'd look good if they
weren't. Any opinions?

The same situation exists immediately following.

> +<sect3 id="advaudio-surround-matrix">
> +<title>Matrix-encoded Audio</title>
> +
> +<para>
> +***TODO***
> +I don't know a thing about this. I don't even know if I have a matrix-encoded
> +sample to test with. Can somebody provide me a clue, a sample, or both? I asked
> +about this on -advusers last night but haven't gotten a response yet.
> +Otherwise I'll just drop this section.
> +</para>

Even if no one comes through for you this time, I might recommend that
instead of dropping the section, you leave it mostly empty except for a
note to the effect that 'if you can help us write this part of the
documentation, please do' and a pointer to the relevant files and
mailing lists.

> +<para>
> +Good links:
> +<itemizedlist>
> +<listitem><para>
> +<ulink url="http://electronics.howstuffworks.com/surround-sound5.htm">http://electronics.howstuffworks.com/surround-sound5.htm</ulink>

I've never been particularly happy with How Stuff Works' layout - it's
too cluttered, and looks comparatively bandwidth-heavy - but I've got to
admit that it's provided me good (if comparatively basic) information
the few times I've needed to go there.

(...okay, that isn't really a comment on the guide, but I wrote it and
don't feel like deleting it.)

> +<para>
> +Although it is not possible to exactly imitate a surround system,
> +<application>MPlayer</application>'s HRTF filter does provide more spatially
> +immersing audio in 2-channel headphones. Regular downmixing simply combines all

I'd probably recommend "immersive" here instead.

> +<para>
> +<option>hrtf</option> only works best with 5 or 6 channels. Also,
> +<option>hrtf</option> requires 48 kHz audio. DVD audio is already 48 kHz, but if
> +you have a file with a different sampling rate that you want to play using
> +<option>hrtf</option> you must resample it:

I'd probably say "works best with 5 or 6 channels" or "only works well
with 5 or 6 channels" - "only works best with" seems odd to me.

> +<para>
> +The <option>-channels</option> option is used to request the number of
> +channels from the audio decoder. Some audio codecs (such as liba52 for decoding
> +AC3) use the number of specified channels to decide if downmixing the source is
> +necessary. Note that this does not always affect the number of output channels.
> +For example, using <option>-channels 4</option> to play a stereo mp3 file will
> +still result in 2-channel output since the mp3 codec will not produce the extra
> +channels.

Is it necessary to note what liba52 is used for, here? It seems a little
off - if nothing else, it seems to imply that it might be the case that
liba52 does this *only* when decoding AC3, not when doing something
else. Whatever the problem is, it can probably be avoided by saying
something like "such as liba52, used for decoding AC3".

"MP3" on those last few lines - it's not a filename extension, a
command-line option or a formally-lowercased fourcc-ish thing here, it
should be capitalized.

> +<para>
> +This averages both channels, resulting in both channels being half as loud as
> +the original. The next sections have examples of other ways to do this without a
> +volume decrease, but they are more complex and require different options
> +depending on which channel to keep. If you really need to maintain the volume
> +than an easier way is to experiment with the <option>volume</option> filter and
> +find the right value. For example:

I don't like "depending on which channel to keep"; if it fits with your
intended meaning, you could say "depending on which channel you want to
keep" instead.

"than" (in that last full sentence) - you mean "then". I'd actually
recommend replacing the word with a comma, for better sentence flow.
(That might introduce problems of its own, around "way", but even if so
I think they're more ignorable.)

> +<listitem><para>
> +There should be two output channels: one for each speaker. The first suboption
> +is "2".

I'd probably prefer a comma rather than a colon, in the above sentence.
If you do want more of a break than that, you could use a hyphen (" - ")
or emdash instead; I think my objection is mainly on the basis of your
having made so much use of the colon for marking off lists elsewhere in
this document.

> +<listitem><para>
> +Decide how many channels to input into <option>pan</option> (further decoded
> +channels are discarded). This is the first suboption, and also controls how many
> +channels are output.

I'm not sure I like the usage "input into" here - it strikes me as
wrong, somehow. For minimal alteration, perhaps "feed into" would work?

> +<listitem><para>
> +Pan should receive and output two channels, so the first suboption is "2".

There is no program or entity at hand called "Pan"; the correct syntax
here would be "<option>pan</option>", with that capitalization.

> +<bridgehead>Example: downmixing a 6-channel wave file</bridgehead>

Technically, to the best of my knowledge, there's no such thing as a
"wave file". It's either a "WAV file" (capitalization may vary AFAIK,
although this is my own preferred form) or a "PCM file".

The same usage occurs below, in at least one other place.

> +The first set of suboptions lists the percentages, in order, that each channel
> +listed above should be mixed into the front left channel: "1:0:1:0:0.5:1". For
> +the front right channel: "0:1:0:1:0.5:1".

"percentages, in order, of each channel listed above that should be
mixed", et cetera. You could also use "which" instead of "that", but
I've been given to understand (albeit by a not-necessarily-authoritative
source) that "which" in such a sense is strictly appropriate only when
following a comma.

> +</sect3>
> +
> +</sect2>
> +
> +</sect1>

I don't know XML very well, but it would seem intuitive to me that each
of these should have been closed immediately before the following
section began... meaning that only section 3 should remain open, here.

-- 
       The Wanderer

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

A government exists to serve its citizens, not to control them.