RepoMirrors
/
mpv
mirror of https://github.com/mpv-player/mpv
1
0
Fork 0
Code Issues Releases Wiki Activity

manpage: proofread and fix formatting

This commit is contained in:
Martin Herkt 2013-07-08 18:02:14 +02:00
parent 1a8ab1d6ad
commit 09d2dd7c3a
9 changed files with 2228 additions and 2106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

442
DOCS/man/en/af.rst
View File

@ -1,79 +1,74 @@
.. _audio_filters:
AUDIO FILTERS
=============
Audio filters allow you to modify the audio stream and its properties. The
syntax is:
--af=<filter1[=parameter1:parameter2:...],filter2,...>
``--af=<filter1[=parameter1:parameter2:...],filter2,...>``
Setup a chain of audio filters.
*NOTE*: To get a full list of available audio filters, see ``--af=help``.
.. note::
To get a full list of available audio filters, see ``--af=help``.
Audio filters are managed in lists. There are a few commands to manage the
filter list.
filter list:
--af-add=<filter1[,filter2,...]>
``--af-add=<filter1[,filter2,...]>``
Appends the filters given as arguments to the filter list.
--af-pre=<filter1[,filter2,...]>
``--af-pre=<filter1[,filter2,...]>``
Prepends the filters given as arguments to the filter list.
--af-del=<index1[,index2,...]>
``--af-del=<index1[,index2,...]>``
Deletes the filters at the given indexes. Index numbers start at 0,
negative numbers address the end of the list (-1 is the last).
--af-clr
``--af-clr``
Completely empties the filter list.
Available filters are:
lavrresample[=option1:option2:...]
``lavrresample[=option1:option2:...]``
This filter uses libavresample (or libswresample, depending on the build)
to change sample rate, sample format, or channel layout of the audio stream.
This filter is automatically enabled if the audio output doesn't support
This filter is automatically enabled if the audio output does not support
the audio configuration of the file being played.
It supports only the following sample formats: u8, s16ne, s32ne, floatne.
srate=<srate>
the output sample rate
length=<length>
length of the filter with respect to the lower sampling rate (default:
``srate=<srate>``
The output sample rate.
``length=<length>``
Length of the filter with respect to the lower sampling rate. (default:
16)
phase_shift=<count>
log2 of the number of polyphase entries (..., 10->1024, 11->2048,
``phase_shift=<count>``
Log2 of the number of polyphase entries. (..., 10->1024, 11->2048,
12->4096, ...) (default: 10->1024)
cutoff=<cutoff>
cutoff frequency (0.0-1.0), default set depending upon filter length
linear
if set then filters will be linearly interpolated between polyphase
entries (default: no)
no-detach
don't detach if input and output audio format/rate/channels are the
same. You should add this option if you specify additional parameters,
as automatically inserted lavrresample instances will use the
default settings.
``cutoff=<cutoff>``
Cutoff frequency (0.0-1.0), default set depending upon filter length.
``linear``
If set then filters will be linearly interpolated between polyphase
entries. (default: no)
``no-detach``
Do not detach if input and output audio format/rate/channels match.
You should add this option if you specify additional parameters, as
automatically inserted lavrresample instances will use the default
settings.
lavcac3enc[=tospdif[:bitrate[:minchn]]]
``lavcac3enc[=tospdif[:bitrate[:minchn]]]``
Encode multi-channel audio to AC-3 at runtime using libavcodec. Supports
16-bit native-endian input format, maximum 6 channels. The output is
big-endian when outputting a raw AC-3 stream, native-endian when
outputting to S/PDIF. The output sample rate of this filter is same with
the input sample rate. When input sample rate is 48kHz, 44.1kHz, or 32kHz,
this filter directly use it. Otherwise a resampling filter is
auto-inserted before this filter to make the input and output sample rate
be 48kHz. You need to specify ``--channels=N`` to make the decoder decode
audio into N-channel, then the filter can encode the N-channel input to
AC-3.
outputting to S/PDIF. If the input sample rate is not 48 kHz, 44.1 kHz or
32 kHz, it will be resampled to 48 kHz.
<tospdif>
``<tospdif>``
Output raw AC-3 stream if zero or not set, output to S/PDIF for
passthrough when <tospdif> is set non-zero.
<bitrate>
The bitrate to encode the AC-3 stream. Set it to either 384 or 384000
to get 384kbits.
passthrough when ``<tospdif>`` is set non-zero.
``<bitrate>``
The bitrate use for the AC-3 stream. Set it to either 384 or 384000
to get 384 kbps.
Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128,
160, 192, 224, 256, 320, 384, 448, 512, 576, 640.
@ -87,41 +82,41 @@ lavcac3enc[=tospdif[:bitrate[:minchn]]]
:5ch: 448
:6ch: 448
<minchn>
If the input channel number is less than <minchn>, the filter will
``<minchn>``
If the input channel number is less than ``<minchn>``, the filter will
detach itself (default: 5).
sweep[=speed]
``sweep[=speed]``
Produces a sine sweep.
<0.0-1.0>
``<0.0-1.0>``
Sine function delta, use very low values to hear the sweep.
sinesuppress[=freq:decay]
``sinesuppress[=freq:decay]``
Remove a sine at the specified frequency. Useful to get rid of the 50/60Hz
noise on low quality audio equipment. It probably only works on mono input.
noise on low quality audio equipment. It only works on mono input.
<freq>
``<freq>``
The frequency of the sine which should be removed (in Hz) (default:
50)
<decay>
``<decay>``
Controls the adaptivity (a larger value will make the filter adapt to
amplitude and phase changes quicker, a smaller value will make the
adaptation slower) (default: 0.0001). Reasonable values are around
0.001.
bs2b[=option1:option2:...]
Bauer stereophonic to binaural transformation using ``libbs2b``. Improves
the headphone listening experience by making the sound similar to that
from loudspeakers, allowing each ear to hear both channels and taking into
``bs2b[=option1:option2:...]``
Bauer stereophonic to binaural transformation using libbs2b. Improves the
headphone listening experience by making the sound similar to that from
loudspeakers, allowing each ear to hear both channels and taking into
account the distance difference and the head shadowing effect. It is
applicable only to 2 channel audio.
applicable only to 2-channel audio.
fcut=<300-1000>
``fcut=<300-1000>``
Set cut frequency in Hz.
feed=<10-150>
``feed=<10-150>``
Set feed level for low frequencies in 0.1*dB.
profile=<value>
``profile=<value>``
Several profiles are available for convenience:
:default: will be used if nothing else was specified (fcut=700,
@ -129,11 +124,11 @@ bs2b[=option1:option2:...]
:cmoy: Chu Moy circuit implementation (fcut=700, feed=60)
:jmeier: Jan Meier circuit implementation (fcut=650, feed=95)
If fcut or feed options are specified together with a profile, they will
be applied on top of the selected profile.
If ``fcut`` or ``feed`` options are specified together with a profile, they
will be applied on top of the selected profile.
hrtf[=flag]
Head-related transfer function: Converts multichannel audio to 2 channel
``hrtf[=flag]``
Head-related transfer function: Converts multichannel audio to 2-channel
output for headphones, preserving the spatiality of the sound.
==== ===================================
@ -144,8 +139,8 @@ hrtf[=flag]
0 no matrix decoding (default)
==== ===================================
equalizer=[g1:g2:g3:...:g10]
10 octave band graphic equalizer, implemented using 10 IIR band pass
``equalizer=[g1:g2:g3:...:g10]``
10 octave band graphic equalizer, implemented using 10 IIR band-pass
filters. This means that it works regardless of what type of audio is
being played back. The center frequencies for the 10 bands are:
@ -169,48 +164,50 @@ equalizer=[g1:g2:g3:...:g10]
bug with this filter is that the characteristics for the uppermost band
are not completely symmetric if the sample rate is close to the center
frequency of that band. This problem can be worked around by upsampling
the sound using the resample filter before it reaches this filter.
the sound using a resampling filter before it reaches this filter.
<g1>:<g2>:<g3>:...:<g10>
``<g1>:<g2>:<g3>:...:<g10>``
floating point numbers representing the gain in dB for each frequency
band (-12-12)
*EXAMPLE*:
.. admonition:: Example
``mpv --af=equalizer=11:11:10:5:0:-12:0:5:12:12 media.avi``
Would amplify the sound in the upper and lower frequency region while
canceling it almost completely around 1kHz.
``mpv --af=equalizer=11:11:10:5:0:-12:0:5:12:12 media.avi``
Would amplify the sound in the upper and lower frequency region
while canceling it almost completely around 1kHz.
channels=nch[:nr:from1:to1:from2:to2:from3:to3:...]
``channels=nch[:nr:from1:to1:from2:to2:from3:to3:...]``
Can be used for adding, removing, routing and copying audio channels. If
only <nch> is given the default routing is used, it works as follows: If
the number of output channels is bigger than the number of input channels
empty channels are inserted (except mixing from mono to stereo, then the
mono channel is repeated in both of the output channels). If the number of
output channels is smaller than the number of input channels the exceeding
only ``<nch>`` is given, the default routing is used. It works as follows:
If the number of output channels is greater than the number of input
channels, empty channels are inserted (except when mixing from mono to
stereo; then the mono channel is duplicated). If the number of output
channels is less than the number of input channels, the exceeding
channels are truncated.
<nch>
``<nch>``
number of output channels (1-8)
<nr>
``<nr>``
number of routes (1-8)
<from1:to1:from2:to2:from3:to3:...>
``<from1:to1:from2:to2:from3:to3:...>``
Pairs of numbers between 0 and 7 that define where to route each
channel.
*EXAMPLE*:
.. admonition:: Examples
``mpv --af=channels=4:4:0:1:1:0:2:2:3:3 media.avi``
Would change the number of channels to 4 and set up 4 routes that swap
channel 0 and channel 1 and leave channel 2 and 3 intact. Observe that
if media containing two channels was played back, channels 2 and 3
would contain silence but 0 and 1 would still be swapped.
``mpv --af=channels=4:4:0:1:1:0:2:2:3:3 media.avi``
Would change the number of channels to 4 and set up 4 routes that
swap channel 0 and channel 1 and leave channel 2 and 3 intact.
Observe that if media containing two channels were played back,
channels 2 and 3 would contain silence but 0 and 1 would still be
swapped.
``mpv --af=channels=6:4:0:0:0:1:0:2:0:3 media.avi``
Would change the number of channels to 6 and set up 4 routes that copy
channel 0 to channels 0 to 3. Channel 4 and 5 will contain silence.
``mpv --af=channels=6:4:0:0:0:1:0:2:0:3 media.avi``
Would change the number of channels to 6 and set up 4 routes that
copy channel 0 to channels 0 to 3. Channel 4 and 5 will contain
silence.
force=in-format:in-srate:in-channels:out-format:out-srate:out-channels
``force=in-format:in-srate:in-channels:out-format:out-srate:out-channels``
Force a specific audio format/configuration without actually changing the
audio data. Keep in mind that the filter system might auto-insert actual
conversion filters before or after this filter if needed.
@ -220,49 +217,43 @@ force=in-format:in-srate:in-channels:out-format:out-srate:out-channels
actually doing a conversion. The data will be 'reinterpreted' by the
filters or audio outputs following this filter.
<in-format>
``<in-format>``
Force conversion to this format. See ``format`` filter for valid audio
format values.
<in-srate>
``<in-srate>``
Force conversion to a specific sample rate. The rate is an integer,
48000 for example.
<in-channels>
``<in-channels>``
Force mixing to a specific channel layout. See ``--channels`` option
for possible values.
<out-format>
``<out-format>``
<out-srate>
``<out-srate>``
<out-channels>
``<out-channels>``
format[=format]
``format[=format]``
Convert between different sample formats. Automatically enabled when
needed by the sound card or another filter. See also ``--format``.
needed by the audio output or another filter. See also ``--format``.
<format>
``<format>``
Sets the desired format. The general form is 'sbe', where 's' denotes
the sign (either 's' for signed or 'u' for unsigned), 'b' denotes the
number of bits per sample (16, 24 or 32) and 'e' denotes the
endianness ('le' means little-endian, 'be' big-endian and 'ne' the
endianness of the computer mpv is running on). Valid values
(amongst others) are: 's16le', 'u32be' and 'u24ne'. Exceptions to this
rule that are also valid format specifiers: u8, s8, floatle, floatbe,
floatne, mpeg2, and ac3.
endianness of the computer mpv is running on). Valid values (amongst
others) are: 's16le', 'u32be' and 'u24ne'. Exceptions to this rule that
are also valid format specifiers: u8, s8, floatle, floatbe, floatne,
mpeg2, and ac3.
volume[=v[:sc[:fast]]]
``volume[=v[:sc[:fast]]]``
Implements software volume control. Use this filter with caution since it
can reduce the signal to noise ratio of the sound. In most cases it is
best to set the level for the PCM sound to max, leave this filter out and
control the output level to your speakers with the master volume control
of the mixer. In case your sound card has a digital PCM mixer instead of
an analog one, and you hear distortion, use the MASTER mixer instead. If
there is an external amplifier connected to the computer (this is almost
always the case), the noise level can be minimized by adjusting the master
level and the volume knob on the amplifier until the hissing noise in the
background is gone.
best to use the *Master* volume control of your sound card or the volume
knob on your amplifier.
This filter has a second feature: It measures the overall maximum sound
level and prints out that level when mpv exits. This feature currently
@ -271,128 +262,131 @@ volume[=v[:sc[:fast]]]
*NOTE*: This filter is not reentrant and can therefore only be enabled
once for every audio stream.
<v>
``<v>``
Sets the desired gain in dB for all channels in the stream from -200dB
to +60dB, where -200dB mutes the sound completely and +60dB equals a
gain of 1000 (default: 0).
<sc>
``<sc>``
Turns soft clipping on (1) or off (0). Soft-clipping can make the
sound more smooth if very high volume levels are used. Enable this
option if the dynamic range of the loudspeakers is very low.
*WARNING*: This feature creates distortion and should be considered a
last resort.
<fast>
``<fast>``
Force S16 sample format if set to 1. Lower quality, but might be faster
in some situations.
*EXAMPLE*:
.. admonition:: Example
``mpv --af=volume=10.1:0 media.avi``
Would amplify the sound by 10.1dB and hard-clip if the sound level is
too high.
``mpv --af=volume=10.1:0 media.avi``
Would amplify the sound by 10.1dB and hard-clip if the sound level
is too high.
pan=n[:L00:L01:L02:...L10:L11:L12:...Ln0:Ln1:Ln2:...]
``pan=n[:L00:L01:L02:...L10:L11:L12:...Ln0:Ln1:Ln2:...]``
Mixes channels arbitrarily. Basically a combination of the volume and the
channels filter that can be used to down-mix many channels to only a few,
e.g. stereo to mono or vary the "width" of the center speaker in a
e.g. stereo to mono, or vary the "width" of the center speaker in a
surround sound system. This filter is hard to use, and will require some
tinkering before the desired result is obtained. The number of options for
this filter depends on the number of output channels. An example how to
downmix a six-channel file to two channels with this filter can be found
in the examples section near the end.
<n>
number of output channels (1-8)
<Lij>
``<n>``
Number of output channels (1-8).
``<Lij>``
How much of input channel i is mixed into output channel j (0-1). So
in principle you first have n numbers saying what to do with the first
input channel, then n numbers that act on the second input channel
etc. If you do not specify any numbers for some input channels, 0 is
assumed.
*EXAMPLE*:
.. admonition:: Examples
``mpv --af=pan=1:0.5:0.5 media.avi``
Would down-mix from stereo to mono.
``mpv --af=pan=1:0.5:0.5 media.avi``
Would downmix from stereo to mono.
``mpv --af=pan=3:1:0:0.5:0:1:0.5 media.avi``
Would give 3 channel output leaving channels 0 and 1 intact, and mix
channels 0 and 1 into output channel 2 (which could be sent to a
subwoofer for example).
``mpv --af=pan=3:1:0:0.5:0:1:0.5 media.avi``
Would give 3 channel output leaving channels 0 and 1 intact, and mix
channels 0 and 1 into output channel 2 (which could be sent to a
subwoofer for example).
*NOTE*: if you just want to force remixing to a certain output channel
layout, it's easier to use the ``force`` filter. For example,
``mpv '--af=force=channels=5.1' '--channels=5.1'`` would always force
remixing audio to 5.1 and output it like this.
.. note::
sub[=fc:ch]
If you just want to force remixing to a certain output channel
layout, it is easier to use the ``force`` filter. For example,
``mpv '--af=force=channels=5.1' '--channels=5.1'`` would always
force remixing audio to 5.1 and output it like this.
``sub[=fc:ch]``
Adds a subwoofer channel to the audio stream. The audio data used for
creating the subwoofer channel is an average of the sound in channel 0 and
channel 1. The resulting sound is then low-pass filtered by a 4th order
Butterworth filter with a default cutoff frequency of 60Hz and added to a
separate channel in the audio stream.
*Warning*: Disable this filter when you are playing DVDs with Dolby
Digital 5.1 sound, otherwise this filter will disrupt the sound to the
subwoofer.
.. warning::
<fc>
Disable this filter when you are playing media with an LFE channel
(e.g. 5.1 surround sound), otherwise this filter will disrupt the sound
to the subwoofer.
``<fc>``
cutoff frequency in Hz for the low-pass filter (20Hz to 300Hz)
(default: 60Hz) For the best result try setting the cutoff frequency
as low as possible. This will improve the stereo or surround sound
experience.
<ch>
``<ch>``
Determines the channel number in which to insert the sub-channel
audio. Channel number can be between 0 and 7 (default: 5). Observe
that the number of channels will automatically be increased to <ch> if
necessary.
*EXAMPLE*:
.. admonition:: Example
``mpv --af=sub=100:4 --channels=5 media.avi``
Would add a sub-woofer channel with a cutoff frequency of 100Hz to
output channel 4.
``mpv --af=sub=100:4 --channels=5 media.avi``
Would add a subwoofer channel with a cutoff frequency of 100Hz to
output channel 4.
center
``center``
Creates a center channel from the front channels. May currently be low
quality as it does not implement a high-pass filter for proper extraction
yet, but averages and halves the channels instead.
<ch>
``<ch>``
Determines the channel number in which to insert the center channel.
Channel number can be between 0 and 7 (default: 5). Observe that the
number of channels will automatically be increased to <ch> if
number of channels will automatically be increased to ``<ch>`` if
necessary.
surround[=delay]
Decoder for matrix encoded surround sound like Dolby Surround. Many files
with 2 channel audio actually contain matrixed surround sound. Requires a
sound card supporting at least 4 channels.
``surround[=delay]``
Decoder for matrix encoded surround sound like Dolby Surround. Some files
with 2-channel audio actually contain matrix encoded surround sound.
<delay>
``<delay>``
delay time in ms for the rear speakers (0 to 1000) (default: 20) This
delay should be set as follows: If d1 is the distance from the
listening position to the front speakers and d2 is the distance from
the listening position to the rear speakers, then the delay should be
set to 15ms if d1 <= d2 and to 15 + 5*(d1-d2) if d1 > d2.
*EXAMPLE*:
.. admonition:: Example
``mpv --af=surround=15 --channels=4 media.avi``
Would add surround sound decoding with 15ms delay for the sound to the
rear speakers.
``mpv --af=surround=15 --channels=4 media.avi``
Would add surround sound decoding with 15ms delay for the sound to
the rear speakers.
delay[=ch1:ch2:...]
``delay[=ch1:ch2:...]``
Delays the sound to the loudspeakers such that the sound from the
different channels arrives at the listening position simultaneously. It is
only useful if you have more than 2 loudspeakers.
ch1,ch2,...
``ch1,ch2,...``
The delay in ms that should be imposed on each channel (floating point
number between 0 and 1000).
To calculate the required delay for the different channels do as follows:
To calculate the required delay for the different channels, do as follows:
1. Measure the distance to the loudspeakers in meters in relation to your
listening position, giving you the distances s1 to s5 (for a 5.1
@ -405,46 +399,47 @@ delay[=ch1:ch2:...]
3. Calculate the required delays in ms as ``d[i] = 1000*s[i]/342; i =
1...5``.
*EXAMPLE*:
.. admonition:: Example
``mpv --af=delay=10.5:10.5:0:0:7:0 media.avi``
Would delay front left and right by 10.5ms, the two rear channels and
the sub by 0ms and the center channel by 7ms.
``mpv --af=delay=10.5:10.5:0:0:7:0 media.avi``
Would delay front left and right by 10.5ms, the two rear channels
and the subwoofer by 0ms and the center channel by 7ms.
export[=mmapped_file[:nsamples]]
``export[=mmapped_file[:nsamples]]``
Exports the incoming signal to other processes using memory mapping
(``mmap()``). Memory mapped areas contain a header:
(``mmap()``). Memory mapped areas contain a header::
| int nch /\* number of channels \*/
| int size /\* buffer size \*/
| unsigned long long counter /\* Used to keep sync, updated every time new data is exported. \*/
int nch /* number of channels */
int size /* buffer size */
unsigned long long counter /* Used to keep sync, updated every time
new data is exported. */
The rest is payload (non-interleaved) 16 bit data.
The rest is payload (non-interleaved) 16-bit data.
<mmapped_file>
file to map data to (default: ``~/.mpv/mpv-af_export``)
<nsamples>
number of samples per channel (default: 512)
``<mmapped_file>``
File to map data to (default: ``~/.mpv/mpv-af_export``).
``<nsamples>``
number of samples per channel (default: 512).
*EXAMPLE*:
.. admonition:: Example
``mpv --af=export=/tmp/mpv-af_export:1024 media.avi``
Would export 1024 samples per channel to ``/tmp/mpv-af_export``.
``mpv --af=export=/tmp/mpv-af_export:1024 media.avi``
Would export 1024 samples per channel to ``/tmp/mpv-af_export``.
extrastereo[=mul]
``extrastereo[=mul]``
(Linearly) increases the difference between left and right channels which
adds some sort of "live" effect to playback.
<mul>
``<mul>``
Sets the difference coefficient (default: 2.5). 0.0 means mono sound
(average of both channels), with 1.0 sound will be unchanged, with
-1.0 left and right channels will be swapped.
drc[=method:target]
``drc[=method:target]``
Applies dynamic range compression. This maximizes the volume by compressing
the audio signal's dynamic range.
<method>
``<method>``
Sets the used method.
1
@ -454,41 +449,46 @@ drc[=method:target]
Use several samples to smooth the variations via the standard
weighted mean over past samples.
<target>
``<target>``
Sets the target amplitude as a fraction of the maximum for the sample
type (default: 0.25).
*NOTE*: This filter can cause distortion with audio signals that have a
very large dynamic range.
.. note::
ladspa=file:label[:controls...]
This filter can cause distortion with audio signals that have a very
large dynamic range.
``ladspa=file:label[:controls...]``
Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin. This
filter is reentrant, so multiple LADSPA plugins can be used at once.
<file>
Specifies the LADSPA plugin library file. If ``LADSPA_PATH`` is set,
it searches for the specified file. If it is not set, you must supply
a fully specified pathname.
<label>
``<file>``
Specifies the LADSPA plugin library file.
.. note::
See also the note about the ``LADSPA_PATH`` variable in the
`ENVIRONMENT VARIABLES`_ section.
``<label>``
Specifies the filter within the library. Some libraries contain only
one filter, but others contain many of them. Entering 'help' here,
one filter, but others contain many of them. Entering 'help' here
will list all available filters within the specified library, which
eliminates the use of 'listplugins' from the LADSPA SDK.
<controls>
``<controls>``
Controls are zero or more floating point values that determine the
behavior of the loaded plugin (for example delay, threshold or gain).
In verbose mode (add ``-v`` to the mpv command line), all
available controls and their valid ranges are printed. This eliminates
the use of 'analyseplugin' from the LADSPA SDK.
karaoke
``karaoke``
Simple voice removal filter exploiting the fact that voice is usually
recorded with mono gear and later 'center' mixed onto the final audio
stream. Beware that this filter will turn your signal into mono. Works
well for 2 channel tracks; do not bother trying it on anything but 2
channel stereo.
scaletempo[=option1:option2:...]
``scaletempo[=option1:option2:...]``
Scales audio tempo without altering pitch, optionally synced to playback
speed (default).
@ -498,22 +498,22 @@ scaletempo[=option1:option2:...]
optionally performs a short statistical analysis on the next 'search' ms
of audio to determine the best overlap position.
scale=<amount>
``scale=<amount>``
Nominal amount to scale tempo. Scales this amount in addition to
speed. (default: 1.0)
stride=<amount>
Length in milliseconds to output each stride. Too high of value will
cause noticable skips at high scale amounts and an echo at low scale
``stride=<amount>``
Length in milliseconds to output each stride. Too high of a value will
cause noticeable skips at high scale amounts and an echo at low scale
amounts. Very low values will alter pitch. Increasing improves
performance. (default: 60)
overlap=<percent>
``overlap=<percent>``
Percentage of stride to overlap. Decreasing improves performance.
(default: .20)
search=<amount>
``search=<amount>``
Length in milliseconds to search for best overlap position. Decreasing
improves performance greatly. On slow systems, you will probably want
to set this very low. (default: 14)
speed=<tempo|pitch|both|none>
``speed=<tempo|pitch|both|none>``
Set response to speed change.
tempo
@ -524,39 +524,45 @@ scaletempo[=option1:option2:...]
1.059463094352953`` to your ``input.conf`` to step by musical
semi-tones.
*WARNING*: Loses sync with video.
.. warning::
Loses sync with video.
both
Scale both tempo and pitch.
none
Ignore speed changes.
*EXAMPLE*:
.. admonition:: Examples
``mpv --af=scaletempo --speed=1.2 media.ogg``
Would playback media at 1.2x normal speed, with audio at normal pitch.
Changing playback speed, would change audio tempo to match.
``mpv --af=scaletempo --speed=1.2 media.ogg``
Would play media at 1.2x normal speed, with audio at normal
pitch. Changing playback speed would change audio tempo to match.
``mpv --af=scaletempo=scale=1.2:speed=none --speed=1.2 media.ogg``
Would playback media at 1.2x normal speed, with audio at normal pitch,
but changing playback speed has no effect on audio tempo.
``mpv --af=scaletempo=scale=1.2:speed=none --speed=1.2 media.ogg``
Would play media at 1.2x normal speed, with audio at normal
pitch, but changing playback speed would have no effect on audio
tempo.
``mpv --af=scaletempo=stride=30:overlap=.50:search=10 media.ogg``
Would tweak the quality and performace parameters.
``mpv --af=scaletempo=stride=30:overlap=.50:search=10 media.ogg``
Would tweak the quality and performace parameters.
``mpv --af=format=floatne,scaletempo media.ogg``
Would make scaletempo use float code. Maybe faster on some platforms.
``mpv --af=format=floatne,scaletempo media.ogg``
Would make scaletempo use float code. Maybe faster on some
platforms.
``mpv --af=scaletempo=scale=1.2:speed=pitch audio.ogg``
Would playback audio file at 1.2x normal speed, with audio at normal
pitch. Changing playback speed, would change pitch, leaving audio
tempo at 1.2x.
``mpv --af=scaletempo=scale=1.2:speed=pitch audio.ogg``
Would play media at 1.2x normal speed, with audio at normal pitch.
Changing playback speed would change pitch, leaving audio tempo at
1.2x.
lavfi=graph
``lavfi=graph``
Filter audio using ffmpeg's libavfilter.
<graph>
``<graph>``
Libavfilter graph. See ``lavfi`` video filter for details - the graph
syntax is the same.
Warning: due to shortcomings in the current ``-af`` option parser code,
the filter graph must not contain any ``,``.
.. warning::
Due to shortcomings in the current ``-af`` option parser code,
the filter graph must not contain any ``,``.

122
DOCS/man/en/ao.rst
View File

@ -1,20 +1,20 @@
.. _audio_outputs:
AUDIO OUTPUT DRIVERS
====================
Audio output drivers are interfaces to different audio output facilities. The
syntax is:
--ao=<driver1[:suboption1[=value]:...],driver2,...[,]>
``--ao=<driver1[:suboption1[=value]:...],driver2,...[,]>``
Specify a priority list of audio output drivers to be used.
If the list has a trailing ',' mpv will fall back on drivers not contained
If the list has a trailing ',', mpv will fall back on drivers not contained
in the list. Suboptions are optional and can mostly be omitted.
*NOTE*: See ``--ao=help`` for a list of compiled-in audio output drivers.
.. note::
*EXAMPLE*:
See ``--ao=help`` for a list of compiled-in audio output drivers.
.. admonition:: Examples
- ``--ao=alsa,oss,`` Try the ALSA driver, then the OSS driver, then others.
- ``--ao=alsa:noblock:device=hw=0.3`` Sets noblock-mode and the device-name
@ -22,132 +22,132 @@ in the list. Suboptions are optional and can mostly be omitted.
Available audio output drivers are:
alsa
``alsa`` (Linux only)
ALSA 0.9/1.x audio output driver
noblock
``noblock``
Sets noblock-mode.
device=<device>
``device=<device>``
Sets the device name. Replace any ',' with '.' and any ':' with '=' in
the ALSA device name. For hwac3 output via S/PDIF, use an "iec958" or
"spdif" device, unless you really know how to set it correctly.
oss
``oss``
OSS audio output driver
<dsp-device>
``<dsp-device>``
Sets the audio output device (default: ``/dev/dsp``).
<mixer-device>
``<mixer-device>``
Sets the audio mixer device (default: ``/dev/mixer``).
<mixer-channel>
Sets the audio mixer channel (default: pcm).
``<mixer-channel>``
Sets the audio mixer channel (default: ``pcm``).
jack
audio output through JACK (Jack Audio Connection Kit)
``jack``
JACK (Jack Audio Connection Kit) audio output driver
port=<name>
``port=<name>``
Connects to the ports with the given name (default: physical ports).
name=<client>
``name=<client>``
Client name that is passed to JACK (default: mpv [<PID>]). Useful
if you want to have certain connections established automatically.
(no-)estimate
``(no-)estimate``
Estimate the audio delay, supposed to make the video playback smoother
(default: enabled).
(no-)autostart
``(no-)autostart``
Automatically start jackd if necessary (default: disabled). Note that
this seems unreliable and will spam stdout with server messages.
(no-)connect
this tends to be unreliable and will flood stdout with server messages.
``(no-)connect``
Automatically create connections to output ports (default: enabled).
When enabled, the maximum number of output channels will be limited to
the number of available output ports.
std-channel-layout=alsa|waveext|any
``std-channel-layout=alsa|waveext|any``
Select the standard channel layout (default: alsa). JACK itself has no
notion of channel layouts (i.e. assigning which speaker a given
channel is supposed to map to) - it just takes whatever the application
outputs, and reroutes it to whatever the user defines. This means the
user and the application is in charge of dealing with the channel
user and the application are in charge of dealing with the channel
layout. ``alsa`` uses the old MPlayer layout, which is inspired by
ALSA's standard layouts. In this mode, ao_jack will refuse to play 3
or 7 channels (because these don't really have a defined meaning in
MPlayer). ``waveext`` uses WAVE_FORMAT_EXTENSIBLE order, which even
or 7 channels (because these do not really have a defined meaning in
MPlayer). ``waveext`` uses WAVE_FORMAT_EXTENSIBLE order, which, even
though it was defined by Microsoft, is the standard on many systems.
The value ``any`` makes JACK accept whatever comes from the audio
filter chain, regardless of channel layout and without reordering. This
mode is probably not very useful, other than debugging or when used
mode is probably not very useful, other than for debugging or when used
with fixed setups.
coreaudio (Mac OS X only)
native Mac OS X audio output driver
``coreaudio`` (Mac OS X only)
Native Mac OS X audio output driver
device_id=<id>
``device_id=<id>``
ID of output device to use (0 = default device)
help
``help``
List all available output devices with their IDs.
openal
``openal``
Experimental OpenAL audio output driver
pulse
``pulse``
PulseAudio audio output driver
[<host>][:<output sink>]
``[<host>][:<output sink>]``
Specify the host and optionally output sink to use. An empty <host>
string uses a local connection, "localhost" uses network transfer
(most likely not what you want).
portaudio
PortAudio audio output driver. This works on all platforms, and has extensive
MS Windows support.
``portaudio``
PortAudio audio output driver. This works on all platforms, and has
extensive MS Windows support.
device
``device``
Specify the subdevice to use. Giving ``help`` as device name lists all
devices found by PortAudio. Devices can be given as numeric values,
starting from ``1``.
dsound (Windows only)
``dsound`` (Windows only)
DirectX DirectSound audio output driver
device=<devicenum>
``device=<devicenum>``
Sets the device number to use. Playing a file with ``-v`` will show a
list of available devices.
sdl
SDL 1.2+ audio output driver. Should work everywhere where SDL 1.2 builds,
but may require the SDL_AUDIODRIVER environment variable to be set
``sdl``
SDL 1.2+ audio output driver. Should work on any platform supported by SDL
1.2, but may require the ``SDL_AUDIODRIVER`` environment variable to be set
appropriately for your system.
buflen=<length>
Sets the audio buffer length in seconds. Is used only approximately,
or even disaregarded entirely by the sound system. Playing a file with
``-v`` will show the requested and obtained exact buffer size. A value
of 0 selects the sound system default.
``buflen=<length>``
Sets the audio buffer length in seconds. Is used only as a hint by the
sound system. Playing a file with ``-v`` will show the requested and
obtained exact buffer size. A value of 0 selects the sound system
default.
bufcnt=<count>
``bufcnt=<count>``
Sets the number of extra audio buffers in mpv. Usually needs not be
changed.
null
``null``
Produces no audio output but maintains video playback speed. Use
``--no-audio`` for benchmarking.
pcm
raw PCM/wave file writer audio output
``pcm``
Raw PCM/WAVE file writer audio output
(no-)waveheader
Include or do not include the wave header (default: included). When
``(no-)waveheader``
Include or do not include the WAVE header (default: included). When
not included, raw PCM will be generated.
file=<filename>
Write the sound to <filename> instead of the default
``audiodump.wav``. If nowaveheader is specified, the default is
``file=<filename>``
Write the sound to ``<filename>`` instead of the default
``audiodump.wav``. If ``no-waveheader`` is specified, the default is
``audiodump.pcm``.
rsound
audio output to an RSound daemon
``rsound``
Audio output to an RSound daemon
host=<name/path>
``host=<name/path>``
Set the address of the server (default: localhost). Can be either a
network hostname for TCP connections or a Unix domain socket path
starting with '/'.
port=<number>
``port=<number>``
Set the TCP port used for connecting to the server (default: 12345).
Not used if connecting to a Unix domain socket.

169
DOCS/man/en/changes.rst
View File

@ -1,5 +1,3 @@
.. _changes:
CHANGES FROM OTHER VERSIONS OF MPLAYER
======================================
@ -8,11 +6,11 @@ MPlayer (also called mplayer, mplayer-svn, mplayer1). Many changes
have been made. Some changes are incompatible, or completely change how the
player behaves.
General Changes for MPlayer-svn to mplayer2
-------------------------------------------
General Changes for MPlayer to mplayer2
---------------------------------------
* Removal of the internal GUI, MEncoder, OSD menu
* Better pause handling (don't unpause on a command)
* Better pause handling (do not unpause on a command)
* Better MKV support (such as ordered chapters)
* vo_vdpau improvements
* Precise seeking support
@ -83,60 +81,62 @@ Command Line Switches
syntax. ``-optname optvalue`` becomes ``--optname=optvalue``.
The old syntax will not be removed in the near future. However, the new
syntax is mentioned in all documentation and so on, so it's a good thing to
syntax is mentioned in all documentation and so on, so it is a good thing to
know about this change.
(The new syntax was introduced in mplayer2.)
* In general, negating switches like ``-noopt`` now have to be written as
``-no-opt``, or better ``--no-opt``.
* Per-file options are not the default anymore. You can explicitly specify
file local options. See ``Usage`` section.
file-local options. See ``Usage`` section.
* Table of renamed/replaced switches:
=================================== ===================================
Old New
=================================== ===================================
-no<opt> --no-<opt> (add a dash)
-nosound --no-audio
-use-filename-title --title="${filename}"
-loop 0 --loop=inf
-hardframedrop --framedrop=hard
-osdlevel --osd-level
-delay --audio-delay
-subdelay --sub-delay
-subpos --sub-pos
-forcedsubsonly --sub-forced-only
-ni --avi-ni
-benchmark --untimed (no stats)
-xineramascreen --screen (different values)
-ss --start
-endpos --length
--cursor-autohide-delay --cursor-autohide
-sub-fuzziness --autosub-match
-subfont --sub-text-font
-font --osd-font
-subfont-* --sub-text-*, --osd-*
-subfont-text-scale --sub-scale
-spugauss --sub-gauss
-vobsub --sub (pass the .idx file)
-ass-bottom-margin --vf=sub=bottom:top
-vc ffh264vdpau (etc.) --hwdec=vdpau
-ac spdifac3 --ad=spdif:ac3 (see --ad=help)
-afm hwac3 --ad=spdif:ac3,spdif:dts
-x W, -y H --geometry=WxH + --no-keepaspect
-xy W --autofit=W
-a52drc level --ad-lavc-ac3drc=level
-dumpstream --stream-dump=<filename>
-capture --stream-capture=<filename>
-stop-xscreensaver --stop-screensaver
-subfile --sub
-lavdopts ... --vd-lavc-...
-lavfdopts --demuxer-lavf-...
-rawaudio ... --demuxer-rawaudio-...
-rawvideo ... --demuxer-rawvideo-...
=================================== ===================================
=========================== ========================================
Old New
=========================== ========================================
``-no<opt>`` ``--no-<opt>`` (add a dash)
``-nosound`` ``--no-audio``
``-use-filename-title`` ``--title="${filename}"``
``-loop 0`` ``--loop=inf``
``-hardframedrop`` ``--framedrop=hard``
``-osdlevel`` ``--osd-level``
``-delay`` ``--audio-delay``
``-subdelay`` ``--sub-delay``
``-subpos`` ``--sub-pos``
``-forcedsubsonly`` ``--sub-forced-only``
``-ni`` ``--avi-ni``
``-benchmark`` ``--untimed`` (no stats)
``-xineramascreen`` ``--screen`` (different values)
``-ss`` ``--start``
``-endpos`` ``--length``
``--cursor-autohide-delay`` ``--cursor-autohide``
``-sub-fuzziness`` ``--autosub-match``
``-subfont`` ``--sub-text-font``
``-font`` ``--osd-font``
``-subfont-*`` ``--sub-text-*``, ``--osd-*``
``-subfont-text-scale`` ``--sub-scale``
``-spugauss`` ``--sub-gauss``
``-vobsub`` ``--sub`` (pass the .idx file)
``-ass-bottom-margin`` ``--vf=sub=bottom:top``
``-vc ffh264vdpau`` (etc.) ``--hwdec=vdpau``
``-ac spdifac3`` ``--ad=spdif:ac3`` (see ``--ad=help``)
``-afm hwac3`` ``--ad=spdif:ac3,spdif:dts``
``-x W``, ``-y H`` ``--geometry=WxH`` + ``--no-keepaspect``
``-xy W`` ``--autofit=W``
``-a52drc level`` ``--ad-lavc-ac3drc=level``
``-dumpstream`` ``--stream-dump=<filename>``
``-capture`` ``--stream-capture=<filename>``
``-stop-xscreensaver`` ``--stop-screensaver``
``-subfile`` ``--sub``
``-lavdopts ...`` ``--vd-lavc-...``
``-lavfdopts`` ``--demuxer-lavf-...``
``-rawaudio ...`` ``--demuxer-rawaudio-...``
``-rawvideo ...`` ``--demuxer-rawvideo-...``
=========================== ========================================
*NOTE*: ``-opt val`` becomes ``--opt=val``.
.. note::
``-opt val`` becomes ``--opt=val``.
input.conf and Slave Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -153,52 +153,55 @@ input.conf and Slave Commands
+--------------------------------+----------------------------------------+
| Old | New |
+================================+========================================+
| pt_step 1 [0|1] | playlist_next [weak|force] |
| | (translation layer can't deal with |
| ``pt_step 1 [0|1]`` | ``playlist_next [weak|force]`` |
| | (translation layer cannot deal with |
| | whitespace) |
+--------------------------------+----------------------------------------+
| pt_step -1 [0|1] | playlist_prev [weak|force] (same) |
| ``pt_step -1 [0|1]`` | ``playlist_prev [weak|force] (same)`` |
+--------------------------------+----------------------------------------+
| switch_ratio [<ratio>] | set aspect <ratio> |
| | set aspect 0 (to reset aspect) |
| ``switch_ratio [<ratio>]`` | ``set aspect <ratio>`` |
| | |
| | ``set aspect 0`` (to reset aspect) |
+--------------------------------+----------------------------------------+
| step_property_osd <prop> <step>| cycle <prop> <step> (wraps), |
| <dir> | add <prop> <step> (clamps). |
| | <dir> parameter unsupported. Use |
| | a negative step instead. |
| ``step_property_osd <prop>`` | ``cycle <prop> <step>`` (wraps), |
| ``<step> <dir>`` | ``add <prop> <step>`` (clamps). |
| | ``<dir>`` parameter unsupported. Use |
| | a negative ``<step>`` instead. |
+--------------------------------+----------------------------------------+
| step_property <prop> <step> | Prefix cycle or add with no-osd: |
| <dir> | no-osd cycle <prop> <step> |
| ``step_property <prop>`` | Prefix ``cycle`` or ``add`` with |
| ``<step> <dir>`` | ``no-osd``: ``no-osd cycle <prop>`` |
| | ``<step>`` |
+--------------------------------+----------------------------------------+
| osd_show_property_text <text> | show_text <text> |
| | The property expansion format string |
| ``osd_show_property_text`` | ``show_text <text>`` |
| ``<text>`` | The property expansion format string |
| | syntax slightly changed. |
+--------------------------------+----------------------------------------+
| osd_show_text | Now does the same as |
| | osd_show_property_text. Use the raw |
| | prefix to disable property expansion. |
| ``osd_show_text`` | Now does the same as |
| | ``osd_show_property_text``. Use the |
| | ``raw`` prefix to disable property |
| | expansion. |
+--------------------------------+----------------------------------------+
| show_tracks | show_text ${track-list} |
| ``show_tracks`` | ``show_text ${track-list}`` |
+--------------------------------+----------------------------------------+
| show_chapters | show_text ${chapter-list} |
| ``show_chapters`` | ``show_text ${chapter-list}`` |
+--------------------------------+----------------------------------------+
Other
~~~~~
* The playtree has been removed. **mpv**'s internal playlist is a simple and
flat list now. This makes the code easier, and makes **mpv** usage less
flat list now. This simplifies the code and makes **mpv** usage less
confusing.
* Slave mode is broken. This mode is entirely insane in the ``old`` versions of
mplayer. A proper slave mode application needed tons of code and hacks to get
MPlayer. A proper slave mode application needed tons of code and hacks to get
it right. The main problem is that slave mode is a bad and incomplete
interface, and to get around that, applications parsed output messages
intended for users. It's hard to know which messages exactly are parsed by
intended for users. It is hard to know which messages exactly are parsed by
slave mode applications. This makes it virtually impossible to improve
terminal output intended for users without possibly breaking something.
This is absolutely insane, and **mpv** will not try to keep slave mode
compatible. If you're a developer of a slave mode application, contact us,
compatible. If you are a developer of a slave mode application, contact us,
and a new and better protocol can be developed.
Policy for Removed Features
@ -210,22 +213,22 @@ likely to be not used by many, and causes problems otherwise, it will be
removed. Developers should not be burdened with fixing or cleaning up code that
has no actual use.
It's always possible to add back removed features. File a feature request if a
feature you relied on was removed, and you want it back. Though it might be
rejected in the worst case, it's much more likely that it will be either added
It is always possible to add back removed features. File a feature request if a
feature you relied on has been removed, and you want it back. Though it might be
rejected in the worst case, it is much more likely that it will be either added
back, or that a better solution will be implemented.
Why this Fork?
--------------
* mplayer-svn wants to maintain old code, even if it's very bad code. It seems
mplayer2 was forked, because mplayer-svn developers refused to get rid of
all the cruft. The mplayer2 and mplayer-svn codebases also deviated enough to
make a reunification unlikely.
* mplayer2 development is slow, and it's hard to get in changes. Details
* MPlayer wants to maintain old code, even if it is very bad code. It seems
mplayer2 was forked because MPlayer developers refused to get rid of all the
cruft. The mplayer2 and MPlayer codebases also deviated enough to make a
reunification unlikely.
* mplayer2 development is slow, and it is hard to get in changes. Details
withheld as to not turn this into a rant.
* mplayer-svn rarely merged from mplayer2, and mplayer2 practically stopped
merging from mplayer-svn (not even code cleanups or new features are merged)
* **mpv** intents to continuously merge from mplayer-svn and mplayer2, while
* MPlayer rarely merged from mplayer2, and mplayer2 practically stopped
merging from MPlayer (not even code cleanups or new features are merged)
* **mpv** intends to continuously merge from mplayer-svn and mplayer2, while
speeding up development. There is willingness for significant changes, even
if this means breaking compatibility.

116
DOCS/man/en/encode.rst
View File

@ -1,147 +1,151 @@
.. _encode:
ENCODING
========
You can encode files from one format/codec to another using this facility.
-o <filename>
``-o <filename>``
Enables encoding mode and specifies the output file name.
--of=<format>
Specifies the output format (overrides autodetection by the extension of
the file specified by -o). This can be a comma separated list of possible
formats to try. See --of=help for a full list of supported formats.
``--of=<format>``
Specifies the output format (overrides autodetection by the file name
extension of the file specified by ``-o``). This can be a comma separated
list of possible formats to try. See ``--of=help`` for a full list of
supported formats.
--ofopts=<options>
``--ofopts=<options>``
Specifies the output format options for libavformat.
See --ofopts=help for a full list of supported options.
See ``--ofopts=help`` for a full list of supported options.
Options are managed in lists. There are a few commands to manage the
options list.
--ofopts-add=<options1[,options2,...]>
``--ofopts-add=<options1[,options2,...]>``
Appends the options given as arguments to the options list.
--ofopts-pre=<options1[,options2,...]>
``--ofopts-pre=<options1[,options2,...]>``
Prepends the options given as arguments to the options list.
--ofopts-del=<index1[,index2,...]>
``--ofopts-del=<index1[,index2,...]>``
Deletes the options at the given indexes. Index numbers start at 0,
negative numbers address the end of the list (-1 is the last).
--ofopts-clr
``--ofopts-clr``
Completely empties the options list.
--ofps=<float value>
``--ofps=<float value>``
Specifies the output format time base (default: 24000). Low values like 25
limit video fps by dropping frames.
--oautofps
``--oautofps``
Sets the output format time base to the guessed frame rate of the input
video (simulates mencoder behaviour, useful for AVI; may cause frame
drops). Note that not all codecs and not all formats support VFR
encoding, and some which do have bugs when a target bitrate is
specified - use --ofps or --oautofps to force CFR encoding in these
cases.
video (simulates mencoder behavior, useful for AVI; may cause frame drops).
Note that not all codecs and not all formats support VFR encoding, and some
which do have bugs when a target bitrate is specified - use ``--ofps`` or
``--oautofps`` to force CFR encoding in these cases.
--omaxfps=<float value>
``--omaxfps=<float value>``
Specifies the minimum distance of adjacent frames (default: 0, which means
unset). Content of lower frame rate is not readjusted to this frame rate;
content of higher frame rate is decimated to this frame rate.
--oharddup
If set, the frame rate given by --ofps is attained not by skipping time
``--oharddup``
If set, the frame rate given by ``--ofps`` is attained not by skipping time
codes, but by duplicating frames (constant frame rate mode).
--oneverdrop
``--oneverdrop``
If set, frames are never dropped. Instead, time codes of video are
readjusted to always increase. This may cause AV desync, though; to
work around this, use a high-fps time base using --ofps and absolutely
avoid --oautofps.
readjusted to always increase. This may cause AV desync, though; to work
around this, use a high-fps time base using ``--ofps`` and absolutely
avoid ``--oautofps``.
--oac=<codec>
``--oac=<codec>``
Specifies the output audio codec. This can be a comma separated list of
possible codecs to try. See --oac=help for a full list of supported codecs.
possible codecs to try. See ``--oac=help`` for a full list of supported
codecs.
--oaoffset=<value>
``--oaoffset=<value>``
Shifts audio data by the given time (in seconds) by adding/removing
samples at the start.
--oacopts=<options>
``--oacopts=<options>``
Specifies the output audio codec options for libavcodec.
See --oacopts=help for a full list of supported options.
See ``--oacopts=help`` for a full list of supported options.
EXAMPLE: "--oac=libmp3lame --oacopts=b=128000" selects 128kbps MP3
encoding.
.. admonition:: Example
"``--oac=libmp3lame --oacopts=b=128000``"
selects 128kbps MP3 encoding.
Options are managed in lists. There are a few commands to manage the
options list.
--oacopts-add=<options1[,options2,...]>
``--oacopts-add=<options1[,options2,...]>``
Appends the options given as arguments to the options list.
--oacopts-pre=<options1[,options2,...]>
``--oacopts-pre=<options1[,options2,...]>``
Prepends the options given as arguments to the options list.
--oacopts-del=<index1[,index2,...]>
``--oacopts-del=<index1[,index2,...]>``
Deletes the options at the given indexes. Index numbers start at 0,
negative numbers address the end of the list (-1 is the last).
--oacopts-clr
``--oacopts-clr``
Completely empties the options list.
--oafirst
``--oafirst``
Force the audio stream to become the first stream in the output. By default
the order is unspecified.
--ovc=<codec>
``--ovc=<codec>``
Specifies the output video codec. This can be a comma separated list of
possible codecs to try. See --ovc=help for a full list of supported codecs.
possible codecs to try. See ``--ovc=help`` for a full list of supported
codecs.
--ovoffset=<value>
``--ovoffset=<value>``
Shifts video data by the given time (in seconds) by shifting the pts
values.
--ovcopts <options>
``--ovcopts <options>``
Specifies the output video codec options for libavcodec.
See --ovcopts=help for a full list of supported options.
EXAMPLE: "--ovc=mpeg4 --oacopts=qscale=5" selects constant quantizer scale
5 for MPEG-4 encoding.
.. admonition:: Examples
EXAMPLE: "--ovc=libx264 --ovcopts=crf=23" selects VBR quality factor 23 for
H.264 encoding.
``"--ovc=mpeg4 --oacopts=qscale=5"``
selects constant quantizer scale 5 for MPEG-4 encoding.
``"--ovc=libx264 --ovcopts=crf=23"``
selects VBR quality factor 23 for H.264 encoding.
Options are managed in lists. There are a few commands to manage the
options list.
--ovcopts-add=<options1[,options2,...]>
``--ovcopts-add=<options1[,options2,...]>``
Appends the options given as arguments to the options list.
--ovcopts-pre=<options1[,options2,...]>
``--ovcopts-pre=<options1[,options2,...]>``
Prepends the options given as arguments to the options list.
--ovcopts-del=<index1[,index2,...]>
``--ovcopts-del=<index1[,index2,...]>``
Deletes the options at the given indexes. Index numbers start at 0,
negative numbers address the end of the list (-1 is the last).
--ovcopts-clr
``--ovcopts-clr``
Completely empties the options list.
--ovfirst
``--ovfirst``
Force the video stream to become the first stream in the output. By default
the order is unspecified.
--ocopyts
``--ocopyts``
Copies input pts to the output video (not supported by some output
container formats, e.g. avi). Discontinuities are still fixed.
container formats, e.g. AVI). Discontinuities are still fixed.
By default, audio pts are set to playback time and video pts are
synchronized to match audio pts, as some output formats do not support
anything else.
--orawts
``--orawts``
Copies input pts to the output video (not supported by some output
container formats, e.g. avi). In this modem discontinuities are not fixed
container formats, e.g. AVI). In this mode, discontinuities are not fixed
and all pts are passed through as-is. Never seek backwards or use multiple
input files in this mode!

416
DOCS/man/en/input.rst
View File

@ -1,11 +1,9 @@
.. _input:
INPUT.CONF
==========
The input.conf file consists of a list of key bindings, for example:
The input.conf file consists of a list of key bindings, for example::
| s screenshot # take a screenshot with the s key
s screenshot # take a screenshot with the s key
Each line maps a key to an input command. Keys are specified with their literal
value (upper case if combined with ``Shift``), or a name for special keys. For
@ -14,16 +12,16 @@ with shift.
A list of special keys can be obtained with
| **mpv** --input-keylist
``mpv --input-keylist``
In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``:
In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``::
| ctrl+q quit
ctrl+q quit
**mpv** can be started in input test mode, which displays key bindings and the
commands they're bound to on the OSD, instead of running the commands:
commands they're bound to on the OSD, instead of executing the commands::
| **mpv** --input-test --demuxer=rawvideo --rawvideo=w=1280:h=720 /dev/zero
mpv --input-test --demuxer=rawvideo --rawvideo=w=1280:h=720 /dev/zero
(Commands which normally close the player will not work in this mode, and you
must kill **mpv** externally to make it exit.)
@ -31,31 +29,32 @@ must kill **mpv** externally to make it exit.)
General Input Command Syntax
----------------------------
`[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] [<prefixes>] <command> (<argument>)*`
``[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] [<prefixes>] <command> (<argument>)*``
Newlines always start a new binding. ``#`` starts a comment (outside of quoted
string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used.
<key> is either the literal character the key produces (ASCII or unicode
``<key>`` is either the literal character the key produces (ASCII or Unicode
character), or a symbol name.
<section> (braced with ``{`` and ``}``) is the input section for this command.
``<section>`` (braced with ``{`` and ``}``) is the input section for this
command.
Arguments are separated by whitespace. This applies even to string arguments.
For this reason, string arguments should be quoted with ``"``. Inside quotes,
C style escaping can be used.
C-style escaping can be used.
Optional arguments can be skipped with ``-``.
List of Input Commands
----------------------
ignore
``ignore``
Use this to "block" keys that should be unbound, and do nothing. Useful for
disabling default bindings, without disabling all bindings with
``--no-input-default-bindings``.
seek <seconds> [relative|absolute|absolute-percent|- [default-precise|exact|keyframes]]
``seek <seconds> [relative|absolute|absolute-percent|- [default-precise|exact|keyframes]]``
Change the playback position. By default, seeks by a relative amount of
seconds.
@ -78,10 +77,10 @@ seek <seconds> [relative|absolute|absolute-percent|- [default-precise|exact|keyf
keyframes
Always restart playback at keyframe boundaries (fast).
frame_step
``frame_step``
Play one frame, then pause.
frame_back_step
``frame_back_step``
Go back by one frame, then pause. Note that this can be very slow (it tries
to be precise, not fast), and sometimes fails to behave as expected. How
well this works depends on whether precise seeking works correctly (e.g.
@ -90,24 +89,24 @@ frame_back_step
usually work, but might make backstepping silently behave incorrectly in
corner cases.
This doesn't work with audio-only playback.
This does not work with audio-only playback.
set <property> "<value>"
``set <property> "<value>"``
Set the given property to the given value.
add <property> [<value>]
``add <property> [<value>]``
Add the given value to the property. On overflow or underflow, clamp the
property to the maximum. If <value> is omitted, assume ``1``.
property to the maximum. If ``<value>`` is omitted, assume ``1``.
cycle <property> [up|down]
``cycle <property> [up|down]``
Cycle the given property. ``up`` and ``down`` set the cycle direction. On
overflow, set the property back to the minimum, on underflow set it to the
maximum. If ``up`` or ``down`` is omitted, assume ``up``.
speed_mult <value>
``speed_mult <value>``
Multiply the ``speed`` property by the given value.
screenshot [subtitles|video|window|- [single|each-frame]]
``screenshot [subtitles|video|window|- [single|each-frame]]``
Take a screenshot.
First argument:
@ -132,7 +131,7 @@ screenshot [subtitles|video|window|- [single|each-frame]]
Take a screenshot each frame. Issue this command again to stop taking
screenshots.
playlist_next [weak|force]
``playlist_next [weak|force]``
Go to the next entry on the playlist.
weak (default)
@ -140,7 +139,7 @@ playlist_next [weak|force]
force
Terminate playback if there are no more files on the playlist.
playlist_prev [weak|force]
``playlist_prev [weak|force]``
Go to the previous entry on the playlist.
weak (default)
@ -148,7 +147,7 @@ playlist_prev [weak|force]
force
Terminate playback if the first file is being played.
loadfile "<file>" [replace|append]
``loadfile "<file>" [replace|append]``
Load the given file and play it.
Second argument:
@ -158,91 +157,94 @@ loadfile "<file>" [replace|append]
<append>
Append the file to the playlist.
loadlist "<playlist>" [replace|append]
``loadlist "<playlist>" [replace|append]``
Load the given playlist file (like ``--playlist``).
playlist_clear
``playlist_clear``
Clear the playlist, except the currently played file.
playlist_remove <index>
``playlist_remove <index>``
Remove the playlist entry at the given index. Index values start counting
with 0. You can't remove the entry for the currently played file.
with 0. You cannot remove the entry for the currently played file.
playlist_move <index1> <index2>
``playlist_move <index1> <index2>``
Move the playlist entry at index1, so that it takes the place of the
entry index2. (Paradoxically, the moved playlist entry will not have
the index value index2 after moving if index1 was lower than index2,
because index2 refers to the target entry, not the index the entry
will have after moving.)
run "<command>"
``run "<command>"``
Run the given command with ``/bin/sh -c``. The string is expanded like in
property_expansion_.
`Property Expansion`_.
quit [<code>]
``quit [<code>]``
Exit the player using the given exit code.
quit_watch_later
``quit_watch_later``
Exit player, and store current playback position. Playing that file later
will seek to the previous position on start.
sub_add "<file>"
Load the given subtitle file. It's not selected as current subtitle after
``sub_add "<file>"``
Load the given subtitle file. It is not selected as current subtitle after
loading.
sub_remove [<id>]
``sub_remove [<id>]``
Remove the given subtitle track. If the ``id`` argument is missing, remove
the current track. (Works on external subtitle files only.)
sub_reload [<id>]
``sub_reload [<id>]``
Reload the given subtitle tracks. If the ``id`` argument is missing, remove
the current track. (Works on external subtitle files only.)
This works by unloading and re-adding the subtitle track.
sub_step <skip>
Change subtitle timing such, that the subtitle event after the next <skip>
subtitle events is displayed. <skip> can be negative to step back.
``sub_step <skip>``
Change subtitle timing such, that the subtitle event after the next
``<skip>`` subtitle events is displayed. ``<skip>`` can be negative to step
backwards.
osd [<level>]
Toggle OSD level. If <level> is specified, set the OSD mode
``osd [<level>]``
Toggle OSD level. If ``<level>`` is specified, set the OSD mode
(see ``--osd-level`` for valid values).
print_text "<string>"
``print_text "<string>"``
Print text to stdout. The string can contain properties (see
property_expansion_).
`Property Expansion`_).
show_text "<string>" [<duration>|- [<level>]]
``show_text "<string>" [<duration>|- [<level>]]``
Show text on the OSD. The string can contain properties, which are expanded
as described in property_expansion_. This can be used to show playback
as described in `Property Expansion`_. This can be used to show playback
time, filename, and so on.
<duration> is the time in ms to show the message. By default, it uses the
same value as ``--osd-duration``.
<duration>
The time in ms to show the message for. By default, it uses the same
value as ``--osd-duration``.
<level> is the minimum OSD level to show the text (see ``--osd-level``).
<level>
The minimum OSD level to show the text at (see ``--osd-level``).
show_progress
``show_progress``
Show the progress bar, the elapsed time and the total duration of the file
on the OSD.
Input Commands that are Possibly Subject to Change
--------------------------------------------------
af_switch "filter1=params,filter2,..."
``af_switch "filter1=params,filter2,..."``
Replace the current filter chain with the given list.
af_add "filter1=params,filter2,..."
``af_add "filter1=params,filter2,..."``
Add the given list of audio filters to the audio filter chain.
af_del "filter1,filter2,..."
``af_del "filter1,filter2,..."``
Remove the given list of audio filters.
af_clr
``af_clr``
Remove all audio filters. (Conversion filters will be re-added
automatically if needed.)
vf set|add|toggle|del "filter1=params,filter2,..."
``vf set|add|toggle|del "filter1=params,filter2,..."``
Change video filter chain.
The first argument decides what happens:
@ -267,64 +269,66 @@ vf set|add|toggle|del "filter1=params,filter2,..."
filter.
You can assign labels to filter by prefixing them with ``@name:`` (where
``name`` is a user-chosen arbitrary identifiers). Labels can be used to
``name`` is a user-chosen arbitrary identifier). Labels can be used to
refer to filters by name in all of the filter chain modification commands.
For ``add``, using an already used label will replace the existing filter.
*EXAMPLE for input.conf*:
.. admonition:: Example for input.conf
- ``a vf set flip`` turn video upside-down on the ``a`` key
- ``b vf set ""`` remove all video filters on ``b``
- ``c vf toggle lavfi=gradfun`` toggle debanding on ``c``
- ``a vf set flip`` turn video upside-down on the ``a`` key
- ``b vf set ""`` remove all video filters on ``b``
- ``c vf toggle lavfi=gradfun`` toggle debanding on ``c``
enable_section "<section>" [default|exclusive]
``enable_section "<section>" [default|exclusive]``
Enable all key bindings in the named input section.
The enabled input sections form a stack. Bindings in sections on the top of
the stack are preferred to lower sections. This command puts the section
on top of the stack. If the section was already on the stack, it's
implicitly removed beforehand. (A section can't be on the stack twice.)
on top of the stack. If the section was already on the stack, it is
implicitly removed beforehand. (A section cannot be on the stack more than
once.)
If ``exclusive`` is specified as second argument, all sections below the
newly enabled section are disabled. They will be re-enabled as soon as
all exclusive above them are removed.
all exclusive sections above them are removed.
disable_section "<section>"
``disable_section "<section>"``
Disable the named input section. Undoes ``enable_section``.
Undocumented commands: tv_start_scan, tv_step_channel, tv_step_norm,
tv_step_chanlist, tv_set_channel, tv_last_channel, tv_set_freq, tv_step_freq,
tv_set_norm, dvb_set_channel, radio_step_channel, radio_set_channel,
radio_set_freq, radio_step_freq (all of these should be replaced by properties),
stop (questionable use), get_property (?), af_cmdline, vo_cmdline (experimental).
Undocumented commands: ``tv_start_scan``, ``tv_step_channel``, ``tv_step_norm``,
``tv_step_chanlist``, ``tv_set_channel``, ``tv_last_channel``, ``tv_set_freq``,
``tv_step_freq``, ``tv_set_norm``, ``dvb_set_channel``, ``radio_step_channel``,
``radio_set_channel``, ``radio_set_freq``, ``radio_step_freq`` (all of these
should be replaced by properties), ``stop`` (questionable use), ``get_property``
(?), ``af_cmdline``, ``vo_cmdline`` (experimental).
Input Command Prefixes
----------------------
osd-auto (default)
``osd-auto`` (default)
Use the default behavior for this command.
no-osd
``no-osd``
Do not use any OSD for this command.
osd-bar
``osd-bar``
If possible, show a bar with this command. Seek commands will show the
progress bar, property changing commands may show the newly set value.
osd-msg
``osd-msg``
If possible, show an OSD message with this command. Seek command show
the current playback time, property changing commands show the newly set
value as text.
osd-msg-bar
``osd-msg-bar``
Combine osd-bar and osd-msg.
raw
Don't expand properties in string arguments. (Like ``"${property-name}"``.)
expand-properties (default)
All string arguments are expanded as described in property_expansion_.
``raw``
Do not expand properties in string arguments. (Like ``"${property-name}"``.)
``expand-properties`` (default)
All string arguments are expanded as described in `Property Expansion`_.
All of the osd prefixes are still overridden by the global ``--osd-level``
settings.
Undocumented prefixes: pausing, pausing_keep, pausing_toggle,
pausing_keep_force. (Should these be made official?)
Undocumented prefixes: ``pausing``, ``pausing_keep``, ``pausing_toggle``,
``pausing_keep_force``. (Should these be made official?)
Input Sections
--------------
@ -337,10 +341,10 @@ Also see ``enable_section`` and ``disable_section`` commands.
Predefined bindings:
default
``default``
Bindings without input section are implicitly assigned to this section. It
is enabled by default during normal playback.
encode
``encode``
Section which is active in encoding mode. It is enabled exclusively, so
that bindings in the ``default`` sections are ignored.
@ -350,108 +354,106 @@ Properties
Properties are used to set mpv options during runtime, or to query arbitrary
information. They can be manipulated with the ``set``/``add``/``cycle``
commands, and retrieved with ``show_text``, or anything else that uses property
expansion. (See property_expansion_.)
expansion. (See `Property Expansion`_.)
The ``W`` column indicates whether the property is generally writeable. If an
The ``W`` column indicates whether the property is generally writable. If an
option is referenced, the property should take/return exactly the same values
as the option.
=========================== = ==================================================
Name W Comment
=========================== = ==================================================
osd-level x see ``--osd-level``
osd-scale x osd font size multiplicator, see ``--osd-scale``
loop x see ``--loop``
speed x see ``--speed``
filename currently played file (path stripped)
path currently played file (full path)
media-title filename or libquvi QUVIPROP_PAGETITLE
demuxer
stream-path filename (full path) of stream layer filename
stream-pos x byte position in source stream
stream-start start byte offset in source stream
stream-end end position in bytes in source stream
stream-length length in bytes (${stream-end} - ${stream-start})
stream-time-pos x time position in source stream (also see time-pos)
length length of the current file in seconds
avsync last A/V synchronization difference
percent-pos x position in current file (0-100)
ratio-pos x position in current file (0.0-1.0)
time-pos x position in current file in seconds
time-remaining estimated remaining length of the file in seconds
chapter x current chapter number
edition x current MKV edition number
titles number of DVD titles
chapters number of chapters
editions number of MKV editions
angle x current DVD angle
metadata metadata key/value pairs
metadata/<key> value of metadata entry <key>
pause x pause status (bool)
cache network cache fill state (0-100)
pts-association-mode x see ``--pts-association-mode``
hr-seek x see ``--hr-seek``
volume x current volume (0-100)
mute x current mute status (bool)
audio-delay x see ``--audio-delay``
audio-format audio format (string)
audio-codec audio codec selected for decoding
audio-bitrate audio bitrate
samplerate audio samplerate
channels number of audio channels
aid x current audio track (similar to ``--aid``)
audio x alias for ``aid``
balance x audio channel balance
fullscreen x see ``--fullscreen``
deinterlace x deinterlacing, if available (bool)
colormatrix x see ``--colormatrix``
colormatrix-input-range x see ``--colormatrix-input-range``
colormatrix-output-range x see ``--colormatrix-output-range``
ontop x see ``--ontop``
border x see ``--border``
framedrop x see ``--framedrop``
gamma x see ``--gamma``
brightness x see ``--brightness``
contrast x see ``--contrast``
saturation x see ``--saturation``
hue x see ``--hue``
panscan x see ``--panscan``
video-format video format (string)
video-codec video codec selected for decoding
video-bitrate video bitrate
width video width (container or decoded size)
height video height
fps container FPS (may contain bogus values)
dwidth video width (after filters and aspect scaling)
dheight video height
aspect x video aspect
vid x current video track (similar to ``--vid``)
video x alias for ``vid``
program x switch TS program (write-only)
sid x current subtitle track (similar to ``--sid``)
sub x alias for ``sid``
sub-delay x see ``--sub-delay``
sub-pos x see ``--sub-pos``
sub-visibility x whether current subtitle is rendered
sub-forced-only x see ``--sub-forced-only``
sub-scale x subtitle font size multiplicator
ass-use-margins x see ``--ass-use-margins``
ass-vsfilter-aspect-compat x see ``--ass-vsfilter-aspect-compat``
ass-style-override x see ``--ass-style-override``
stream-capture x a filename, see ``--capture``
tv-brightness x
tv-contrast x
tv-saturation x
tv-hue x
playlist-pos current position on playlist
playlist-count number of total playlist entries
playlist playlist, current entry marked
track-list list of audio/video/sub tracks, cur. entr. marked
chapter-list list of chapters, current entry marked
quvi-format x see ``--quvi-format``
=========================== = ==================================================
.. _property_expansion:
=============================== = ==================================================
Name W Comment
=============================== = ==================================================
``osd-level`` x see ``--osd-level``
``osd-scale`` x osd font size multiplicator, see ``--osd-scale``
``loop`` x see ``--loop``
``speed`` x see ``--speed``
``filename`` currently played file (path stripped)
``path`` currently played file (full path)
``media-title`` filename or libquvi ``QUVIPROP_PAGETITLE``
``demuxer``
``stream-path`` filename (full path) of stream layer filename
``stream-pos`` x byte position in source stream
``stream-start`` start byte offset in source stream
``stream-end`` end position in bytes in source stream
``stream-length`` length in bytes (``${stream-end} - ${stream-start}``)
``stream-time-pos`` x time position in source stream (also see ``time-pos``)
``length`` length of the current file in seconds
``avsync`` last A/V synchronization difference
``percent-pos`` x position in current file (0-100)
``ratio-pos`` x position in current file (0.0-1.0)
``time-pos`` x position in current file in seconds
``time-remaining`` estimated remaining length of the file in seconds
``chapter`` x current chapter number
``edition`` x current MKV edition number
``titles`` number of DVD titles
``chapters`` number of chapters
``editions`` number of MKV editions
``angle`` x current DVD angle
``metadata`` metadata key/value pairs
``metadata/<key>`` value of metadata entry ``<key>``
``pause`` x pause status (bool)
``cache`` network cache fill state (0-100)
``pts-association-mode`` x see ``--pts-association-mode``
``hr-seek`` x see ``--hr-seek``
``volume`` x current volume (0-100)
``mute`` x current mute status (bool)
``audio-delay`` x see ``--audio-delay``
``audio-format`` audio format (string)
``audio-codec`` audio codec selected for decoding
``audio-bitrate`` audio bitrate
``samplerate`` audio samplerate
``channels`` number of audio channels
``aid`` x current audio track (similar to ``--aid``)
``audio`` x alias for ``aid``
``balance`` x audio channel balance
``fullscreen`` x see ``--fullscreen``
``deinterlace`` x deinterlacing, if available (bool)
``colormatrix`` x see ``--colormatrix``
``colormatrix-input-range`` x see ``--colormatrix-input-range``
``colormatrix-output-range`` x see ``--colormatrix-output-range``
``ontop`` x see ``--ontop``
``border`` x see ``--border``
``framedrop`` x see ``--framedrop``
``gamma`` x see ``--gamma``
``brightness`` x see ``--brightness``
``contrast`` x see ``--contrast``
``saturation`` x see ``--saturation``
``hue`` x see ``--hue``
``panscan`` x see ``--panscan``
``video-format`` video format (string)
``video-codec`` video codec selected for decoding
``video-bitrate`` video bitrate
``width`` video width (container or decoded size)
``height`` video height
``fps`` container FPS (may contain bogus values)
``dwidth`` video width (after filters and aspect scaling)
``dheight`` video height
``aspect`` x video aspect
``vid`` x current video track (similar to ``--vid``)
``video`` x alias for ``vid``
``program`` x switch TS program (write-only)
``sid`` x current subtitle track (similar to ``--sid``)
``sub`` x alias for ``sid``
``sub-delay`` x see ``--sub-delay``
``sub-pos`` x see ``--sub-pos``
``sub-visibility`` x whether current subtitle is rendered
``sub-forced-only`` x see ``--sub-forced-only``
``sub-scale`` x subtitle font size multiplicator
``ass-use-margins`` x see ``--ass-use-margins``
``ass-vsfilter-aspect-compat`` x see ``--ass-vsfilter-aspect-compat``
``ass-style-override`` x see ``--ass-style-override``
``stream-capture`` x a filename, see ``--capture``
``tv-brightness`` x
``tv-contrast`` x
``tv-saturation`` x
``tv-hue`` x
``playlist-pos`` current position on playlist
``playlist-count`` number of total playlist entries
``playlist`` playlist, current entry marked
``track-list`` list of audio/video/sub tracks, cur. entr. marked
``chapter-list`` list of chapters, current entry marked
``quvi-format`` x see ``--quvi-format``
=============================== = ==================================================
Property Expansion
------------------
@ -459,63 +461,63 @@ Property Expansion
All string arguments to input commands as well as certain options (like
``--playing-msg``) are subject to property expansion.
*EXAMPLE for input.conf*:
.. admonition:: Example for input.conf
- ``i show_text "Filename: ${filename}"`` shows the filename of the current file
when pressing the ``i`` key
``i show_text "Filename: ${filename}"``
shows the filename of the current file when pressing the ``i`` key
Within ``input.conf``, property expansion can be inhibited by putting the
``raw`` prefix in front of commands.
The following expansions are supported:
\${NAME}
``${NAME}``
Expands to the value of the property ``NAME``. If retrieving the property
fails, expand to an error string. (Use ``${NAME:}`` with a trailing
``:`` to expand to an empty string instead.)
If ``NAME`` is prefixed with ``=``, expand to the raw value of the property
(see below).
\${NAME:STR}
``${NAME:STR}``
Expands to the value of the property ``NAME``, or ``STR`` if the
property can't be retrieved. ``STR`` is expanded recursively.
\${!NAME:STR}
Expands to ``STR`` (recursively) if the property ``NAME`` can't be
property cannot be retrieved. ``STR`` is expanded recursively.
``${!NAME:STR}``
Expands to ``STR`` (recursively) if the property ``NAME`` cannot be
retrieved.
\${?NAME:STR}
``${?NAME:STR}``
Expands to ``STR`` (recursively) if the property ``NAME`` is available.
\$\$
``$$``
Expands to ``$``.
\$}
``$}``
Expands to ``}``. (To produce this character inside recursive
expansion.)
\$>
``$>``
Disable property expansion and special handling of ``$`` for the rest
of the string.
In places where property expansion is allowed, C-style escapes are often
accepted as well. Example:
- ``\n`` becomes a newline character
- ``\\`` expands to ``\``
- ``\n`` becomes a newline character
- ``\\`` expands to ``\``
Raw and Formatted Properties
----------------------------
Normally, properties are formatted as human readable text, meant to be
Normally, properties are formatted as human-readable text, meant to be
displayed on OSD or on the terminal. It is possible to retrieve an unformatted
(raw) value from a property by prefixing its name with ``=``. These raw values
can be parsed by scripts, and follow the same conventions as the options
can be parsed by other programs and follow the same conventions as the options
associated with the properties.
*EXAMPLE*:
.. admonition:: Examples
- ``${time-pos}`` expands to ``00:14:23`` (if playback position is at 15 minutes
32 seconds)
- ``${=time-pos}`` expands to ``863.4`` (same time, plus 400 milliseconds -
milliseconds are normally not shown in the formatted case)
- ``${time-pos}`` expands to ``00:14:23`` (if playback position is at 14
minutes 23 seconds)
- ``${=time-pos}`` expands to ``863.4`` (same time, plus 400 milliseconds -
milliseconds are normally not shown in the formatted case)
Sometimes, the difference in amount of information carried by raw and formatted
property values can be rather big. In some cases, raw values have more
information, like higher precision than seconds with ``time-pos``. Sometimes
it's the other way around, e.g. ``aid`` shows track title and language in the
formatted case, but only the track number if it's raw.
it is the other way around, e.g. ``aid`` shows track title and language in the
formatted case, but only the track number if it is raw.

191
DOCS/man/en/mpv.rst
View File

@ -1,3 +1,9 @@
..
Hint: To generate a nicely formatted XeLaTeX document from this file, use
rst2xetex --use-latex-docinfo --use-latex-toc --hyperlink-color=MidnightBlue --latex-preamble="\usepackage[usenames,dvipsnames]{xcolor}\usepackage{fullpage}\setmainfont{Droid Sans}\setsansfont{Linux Biolinum O}\setmonofont[HyphenChar=None]{DejaVu Sans Mono}" mpv.rst
You might want to put the .. contents:: directive below to generate a TOC.
mpv
###
@ -6,7 +12,7 @@ a movie player
##############
:Author: wm4
:Date: 2013-07-07
:Date: 2013-07-08
:Copyright: GPLv3
:Version: git
:Manual section: 1
@ -83,7 +89,7 @@ ENTER
p / SPACE
Pause (pressing again unpauses).
.
\.
Step forward. Pressing once will pause movie, every consecutive press will
play one frame and then go into pause mode again.
@ -275,58 +281,61 @@ is the same as ``--no-fs``.
If an option is marked as *(XXX only)*, it will only work in combination with
the *XXX* option or if *XXX* is compiled in.
| *NOTE*: The suboption parser (used for example for ``--ao=pcm`` suboptions)
supports a special kind of string-escaping intended for use with external
GUIs.
| It has the following format:
| %n%string\_of\_length\_n
.. note::
| *EXAMPLES*:
| `mpv --ao=pcm:file=%10%C:test.wav test.avi`
| Or in a script:
| `mpv --ao=pcm:file=%\`expr length "$NAME"\`%"$NAME" test.avi`
The suboption parser (used for example for ``--ao=pcm`` suboptions)
supports a special kind of string-escaping intended for use with external
GUIs.
It has the following format::
%n%string_of_length_n
.. admonition:: Examples
``mpv --ao=pcm:file=%10%C:test.wav test.avi``
Or in a script:
``mpv --ao=pcm:file=%`expr length "$NAME"`%"$NAME" test.avi``
Per-File Options
----------------
When playing multiple files, any option given on the command line usually
affects all files. Example:
affects all files. Example::
`mpv --a file1.mkv --b file2.mkv --c`
mpv --a file1.mkv --b file2.mkv --c
+-----------+-------------------------+
| File | Active options |
+===========+=========================+
| file1.mkv | --a --b --c |
+-----------+-------------------------+
| file2.mkv | --a --b --c |
+-----------+-------------------------+
=============== ===========================
File Active options
=============== ===========================
file1.mkv ``--a --b --c``
file2.mkv ``--a --b --c``
=============== ===========================
Also, if any option is changed at runtime (via input commands), they aren't
Also, if any option is changed at runtime (via input commands), they are not
reset when a new file is played.
Sometimes, it's useful to change options per-file. This can be achieved by
adding the special per-file markers `--{` and `--}`. (Note that you must
escape these on some shells.) Example:
Sometimes, it is useful to change options per-file. This can be achieved by
adding the special per-file markers ``--{`` and ``--}``. (Note that you must
escape these on some shells.) Example::
`mpv --a file1.mkv --b --\\\{ --c file2.mkv --d file3.mkv --e --\\\} file4.mkv --f`
mpv --a file1.mkv --b --\{ --c file2.mkv --d file3.mkv --e --\} file4.mkv --f
+-----------+-------------------------+
| File | Active options |
+===========+=========================+
| file1.mkv | --a --b --f |
+-----------+-------------------------+
| file2.mkv | --a --b --f --c --d --e |
+-----------+-------------------------+
| file3.mkv | --a --b --f --c --d --e |
+-----------+-------------------------+
| file4.mkv | --a --b --f |
+-----------+-------------------------+
=============== ===========================
File Active options
=============== ===========================
file1.mkv ``--a --b --f``
file2.mkv ``--a --b --f --c --d --e``
file3.mkv ``--a --b --f --c --d --e``
file4.mkv ``--a --b --f``
=============== ===========================
Additionally, any file-local option changed at runtime is reset when the current
file stops playing. If option ``--c`` is changed during playback of `file2.mkv`,
it's reset when advancing to `file3.mkv`. This only affects file-local options.
The option ``--a`` is never reset here.
file stops playing. If option ``--c`` is changed during playback of
``file2.mkv``, it is reset when advancing to ``file3.mkv``. This only affects
file-local options. The option ``--a`` is never reset here.
CONFIGURATION FILES
===================
@ -335,21 +344,23 @@ Location and Syntax
-------------------
You can put all of the options in configuration files which will be read every
time mpv is run. The system-wide configuration file 'mpv.conf' is in
your configuration directory (e.g. ``/etc/mpv`` or
``/usr/local/etc/mpv``), the user specific one is ``~/.mpv/config``.
User specific options override system-wide options and options given on the
time mpv is run. The system-wide configuration file 'mpv.conf' is in your
configuration directory (e.g. ``/etc/mpv`` or ``/usr/local/etc/mpv``), the
user-specific one is ``~/.mpv/config``.
User-specific options override system-wide options and options given on the
command line override either. The syntax of the configuration files is
``option=<value>``, everything after a *#* is considered a comment. Options
``option=<value>``; everything after a *#* is considered a comment. Options
that work without values can be enabled by setting them to *yes* and disabled by
setting them to *no*. Even suboptions can be specified in this way.
*EXAMPLE CONFIGURATION FILE:*
.. admonition:: Example configuration file
| # Use opengl video output by default.
| vo=opengl
| # Use quotes for text that can contain spaces:
| status-msg="Time: ${time-pos}"
::
# Use opengl video output by default.
vo=opengl
# Use quotes for text that can contain spaces:
status-msg="Time: ${time-pos}"
Putting Command Line Options into the Configuration File
--------------------------------------------------------
@ -357,19 +368,16 @@ Putting Command Line Options into the Configuration File
Almost all command line options can be put into the configuration file. Here
is a small guide:
+----------------------+--------------------------+
| Option | Configuration file entry |
+======================+==========================+
| --flag | flag |
+----------------------+--------------------------+
| -opt val | opt=val |
+----------------------+--------------------------+
| --opt=val | opt=val |
+----------------------+--------------------------+
| -opt "has spaces" | opt="has spaces" |
+----------------------+--------------------------+
======================= ========================
Option Configuration file entry
======================= ========================
``--flag`` ``flag``
``-opt val`` ``opt=val``
``--opt=val`` ``opt=val``
``-opt "has spaces"`` ``opt="has spaces"``
======================= ========================
File Specific Configuration Files
File-specific Configuration Files
---------------------------------
You can also write file-specific configuration files. If you wish to have a
@ -388,30 +396,32 @@ as the file played and then tries to load any file-specific configuration.
Profiles
--------
To ease working with different configurations profiles can be defined in the
configuration files. A profile starts with its name between square brackets,
e.g. *[my-profile]*. All following options will be part of the profile. A
description (shown by ``--profile=help``) can be defined with the profile-desc
option. To end the profile, start another one or use the profile name
*default* to continue with normal options.
To ease working with different configurations, profiles can be defined in the
configuration files. A profile starts with its name in square brackets,
e.g. ``[my-profile]``. All following options will be part of the profile. A
description (shown by ``--profile=help``) can be defined with the
``profile-desc`` option. To end the profile, start another one or use the
profile name ``default`` to continue with normal options.
*EXAMPLE MPV PROFILE:*
.. admonition:: Example mpv profile
| [vo.vdpau]
| # Use hardware decoding (this might break playback of some h264 files)
| hwdec=vdpau
|
| [protocol.dvd]
| profile-desc="profile for dvd:// streams"
| vf=pp=hb/vb/dr/al/fd
| alang=en
|
| [extension.flv]
| profile-desc="profile for .flv files"
| flip=yes
|
| [ao.alsa]
| device=spdif
::
[vo.vdpau]
# Use hardware decoding (this might break playback of some h264 files)
hwdec=vdpau
[protocol.dvd]
profile-desc="profile for dvd:// streams"
vf=pp=hb/vb/dr/al/fd
alang=en
[extension.flv]
profile-desc="profile for .flv files"
flip=yes
[ao.alsa]
device=spdif
OPTIONS
@ -440,7 +450,7 @@ input mode command, which is by default bound to the ``s`` key. Files named
available number - no files will be overwritten.
A screenshot will usually contain the unscaled video contents at the end of the
video filter chain and subtitles. By default the ``S`` takes screenshots without
video filter chain and subtitles. By default, ``S`` takes screenshots without
subtitles, while ``s`` includes subtitles.
The ``screenshot`` video filter is not required when using a recommended GUI
@ -470,8 +480,8 @@ behavior of mpv.
libaf:
``LADSPA_PATH``
If ``LADSPA_PATH`` is set, it searches for the specified file. If it
is not set, you must supply a fully specified pathname.
Specifies the search path for LADSPA plugins. If it is unset, fully
qualified path names must be used.
FIXME: This is also mentioned in the ladspa section.
@ -483,12 +493,12 @@ libdvdcss:
subdirectory is created named after the DVD's title or manufacturing
date. If ``DVDCSS_CACHE`` is not set or is empty, libdvdcss will use
the default value which is ``${HOME}/.dvdcss/`` under Unix and
``C:\Documents and Settings\$USER\Application Data\dvdcss\`` under
Win32. The special value "off" disables caching.
the roaming application data directory (``%APPDATA%``) under
Windows. The special value "off" disables caching.
``DVDCSS_METHOD``
Sets the authentication and decryption method that libdvdcss will use
to read scrambled discs. Can be one of title, key or disc.
to read scrambled discs. Can be one of ``title``, ``key`` or ``disc``.
key
is the default method. libdvdcss will use a set of calculated
@ -591,9 +601,6 @@ FILES
``~/.mpv/input.conf``
input bindings (see ``--input-keylist`` for the full list)
``~/.mpv/DVDkeys/``
cached CSS keys
EXAMPLES OF MPV USAGE
=====================

1739
DOCS/man/en/options.rst
View File

File diff suppressed because it is too large Load Diff

674
DOCS/man/en/vf.rst
View File

File diff suppressed because it is too large Load Diff

465
DOCS/man/en/vo.rst
View File

@ -1,39 +1,39 @@
.. _video_outputs:
VIDEO OUTPUT DRIVERS
====================
Video output drivers are interfaces to different video output facilities. The
syntax is:
--vo=<driver1[:suboption1[=value]:...],driver2,...[,]>
``--vo=<driver1[:suboption1[=value]:...],driver2,...[,]>``
Specify a priority list of video output drivers to be used.
If the list has a trailing ',' mpv will fall back on drivers not contained
If the list has a trailing ',', mpv will fall back on drivers not contained
in the list. Suboptions are optional and can mostly be omitted.
*NOTE*: See ``--vo=help`` for a list of compiled-in video output drivers.
.. note::
*EXAMPLE*:
See ``--vo=help`` for a list of compiled-in video output drivers.
.. admonition:: Example
``--vo=opengl,xv,``
Try the OpenGL driver, then the Xv driver, then others.
Try the ``opengl`` driver, then the ``xv`` driver, then others.
Available video output drivers are:
xv (X11 only)
Uses the XVideo extension to enable hardware accelerated playback. This is
the most compatible VO on X, but may be low quality, and has issues with
``xv`` (X11 only)
Uses the XVideo extension to enable hardware-accelerated playback. This is
the most compatible VO on X, but may be low-quality, and has issues with
OSD and subtitle display.
For information about what colorkey is used and how it is drawn run
mpv with ``-v`` option and look out for the lines tagged with ``[xv
For information about what colorkey is used and how it is drawn, run
mpv with the ``-v`` option and look out for the lines tagged with ``[xv
common]`` at the beginning.
adaptor=<number>
``adaptor=<number>``
Select a specific XVideo adaptor (check xvinfo results).
port=<number>
``port=<number>``
Select a specific XVideo port.
ck=<cur|use|set>
``ck=<cur|use|set>``
Select the source from which the colorkey is taken (default: cur).
cur
@ -44,7 +44,7 @@ xv (X11 only)
set
Same as use but also sets the supplied colorkey.
ck-method=<man|bg|auto>
``ck-method=<man|bg|auto>``
Sets the colorkey drawing method (default: man).
man
@ -54,94 +54,93 @@ xv (X11 only)
auto
Let Xv draw the colorkey.
x11 (X11 only)
``x11`` (X11 only)
Shared memory video output driver without hardware acceleration that works
whenever X11 is present.
*NOTE*: this is a fallback only, and shouldn't be normally used.
.. note:: This is a fallback only, and should not be normally used.
vdpau (X11 only)
``vdpau`` (X11 only)
Uses the VDPAU interface to display and optionally also decode video.
Hardware decoding is used with ``--hwdec=vdpau``.
sharpen=<-1-1>
``sharpen=<-1-1>``
For positive values, apply a sharpening algorithm to the video, for
negative values a blurring algorithm (default: 0).
denoise=<0-1>
Apply a noise reduction algorithm to the video (default: 0, no noise
``denoise=<0-1>``
Apply a noise reduction algorithm to the video (default: 0; no noise
reduction).
deint=<-4-4>
``deint=<-4-4>``
Select deinterlacing mode (default: -3). Positive values choose mode
and enable deinterlacing. Corresponding negative values select the
same deinterlacing mode, but do not enable deinterlacing on startup
(useful in configuration files to specify what mode will be enabled by
(useful in configuration files to specify which mode will be enabled by
the "D" key). All modes respect ``--field-dominance``.
0
same as -3
Same as -3.
1
Show only first field, similar to ``--vf=field``.
Show only first field.
2
Bob deinterlacing, similar to ``--vf=tfields=1``.
Bob deinterlacing.
3
motion adaptive temporal deinterlacing. May lead to A/V desync
Motion-adaptive temporal deinterlacing. May lead to A/V desync
with slow video hardware and/or high resolution.
4
motion adaptive temporal deinterlacing with edge-guided spatial
Motion-adaptive temporal deinterlacing with edge-guided spatial
interpolation. Needs fast video hardware.
chroma-deint
``chroma-deint``
Makes temporal deinterlacers operate both on luma and chroma (default).
Use no-chroma-deint to solely use luma and speed up advanced
deinterlacing. Useful with slow video memory.
pullup
``pullup``
Try to apply inverse telecine, needs motion adaptive temporal
deinterlacing.
hqscaling=<0-9>
``hqscaling=<0-9>``
0
Use default VDPAU scaling (default).
1-9
Apply high quality VDPAU scaling (needs capable hardware).
fps=<number>
``fps=<number>``
Override autodetected display refresh rate value (the value is needed
for framedrop to allow video playback rates higher than display
refresh rate, and for vsync-aware frame timing adjustments). Default 0
means use autodetected value. A positive value is interpreted as a
refresh rate in Hz and overrides the autodetected value. A negative
value disables all timing adjustment and framedrop logic.
composite-detect
``composite-detect``
NVIDIA's current VDPAU implementation behaves somewhat differently
under a compositing window manager and does not give accurate frame
timing information. With this option enabled, the player tries to
detect whether a compositing window manager is active. If one is
detected, the player disables timing adjustments as if the user had
specified fps=-1 (as they would be based on incorrect input). This
specified ``fps=-1`` (as they would be based on incorrect input). This
means timing is somewhat less accurate than without compositing, but
with the composited mode behavior of the NVIDIA driver there is no
with the composited mode behavior of the NVIDIA driver, there is no
hard playback speed limit even without the disabled logic. Enabled by
default, use no-composite-detect to disable.
queuetime_windowed=<number> and queuetime_fs=<number>
default, use ``no-composite-detect`` to disable.
``queuetime_windowed=<number>`` and ``queuetime_fs=<number>``
Use VDPAU's presentation queue functionality to queue future video
frame changes at most this many milliseconds in advance (default: 50).
See below for additional information.
output_surfaces=<2-15>
``output_surfaces=<2-15>``
Allocate this many output surfaces to display video frames (default:
3). See below for additional information.
Using the VDPAU frame queueing functionality controlled by the queuetime
options makes mpv's frame flip timing less sensitive to system CPU
load and allows mpv to start decoding the next frame(s) slightly
earlier which can reduce jitter caused by individual slow-to-decode
frames. However the NVIDIA graphics drivers can make other window behavior
such as window moves choppy if VDPAU is using the blit queue (mainly
happens if you have the composite extension enabled) and this feature is
active. If this happens on your system and it bothers you then you can set
the queuetime value to 0 to disable this feature. The settings to use in
windowed and fullscreen mode are separate because there should be less
reason to disable this for fullscreen mode (as the driver issue shouldn't
affect the video itself).
options makes mpv's frame flip timing less sensitive to system CPU load and
allows mpv to start decoding the next frame(s) slightly earlier, which can
reduce jitter caused by individual slow-to-decode frames. However, the
NVIDIA graphics drivers can make other window behavior such as window moves
choppy if VDPAU is using the blit queue (mainly happens if you have the
composite extension enabled) and this feature is active. If this happens on
your system and it bothers you then you can set the queuetime value to 0 to
disable this feature. The settings to use in windowed and fullscreen mode
are separate because there should be no reason to disable this for
fullscreen mode (as the driver issue should not affect the video itself).
You can queue more frames ahead by increasing the queuetime values and the
output_surfaces count (to ensure enough surfaces to buffer video for a
``output_surfaces`` count (to ensure enough surfaces to buffer video for a
certain time ahead you need at least as many surfaces as the video has
frames during that time, plus two). This could help make video smoother in
some cases. The main downsides are increased video RAM requirements for
@ -150,73 +149,71 @@ vdpau (X11 only)
driver implementation may also have limits on the length of maximum
queuing time or number of queued surfaces that work well or at all.
direct3d_shaders (Windows only)
``direct3d_shaders`` (Windows only)
Video output driver that uses the Direct3D interface.
prefer-stretchrect
Use IDirect3DDevice9::StretchRect over other methods if possible.
``prefer-stretchrect``
Use ``IDirect3DDevice9::StretchRect`` over other methods if possible.
disable-stretchrect
Never render the video using IDirect3DDevice9::StretchRect.
``disable-stretchrect``
Never render the video using ``IDirect3DDevice9::StretchRect``.
disable-textures
Never render the video using D3D texture rendering. (Rendering with
textures + shader will still be allowed. Add disable-shaders to
completely disable video rendering with textures.)
``disable-textures``
Never render the video using D3D texture rendering. Rendering with
textures + shader will still be allowed. Add ``disable-shaders`` to
completely disable video rendering with textures.
disable-shaders
``disable-shaders``
Never use shaders when rendering video.
only-8bit
``only-8bit``
Never render YUV video with more than 8 bits per component.
(Using this flag will force software conversion to 8 bit.)
Using this flag will force software conversion to 8-bit.
disable-texture-align
``disable-texture-align``
Normally texture sizes are always aligned to 16. With this option
enabled, the video texture will always have exactly the same size as
the video itself.
Debug options. These might be incorrect, might be removed in the future, might
crash, might cause slow downs, etc. Contact the developers if you actually need
any of these for performance or proper operation.
Debug options. These might be incorrect, might be removed in the future,
might crash, might cause slow downs, etc. Contact the developers if you
actually need any of these for performance or proper operation.
force-power-of-2
``force-power-of-2``
Always force textures to power of 2, even if the device reports
non-power-of-2 texture sizes as supported.
texture-memory=N
``texture-memory=N``
Only affects operation with shaders/texturing enabled, and (E)OSD.
Values for N:
0
default, will often use an additional shadow texture + copy
1
use D3DPOOL_MANAGED
use ``D3DPOOL_MANAGED``
2
use D3DPOOL_DEFAULT
use ``D3DPOOL_DEFAULT``
3
use D3DPOOL_SYSTEMMEM, but without shadow texture
use ``D3DPOOL_SYSTEMMEM``, but without shadow texture
swap-discard
Use D3DSWAPEFFECT_DISCARD, which might be faster.
Might be slower too, as it must (?) clear every frame.
``swap-discard``
Use ``D3DSWAPEFFECT_DISCARD``, which might be faster.
Might be slower too, as it must(?) clear every frame.
exact-backbuffer
``exact-backbuffer``
Always resize the backbuffer to window size.
direct3d (Windows only)
``direct3d`` (Windows only)
Same as ``direct3d_shaders``, but with the options ``disable-textures``
and ``disable-shaders`` forced.
corevideo (Mac OS X 10.6 and later)
``corevideo`` (Mac OS X 10.6 and later)
Mac OS X CoreVideo video output driver. Uses the CoreVideo APIs to fill
PixelBuffers and generate OpenGL textures from them (useful as a fallback
for vo_opengl_).
for ``opengl``).
.. _vo_opengl:
opengl
``opengl``
OpenGL video output driver. It supports extended scaling methods, dithering
and color management.
@ -224,13 +221,13 @@ opengl
``opengl-hq`` to use this driver with defaults set to high quality
rendering.
Requires at least OpenGL 2.1 and the GL_ARB_texture_rg extension. For older
drivers, ``opengl-old`` may work.
Requires at least OpenGL 2.1 and the ``GL_ARB_texture_rg`` extension. For
older drivers, ``opengl-old`` may work.
Some features are available with OpenGL 3 capable graphics drivers only
(or if the necessary extensions are available).
lscale=<filter>
``lscale=<filter>``
Set the scaling filter. Possible choices:
bilinear
bicubic_fast
@ -257,41 +254,41 @@ opengl
blackman3
blackman4
bilinear
``bilinear``
Bilinear hardware texture filtering (fastest, mid-quality).
This is the default.
lanczos2
``lanczos2``
Lanczos scaling with radius=2. Provides good quality and speed.
This is the default when using ``opengl-hq``.
lanczos3
``lanczos3``
Lanczos with radius=3.
bicubic_fast
``bicubic_fast``
Bicubic filter. Has a blurring effect on the image, even if no
scaling is done.
sharpen3
``sharpen3``
Unsharp masking (sharpening) with radius=3 and a default strength
of 0.5 (see ``lparam1``).
sharpen5
``sharpen5``
Unsharp masking (sharpening) with radius=5 and a default strength
of 0.5 (see ``lparam1``).
mitchell
``mitchell``
Mitchell-Netravali. The ``b`` and ``c`` parameters can be set with
``lparam1`` and ``lparam2``. Both are set to 1/3 by default.
lparam1=<value>
``lparam1=<value>``
Set filter parameters. Ignored if the filter is not tunable. These are
unset by default, and use the filter specific default if applicable.
lparam2=<value>
``lparam2=<value>``
See ``lparam1``.
scaler-resizes-only
``scaler-resizes-only``
Disable the scaler if the video image is not resized. In that case,
``bilinear`` is used instead whatever is set with ``lscale``. Bilinear
will reproduce the source image perfectly if no scaling is performed.
@ -299,7 +296,7 @@ opengl
processing chain might do chroma scaling differently if ``lscale`` is
disabled.
stereo=<value>
``stereo=<value>``
Select a method for stereo display. You may have to use ``--aspect`` to
fix the aspect value. Experimental, do not expect too much from it.
@ -313,36 +310,40 @@ opengl
Convert side by side input to quadbuffered stereo. Only supported
by very few OpenGL cards.
srgb
``srgb``
Enable gamma-correct scaling by working in linear light. This
makes use of sRGB textures and framebuffers.
This option forces the options 'indirect' and 'gamma'.
NOTE: for YUV colorspaces, gamma 1/0.45 (2.222) is assumed. RGB input
is always assumed to be in sRGB.
This option forces the options ``indirect`` and ``gamma``.
.. note::
for YUV colorspaces, gamma 1/0.45 (2.222) is assumed. RGB input is
always assumed to be in sRGB.
This option is not really useful, as gamma-correct scaling has not much
influence on typical video playback. Most visible effect comes from
slightly different gamma.
pbo
Enable use of PBOs. This is faster, but can sometimes lead to
sporadic and temporary image corruption.
``pbo``
Enable use of PBOs. This is faster, but can sometimes lead to sporadic
and temporary image corruption.
dither-depth=<N|no|auto>
``dither-depth=<N|no|auto>``
Set dither target depth to N. Default: no.
no
Disable any dithering done by mpv.
auto
Automatic selection. If output bit depth can't be detected,
Automatic selection. If output bit depth cannot be detected,
8 bits per component are assumed.
8
Dither to 8 bit output.
Note that the depth of the connected video display device can not be
detected. Often, LCD panels will do dithering on their own, which
conflicts with vo_opengl's dithering, and leads to ugly output.
conflicts with ``opengl``'s dithering and leads to ugly output.
dither-size-fruit=<2-8>
``dither-size-fruit=<2-8>``
Set the size of the dither matrix (default: 6). The actual size of
the matrix is ``(2^N) x (2^N)`` for an option value of ``N``, so a
value of 6 gives a size of 64x64. The matrix is generated at startup
@ -350,27 +351,26 @@ opengl
Used in ``dither=fruit`` mode only.
dither=<fruit|ordered|no>
``dither=<fruit|ordered|no>``
Select dithering algorithm (default: fruit).
temporal-dither
``temporal-dither``
Enable temporal dithering. (Only active if dithering is enabled in
general.) This changes between 8 different dithering pattern on each
frame by changing the orientation of the tiled dithering matrix.
Unfortunately, this can lead to flicker on LCD displays, since these
have a high reaction time.
debug
Check for OpenGL errors, i.e. call glGetError(). Also request a
``debug``
Check for OpenGL errors, i.e. call ``glGetError()``. Also request a
debug OpenGL context (which does nothing with current graphics drivers
as of this writing).
swapinterval=<n>
``swapinterval=<n>``
Interval in displayed frames between two buffer swaps.
1 is equivalent to enable VSYNC, 0 to disable VSYNC.
no-scale-sep
``no-scale-sep``
When using a separable scale filter for luma, usually two filter
passes are done. This is often faster. However, it forces
conversion to RGB in an extra pass, so it can actually be slower
@ -378,27 +378,27 @@ opengl
this options will make rendering a single operation.
Note that chroma scalers are always done as 1-pass filters.
cscale=<n>
As lscale but for chroma (2x slower with little visible effect).
``cscale=<n>``
As ``lscale``, but for chroma (2x slower with little visible effect).
Note that with some scaling filters, upscaling is always done in
RGB. If chroma is not subsampled, this option is ignored, and the
luma scaler is used instead. Setting this option is often useless.
fancy-downscaling
``fancy-downscaling``
When using convolution based filters, extend the filter size
when downscaling. Trades quality for reduced downscaling performance.
no-npot
``no-npot``
Force use of power-of-2 texture sizes. For debugging only.
Borders will be distorted due to filtering.
glfinish
Call glFinish() before swapping buffers
``glfinish``
Call ``glFinish()`` before swapping buffers
sw
``sw``
Continue even if a software renderer is detected.
backend=<sys>
``backend=<sys>``
auto
auto-select (default)
cocoa
@ -410,39 +410,37 @@ opengl
wayland
Wayland/EGL
indirect
Do YUV conversion and scaling as separate passes. This will
first render the video into a video-sized RGB texture, and
draw the result on screen. The luma scaler is used to scale
the RGB image when rendering to screen. The chroma scaler
is used only on YUV conversion, and only if the video is
chroma-subsampled (usually the case).
``indirect``
Do YUV conversion and scaling as separate passes. This will first render
the video into a video-sized RGB texture, and draw the result on screen.
The luma scaler is used to scale the RGB image when rendering to screen.
The chroma scaler is used only on YUV conversion, and only if the video
is chroma-subsampled (usually the case).
This mechanism is disabled on RGB input.
Specifying this option directly is generally useful for debugging only.
fbo-format=<fmt>
``fbo-format=<fmt>``
Selects the internal format of textures used for FBOs. The format can
influence performance and quality of the video output. (FBOs are not
always used, and typically only when using extended scalers.)
fmt can be one of: rgb, rgba, rgb8, rgb10, rgb16, rgb16f, rgb32f,
``fmt`` can be one of: rgb, rgba, rgb8, rgb10, rgb16, rgb16f, rgb32f,
rgba12, rgba16, rgba16f, rgba32f.
Default: rgb.
gamma
``gamma``
Always enable gamma control. (Disables delayed enabling.)
icc-profile=<file>
Load an ICC profile and use it to transform linear RGB to
screen output. Needs LittleCMS2 support compiled in.
``icc-profile=<file>``
Load an ICC profile and use it to transform linear RGB to screen output.
Needs LittleCMS2 support compiled in.
icc-cache=<file>
Store and load the 3D LUT created from the ICC profile in
this file. This can be used to speed up loading, since
LittleCMS2 can take a while to create the 3D LUT.
Note that this file contains an uncompressed LUT. Its size depends on
the ``3dlut-size``, and can be very big.
``icc-cache=<file>``
Store and load the 3D LUT created from the ICC profile in this file.
This can be used to speed up loading, since LittleCMS2 can take a while
to create the 3D LUT. Note that this file contains an uncompressed LUT.
Its size depends on the ``3dlut-size``, and can be very big.
icc-intent=<value>
``icc-intent=<value>``
0
perceptual
1
@ -452,69 +450,65 @@ opengl
3
absolute colorimetric (default)
3dlut-size=<r>x<g>x<b>
Size of the 3D LUT generated from the ICC profile in each
dimension. Default is 128x256x64.
``3dlut-size=<r>x<g>x<b>``
Size of the 3D LUT generated from the ICC profile in each dimension.
Default is 128x256x64.
Sizes must be a power of two, and 256 at most.
alpha
``alpha``
Try to create a framebuffer with alpha component. This only makes sense
if the video contains alpha information (which is extremely rare). May
not be supported on all platforms. If alpha framebuffers are
unavailable, it silently falls back to a normal framebuffer. Note
that when using FBO indirections (such as with ``opengl-hq``), a FBO
unavailable, it silently falls back on a normal framebuffer. Note
that when using FBO indirections (such as with ``opengl-hq``), an FBO
format with alpha must be specified with the ``fbo-format`` option.
chroma-location=<auto|center|left>
``chroma-location=<auto|center|left>``
Set the YUV chroma sample location. auto means use the bitstream
flags (default: auto).
opengl-hq
``opengl-hq``
Same as ``opengl``, but with default settings for high quality rendering.
This is equivalent to:
This is equivalent to::
| --vo=opengl:lscale=lanczos2:dither-depth=auto:pbo:fbo-format=rgb16
--vo=opengl:lscale=lanczos2:dither-depth=auto:pbo:fbo-format=rgb16
Note that some cheaper LCDs do dithering that gravely interferes with
vo_opengl's dithering. Disabling dithering with ``dither-depth=no`` helps.
``opengl``'s dithering. Disabling dithering with ``dither-depth=no`` helps.
Unlike ``opengl``, ``opengl-hq`` makes use of FBOs by default. Sometimes you
can achieve better quality or performance by changing the fbo-format
sub-option to ``rgb16f``, ``rgb32f`` or ``rgb``. (Known problems include
can achieve better quality or performance by changing the ``fbo-format``
suboption to ``rgb16f``, ``rgb32f`` or ``rgb``. Known problems include
Mesa/Intel not accepting ``rgb16``, Mesa sometimes not being compiled with
float texture support, and some OSX setups being very slow with ``rgb16``,
but fast with ``rgb32f``.)
float texture support, and some OSX setups being very slow with ``rgb16``
but fast with ``rgb32f``.
opengl-old
``opengl-old``
OpenGL video output driver, old version. Video size must be smaller
than the maximum texture size of your OpenGL implementation. Intended to
work even with the most basic OpenGL implementations, but also makes use
of newer extensions, which allow support for more colorspaces.
of newer extensions which allow support for more color spaces.
The code performs very few checks, so if a feature does not work, this
might be because it is not supported by your card/OpenGL implementation
even if you do not get any error message. Use ``glxinfo`` or a similar
tool to display the supported OpenGL extensions.
might be because it is not supported by your card and/or OpenGL
implementation, even if you do not get any error message. Use ``glxinfo``
or a similar tool to display the supported OpenGL extensions.
(no-)ati-hack
``(no-)ati-hack``
ATI drivers may give a corrupted image when PBOs are used (when using
`force-pbo`). This option fixes this, at the expense of
using a bit more memory.
(no-)force-pbo
``force-pbo``). This option fixes this, at the expense of using a bit
more memory.
``(no-)force-pbo``
Always uses PBOs to transfer textures even if this involves an extra
copy. Currently this gives a little extra speed with NVidia drivers
and a lot more speed with ATI drivers. May need
the ati-hack suboption to work correctly.
(no-)scaled-osd
Changes the way the OSD behaves when the size of the window changes
(default: disabled). When enabled behaves more like the other video
output drivers, which is better for fixed-size fonts. Disabled looks
much better with FreeType fonts and uses the borders in fullscreen
mode. Does not work correctly with ass subtitles (see ``--ass``), you
can instead render them without OpenGL support via ``--vf=ass``.
rectangle=<0,1,2>
Select usage of rectangular textures which saves video RAM, but often
copy. Currently this gives a little extra speed with NVIDIA drivers
and a lot more speed with ATI drivers. May need the ``ati-hack``
suboption to work correctly.
``(no-)scaled-osd``
Scales the OSD and subtitles instead of rendering them at display size
(default: disabled).
``rectangle=<0,1,2>``
Select usage of rectangular textures, which saves video RAM, but often
is slower (default: 0).
0
@ -525,18 +519,18 @@ opengl-old
Use the ``GL_ARB_texture_non_power_of_two`` extension. In some
cases only supported in software and thus very slow.
swapinterval=<n>
``swapinterval=<n>``
Minimum interval between two buffer swaps, counted in displayed frames
(default: 1). 1 is equivalent to enabling VSYNC, 0 to disabling VSYNC.
Values below 0 will leave it at the system default. This limits the
framerate to (horizontal refresh rate / n). Requires
``GLX_SGI_swap_control`` support to work. With some (most/all?)
implementations this only works in fullscreen mode.
ycbcr
``ycbcr``
Use the ``GL_MESA_ycbcr_texture`` extension to convert YUV to RGB. In
most cases this is probably slower than doing software conversion to
RGB.
yuv=<n>
``yuv=<n>``
Select the type of YUV to RGB conversion. The default is
auto-detection deciding between values 0 and 2.
@ -544,16 +538,16 @@ opengl-old
Use software conversion. Compatible with all OpenGL versions.
Provides brightness, contrast and saturation control.
1
Same as 2. This used to use nVidia-specific extensions, which
didn't provide any advantages over using fragment programs, except
possibly on very ancient graphic cards. It produced a gray-ish
Same as 2. This used to use NVIDIA-specific extensions, which
did not provide any advantages over using fragment programs, except
possibly on very ancient graphics cards. It produced a gray-ish
output, which is why it has been removed.
2
Use a fragment program. Needs the ``GL_ARB_fragment_program``
extension and at least three texture units. Provides brightness,
contrast, saturation and hue control.
3
Use a fragment program using the POW instruction. Needs the
Use a fragment program using the ``POW`` instruction. Needs the
``GL_ARB_fragment_program`` extension and at least three texture
units. Provides brightness, contrast, saturation, hue and gamma
control. Gamma can also be set independently for red, green and
@ -579,7 +573,7 @@ opengl-old
also be set independently for red, green and blue. Speed depends
more on GPU memory bandwidth than other methods.
lscale=<n>
``lscale=<n>``
Select the scaling function to use for luminance scaling. Only valid
for yuv modes 2, 3, 4 and 6.
@ -597,18 +591,18 @@ opengl-old
some cards.
4
Use experimental unsharp masking with 3x3 support and a default
strength of 0.5 (see `filter-strength`).
strength of 0.5 (see ``filter-strength``).
5
Use experimental unsharp masking with 5x5 support and a default
strength of 0.5 (see `filter-strength`).
strength of 0.5 (see ``filter-strength``).
cscale=<n>
``cscale=<n>``
Select the scaling function to use for chrominance scaling. For
details see `lscale`.
filter-strength=<value>
Set the effect strength for the `lscale`/`cscale` filters that support
it.
stereo=<value>
details see ``lscale``.
``filter-strength=<value>``
Set the effect strength for the ``lscale``/``cscale`` filters that
support it.
``stereo=<value>``
Select a method for stereo display. You may have to use ``--aspect`` to
fix the aspect value. Experimental, do not expect too much from it.
@ -622,44 +616,43 @@ opengl-old
Convert side by side input to quadbuffered stereo. Only supported
by very few OpenGL cards.
The following options are only useful if writing your own fragment
programs.
The following options are only useful if writing your own fragment programs.
customprog=<filename>
Load a custom fragment program from <filename>. See
``customprog=<filename>``
Load a custom fragment program from ``<filename>``. See
``TOOLS/edgedect.fp`` for an example.
customtex=<filename>
Load a custom "gamma ramp" texture from <filename>. This can be used
in combination with yuv=4 or with the customprog option.
(no-)customtlin
``customtex=<filename>``
Load a custom "gamma ramp" texture from ``<filename>``. This can be used
in combination with ``yuv=4`` or with the ``customprog`` option.
``(no-)customtlin``
If enabled (default) use ``GL_LINEAR`` interpolation, otherwise use
``GL_NEAREST`` for customtex texture.
(no-)customtrect
If enabled, use texture_rectangle for customtex texture. Default is
disabled.
(no-)mipmapgen
``(no-)customtrect``
If enabled, use ``texture_rectangle`` for the ``customtex`` texture.
Default is disabled.
``(no-)mipmapgen``
If enabled, mipmaps for the video are automatically generated. This
should be useful together with the customprog and the TXB instruction
to implement blur filters with a large radius. For most OpenGL
implementations this is very slow for any non-RGB formats. Default is
disabled.
should be useful together with the ``customprog`` and the ``TXB``
instruction to implement blur filters with a large radius. For most
OpenGL implementations, this is very slow for any non-RGB formats.
Default is disabled.
Normally there is no reason to use the following options, they mostly
Normally there is no reason to use the following options; they mostly
exist for testing purposes.
(no-)glfinish
``(no-)glfinish``
Call ``glFinish()`` before swapping buffers. Slower but in some cases
more correct output (default: disabled).
(no-)manyfmts
Enables support for more (RGB and BGR) color formats (default:
enabled). Needs OpenGL version >= 1.2.
slice-height=<0-...>
``(no-)manyfmts``
Enables support for more (RGB and BGR) color formats (default: enabled).
Needs OpenGL version >= 1.2.
``slice-height=<0-...>``
Number of lines copied to texture in one piece (default: 0). 0 for
whole image.
sw
``sw``
Continue even if a software renderer is detected.
backend=<sys>
``backend=<sys>``
auto
auto-select (default)
cocoa
@ -671,28 +664,28 @@ opengl-old
wayland
Wayland/EGL
sdl
``sdl``
SDL 2.0+ Render video output driver, depending on system with or without
hardware acceleration. Should work everywhere where SDL 2.0 builds. For
tuning, refer to your copy of the file SDL_hints.h.
hardware acceleration. Should work on all platforms supported by SDL 2.0.
For tuning, refer to your copy of the file ``SDL_hints.h``.
sw
``sw``
Continue even if a software renderer is detected.
switch-mode
``switch-mode``
Instruct SDL to switch the monitor video mode when going fullscreen.
null
``null``
Produces no video output. Useful for benchmarking.
caca
``caca``
Color ASCII art video output driver that works on a text console.
image
``image``
Output each frame into an image file in the current directory. Each file
takes the frame number padded with leading zeros as name.
format=<format>
``format=<format>``
Select the image file format.
jpg
@ -710,22 +703,22 @@ image
tga
Truevision TGA.
png-compression=<0-9>
``png-compression=<0-9>``
PNG compression factor (speed vs. file size tradeoff) (default: 7)
png-filter=<0-5>
``png-filter=<0-5>``
Filter applied prior to PNG compression (0 = none; 1 = sub; 2 = up;
3 = average; 4 = Paeth; 5 = mixed) (default: 5)
jpeg-quality=<0-100>
``jpeg-quality=<0-100>``
JPEG quality factor (default: 90)
[no-]jpeg-progressive
``(no-)jpeg-progressive``
Specify standard or progressive JPEG (default: no).
[no-]jpeg-baseline
``(no-)jpeg-baseline``
Specify use of JPEG baseline or not (default: yes).
jpeg-optimize=<0-100>
``jpeg-optimize=<0-100>``
JPEG optimization factor (default: 100)
jpeg-smooth=<0-100>
``jpeg-smooth=<0-100>``
smooth factor (default: 0)
jpeg-dpi=<1->
``jpeg-dpi=<1->``
JPEG DPI (default: 72)
outdir=<dirname>
``outdir=<dirname>``
Specify the directory to save the image files to (default: ``./``).