# Usage

## Command line

MPlayer utilizes a complex playtree. Options passed on the command line can apply to all files/URLs or just to specific ones depending on their position. For example

    mplayer -vfm ffmpeg movie1.avi movie2.avi

will use FFmpeg decoders for both files, but

    mplayer -vfm ffmpeg movie1.avi movie2.avi -vfm dmo

will play the second file with a DMO decoder.

You can group filenames/URLs together using `{` and `}`. It is useful with option `-loop`:

    mplayer { 1.avi -loop 2 2.avi } -loop 3

The above command will play files in this order: 1, 1, 2, 1, 1, 2, 1, 1, 2.

Playing a file:

    mplayer [options] [path/]filename

Another way to play a file:

    mplayer [options] file:///uri-escaped-path

Playing more files:

    mplayer [default options] [path/]filename1 [options for filename1] filename2 [options for filename2] ...

Playing VCD:

    mplayer [options] vcd://trackno [-cdrom-device /dev/cdrom]

Playing DVD:

    mplayer [options] dvd://titleno [-dvd-device /dev/dvd]

Playing from the WWW:

    mplayer [options] http://site.com/file.asf

(playlists can be used, too)

Playing from RTSP:

    mplayer [options] rtsp://server.example.com/streamName

Examples:

    mplayer -vo x11 /mnt/Films/Contact/contact2.mpg
    mplayer vcd://2 -cdrom-device /dev/hdc
    mplayer -afm 3 /mnt/DVDtrailers/alien4.vob
    mplayer dvd://1 -dvd-device /dev/hdc
    mplayer -abs 65536 -delay -0.4 -nobps ~/movies/test.avi

## Subtitles and OSD

MPlayer can display subtitles along with movie files. Currently the following formats are supported:

- VOBsub

- OGM

- CC (closed caption)

- MicroDVD

- SubRip

- SubViewer

- Sami

- VPlayer

- RT

- SSA

- PJS (Phoenix Japanimation Society)

- MPsub

- AQTitle

- JACOsub

MPlayer can dump the previously listed subtitle formats (except the three first) into the following destination formats, with the given options:

- MPsub: `-dumpmpsub`

- SubRip: `-dumpsrtsub`

- MicroDVD: `-dumpmicrodvdsub`

- JACOsub: `-dumpjacosub`

- Sami: `-dumpsami`

MEncoder can dump DVD subtitles into VOBsub format.

The command line options differ slightly for the different formats:

## VOBsub subtitles

VOBsub subtitles consist of a big (some megabytes) `.SUB` file, and optional `.IDX` and/or `.IFO` files. If you have files like ``sample.sub``, ``sample.ifo`` (optional), ``sample.idx`` - you have to pass MPlayer the `-vobsub sample [-vobsubid `id`]` options (full path optional). The `-vobsubid` option is like `-sid` for DVDs, you can choose between subtitle tracks (languages) with it. In case that `-vobsubid` is omitted, MPlayer will try to use the languages given by the `-slang` option and fall back to the `langidx` in the `.IDX` file to set the subtitle language. If it fails, there will be no subtitles.

## Other subtitles

The other formats consist of a single text file containing timing, placement and text information. Usage: If you have a file like ``sample.txt``, you have to pass the option `-sub `sample.txt`` (full path optional).

## Adjusting subtitle timing and placement:

`-subdelay `sec``

- Delays subtitles by ``sec`` seconds. Can be negative. The value is added to movie's time position counter.

`-subfps `RATE``

- Specify frame/sec rate of subtitle file (float number).

`-subpos `0-100``

- Specify the position of subtitles.

If you experience a growing delay between the movie and the subtitles when using a MicroDVD subtitle file, most likely the framerate of the movie and the subtitle file are different. Please note that the MicroDVD subtitle format uses absolute frame numbers for its timing, but there is no fps information in it, and therefore the `-subfps` option should be used with this format. If you like to solve this problem permanently, you have to manually convert the subtitle file framerate. MPlayer can do this conversion for you:

    mplayer -dumpmicrodvdsub -fps subtitles_fps -subfps avi_fps \
        -sub subtitle_filename dummy.avi

About DVD subtitles, read the DVD section.

## Control

MPlayer has a fully configurable, command driven, control layer which lets you control MPlayer with keyboard, mouse, joystick or remote control (using LIRC). See the man page for the complete list of keyboard controls.

### Controls configuration

MPlayer allows you bind any key/button to any MPlayer command using a simple config file. The syntax consist of a key name followed by a command. The default config file location is `$HOME/.mplayer/input.conf` but it can be overridden using the `-input `conf`` option (relative path are relative to `$HOME/.mplayer`).

You can get a full list of supported key names by running `mplayer -input keylist` and a full list of available commands by running `mplayer -input cmdlist`.

#### A simple input control file

    ##
    ## MPlayer input control file
    ##

    RIGHT seek +10
    LEFT seek -10
    - audio_delay 0.100
    + audio_delay -0.100
    q quit
    > pt_step 1
    < pt_step -1
    ENTER pt_step 1 1

### Control from LIRC

Linux Infrared Remote Control - use an easy to build home-brewed IR-receiver, an (almost) arbitrary remote control and control your Linux box with it! More about it on the LIRC homepage.

If you have the LIRC package installed, `configure` will autodetect it. If everything went fine, MPlayer will print "`Setting up LIRC support...`" on startup. If an error occurs it will tell you. If there is no message about LIRC there is no support compiled in. That's it :-)

The application name for MPlayer is - surprise - `mplayer`. You can use any MPlayer commands and even pass more than one command by separating them with `\n`. Do not forget to enable the repeat flag in `.lircrc` when it makes sense (seek, volume, etc). Here is an excerpt from a sample `.lircrc`:

    begin
         button = VOLUME_PLUS
         prog = mplayer
         config = volume 1
         repeat = 1
    end

    begin
        button = VOLUME_MINUS
        prog = mplayer
        config = volume -1
        repeat = 1
    end

    begin
        button = CD_PLAY
        prog = mplayer
        config = pause
    end

    begin
        button = CD_STOP
        prog = mplayer
        config = seek 0 1\npause
    end

If you do not like the standard location for the lirc-config file (`~/.lircrc`) use the `-lircconf `filename`` switch to specify another file.

### Slave mode

The slave mode allows you to build simple frontends to MPlayer. When run with the `-slave` option MPlayer will read commands separated by a newline (\n) from stdin. The commands are documented in the slave.txt file.

## Streaming from network or pipes

MPlayer can play files from the network, using the HTTP, FTP, MMS or RTSP/RTP protocol.

Playing works simply by passing the URL on the command line. MPlayer honors the `http_proxy` environment variable, using a proxy if available. Proxies can also be forced:

    mplayer http_proxy://proxy.micorsops.com:3128/http://micorsops.com:80/stream.asf

MPlayer can read from stdin (not named pipes). This can for example be used to play from FTP:

    wget ftp://micorsops.com/something.avi -O - | mplayer -

It is also recommended to enable `-cache` when playing from the network:

    wget ftp://micorsops.com/something.avi -O - | mplayer -cache 8192 -

### Saving streamed content

Once you succeed in making MPlayer play your favorite internet stream, you can use the option `-dumpstream` to save the stream into a file. For example:

    mplayer http://217.71.208.37:8006 -dumpstream -dumpfile stream.asf

will save the content streamed from `http://217.71.208.37:8006` into `stream.asf`. This works with all protocols supported by MPlayer, like MMS, RTSP, and so forth.

## DVD playback

For the complete list of available options, please read the man page. The syntax to play a standard DVD is as follows:

    mplayer dvd://<track> [-dvd-device <device>]

Example:

    mplayer dvd://1 -dvd-device /dev/hdc

If you have compiled MPlayer with dvdnav support, the syntax is the same, except that you need to use dvdnav:// instead of dvd://.

The default DVD device is `/dev/dvd`. If your setup differs, make a symlink or specify the correct device on the command line with the `-dvd-device` option.

MPlayer uses `libdvdread` and `libdvdcss` for DVD playback and decryption. These two libraries are contained in the MPlayer source tree, you do not have to install them separately. You can also use system-wide versions of the two libraries, but this solution is not recommended, as it can result in bugs, library incompatibilities and slower speed.

In case of DVD decoding problems, try disabling supermount, or any other such facilities. Some RPC-2 drives may also require setting the region code.

## DVD decryption

DVD decryption is done by `libdvdcss`. The method can be specified through the `DVDCSS_METHOD` environment variable, see the manual page for details.

### region code

DVD drives nowadays come with a nonsensical restriction labeled region code. This is a scheme to force DVD drives to only accept DVDs produced for one of the six different regions into which the world was partitioned. How a group of people can sit around a table, come up with such an idea and expect the world of the 21st century to bow to their will is beyond anyone's guess.

Drives that enforce region settings through software only are also known as RPC-1 drives, those that do it in hardware as RPC-2. RPC-2 drives allow changing the region code five times before it remains fixed. Under Linux you can use the regionset tool to set the region code of your DVD drive.

Thankfully, it is possible to convert RPC-2 drives into RPC-1 drives through a firmware upgrade. Feed the model number of your DVD drive into your favorite search engine or have a look at the forum and download sections of "The firmware page". While the usual caveats for firmware upgrades apply, experience with getting rid of region code enforcement is generally positive.

## VCD playback

For the complete list of available options, please read the man page. The Syntax for a standard Video CD (VCD) is as follows:

    mplayer vcd://<track> [-cdrom-device <device>]

Example:

    mplayer vcd://2 -cdrom-device /dev/hdc

The default VCD device is `/dev/cdrom`. If your setup differs, make a symlink or specify the correct device on the command line with the `-cdrom-device` option.

At least Plextor and some Toshiba SCSI CD-ROM drives have horrible performance reading VCDs. This is because the CDROMREADRAW `ioctl` is not fully implemented for these drives. If you have some knowledge of SCSI programming, please help us implement generic SCSI support for VCDs.

In the meantime you can extract data from VCDs with readvcd and play the resulting file with MPlayer.

## VCD structure

A Video CD (VCD) is made up of CD-ROM XA sectors, i.e. CD-ROM mode 2 form 1 and 2 tracks:

- The first track is in mode 2 form 2 format which means it uses L2 error correction. The track contains an ISO-9660 file system with 2048 bytes/sector. This file system contains VCD metadata information, as well as still frames often used in menus. MPEG segments for menus can also be stored in this first track, but the MPEGs have to be broken up into a series of 150-sector chunks. The ISO-9660 file system may contain other files or programs that are not essential for VCD operation.

- The second and remaining tracks are generally raw 2324 bytes/sector MPEG (movie) tracks, containing one MPEG PS data packet per sector. These are in mode 2 form 1 format, so they store more data per sector at the loss of some error correction. It is also legal to have CD-DA tracks in a VCD after the first track as well. On some operating systems there is some trickery that goes on to make these non-ISO-9660 tracks appear in a file system. On other operating systems like GNU/Linux this is not the case (yet). Here the MPEG data cannot be mounted. As most movies are inside this kind of track, you should try `vcd://2` first.

- There exist VCD disks without the first track (single track and no file system at all). They are still playable, but cannot be mounted.

- The definition of the Video CD standard is called the Philips "White Book" and it is not generally available online as it must be purchased from Philips. More detailed information about Video CDs can be found in the vcdimager documentation.

## About .DAT files

The ~600 MB file visible on the first track of the mounted VCD is not a real file! It is a so called ISO gateway, created to allow Windows to handle such tracks (Windows does not allow raw device access to applications at all). Under Linux you cannot copy or play such files (they contain garbage). Under Windows it is possible as its iso9660 driver emulates the raw reading of tracks in this file. To play a .DAT file you need the kernel driver which can be found in the Linux version of PowerDVD. It has a modified iso9660 file system (`vcdfs/isofs-2.4.X.o`) driver, which is able to emulate the raw tracks through this shadow .DAT file. If you mount the disc using their driver, you can copy and even play .DAT files with MPlayer. But it will not work with the standard iso9660 driver of the Linux kernel! Use `vcd://` instead. Alternatives for VCD copying are the new cdfs kernel driver (not part of the official kernel) that shows CD sessions as image files and cdrdao, a bit-by-bit CD grabbing/copying application.

## Edit Decision Lists (EDL)

The edit decision list (EDL) system allows you to automatically skip or mute sections of videos during playback, based on a movie specific EDL configuration file.

This is useful for those who may want to watch a film in "family-friendly" mode. You can cut out any violence, profanity, Jar-Jar Binks .. from a movie according to your own personal preferences. Aside from this, there are other uses, like automatically skipping over commercials in video files you watch.

The EDL file format is pretty bare-bones. There is one command per line that indicates what to do (skip/mute) and when to do it (using pts in seconds).

### Using an EDL file

Include the `-edl <filename>` flag when you run MPlayer, with the name of the EDL file you want applied to the video.

### Making an EDL file

The current EDL file format is:

    [begin second] [end second] [action]

Where the seconds are floating-point numbers and the action is either `0` for skip or `1` for mute. Example:

    5.3   7.1    0
    15    16.7   1
    420   422    0

This will skip from second 5.3 to second 7.1 of the video, then mute at 15 seconds, unmute at 16.7 seconds and skip from second 420 to second 422 of the video. These actions will be performed when the playback timer reaches the times given in the file.

To create an EDL file to work from, use the `-edlout <filename>` flag. During playback, just hit i to mark the beginning and end of a skip block. A corresponding entry will be written to the file for that time. You can then go back and fine-tune the generated EDL file as well as change the default operation which is to skip the block described by each line.

## Synchronized playback over a network

Multiple instances of MPlayer can synchronize playback over a network. This is useful for creating "video walls" with multiple screens controlled by different computers. Each MPlayer instance can play a different video, but they all will try to stay at the same time offset in the file. It is recommended but not necessary to encode the video files using the same codec and parameters.

The relevant options are `-udp-master`, `-udp-slave`, `-udp-ip`, `-udp-port`, and `-udp-seek-threshold`.

If `-udp-master` is given, MPlayer sends a datagram to `-udp-ip` (default: 127.0.0.1) on `-udp-port` (default: 23867) just before playing each frame. The datagram indicates the master's position in the file. If `-udp-slave` is given, MPlayer listens on `-udp-ip`/`-udp-port` and matches the master's position. Setting `-udp-ip` to the master's broadcast address allows multiple slaves having the same broadcast address to sync to the master. Note that this feature assumes an ethernet-like low-latency network connection. Your mileage may vary on high latency networks.

For example, assume 8 computers are on a network, with IP addresses 192.168.0.1 through 192.168.0.8. Assume the first computer is to be the master. Running ifconfig on all the machines lists "Bcast:192.168.0.255". On the master, run:

    mplayer -udp-master -udp-ip 192.168.0.255 video1.mpg

On each slave, run:

    mplayer -udp-slave -udp-ip 192.168.0.255 videoN.mpg

Seeking, pausing and even playback speed adjustment (see the `-input` option) can be done on the master, and all the slaves will follow. When the master exits, it sends out a "bye" message which causes the slaves to exit as well.

## Surround/Multichannel playback

### DVDs

Most DVDs and many other files include surround sound. MPlayer 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 two channels of audio use `-channels`. For example, to play a DVD with 5.1 audio:

    mplayer dvd://1 -channels 6

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 MPlayer configuration file `~/.mplayer/config`. For example, to make quadraphonic playback the default, add this line:

    channels=4

MPlayer will then output audio in four channels when all four channels are available.

### Playing stereo files to four speakers

MPlayer does not duplicate any channels by default, and neither do most audio drivers. If you want to do that manually:

    mplayer filename -af channels=2:2:0:1:0:0

See the section on channel copying for an explanation.

### AC-3/DTS Passthrough

DVDs usually have surround audio encoded in AC-3 (Dolby Digital) or DTS (Digital Theater System) format. Some modern audio equipment is capable of decoding these formats internally. MPlayer can be configured to relay the audio data without decoding it. This will only work if you have a S/PDIF (Sony/Philips Digital Interface) jack in your sound card, or if you are passing audio over HDMI.

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

### To enable passthrough on the command line:

- For AC-3 only, use `-ac hwac3`

- For DTS only, use `-ac hwdts`

- For both AC-3 and DTS, use `-afm hwac3`

### To enable passthrough in the MPlayer configuration file:

- For AC-3 only, use `ac=hwac3,`

- For DTS only, use `ac=hwdts,`

- For both AC-3 and DTS, use `afm=hwac3`

Note that there is a comma (",") at the end of `ac=hwac3,` and `ac=hwdts,`. This will make MPlayer fall back on the codecs it normally uses when playing a file that does not have AC-3 or DTS audio. `afm=hwac3` does not need a comma; MPlayer will fall back anyway when an audio family is specified.

### MPEG audio Passthrough

Digital TV transmissions (such as DVB and ATSC) and some DVDs usually have MPEG audio streams (in particular MP2). Some MPEG hardware decoders such as full-featured DVB cards and DXR2 adapters can natively decode this format. MPlayer can be configured to relay the audio data without decoding it.

To use this codec:

     mplayer -ac hwmpa

### Matrix-encoded audio

***TODO***

This section has yet to be written and cannot be completed until somebody provides sample files for us to test. If you have any matrix-encoded audio files, know where to find some, or have any information that could be helpful, please send a message to the MPlayer-DOCS mailing list. Put "[matrix-encoded audio]" in the subject line.

If no files or further information are forthcoming this section will be dropped.

Good links:

- http://electronics.howstuffworks.com/surround-sound5.htm

- http://www.extremetech.com/article2/0,1697,1016875,00.asp

### Surround emulation in headphones

MPlayer includes an HRTF (Head Related Transfer Function) filter based on an MIT project wherein measurements were taken from microphones mounted on a dummy human head.

Although it is not possible to exactly imitate a surround system, MPlayer's HRTF filter does provide more spatially immersive audio in 2-channel headphones. Regular downmixing simply combines all the channels into two; besides combining the channels, `hrtf` generates subtle echoes, increases the stereo separation slightly, and alters the volume of some frequencies. Whether HRTF sounds better may be dependent on the source audio and a matter of personal taste, but it is definitely worth trying out.

To play a DVD with HRTF:

    mplayer dvd://1 -channels 6 -af hrtf

`hrtf` only works well with 5 or 6 channels. Also, `hrtf` 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 `hrtf` you must resample it:

    mplayer filename -channels 6 -af resample=48000,hrtf

### Troubleshooting

If you do not hear any sound out of your surround channels, check your mixer settings with a mixer program such as alsamixer; audio outputs are often muted and set to zero volume by default.

## Channel manipulation

### General information

Unfortunately, there is no standard for how channels are ordered. The orders listed below are those of AC-3 and are fairly typical; try them and see if your source matches. Channels are numbered starting with 0.

### mono

1. center

### stereo

1. left

2. right

### quadraphonic

1. left front

2. right front

3. left rear

4. right rear

### surround 4.0

1. left front

2. right front

3. center rear

4. center front

### surround 5.0

1. left front

2. right front

3. left rear

4. right rear

5. center front

### surround 5.1

1. left front

2. right front

3. left rear

4. right rear

5. center front

6. subwoofer

The `-channels` option is used to request the number of channels from the audio decoder. Some audio codecs 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 `-channels 4` to play a stereo MP3 file will still result in 2-channel output since the MP3 codec will not produce the extra channels.

The `channels` audio filter can be used to create or remove channels and is useful for controlling the number of channels sent to the sound card. See the following sections for more information on channel manipulation.

### Playing mono with two speakers

Mono sounds a lot better when played through two speakers - especially when using headphones. Audio files that truly have one channel are automatically played through two speakers; unfortunately, most files with mono sound are actually encoded as stereo with one channel silent. The easiest and most foolproof way to make both speakers output the same audio is the `extrastereo` filter:

    mplayer filename -af extrastereo=0

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, it may be easier to experiment with the `volume` filter and find the right value. For example:

    mplayer filename -af extrastereo=0,volume=5

### Channel copying/moving

The `channels` filter can move any or all channels. Setting up all the suboptions for the `channels` filter can be complicated and takes a little care.

1. Decide how many output channels you need. This is the first suboption.

2. Count how many channel moves you will do. This is the second suboption. Each channel can be moved to several different channels at the same time, but keep in mind that when a channel is moved (even if to only one destination) the source channel will be empty unless another channel is moved into it. To copy a channel, keeping the source the same, simply move the channel into both the destination and the source. For example:

       channel 2 --> channel 3
       channel 2 --> channel 2

3. Write out the channel copies as pairs of suboptions. Note that the first channel is 0, the second is 1, etc. The order of these suboptions does not matter as long as they are properly grouped into `source:destination` pairs.

Example: one channel in two speakers

Here is an example of another way to play one channel in both speakers. Suppose for this example that the left channel should be played and the right channel discarded. Following the steps above:

1. In order to provide an output channel for each of the two speakers, the first suboption must be "2".

2. The left channel needs to be moved to the right channel, and also must be moved to itself so it won't be empty. This is a total of two moves, making the second suboption "2" as well.

3. To move the left channel (channel 0) into the right channel (channel 1), the suboption pair is "0:1", "0:0" moves the left channel onto itself.

Putting that all together gives:

    mplayer filename -af channels=2:2:0:1:0:0

The advantage this example has over `extrastereo` is that the volume of each output channel is the same as the input channel. The disadvantage is that the suboptions must be changed to "2:2:1:0:1:1" when the desired audio is in the right channel. Also, it is more difficult to remember and type.

Example: left channel in two speakers shortcut

There is actually a much easier way to use the `channels` filter for playing the left channel in both speakers:

    mplayer filename -af channels=1

The second channel is discarded and, with no further suboptions, the single remaining channel is left alone. Sound card drivers automatically play single-channel audio in both speakers. This only works when the desired channel is on the left.

Example: duplicate front channels to the rear

Another common operation is to duplicate the front channels and play them back on the rear speakers of a quadraphonic setup.

1. There should be four output channels. The first suboption is "4".

2. Each of the two front channels needs to be moved to the corresponding rear channel and also to itself. This is four moves, so the second suboption is "4".

3. The left front (channel 0) needs to moved to the left rear (channel 2): "0:2". The left front also needs to be moved to itself: "0:0". The right front (channel 1) is moved to the right rear (channel 3): "1:3", and also to itself: "1:1".

Combine all the suboptions to get:

    mplayer filename -af channels=4:4:0:2:0:0:1:3:1:1

### Channel mixing

The `pan` filter can mix channels in user-specified proportions. This allows for everything the `channels` filter can do and more. Unfortunately, the suboptions are much more complicated.

1. Decide how many channels to work with. You may need to specify this with `-channels` and/or `-af channels`. Later examples will show when to use which.

2. Decide how many channels to feed into `pan` (further decoded channels are discarded). This is the first suboption, and it also controls how many channels to employ for output.

3. The remaining suboptions specify how much of each channel gets mixed into each other channel. This is the complicated part. To break the task down, split the suboptions into several sets, one set for each input channel. Each suboption within a set corresponds to an output channel. The number you specify will be the percentage of the input channel that gets mixed into the output channel.

   `pan` accepts values from 0 to 512, yielding 0% to 51200% of the original volume. Be careful when using values greater than 1. Not only can this give you very high volume, but if you exceed the sample range of your sound card you may hear painful pops and clicks. If you want you can follow `pan` with `,volume` to enable clipping, but it is best to keep the values of `pan` low enough that clipping is not necessary.

Example: one channel in two speakers

Here is yet another example for playing the left channel in two speakers. Follow the steps above:

1. `pan` should output two channels, so the first suboption is "2".

2. Since we have two input channels, there will be two sets of suboptions. Since there are also two output channels, there will be two suboptions per set. The left channel from the file should go with full volume to the new left and the right channels. Thus the first set of suboptions is "1:1". The right channel should be discarded, so the second would be "0:0". Any 0 values at the end can be left out, but for ease of understanding we will keep them.

Putting those options together gives:

    mplayer filename -af pan=2:1:1:0:0

If the right channel is desired instead of the left, the suboptions to `pan` will be "2:0:0:1:1".

Example: left channel in two speakers shortcut

As with `channels`, there is a shortcut that only works with the left channel:

    mplayer filename -af pan=1:1

Since `pan` has only one channel of input (the other channel is discarded), there is only one set with one suboption, which specifies that the only channel gets 100% of itself.

Example: downmixing 6-channel PCM

MPlayer's decoder for 6-channel PCM is not capable of downmixing. Here is a way to downmix PCM using `pan`:

1. The number of output channels is 2, so the first suboption is "2".

2. With six input channels there will be six sets of options. Fortunately, since we only care about the output of the first two channels, we only need to make two sets; the remaining four sets can be omitted. Beware that not all multichannel audio files have the same channel order! This example demonstrates downmixing a file with the same channels as AC-3 5.1:

       0 - front left
       1 - front right
       2 - rear left
       3 - rear right
       4 - center front
       5 - subwoofer

   The first set of suboptions lists the percentages of the original volume, in order, which each output channel should receive from the front left channel: "1:0". The front right channel should go into the right output: "0:1". The same for the rear channels: "1:0" and "0:1". The center channel goes into both output channels with half volume: "0.5:0.5", and the subwoofer goes into both with full volume: "1:1".

Put all that together, for:

    mplayer 6-channel.wav -af pan=2:1:0:0:1:1:0:0:1:0.5:0.5:1:1

The percentages listed above are only a rough example. Feel free to tweak them.

Example: Playing 5.1 audio on big speakers without a subwoofer

If you have a huge pair of front speakers you may not want to waste any money on buying a subwoofer for a complete 5.1 sound system. If you use `-channels 5` to request that liba52 decode 5.1 audio in 5.0, the subwoofer channel is simply discarded. If you want to distribute the subwoofer channel yourself you need to downmix manually with `pan`:

1. Since `pan` needs to examine all six channels, specify `-channels 6` so liba52 decodes them all.

2. `pan` outputs to only five channels, the first suboption is 5.

3. Six input channels and five output channels means six sets of five suboptions.

   - The left front channel only replicates onto itself: "1:0:0:0:0"

   - Same for the right front channel: "0:1:0:0:0"

   - Same for the left rear channel: "0:0:1:0:0"

   - And also the same for the right rear channel: "0:0:0:1:0"

   - Center front, too: "0:0:0:0:1"

   - And now we have to decide what to do with the subwoofer, e.g. half into front right and front left: "0.5:0.5:0:0:0"

Combine all those options to get:

    mplayer dvd://1 -channels 6 -af pan=5:1:0:0:0:0:0:1:0:0:0:0:0:1:0:0:0:0:0:1:0:0:0:0:0:1:0.5:0.5:0:0:0

## Software Volume adjustment

Some audio tracks are too quiet to be heard comfortably without amplification. This becomes a problem when your audio equipment cannot amplify the signal for you. The `-softvol` option directs MPlayer to use an internal mixer. You can then use the volume adjustment keys (by default 9 and 0) to reach much higher volume levels. Note that this does not bypass your sound card's mixer; MPlayer only amplifies the signal before sending it to your sound card. The following example is a good start:

    mplayer quiet-file -softvol -softvol-max 300

The `-softvol-max` option specifies the maximum allowable output volume as a percentage of the original volume. For example, `-softvol-max 200` would allow the volume to be adjusted up to twice its original level. It is safe to specify a large value with `-softvol-max`; the higher volume will not be used until you use the volume adjustment keys. The only disadvantage of a large value is that, since MPlayer adjusts volume by a percentage of the maximum, you will not have as precise control when using the volume adjustment keys. Use a lower value with `-softvol-max` and/or specify `-volstep 1` if you need higher precision.

The `-softvol` option works by controlling the `volume` audio filter. If you want to play a file at a certain volume from the beginning you can specify `volume` manually:

    mplayer quiet-file -af volume=10

This will play the file with a ten decibel gain. Be careful when using the `volume` filter - you could easily hurt your ears if you use too high a value. Start low and work your way up gradually until you get a feel for how much adjustment is required. Also, if you specify excessively high values, `volume` may need to clip the signal to avoid sending your sound card data that is outside the allowable range; this will result in distorted audio.

## TV input

This section is about how to enable watching/grabbing from V4L compatible TV tuner. See the man page for a description of TV options and keyboard controls.

### Usage tips

The full listing of the options is available on the manual page. Here are just a few tips:

- Make sure your tuner works with another TV software in Linux, for example XawTV.

- Use the `channels` option. An example:

      -tv channels=26-MTV1,23-TV2

  Explanation: Using this option, only the 26 and 23 channels will be usable, and there will be a nice OSD text upon channel switching, displaying the channel's name. Spaces in the channel name must be replaced by the "_" character.

- Choose some sane image dimensions. The dimensions of the resulting image should be divisible by 16.

- If you capture the video with the vertical resolution higher than half of the full resolution (i.e. 288 for PAL or 240 for NTSC), then the 'frames' you get will really be interleaved pairs of fields. Depending on what you want to do with the video you may leave it in this form, destructively deinterlace, or break the pairs apart into individual fields.

  Otherwise you'll get a movie which is distorted during fast-motion scenes and the bitrate controller will be probably even unable to retain the specified bitrate as the interlacing artifacts produce high amount of detail and thus consume lot of bandwidth. You can enable deinterlacing with `-vf pp=DEINT_TYPE`. Usually `pp=lb` does a good job, but it can be matter of personal preference. See other deinterlacing algorithms in the manual and give it a try.

- Crop out the dead space. When you capture the video, the areas at the edges are usually black or contain some noise. These again consume lots of unnecessary bandwidth. More precisely it's not the black areas themselves but the sharp transitions between the black and the brighter video image which do but that's not important for now. Before you start capturing, adjust the arguments of the `crop` option so that all the crap at the margins is cropped out. Again, don't forget to keep the resulting dimensions sane.

- Watch out for CPU load. It shouldn't cross the 90% boundary for most of the time. If you have a large capture buffer, MEncoder can survive an overload for few seconds but nothing more. It's better to turn off the 3D OpenGL screensavers and similar stuff.

- Don't mess with the system clock. MEncoder uses the system clock for doing A/V sync. If you adjust the system clock (especially backwards in time), MEncoder gets confused and you will lose frames. This is an important issue if you are hooked to a network and run some time synchronization software like NTP. You have to turn NTP off during the capture process if you want to capture reliably.

- Don't change the `outfmt` unless you know what you are doing or your card/driver really doesn't support the default (YV12 colorspace). In the older versions of MPlayer/ MEncoder it was necessary to specify the output format. This issue should be fixed in the current releases and `outfmt` isn't required anymore, and the default suits the most purposes. For example, if you are capturing into DivX using `libavcodec` and specify `outfmt=RGB24` in order to increase the quality of the captured images, the captured image will be actually later converted back into YV12 so the only thing you achieve is a massive waste of CPU power.

- There are several ways of capturing audio. You can grab the sound either using your sound card via an external cable connection between video card and line-in, or using the built-in ADC in the bt878 chip. In the latter case, you have to load the btaudio driver. Read the `linux/Documentation/sound/btaudio` file (in the kernel tree, not MPlayer's) for some instructions on using this driver.

- If MEncoder cannot open the audio device, make sure that it is really available. There can be some trouble with the sound servers like aRts (KDE) or ESD (GNOME). If you have a full duplex sound card (almost any decent card supports it today), and you are using KDE, try to check the "full duplex" option in the sound server preference menu.

### Examples

Dummy output, to AAlib :)

    mplayer -tv driver=dummy:width=640:height=480 -vo aa tv://

Input from standard V4L:

    mplayer -tv driver=v4l:width=640:height=480:outfmt=i420 -vc rawi420 -vo xv tv://

A more sophisticated example. This makes MEncoder capture the full PAL image, crop the margins, and deinterlace the picture using a linear blend algorithm. Audio is compressed with a constant bitrate of 64kbps, using LAME codec. This setup is suitable for capturing movies.

    mencoder -tv driver=v4l:width=768:height=576 -oac mp3lame -lameopts cbr:br=64\
        -ovc lavc -lavcopts vcodec=mpeg4:vbitrate=900 \
        -vf crop=720:544:24:16,pp=lb -o output.avi tv://

This will additionally rescale the image to 384x288 and compresses the video with the bitrate of 350kbps in high quality mode. The vqmax option looses the quantizer and allows the video compressor to actually reach so low bitrate even at the expense of the quality. This can be used for capturing long TV series, where the video quality isn't so important.

    mencoder -tv driver=v4l:width=768:height=576 \
        -ovc lavc -lavcopts vcodec=mpeg4:vbitrate=350:vhq:vqmax=31:keyint=300 \
        -oac mp3lame -lameopts cbr:br=48 -sws 1 -o output.avi\
        -vf crop=720:540:24:18,pp=lb,scale=384:288 tv://

It's also possible to specify smaller image dimensions in the `-tv` option and omit the software scaling but this approach uses the maximum available information and is a little more resistant to noise. The bt8x8 chips can do the pixel averaging only in the horizontal direction due to a hardware limitation.

## Teletext

Teletext is currently available only in MPlayer for v4l and v4l2 drivers.

### Implementation notes

MPlayer supports regular text, graphics and navigation links. Unfortunately, colored pages are not fully supported yet - all pages are shown as grayscaled. Subtitle pages (also known as Closed Captions) are supported, too.

MPlayer starts caching all teletext pages upon starting to receive TV input, so you do not need to wait until the requested page is loaded.

Note: Using teletext with `-vo xv` causes strange colors.

### Using teletext

To enable teletext decoding you must specify the VBI device to get teletext data from (usually `/dev/vbi0` for Linux). This can be done by specifying `tdevice` in your configuration file, like shown below:

    tv=tdevice=/dev/vbi0

You might need to specify the teletext language code for your country. To list all available country codes use

    tv=tdevice=/dev/vbi0:tlang=-1

Here is an example for Russian:

    tv=tdevice=/dev/vbi0:tlang=33

## Radio

This section is about how to enable listening to radio from a V4L-compatible radio tuner. See the man page for a description of radio options and keyboard controls.

### Usage tips

The full listing of the options is available in the manual page. Here are just a few tips:

- Make sure your tuner works with another radio software in Linux, for example XawTV.

- Use the `channels` option. An example:

      -radio channels=104.4-Sibir,103.9-Maximum

  Explanation: With this option, only the 104.4 and 103.9 radio stations will be usable. There will be a nice OSD text upon channel switching, displaying the channel's name. Spaces in the channel name must be replaced by the "_" character.

- There are several ways of capturing audio. You can grab the sound either using your sound card via an external cable connection between video card and line-in, or using the built-in ADC in the saa7134 chip. In the latter case, you have to load the `saa7134-alsa` or `saa7134-oss` driver.

- MEncoder cannot be used for audio capture, because it requires a video stream to work. So your can either use arecord from ALSA project or use `-ao pcm:file=file.wav`. In the latter case you will not hear any sound (unless you are using a line-in cable and have switched line-in mute off).

### Examples

Input from standard V4L (using line-in cable, capture switched off):

    mplayer radio://104.4

Input from standard V4L (using line-in cable, capture switched off, V4Lv1 interface):

    mplayer -radio driver=v4l radio://104.4

Playing second channel from channel list:

    mplayer -radio channels=104.4=Sibir,103.9=Maximm radio://2

Passing sound over the PCI bus from the radio card's internal ADC. In this example the tuner is used as a second sound card (ALSA device hw:1,0). For saa7134-based cards either the `saa7134-alsa` or `saa7134-oss` module must be loaded.

    mplayer -rawaudio rate=32000 radio://2/capture \
        -radio adevice=hw=1.0:arate=32000:channels=104.4=Sibir,103.9=Maximm

When using ALSA device names colons must be replaced by equal signs, commas by periods.