Documentation:Command line

See also: Command-line interface

This page is outdated and information might be incorrect. Create an account to start editing, and then click here to update this article.

Use the command line

TODO: completely outdated

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the --option-name="value" syntax instead of the --option-name value syntax.

Getting help

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e., the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using vlc --help, you will get the basic core options. vlc --longhelp will give all the basic options (core + modules). Adding --advanced will give the "advanced options" (for advanced users). So vlc --longhelp --advanced will give you all options. You can also append --help-verbose if you want more detailed help.

Also, you might want to get debug informations. To do this, use -v or -vv (this will show lower severity messages). If your console supports it, you can add --color to get messages in color.

Opening streams

The following commands start VLC and start reading the given element(s):

Opening a file

Start VLC with:

% vlc my_file

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the VLC features list.

Opening a DVD or VCD, or an audio CD

Start VLC with:

For a DVD with menus:

% vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]

In most cases, vlc dvd:// or vlc dvd://[device] will do.

• On GNU/Linux [device] is the path to the block device: e.g., vlc dvd:///dev/dvd.
• On Windows, [device] is the drive letter with / and :/: e.g., vlc dvd:///D:/.

or

(DVD without menus):

% vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]

or

(VCD):

% vlc vcd://[device][@{E|P|E|T|S}[number]]

or

(Audio CD):

% vlc cdda://[device][@[track]]

Receiving a network stream

To receive an unicast RTP/UDP stream (sent by VLC's stream output), start VLC with:

% vlc rtp://@:5004

If 5004 is the port to which packets are sent. 1234 is another commonly used port number. you use the default port (1234), vlc rtp:// will do. For more information, look at the Streaming Howto.

To receive an multicast UDP/RTP stream (sent by VLC's stream output), start VLC with:

% vlc rtp://@multicast_address:port

To receive a SSM (source specific multicast) stream, you can use:

% vlc rtp://server_address@multicast_address:port

This only works on OSs that support SSM (Windows XP and Linux).

To receive a HTTP stream, start VLC with:

% vlc http://www.example.org/your_file.mpg

To receive a RTSP stream, start VLC with:

% vlc rtsp://www.example.org/your_stream

Modules selection

See also: Documentation:Modules

VLC always tries to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

• --intf <module> allows you to select the interface module.
• --extraintf <module> allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special control interfaces, like HTTP, RC (Remote Control), ... (see below)
• --aout <module> allows you to select the audio output module.
• --vout <module> allows you to select the video output module.
• --memcpy <module> allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using vlc -l

Stream Output

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the Streaming HowTo.

Other Options

Audio options

Note that in recent versions (3.x.x branch, possibly earlier):

• --mono no longer exists: use --stereo-mode=0 instead
• --volume no longer exists but --volume-step and --gain may be used
• --aout-rate no longer exists: --audio-resampler might be equivalent?
• --desync no longer exists: use --audio-desync instead

---

• --audio, --no-audio disables audio output. Note that if you are streaming (ex: to a file) this has no effect (streaming copies the audio verbatim). Use --sout-xxx instead (ex: --no-sout-audio)
• --gain <float> audio gain (between 0 and 8)
• --volume-step <float> audio output volume step (between 1 and 256)
• --volume-save, --no-volume-save remember the volume (default enabled)
• --spdif, --no-spdif Force S/PDIF support (default disabled)
• --force-dolby-surround {0 (Auto), 1 (On), 2 (Off)} Force detection of Dolby Surround
• --stereo-mode {0 (Unset), 1 (Stereo), 2 (Reverse stereo), 3 (Left), 4 (Right), 5 (Dolby Surround), 6 (Headphones)} Stereo audio output mode
• --audio-desync <integer> Audio desynchronization compensation
• --audio-replay-gain-mode {none,track,album} Replay gain mode
• --audio-replay-gain-preamp <float> Replay preamp
• --audio-replay-gain-default <float> Default replay gain
• --audio-replay-gain-peak-protection, --no-audio-replay-gain-peak-protection Peak protection (default enabled)
• --audio-time-stretch, --no-audio-time-stretch Enable time stretching audio (default enabled)
• -A, --aout {any,pulse,alsa,sndio,adummy,afile,amem,none} Audio output module
• --role {video,music,communication,game,notification,animation,production,accessibility,test} Media role
• --audio-filter <string> adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone spatialization) and normalizer (volume normalizer)
• --audio-visual {any,visual,glspectrum,none} Audio visualizations
• --audio-resampler {any,samplerate,ugly,soxr,speex_resampler,none} Audio resampler

Video options

• --no-video disables video output.
• --grayscale turns video output into grayscale mode.
• --fullscreen ( or -f) sets fullscreen video.
• --nooverlay disables hardware acceleration for the video output.
• --width, --height <integer> sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
• --start-time <integer> starts the video here; the integer is the number of seconds from the beginning (e.g. 1:30 is written as 90)
• --stop-time <integer> stops the video here; the integer is the number of seconds from the beginning (e.g. 1:30 is written as 90)
• --zoom <float> adds a zoom factor.
• --aspect-ratio <mode> forces source aspect ratio. Modes are 4x3, 16x9, ...
• --spumargin <integer> forces SPU subtitles postion.
• --video-filter <string> adds video filters to the processing chain. You can add several filters, separated by commas
• --video-splitter <string> adds video splitters to the processing chain. (wall, panoramix, clone)
• --sub-filter <string> adds video subpictures filter to the processing chain.

Desktop/Screen grab options

You can see the various options for "grabbing the desktop" (VLC's built-in screen grabber capture device) by using the GUI. See http://forum.videolan.org/viewtopic.php?f=4&t=46971

Playlist options

• --random plays files randomly forever.
• --loop loops playlist on end.
• --repeat repeats current item until another item is forced
• --play-and-stop stops the playlist after each played item.
• --no-repeat --no-loop prevents the video from being executed again. (Useful when want to encode a file)

Network options

• --server-port <integer> sets server port.
• --iface <string> specifies the network interface to use.
• --iface-addr <string> specifies your network interface IP address.
• --mtu <integer> specifies the MTU of the network interface.
• --ipv6 forces IPv6.
• --ipv4 forces IPv4.

CPU options

You should probably not touch these options unless you know what you are doing.

• --nommx disables the use of MMX CPU extensions.
• --no3dn disables the use of 3D Now! CPU extensions.
• --nommxext disables the use of MMX Ext CPU extensions.
• --nosse disables the use of SSE CPU extensions.
• --noaltivec disables the use of Altivec CPU extensions.

Miscellaneous options

• --quiet deactivates all console messages.
• --color displays color messages.
• --search-path <string> specifies interface default search path.
• --plugin-path <string> specifies plugin search path.
• --no-plugins-cache disables the plugin cache (plugins cache speeds up startup)
• --dvd <string> specifies the default DVD device.
• --vcd <string> specifies the default VCD device.
• --program <integer> specifies program (SID) (for streams with several programs, like satellite ones).
• --audio-type <integer> specifies the default audio type to use with dvds.
• --audio-channel <integer> specifies the default audio channel to use with dvds.
• --spu-channel <integer> specifies the default subtitle channel to use with dvds.
• --version gives you information about the current VLC version.
• --module <module> displays help about specified module. (Shortcut: -p)

Item-specific options

There are many options that are related to items (like --novideo, --codec, --fullscreen).

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% vlc file1.mpg :fullscreen file2.mpg

will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas

% vlc --fullscreen file1.mpg file2.mpg

will play both files in fullscreen mode

% vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort

will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options).

Filters

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed. However, on version 1.1.11 you are still able to apply these filters in transcode module using parameter vfilter. More information can be found on Advanced Streaming Using the Command Line.

Deinterlacing video filter

Further information: Documentation:Modules/deinterlace

Module name: deinterlace

• sout-deinterlace-mode <string> {discard,blend,mean,bob,linear,x,yadif,yadif2x,phosphor,ivtc} : Streaming deinterlace mode. Deinterlace method to use for streaming
• sout-deinterlace-phosphor-chroma <integer> {1,2,3,4} : Phosphor chroma mode for 4:2:0 input. Choose handling for colours in those output frames that fall across input frame boundaries.
  • Latest (1): take chroma from new (bright) field. Good for interlaced input, such as videos from a camcorder
  • AltLine (2): take chroma line 1 from top field, line 2 from bottom field, etc. Default, good for NTSC telecined input (anime DVDs, etc.)
  • Blend (3): average input field chromas. May distort the colours of the new (bright) field, too
  • Upconvert (4): output in 4:2:2 format (independent chroma for each field). Best simulation, but requires more CPU and memory bandwidth default value: 2
• sout-deinterlace-phosphor-dimmer <integer> {1,2,3,4} : Phosphor old field dimmer strength: 1 (Off), 2 (Low), 3 (Medium), 4 (High). This controls the strength of the darkening filter that simulates CRT TV phosphor light decay for the old field in the Phosphor framerate default value: 2

Invert video filter

Further information: Documentation:Modules/invert

Module name: invert

Image properties filter

Further information: Documentation:Modules/adjust

Module name: adjust

• contrast <float [0.0 .. 2.0]> : Contrast default value: 1.0
• brightness <float [0.0 .. 2.0]> : Brightness default value: 1.0
• hue <float [-180 .. 180]> : Hue default value: 0
• saturation <float [0.0 .. 3.0]> : Saturation default value: 1.0
• gamma <float [0.01 .. 10.0]> : Gamma default value: 1.0
• brightness-threshold <boolean> : When this mode is enabled, pixels will be shown as black or white. Also may invert the brightness value. The threshold value will be the brightness defined below default value: disabled

Wall video filter

Further information: Documentation:Modules/wall

Module name: wall

This filter splits the output in several windows.

• wall-cols <integer [1 .. 15]> : Number of horizontal windows in which to split the video default value: 3
• wall-rows <integer [1 .. 15]> : Number of vertical windows in which to split the video default value: 3
• wall-active <string> : Comma-separated list of active windows, defaults to all default value: NULL
• wall-element-aspect <string> : Aspect ratio of the individual displays building the wall default value: 4:3

Note: for --wall-active, to select windows 2 and 4 you would write --wall-active 2,4. When this option isn't specified, all windows are displayed.

Video transformation filter

Further information: Documentation:Modules/transform

Module name: transform

• --transform-type {90,180,270,hflip,vflip} Select rotation angle or symmetry.

Distort video filter

Further information: Documentation:Modules/distort

Module name: distort

Clone video filter

Further information: Documentation:Modules/clone

This filter clones the output window.

Module name: clone

• clone-count <integer> : Number of video windows in which to clone the video. default value: 2
• clone-vout-list <string> : You can use specific video output modules for the clones. Use a comma-separated list of modules. default value: ""

Crop video filter

Further information: Documentation:Modules/crop

Module name: crop

• crop-geometry <string> : Set the geometry of the zone to crop. This is set as <width> × <height> + <left offset> + <top offset>
• autocrop <boolean> : Automatically detect black borders and crop them default value: disabled
• autocrop-ratio-max <integer [0 .. 15000]> : Maximum image ratio. The crop plugin will never automatically crop to a higher ratio (ie, to a more "flat" image). The value is ×1000: 1333 means 4⁄3 default value: 2405
• crop-ratio <integer [0 .. 15000]> : Force a ratio (0 for automatic). Value is ×1000: 1333 means 4⁄3 default value: 0
• autocrop-time <integer> : The number of consecutive images with the same detected ratio (different from the previously detected ratio) to consider that ratio changed and trigger recrop default value: 25
• autocrop-diff <integer> : The minimum difference in the number of detected black lines to consider that ratio changed and trigger recrop default value: 16
• autocrop-non-black-pixels <integer> : The maximum of non-black pixels in a line to consider that the line is black default value: 3
• autocrop-skip-percent <integer [0 .. 100]> : Percentage of the line to consider while checking for black lines. This allows skipping logos in black borders and crop them anyway default value: 17
• autocrop-luminance-threshold <integer [0 .. 128]> : Maximum luminance to consider a pixel as black (0-128) default value: 40

Motion blur filter

Further information: Documentation:Modules/motionblur

Module name: motionblur

• blur-factor <integer> Blur factor in the 1-127 range.

Video pictures blending

Further information: Documentation:Modules/blend

Module name: blend

Video scaling filter

Further information: Documentation:Modules/scale

Module name: scale

Subpictures Filters

These are the new VLC filters. They can be streamed.

Marquee display sub filter

Further information: Documentation:Modules/marq

Module name: marq

• marq-marquee <string> : Marquee text to display. default value: VLC
• marq-file <string> : File to read the marquee text from. default value: NULL
• marq-x <integer> : X offset, from the left screen edge. default value: 0
• marq-y <integer> : Y offset, down from the top. default value: 0
• marq-position <integer> : Marquee position: 0=center, 1=left, 2=right, 4=top, 8=bottom, you can also use combinations of these values, eg 6 = top-right. default value: -1
• marq-opacity <integer [0 .. 255]> : Opacity (inverse of transparency) of overlaid text. 0 = transparent, 255 = totally opaque. default value: 255
• marq-color <integer> { 0x000000, 0x808080, 0xC0C0C0, 0xFFFFFF, 0x800000, 0xFF0000, 0xFF00FF, 0xFFFF00, 0x808000, 0x008000, 0x008080, 0x00FF00, 0x800080, 0x000080, 0x0000FF, 0x00FFFF } : Color of the text that will be rendered on the video. This must be an hexadecimal (like HTML colors). The first two chars are for red, then green, then blue. default value: 0xFFFFFF
• marq-size <integer [0 .. 4096]> : Font size, in pixels. 0 uses the default font size. default value: 0
• marq-timeout <integer> : Number of milliseconds the marquee must remain displayed. 0 means forever. default value: 0
• marq-refresh <integer> : Number of milliseconds between string updates. This is mainly useful when using meta data or time format string sequences. default value: 1000

The time sub filter was merged into this module.

Logo video filter

Further information: Documentation:Modules/logo

Module name: logo

This filter can be used both as an old style filter or a subpictures filter.

• logo-file <string> : Image to display. The full format is <image>[,<delay in ms>[,<alpha>]][;<image>[,<delay>[,<alpha>]]][;...].
• logo-x <integer> : X offset from upper left corner. default value: 0
• logo-y <integer> : Y offset from upper left corner. default value: 0
• logo-position <integer> { 0, 1, 2, 4, 8, 5, 6, 9, 10 } : Logo position. default value: 5
• logo-opacity <integer [0 .. 255]> : Logo opacity. 0 is transparent, 255 is fully opaque. default value: 255
• logo-delay <integer> : Global delay in ms. Sets the duration each image will be displayed for in a loop iteration unless specified otherwise in the --logo-file option. default value: 1000
• logo-repeat <integer> : Number of loops for the logo animation. -1 for continuous, 0 to disable. default value: -1

Note: You can move the logo by left-clicking on it.

This page is part of official VLC media player Documentation (User Guide • Streaming HowTo • Hacker Guide • Modules)
Please read the Documentation Editing Guidelines before you edit the documentation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.