Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”
This is a manual describing software and methods for playing movies and troubleshooting issues with playback of digital video on GNU/Linux systems.
Copyright © 2004 David W. Yip.
GNU (GNU's Not Unix)/Linux systems are capable of playback of just about any sort of video that one may care to play. However, the configuration of these systems, though substantially easier than it has been in years past, can still be somewhat daunting for the GNU/Linux neophyte. This manual will attempt to redress that problem.
Most modern GNU/Linux systems do not require gargantuan amounts of effort to achieve good video playback. In some cases, the system already comes with all the tools one would need to enjoy good video playback.
You should start with this chapter, and only go to the following chapters if you find that you have issues with the material in this chapter.
Without a properly configured system, video playback will never be enjoyable. This section addresses the topic of proper configuration and system optimization.
The X Window System is the most commonly used graphical environment for GNU/Linux systems. As a result, it will be discussed first.
The most important factor in smooth video playback under any graphical environment is the proper utilization of hardware overlays. Hardware overlays are what they sound like they are: they are sections of the screen overlaid with data directly streamed from the video hardware. This is far faster than just about any method (except perhaps, in some cases, OpenGL) and should be used whenever possible.
Xorg and XFree86 are the two most commonly used X Window system implementations on GNU/Linux systems. Xorg is a fork of XFree86 started by freedesktop.org to avoid licensing problems with the new XFree86 license, and is now considered by many to be the more active implementation, from the standpoint of development status.
The X extension used in the Xorg X server (and, by inheritance, the XFree86 server) is the Xv extension, which is short for Xvideo. If this extension is loaded and active, then Xv support is installed and working properly.
It is very easy to determine if Xv is properly functioning. To check, run the
xvinfo | lesscommand. You will see a flurry of output, which is dissected here.
bash-2.05b$ xvinfo X-Video Extension version 2.2 screen #0
This begins the listing of overlays available on screen 0. One method that X uses to identify multiple output devices is the idea of a screen, which may be a physically separate video output device or a logically separate output (such as tunnelling X data over an SSH (Secure Shell) link.
Adaptor #0: "ATI Radeon Video Overlay"
number of ports: 1
port base: 69
operations supported: PutImage
supported visuals:
This is one of the important parts of the output. If a line similar to this (adjusted for the video card being used) is present, Xv is most likely active.
depth 24, visualID 0x23
depth 24, visualID 0x24
depth 24, visualID 0x25
depth 24, visualID 0x26
depth 24, visualID 0x27
depth 24, visualID 0x28
depth 24, visualID 0x29
depth 24, visualID 0x2a
depth 24, visualID 0x2b
depth 24, visualID 0x2c
depth 24, visualID 0x2d
depth 24, visualID 0x2e
depth 24, visualID 0x2f
depth 24, visualID 0x30
depth 24, visualID 0x31
depth 24, visualID 0x32
These are color depths and visual IDs assigned by X, and are helpful for determining exactly what colordepth the overlay is operating at.
number of attributes: 15
"XV_SET_DEFAULTS" (range 0 to 1)
client settable attribute
"XV_AUTOPAINT_COLORKEY" (range 0 to 1)
client settable attribute
client gettable attribute (current value is 1)
"XV_COLORKEY" (range 0 to -1)
client settable attribute
client gettable attribute (current value is 30)
"XV_DOUBLE_BUFFER" (range 0 to 1)
client settable attribute
client gettable attribute (current value is 1)
"XV_BRIGHTNESS" (range -1000 to 1000)
client settable attribute
client gettable attribute (current value is 0)
"XV_CONTRAST" (range -1000 to 1000)
client settable attribute
client gettable attribute (current value is 0)
"XV_SATURATION" (range -1000 to 1000)
client settable attribute
client gettable attribute (current value is 0)
"XV_COLOR" (range -1000 to 1000)
client settable attribute
client gettable attribute (current value is 0)
"XV_HUE" (range -1000 to 1000)
client settable attribute
client gettable attribute (current value is 0)
"XV_RED_INTENSITY" (range -1000 to 1000)
client settable attribute
client gettable attribute (current value is 0)
"XV_GREEN_INTENSITY" (range -1000 to 1000)
client settable attribute
client gettable attribute (current value is 0)
"XV_BLUE_INTENSITY" (range -1000 to 1000)
client settable attribute
client gettable attribute (current value is 0)
"XV_SWITCHCRT" (range 0 to 1)
client settable attribute
client gettable attribute (current value is 0)
"XV_GAMMA" (range 100 to 10000)
client settable attribute
client gettable attribute (current value is 1000)
"XV_COLORSPACE" (range 0 to 1)
client settable attribute
client gettable attribute (current value is 0)
These are attributes that the overlay has flagged as adjustable. For example, in this example, attributes such as gamma correction, hue correction, brightness, saturation, and double buffering may be adjusted by applications that can use Xv.
maximum XvImage size: 2048 x 2048
This dimension states the largest possible image that can be used with this overlay device.
Number of image formats: 4
id: 0x32595559 (YUY2)
guid: 59555932-0000-0010-8000-00aa00389b71
bits per pixel: 16
number of planes: 1
type: YUV (packed)
id: 0x59565955 (UYVY)
guid: 55595659-0000-0010-8000-00aa00389b71
bits per pixel: 16
number of planes: 1
type: YUV (packed)
id: 0x32315659 (YV12)
guid: 59563132-0000-0010-8000-00aa00389b71
bits per pixel: 12
number of planes: 3
type: YUV (planar)
id: 0x30323449 (I420)
guid: 49343230-0000-0010-8000-00aa00389b71
bits per pixel: 12
number of planes: 3
type: YUV (planar)
This is another important section. Almost all modern codecs operate in YUV 4:2:0 planar colorspace, which is a way of stating that the luminance, red chrominance, and blue chrominance information is stored separately, rather than packed into triplets. The name also contains information about the ratio of chrominance to luminance samples (in this case, two chrominance samples – one red, one blue – to every four luminance samples). YUV 4:2:0 planar is also called YV12.
The overlay being used must be able to handle YV12 video data. As most – if not all – modern hardware-accelerated overlay circuitry directly supports YV12 video data, the presence of the YV12 image format and the overlay name is a very reliable measure for determining the presence (or lack thereof) of Xv acceleration.
Xv support is included with drivers for most modern cards. The cards listed below have been confirmed by the author to have working Xv support:
A more comprehensive listing may be found either at Xorg's driver listing or XFree86's driver listing.
Acceptable performance on NVIDIA cards can be achieved using the drivers provided with Xorg or XFree86, but far superior performance is currently achieved using NVIDIA's proprietary Linux drivers.
The X Composite Extension provides an off-screen buffer for X Window systems that implement it. When this extension is in use, draw calls made by X applications are redirected to the buffer, where compositing operations may be done on the objects in the buffer. Among other things, this allows expanded possibilities for visual effects.
The Composite extension is still experimental, and at the moment does not interact well with Xv. Xv-accelerated video works; however, because Xv draws directly to video memory instead of the Composite buffer, graphical artifacts and other undesirable problems may appear.
Additionally, OpenGL applications also do not yet interact well with Composite, for a similar reason. These two problems effectively make both Xv and OpenGL – the two fastest video renderers – unusable under Composite.
For these reasons, usage of Composite is not yet recommended.
The author does not use DirectFB, and is thus unable to provide any specific advice regarding DirectFB usage. However, Matrox cards are reported to work best on DirectFB.
More information is available at the DirectFB project website.
No information is available at this time.
No information is available at this time.
This section is intended primarily for experts who – although being expert in their usage of GNU/Linux systems – may not be aware of substantial performance enhancements for playing digital video.
This section does not describe how to fix problems such as unrecognized sound cards, as most modern distributions do a good job of such basic tasks. Such questions should first be answered in distribution-specific documentation; or, if that fails, by directly contacting the author. See Contact the Author.
The Linux kernel available on modern distributions will handle digital video just fine in almost all cases. These suggestions are only for those who may be running older kernels or want to squeeze performance out of their operating system software. It is assumed that readers of this section are familiar with the kernel compilation process.
Additionally, almost all (if not all) of these features are enabled in kernels on modern distributions, thereby further reducing the chance of having to do kernel configuration.
MTRRs are an abbreviation for Memory Type Range Registers. They first entered the Intel series of CPUs in the P6 (Pentium-Pro, Pentium II) generation, and have been present on all Intel chips and x86/x86-64 chips since.
The idea behind usage of MTRRs is that bus writes (i.e. moving data from memory to video) can be combined into a larger transfer before the data is moved from location to location. Such write-combining operations can lead to a very significant increase: the Linux kernel documentation states a speed gain in image draw operations of at least 2.5x.
Needless to say, the kernel should be made aware of such hardware features – these days, there is almost no reason to not make the kernel aware of MTRRs. To enable them, go to "Processor type and features", and select "MTRR (Memory Type Range Register) support".
The preemptible kernel code is designed to allow a low priority process (i.e. a process not given a large share of CPU time) to be preempted even if it is executing in kernel mode (i.e. running privileged instructions) during a system call instruction.
The English translation of the above sentence may be roughly stated as "low priority processes using operating-system provided services may be interrupted". Ordinarily, processes in such situations could not be preempted (interrupted) by the kernel.
This can reduce the latency of the Linux kernel quite a bit when it is handling real-time or interactive events (read: video players).
On Intel 32-bit machines, there is really no good reason to not enable this option, except for known conflicts with kernel preemption. This option is in the same location as MTRR support.
The traditional method of accessing IDE/ATA drives has been to poll their controller hardware periodically to check for the existence of new data. This method is called programmed I/O, or PIO for short. It is, as one might expect, rather slow and needlessly inefficient.
However, the data on IDE/ATA drives can also be accessed directly through memory, using DMA (Direct Memory Access) channels. This has the benefit of greatly speeding up disk access, which is important for videos that require a high data streaming rate (such as MPEG-2 encodes which may be distributed at anime conventions).
Some IDE chipsets, however, are flaky. With these chipsets, filesystem damage may occur. However, most modern IDE chipsets are stable enough to allow usage of PCI DMA; the only chipset listed by the Linux kernel as unstable is the VIA VP2 chipset. In just about every case, this option should be on.
This option is under "Device Drivers" -> "ATA/ATAPI/MFM/RLL support" -> "Use PCI DMA by default when available". The appropriate driver for the IDE chipset being used must also be available in the kernel; for example, if an NVIDIA NForce controller is driving IDE drives, then the NVIDIA NForce driver must also be present.
There exists a large number of media players for the GNU/Linux system. This section will be expanded and modified to provide information on obtaining, using, and tweaking these players.
mplayer is often regarded as one of the best video players available not only on GNU/Linux systems, but also on many other UNIX-like systems. It includes video player software, a video filtering backend, and an encoding mechanism based on the ffmpeg video library.
mplayer makes heavy use of various video decoder/encoder libraries to provide its extensive capabilities. mplayer is capable of parsing nearly any container format you throw at it, and has native decoders for a plethora of formats. On some systems, such as Intel 32-bit platforms or AMD64 setups running mplayer in 32-bit compatibility mode, mplayer can make use of 32-bit Windows codec libraries to decode additional content, such as Windows Media Video 9 files.
mplayer, like almost all GNU/Linux video players, also has a variety of output devices: that is, you can determine how the video is displayed. The most common output device is Xv, but you can use others, such as OpenGL rendering, X11 DGA, and even exotic renderers such as monochrome and color ASCII art renderers.
For full information on mplayer's capabilities, check the mplayer information page.
The source code for mplayer can be obtained from the mplayer homepage. If you are using Slackware, Linux from Scratch, or just like to install software from source, you will want to use these. Otherwise, it is probably best to install using your distribution's specific package system.
Many distributions include precompiled binary versions of mplayer; however, the feature list in some distributions is more limited than others. For example, some distributions do not include the Windows DirectMedia DLLs that some distributions do. The Debian GNU/Linux project is one of these distributions: they do not include the Win32 codec libraries because of politics internal to the Debian project. In cases like this, the mplayer Win32 codec package will have to be downloaded and installed manually. The location for untarring is usually /usr/lib/win32codecs.
mplayer can be used in two ways. The first, and most common, method is to start mplayer from a terminal within X:
mplayer [movie file here]
Streaming video is handled similarly. For Web-based streaming:
mplayer http:// ...
Over FTP:
mplayer ftp:// ...
RealMedia streaming:
mplayer rtsp:// ...
There are many more examples; see the mplayer manual page for further details.
mplayer contains a GUI, which may be accessed by running gmplayer instead of just mplayer.
mplayer can also be started with or without a GUI by associating it with movie files in a desktop environment such as GNOME, KDE, or XFCE. However, mplayer tends to be more stable without its GUI. If you encounter problems such as program crashes when switching between fullscreen and windowed mode, use mplayer without the GUI.
mplayer has a wealth of features that many users (unfortunately) do not explore. This section is designed to highlight some of the more useful features.
The reader is strongly recommended to read every sentence of the mplayer documentation, as this section of this guide is supplementary to the official documentation.
mplayer options should be first experimented with on the mplayer command line. Once the desired options and parameters are found, it is best to place them in the user-specific mplayer configuration file. This is found in
~/.mplayer/configwhere "~" denotes the location of a user's home directory.
The format of the mplayer configuration file is a key/value structure, an example of which follows:
vf=pp=hb/vb/dr/al:a sid=0 slang=eng osdlevel=0 ffactor=1 subwidth=80 ao=alsa nomouseinput=1 fs=1
All configuration options are mplayer command-line arguments, and vice versa.
One of mplayer's greatest strengths lies in its postprocessing capabilities, which are similar to the postprocessing options in ffdshow.
The syntax to enable these filters, however, is rather messy and off-putting to many users. This section of this guide will thus attempt to clarify usage of postprocessing filters in mplayer. Further information may be found in the mplayer documentation or the mplayer manual page.
Postprocessing filters are enabled and configured through the vf option. The syntax of the vf option on the mplayer command line is as follows:
-vf filter1=parameters,filter2=parameters,...
In the configuration file, this becomes
vf=filter1=parameters,filter2=parameters,...
An example of a simple vf line can be found in the previous section, and is repeated here for convenience:
vf=pp=hb/vb/dr/al:a
This instructs mplayer to activate its internal postprocessing filter, using horizontal deblocking (hb), vertical deblocking (vb), deringing (dr), and automatic luminance (al). The :a tacked on to the al option is a flag instructing the internal postprocessing filter to toggle the automatic luminance feature off if the CPU is detected to be too slow to facilitate smooth playback while doing a particular filter process.
A list of filters and their syntax is provided in this guide. See mplayer filters.
mplayer can toggle between different video and audio output devices, as specified by the vo and ao options, respectively. Run
mplayer -ao help mplayer -vo help
to see what output devices are available.
In almost all cases, the best video output device is Xv. SDL (Simple DirectMedia Layer) output is often also available, but if Xv is present, SDL will use Xv for video output anyway. In some cases, interesting effects can be obtained by using aalib or caca (monochrome and color ASCII art renderers, respectively), or speedups may occur by using OpenGL rendering. The latter renderer may also be of help in cases where the video card being used does not support Xv on anything but the first screen in multi-screen environments. However, in the vast majority of video-viewing tasks, Xv is the best choice.
In the realm of audio outputs, however, there is more reason to switch. mplayer, for example, is fully equipped to deal with multichannel audio – but some audio outputs aren't. A good example can be found in sound devices that are supported by drivers from both the ALSA (Advanced Linux Sound Architecture) project and OSS (Open Sound System) project. Many multichannel sound boards have their multichannel capabilities fully supported by ALSA, but not by OSS. Therefore, if both OSS and ALSA output capabilities are present and functional (which is not a hypothetical situation, as most ALSA installations include OSS compatibility libraries), usage of OSS for sound output will most likely result in malfunctioning or completely nonfunctional multichannel audio.
The conclusion of the case study is that one should always try different audio outputs to see which one works best. As a rule of thumb, however, contemporary ALSA drivers are almost always far superior to OSS drivers (except for a few bizarre cases such as NVIDIA SoundStorm systems).
mplayer has excellent support for subtitles, and there is usually little user intervention required to get mplayer to read a subtitle file, either separate from a video file or embedded into the video container (as is the case with DVD VOBs, MPEG-4 containers, Quicktime movies, Ogg containers, or Matroska files, to name a few.)
First, mplayer must be provided with a font to use for subtitles. This should be either copied or symlinked into the ~/.mplayer directory as subfont.ttf.
Selecting a subtitle file is accomplished via the sub option. Multiple subtitle files may be specified. For subtitles embedded in files, mplayer will print an informational message describing which subtitles are present. Here is an example from the Cutie Honey live action movie, released as a fan-subtitled Matroska file:
Playing [Spork] Cutie Honey - Live Action Movie (part 1 of 2)[AC3-DVD].mkv. Cache fill: 0.00% (0 bytes) [mkv] Track ID 1: video (V_MS/VFW/FOURCC), -vid 0 [mkv] Track ID 2: audio (A_AC3), -aid 0, -alang jpn [mkv] Track ID 3: sutitles (S_TEXT/SSA), -sid 0, -slang eng [mkv] Will play video track 1 [mkv] Will play audio track 2 [mkv] Will display subtitle track 3 Matroska file format detected.Passing the parameters -sid 0 and -slang eng to mplayer will activate the subtitles. These parameters actually work for most subtitled video, and they work well inside the mplayer user-specific configuration file.
Given that mplayer is capable of recognizing a large variety of file formats, it should be possible to use that capability to not only play video files but also recognize them. The "kero" video storage server at http://www.animemusicvideos.org makes use of this capability.
To access this capability, run the midentify shell script. midentify returns data that looks like this:
bash-2.05b$ midentify SilverDream.avi ID_FILENAME="SilverDream.avi" ID_VIDEO_FORMAT=MP42 ID_VIDEO_BITRATE=2352480 ID_VIDEO_WIDTH=640 ID_VIDEO_HEIGHT=360 ID_VIDEO_FPS=29.970 ID_VIDEO_ASPECT=0.0000 ID_AUDIO_CODEC=mp3 ID_AUDIO_FORMAT=85 ID_AUDIO_BITRATE=320000 ID_AUDIO_RATE=44100 ID_AUDIO_NCH=2 ID_LENGTH=300
Not all of these data are present for every file. For example, here is the data returned when probing a RealMedia copy of the Wish music video:
bash-2.05b$ midentify Wish.rm ID_FILENAME="Wish.rm" ID_VIDEO_FORMAT=RV20 ID_VIDEO_BITRATE=0 ID_VIDEO_WIDTH=352 ID_VIDEO_HEIGHT=240 ID_VIDEO_FPS=30.000 ID_VIDEO_ASPECT=0.0000 ID_LENGTH=147
Some of the data is explained below:
xine is another video player. Unlike mplayer, much of xine can be configured graphically.
The xine and mplayer projects are not in competition, despite popular opinion; xine and mplayer members routinely share code and ideas.
xine can handle almost all (but not all) of what mplayer supports. For a full list of what xine supports, see the xine features list.
xine, like mplayer, can be obtained from the xine project page, or from distribution packages. Some Linux distributions, such as Gentoo and Debian, split the xine system into two pieces: the xine library, which contains xine's utility functions, and the xine UI, which is the xine project's official user interface. This separation is made to reflect the idea that xine is not a monolithic player, but a player interface and a player library that can be used in other programs. Kaffeine, covered later in this guide, makes use of the xine player library.
Additionally, some Linux distributions package additional plugins with their xine binary distributions. Gentoo, for example, packages a plugin to enable xine to play CSS-encrypted DVDs; the stock xine distribution does not do this. Distributions that do not include certain plugins can be augmented by manually installing those plugins.
xine configuration is, on the whole, much easier than mplayer's; the graphical interface simplifies configuration issues, as does the xine documentation and manual page. Over time, this section will grow to contain obscure, but useful, configurations for xine.
The VLC Media Player is much more than just a standalone player: it was also designed to be used as a server to broadcast video on IPv4 or IPv6 networks. For example, broadcasting AMVs may be done with this tool in a manner similar to audio streaming as facilitated by SHOUTcast, Icecast, and other audio streaming tools. Precompiled binaries and source code may be obtained at the VLC website.
Kaffeine is a media player for KDE (K Desktop Environment) built using the media handling facilities of the xine player library. It, like xine, can handle a wide variety of local and streaming video; and, like VLC, also supports video broadcasting. Kaffeine can be obtained from the Kaffeine homepage.
Problems are bound to occur in any video setup. This chapter will grow to cover some of the more common problems related to playing videos under GNU/Linux systems.
The most common causes of choppy video are:
Unfortunately, if you've verified the proper functionality of everything else there's not much that can be done to remedy this aside from resizing the file (which will involve recompression, which means loss of video quality) or installing faster components in your computer. Some players, such as mplayer, can at least keep audio and video synchronized (mplayer's -hardframedrop flag is designed for this). This won't fix choppy motion, but it may still provide a tolerable viewing experience.
Many MPEG-4 files use AAC (Advanced Audio Codec) to encode their audio. To decode this, your player must make use of libfaad, an AAC decoding library. Players such as mplayer and xine can make use of libfaad's decoding capabilities, but they must be specifically instructed at compile-time to do so.
To remedy this problem, there are two options.
./configure --help | less
to view a list of all configure options that your player will allow you to
configure.
The author may be reached at either of the two below email addresses:
This text is from the manual page for mplayer 1.0pre5, and is not guaranteed to be accurate for other versions. Updates will occur frequently.
The manual page for mplayer is maintained by Gabucino, Diego Biurrun, and Jonas Jermann.
This section is intended to be informative, not instructive. See mplayer video filtering.
EXAMPLE:
force l3codeca.acm MP3 codec
try libmad first, then fallback to others
try hardware AC3 passthrough, then software AC3 codec, then others
try other codecs except FFmpeg's MP3 decoder
Changes the sample rate of the audio stream to an integer srate (Hz). It only supports the 16 bit little endian format.
Change the number of channels to nch output channels. 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 channels are truncated.
Select the format f and bytes per sample bps used for output from the filter layer. The option bps is an integer and denotes Bytes per sample. The format f is a string containing a concatenated mix of: alaw, mulaw or imaadpcm float or int unsigned or signed le or be (little or big endian)
Select the output volume level. This filter is not reentrant and can therefore only be enabled once for every audio stream.
v: desired gain in dB for all channels in the stream. The gain can be set from -200dB to +60dB (where -200dB mutes the sound completely and +60dB equals a gain of 1000). sc: enable soft clipping.Mixes channels arbitrarily, see DOCS/HTML/en/devices.html#audio-dev for details.
n: number of output channels (1−6). lij: how much of input channel j is mixed into output channel i.Add sub-woofer channel.
fc: Cutoff frequency for low-pass filter (20Hz to 300Hz) default is 60Hz. ch: channel number for the sub-channel.Decoder for matrix encoded surround sound, works on many 2 channel files.
d: delay time in ms for the rear speakers (0ms to 1000ms) default is 15ms.Delays the sound output. Specify the delay separately for each channel in milliseconds (floating point number between 0 and 1000).
Exports the incoming signal to other processes using memory mapping (mmap()).
mmapped_file: File to map data to (default: ~/.mplayer/mplayer-af_export). nsamples: number of samples per channel (default: 512)
Forces the insertion of audio filters to one of the following:
0: Completely automatic insertion of filters (default) 1: Optimize for accuracy 2: Optimize for speed 3: Turn off autoSame as −af (see −af option).
EXAMPLE:
try FFmpeg's libavcodec (mp1/\:2/\:3) codecs first
try Win32 codecs first
EXAMPLE:
−aspect 4:3 or −aspect 1.3333 −aspect 16:9 or −aspect 1.7777
EXAMPLE:
−lavdopts bug=1
NOTE: Just add the values of the things you want to enable. Available options are:
error concealment:
1: use strong deblock filter for damaged MBs 2: iterative MV search (slow) 3: all (default)error resilience:
0: disabled 1: careful (should work with broken encoders) 2: normal (default) (works with compliant encoders) 3: agressive (more checks but might cause problems even for valid bitstreams) 4: very agressivedebug:
0: disabled 1: picture info 2: rate control 4: bitstream 8: MB type 16: QP 32: Motion vector 0x0040: Motion vector visualization (use −noslices) 0x0080: MB skip 0x0100: startcode 0x0200: PTS 0x0400: error resilience 0x0800: memory management control operations (H264) 0x1000: bugsvismv:
0: disabled 1: visualize forward predicted MVs of P frames 2: visualize forward predicted MVs of B frames 4: visualize backward predicted MVs of B framesmanually work around encoder bugs:
0: nothing 1: autodetect bugs (default) 2 (msmpeg4v3): some old lavc generated msmpeg4v3 files (no autodetect) 4 (mpeg4): XviD interlacing bug (autodetected if fourcc==XVIX) 8 (mpeg4): UMP4 (autodetected if fourcc==UMP4) 16 (mpeg4): padding bug (autodetected) 32 (mpeg4): illegal vlc bug (autodetected per fourcc) 64 (mpeg4): XviD and DivX qpel bug (autodetected per fourcc/ver) 128 (mpeg4): old standard qpel (autodetected per fourcc/ver) 256 (mpeg4): another qpel bug (autodetected per fourcc/ver) 512 (mpeg4): direct-qpel-blocksize bug (autodetected per fourcc/ver) 1024 (mpeg4): edge padding bug (autodetected per fourcc/ver)(see lavcopts) For best decoding quality use the same idct algorithm for decoding and encoding. This may come at a price in accuracy, though.
grayscale only decoding (a bit faster than with color)
EXAMPLE:
−vf scale −ssf lgb=3.0
Gaussian blur filter (luma)
Gaussian blur filter (chroma)
sharpen filter (luma)
sharpen filter (chroma)
chroma horizontal shifting
chroma vertical shifting
Stereo
Left channel
Right channel
fast bilinear (default)
bilinear
bicubic (good quality)
experimental
nearest neighbour (bad quality)
area
luma bicubic / chroma bilinear
gauss
sincR
lanczos
bicubic spline
EXAMPLE:
force Win32/\:VFW DivX codec, no fallback
try divx4linux codec first, then fallback to others
try other codecs except Win32 DivX codecs
try libavcodec's MPEG1/\:2 codec, then libmpeg2, then others
EXAMPLE:
try the libavcodec, then Directshow, then VFW codecs and fallback to the others, if still none is ok
try XAnim codecs first
Activate XviD internal postprocessing filter: chroma deblock filter. See also −vf pp, which is faster than XviD's own filter.
Activate XviD internal postprocessing filter: luma deblock filter. See also −vf pp, which is faster than XviD's own filter.
Activate direct rendering method 2.
Deactivate direct rendering method 2.
Activate XviD internal film grain effect. Adds artificial film grain to the video. May increase perceived quality, while lowering true quality. Also see −vf noise.
Scale image by factor <value>.
Set width to value and calculate height to keep correct aspect ratio.
Video filter are plugins that allow you to modify the video stream and its properties. The syntax is:
The parameters are optional and if omitted, some of them are set to default values. Use '-1' to keep the default value. Parameters w:h means width x height in pixels, x:y means x;y position counted from the upper left corner of the bigger image. NOTE: To get a full list of available filters, see −vf help.
Filters are managed in lists.
There are a few commands to manage the filter list.
With filters that support it, you can access parameters by their name.
Available filters are:
Cropped width and height, defaults to original width and height.
Position of the cropped picture, defaults to center.
width and height (default: -1, maximum possible width where boundaries are still visible.
top left corner position (default: -1, uppermost leftmost)
expanded width,height (default: original width,height). Negative values for w and h are treated as offsets to the original size.
EXAMPLE:
adds a 50 pixel border to the bottom of the picture
position of original image on the expanded image (default: center)
OSD/subtitle rendering
0: disable (default) 1: enable
scaled width/height (default: original width/height) NOTE: If −zoom is used, and underlying filters (including libvo) are incapable of scaling, it defaults to d_width/\:d_height!
0: scaled d_width/\:d_height -1: original width/\:height -2: Calculate w/\:h using the other dimension and the prescaled aspect ratio. -3: Calculate w/\:h using the other dimension and the original aspect ratio.Toggle interlaced scaling.
chroma skipping
0: use all available input lines for chroma 1: use only every 2. input line for chroma 2: use only every 4. input line for chroma 3: use only every 8. input line for chromascaling parameter (depends upon the scaling method used)
−sws 2 (bicubic): sharpness (0 (soft) − 100 (sharp)) −sws 7 (gaussian): sharpness (0 (soft) − 100 (sharp)) −sws 9 (lanczos): filter length (1−10)Scale to preset sizes.
qntsc: 352x240 (NTSC quarter screen) qpal: 352x288 (PAL quarter screen) ntsc: 720x480 (standard NTSC) pal: 720x576 (standard PAL) sntsc: 640x480 (square pixel NTSC) spal: 768x576 (square pixel PAL)
Also perform R <−> B swapping.
format name like rgb15, bgr24, yv12, etc (default: yuy2)
format name like rgb15, bgr24, yv12, etc (default: yv12)
Automatically switches the filter off if the CPU is too slow.
Do chrominance filtering, too.
Do not do chrominance filtering (only luminance filtering).
EXAMPLE:
horizontal and vertical deblocking, deringing and automatic brightness/\:contrast
horizontal and vertical deblocking, deringing, automatic brightness/\:contrast and linear blend deinterlacer
default filters without brightness/\:contrast correction
Enable default filters & temporal denoiser.
Deblock horizontal only luminance and switch vertical deblocking on or off automatically depending on available CPU time.
0−6 (default: 3)
force quantization parameter (default: 0, use qp from video)
0: hard thresholding (default) 1: soft thresholding (better deringing, but blurrier)
some equation like "2+2*sin(PI*qp)"
1−31: fixed qscale 32−: fixed bitrate in kBitsforce output fps (float value) (default: 0, autodetect based on height)
control aspect ratio, calculate as DVB_HEIGHT*ASPECTRATIO (default: 576*4/3=768), set it to 576*(16/9)=1024 for a 16:9 TV.
luma noise
chroma noise
uniform noise (gaussian otherwise)
temporal noise (noise pattern changes between frames)
averaged temporal noise (smoother, but a lot slower)
high quality (slightly better looking, slightly slower)
mix random noise with a (semi)regular pattern
spatial luma strength (default = 4)
spatial chroma strength (default = 3)
temporal strength (default = 6)
Threshold (default 10).
Paint pixels which exceed the threshold white (default: 0).
Swap fields if 1 (default: 0).
Enable additional sharpening (default: 0).
Enable twoway sharpening (default: 0).
Apply effect on luma component.
Apply effect on chroma components.
width and height of the matrix, odd sized in both directions (min = 3x3, max = 13x11 or 11x13, usually something between 3x3 and 7x7)
Relative amount of sharpness/\:blur to add to the image (a sane range should be -1.5−1.5).
<0: blur >0: sharpen
deinterleave (placing one above the other)
interleave
swap fields (exchange even & odd lines)
Deinterleave fields, placing them side by side.
Interleave fields again (reversing the effect of fil=d).
Set the frame dropping mode. 0 (default) means don't drop frames to maintain fixed output framerate. 1 means always drop a frame when there have been no drops or telecine merges in the past 5 frames. 2 means always maintain exact 5:4 input to output frame ratio. NOTE: Use mode 1 or 2 with MEncoder.
Analysis mode. Available values are 0 (fixed pattern with initial frame number specified by fr=#) and 1 (agressive search for telecine pattern). Default is 1.
Set initial frame number in sequence. 0−2 are the three clean progressive frames; 3 and 4 are the two interlaced frames. The default, -1, means 'not in telecine sequence'. The number specified here is the type for the imaginary previous frame before the movie starts.
Threshold values to be used in certain modes.
Just like the crop filter, but faster, and works on mixed hard and soft telecined content as well as when y is not a multiple of 4. If x or y would require cropping fractional pixels from the chroma planes, the crop area is extended. This usually means that x and y must be even.
For each ifps input frames the filter will output ofps frames. The ratio of ifps/ofps should match the −fps/−ofps ratio. This could be used to filter movies that are broadcast on TV at a frame rate different from their original frame rate.
If n is nonzero, the chroma plane is copied unchanged. This is useful for YV12 sampled TV, which discards one of the chroma fields.
On x86, if n=1, use MMX2 optimized functions, if n=2, use 3DNow! optimized functions, othewise, use plain C. If this option is not specified, MMX2 and 3DNow! are auto-detected, use this option to override auto-detection.
The larger n will speed up the filter at the expense of accuracy. The default value is n=3. If n is odd, a frame immediately following a frame marked with the REPEAT_FIRST_FIELD mpeg flag is assumed to be progressive, thus filter will not spend any time on soft-telecined MPEG-2 content. This is the only effect of this flag if MMX2 or 3DNow! is available. Without MMX2 and 3DNow, if n=0 or 1, the same calculations will be used as with n=2 or 3. If n=2 or 3, the number of luma levels used to find the frame breaks is reduced from 256 to 128, which results in a faster filter without losing much accuracy. If n=4 or 5, a faster, but much less accurate metric will be used to find the frame breaks, which is more likely to misdetect high vertical detail as interlaced content.
If n is nonzero, print the detailed metrics for each frame. Useful for debugging.
Deinterlace threshold. Used during de-interlacing of unmatched frames. Larger value means less deinterlacing, use n=256 to completely turn off deinterlacing. Default is n=8.
Threshold for comparing a top and bottom fields. Defaults to 128.
Threshold to detect temporal change of a field. Default is 128.
Sum of Absolute Difference threshold, default is 64.
Use two-pass mode. This produces best results. Pass 1 analyzes the video and writes the results to a log file. Pass 2 then reads this log file and uses the information to do the actual work. Note that these passes do NOT correspond to pass 1 and 2 of the encoding process. In order to use divtc two-pass with two-pass video encoding, you must perform three passes: first divtc pass 1 and encoder pass 1, then divtc pass 2 and encoder pass 1, and finally divtc pass 2 and encoder pass 2.
Set the 2-pass log file name (default: "framediff.log").
Set the minimum strength the telecine pattern must have for the filter to believe in it (default: 0.5). This is used to avoid recognizing false pattern from the parts of the video that are very dark or very still.
Set the number of past frames to look at when searching for pattern (default: 30). Longer window improves the reliability of the pattern search, but shorter window improves the reaction time to the changes in the telecine phase. This only affects the one-pass mode. The two-pass mode currently uses fixed window that extends to both future and past.
Sets the initial telecine phase for one-pass mode (default: 0). The two-pass mode can see the future, so it is able to use the correct phase from the beginning, but one-pass mode can only guess. It catches the correct phase when it finds it, but this option can be used to fix the possible juddering at the beginning. The first pass of the two-pass mode also uses this, so if you save the output from the first pass, you get constant phase result.
Set the deghosting threshold (0−255 for one-pass mode, -255−255 for two-pass mode, default 0). If nonzero, deghosting mode is used. This is for video that has been deinterlaced by blending the fields together instead of dropping one of the fields. Deghosting amplifies any compression artifacts in the blended frames, so the parameter value is used as a threshold to exclude those pixels from deghosting that differ from the previous frame less than specified value. If two-pass mode is used, then negative value can be used to make the filter analyze the whole video in the beginning of pass-2 to determine whether it needs deghosting or not and then select either zero or the absolute value of the parameter. Specify this option for pass-2, it makes no difference on pass-1.
Capture field order top-first, transfer bottom-first. Filter will delay the bottom field.
Capture bottom-first, transfer top-first. Filter will delay the top field.
Capture and transfer with the same field order. This mode only exists for the documentation of the other options to refer to, but if you actually select it, the filter will faithfully do nothing ;-)
Capture field order determined automatically by field flags, transfer opposite. Filter selects among t and b modes on a frame by frame basis using field flags. If no field information is available, then this works just like u.
Capture unknown or varying, transfer opposite. Filter selects among t and b on a frame by frame basis by analyzing the images and selecting the alternative that produces best match between the fields.
Capture top-first, transfer unknown or varying. Filter selects among t and p using image analysis.
Capture bottom-first, transfer unknown or varying. Filter selects among b and p using image analysis.
Capture determined by field flags, transfer unknown or varying. Filter selects among t, b and p using field flags and image analysis. If no field information is available, then this works just like U. This is the default mode.
Both capture and transfer unknown or varying. Filter selects among t, b and p using image analysis only.
Verbose operation. Prints the selected mode for each frame and the average squared difference between fields for t, b, and p alternatives.
odd frames into upper field, even to lower, generating a full-height frame at half the framerate
only output odd frames, even frames are dropped, height unchanged
only output even frames, odd frames are dropped, height unchanged
expand each frame to full height, but pad alternate lines with black, framerate unchanged
leave fields unchanged (this will jump/flicker)
interpolate missing lines (the algorithm used might not be so good)
translate fields by 1/4 pixel with linear interp (no jump)
translate fields by 1/4 pixel with 4tap filter (higher quality)
size of the filter
How often the filter should be applied.
blur filter strength (~0.1−4.0) (slower if larger)
prefilter strength (~0.1−2.0)
How different the pixels are allowed to be considered. (~0.1−100.0)
blur filter strength (~0.1−5.0) (slower if larger)
blur (0.0−1.0) or sharpen (-1.0−0.0)
filter all (0), filter flat areas (0−30) or filter edges (-30−0)
coordinates of the top left, top right, bottom left, bottom right corners
linear (0) or cubic resampling (1)
number of lines to select from the middle of the image (default: 12)
sets the default value of the 'hidden' flag (boolean)
flag switching between alphablended (transparent) and opaque (fast) mode
path/filename for the FIFO (named pipe connecting mplayer −vf bmovl to the controlling application)
FIFO commands are:
followed by width*height*4 Bytes of raw RGBA32 data.
followed by width*height*4 Bytes of raw ABGR32 data.
followed by width*height*3 Bytes of raw RGB32 data.
followed by width*height*3 Bytes of raw BGR32 data.
change alpha for area
clear area
disable all alpha transparency. Send "ALPHA 0 0 0 0 0" to enable it again.
hide bitmap
show bitmap
Arguments are:
size of image/area
start blitting at X/Y position
set alpha difference. If you set this to -255 you can then send a sequence of ALPHA-commands to set the area to -225, -200, -175 etc for a nice fade-in-effect! ;)
0: same as original 255: makes everything opaque -255: makes everything transparentclear the framebuffer before blitting.
0: The image will just be blitted on top of the old one, so you don't need to send 1,8MB of RGBA32 data everytime a small part of the screen is updated. 1: clear
If you call the filter with I (uppercase) as the parameter, then ONLY keyframes are rendered. For DVDs it generally means one in every 15/12 frames (IBBPBBPBBPBBPBB), for AVI it means every scene change or every keyint value (see −lavcopts keyint= value if you use MEncoder to encode the video).
When a key frame is found, an 'I!' string followed by a newline character is printed, leaving the current line of mplayer/mencoder output on the screen, because it contains the time (in seconds) and frame number of the keyframe (You can use this information to split the AVI.).
If you call the filter with a numeric parameter 'step' then only one in every 'step' frames is rendered.
If you put an 'i' (lowercase) before the number then an I! is printed (like the I parameter).
If you give only the i then nothing is done to the frames, only I! is
printed.
number of tiles on the x axis (default: 5)
number of tiles on the y axis (default: 5)
Render the tile when 'output' number of frames are reached, where 'output' should be a number less than xtile * ytile. Missing tiles are left blank. You could, for example, write an 8 * 7 tile every 50 frames to have one image every 2 seconds @ 25 fps.
pixel at the start (x/y) (default: 2)
pixel between 2 tiles, (x/y) (default: 4)
Position of the top left corner of the logo.
Width and height of the cleared rectangle.
Thickness of the fuzzy edge of the rectangle (added to w and h). When set to -1, a green rectangle is drawn on the screen to simplify finding the right x,y,w,h parameters.
These options set the maximum width and height the zr card can handle (the MPlayer filter layer currently cannot query those).
Use these options to set maxwidth and maxheight automatically to the values known for card/mode combo. For example, valid options are: dc10-PAL and buz-NTSC (default: dc10+PAL)
Select color or black and white encoding. Black and white encoding is faster. Color is the default.
Horizontal decimation 1, 2 or 4.
Vertical decimation 1, 2 or 4.
Set JPEG compression quality [BEST] 1 - 20 [VERY BAD].
By default, decimation is only performed if the Zoran hardware can upscale the resulting MJPEG images to the original size. The option fd instructs the filter to always perform the requested decimation (ugly).
Copyright © 2000,2001,2002 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ascii without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Constructive modification of this manual is encouraged both by the author and the GNU Free Documentation License. However, if you modify this manual, please note your changes here.
Please add to the revision history log according to the following conventions: