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

[Corey Hickey]

I have a new patch attached with most of your concerns addressed. See
below for notes.

You can run a diff between this diff and the last diff if you want to
see the differences. They're a little bit polluted because I re-wrapped
sometimes, but I'd prefer to keep the wrapping nice until this gets
committed.

The Wanderer wrote:
>>* 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.

Thanks.

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

I'm pretty sure that sentence is correct. It's been long enough since
English class that I don't remember very many grammar terms; I have to
look them up and I could be wrong. There are a few places I see where
you might be looking for a comma:

* after "playback"

A comma may be used, and is usually recommended, when a coordinating
conjunction joins two independent clauses. "Does not enable it by
default..." is not an independent clause; it makes no sense by itself
because it has no subject.

* after "default"

"stereo equipment is by far more common" provides an explanation for the
rest of the sentence, so it is a dependent clause. Since the dependent
clause comes at the end, a comma is not necessary (as opposed to this
sentence, in which the dependent clause precedes the independent clause).

* surrounding "by far"

I intend "by" and "far" to be an adjunct rather than a parenthetical
statement. If I had commas there they would interrupt the flow of the
end of the sentence.


Please don't take this as me trying to out-grammar you. :) I looked a
few things up to see if I was right or not and wrote down what I found.

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

Good catch; I think you're right.

> "-channels"

Thanks.

> The word 'channels' in this sentence probably ought to be set out in
> some way - enclosed in <option> tags,

Yeah.

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

You're right. I'll use "and neither".

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

Well, the sentence isn't very accurate anyway. I'll change it to:
"MPlayer can be configured to relay the audio data without decoding it."

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

I agree.

> unless that term is in fact pronounced beginning with the teeth-together
> "sss" sound, the preceding indefinite article should be "an".)

I've only heard it pronounced by a couple people; they both say
"spidiff". I can't find any consensus from google, so I'm leaving it
alone for now.

http://stereos.about.com/cs/glossaryandtools/g/aesebu.htm
http://66.102.7.104/search?q=cache:4JMN35BM75cJ:dcto.duderesearch.com/forums/search.php%3Fdo%3Dfinduser%26u%3D5713+spdif+pronounce&hl=en
http://www.hardcoreware.net/reviews/review-228-1.htm


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

"If your audio equipment can decode both AC3 and DTS, you can safely
enable passthrough for both formats. Otherwise, enable passthrough for
only the format your equipment supports."

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

Perhaps I will.

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

I agree.

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

Now, this is funny: that's exactly what I had there until ispell told me
"immersive" isn't a word. Merriam Webster says it isn't either.
Dictionary.com and the Oxford English Dictionary say it is. I'll change
it back.

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

You're right. I choose the latter.

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

I mention liba52 because it's the most important example, but since I
wouldn't expect most users to relate that to AC3 I wanted to say what
liba52 does. Now that I think about it, though, most users probably
won't know that AC3 is used for DVDs either. I suppose it is sufficient
that I have examples showing how to use -channels with DVDs. I'll remove
the parenthetical statement.

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

Yeah. I knew that, but I was lazy.

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

Yep.

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

That's a typo. I don't have any preference for "then" instead of a
comma. To what problems do you refer?

Forget it. I'm just going to change that sentence around anyway.


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

I think using a colon here is actually correct, but I'm having a hard
time finding proof. I think my usage falls under the category of this
quote from a Wikipedia article:

"The colon is used when the following clause is expanatory[sic] of the
one already expressed, or additional, without an introductory
conjunction. It is used to precede a clause which is the result of the
preceding clause."

http://en.wikipedia.org/wiki/Colon_(punctuation)

If you feel strongly about this we'll talk more.

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

I don't care either way, so I changed it.

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

I missed it.

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

I changed them to "PCM" (but not "PCM file", since, I think,
WAV/WAVE/Wave is the container and PCM is the codec.

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

Hmm.

"...the percentages of the original volume, in order, at which each
channel listed above..."

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

I don't know for sure, and I'm too tired of grammar by now to think
about it. Of course, "at which" is a rather different usage.

>>+</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 sections are hierarchical. A sect1 can include sect2s, a sect2 can
include sect3s, etc.

-Corey