Chapter 4.  The command line interface

Table of Contents

Introduction
Opening streams
Modules selection
Stream Output
Other Options

Introduction

Many options are only available through command line. They are detailed here.

Opening streams

The following commands start VLC and add the first element to the playlist.

Opening a file

Start VLC with:

% vlc -vvv my_file.mpg

Although VLC should be able to recognize the file type, you may tell VLC what codec to use with the --codec option. For example to play my_file.mpg using ffmpeg auido/video decoder do:

% vlc -vvv --codec ffmpeg my_file.mpg 

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:

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

or (VCD):

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

or (Audio CD):

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

where device is the complete path to your DVD or CD-ROM drive.

Receiving a network stream

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

% vlc -vvv udp:[@:server_port]

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

% vlc -vvv udp:@multicast_address[:server_port]

To receive a HTTP stream, start VLC with :

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

To receive a RTSP stream, start VLC with:

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

Modules selection

VLC 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 (for the complete list of modules, see the Modules and options for VLCmodules section) :

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

  • --aout <module> allows you to select the audio output module.

  • --vout <module> allows you to select the video output module.

  • --filter <module> allows you to add a video filter module.

  • --memcpy <module> allows you to choose a memory copy module.

Stream Output

Description of the stream output

VLC's stream output allows VLC to be used as a streaming server instead of a client ! It has very extended capabilities:

  • stream in unicast and multicast on an IPv4 or IPv6 network everything that VLC is able to read, via UDP, RTP or HTTP;

  • save the input stream to a file in AVI, PS, TS or OGG format;

  • transcode an input stream, and then, send it, to the network or to a file.

To know about the full possibilities of VLC's stream output, see the streaming features page.

Architecture and syntax

the stream output has a powerful architecture that uses modules. Each module has capabilities, and you can chain the modules to enhance the possibilities.

Here is the list of the modules currently available:

  • standard "sends" the stream via an access output module: for example, UDP, file, HTTP, ... You will probably want to use this module at the end of your chains.

  • transcode allows you to transcode the audio and the video of the input stream "on the fly" (if your computer is powerful enough).

  • duplicate allows you to create a second chain, where the stream will be handled in an independant way.

  • display allows you to display the input stream, as VLC would normally do. Used with the duplicate module, this allows you to view the stream as you send it.

  • rtp streams over RTP (one UDP port for each elementary stream).

  • es allows you to make separate Elementary Streams (ES) out of an input stream.

Each of these modules may take options. Here is the syntax that you must use:

% vlc input_stream --sout '#module1{option1=...,option2=...}:module2{option1=...,option2=...}:...'

You may also use the following syntax :

% vlc input_stream --sout-module1-option1=... --sout-module1-option2=... --sout-module2-option1=... --sout-module2-option2=... ...

For example, to transcode a stream and send it, use:

% vlc input_stream --sout '#transcode{options}:standard{options}'

Description of the modules

standard (alias std)

Sends a stream.

Options:

  • access: how to send: file, udp, rtp, http.

  • mux: which muxer (ie, which format) will be used. It can be one of avi (for AVI format) ogg (for OGG format) ps (for MPEG2-PS format) ts (for MPEG2-TS format).

  • url: if you use the file access, it will be the location where to store the stream; if you use another access, it will be the unicast or multicast IP address where you want to stream.

  • sap: if you use the udp or rtp accesses, use this option to announce your stream, using SAP/SDP.

  • name! This option contains the name under which you want to announce the program.

  • slp: like sap, but use the SLP protocol. You need to have libslp on your system.

  • sap_ipv: if you use the sap option, use this option to specify if you want to send the SAP announces in IPv4 or IPv6. The value of this option is 4 or 6.

Note

If you are streaming in multicast, you may want to use the global option --ttl 12 to set the TTL to a value superior to 1.

display

Displays the stream.

Options:

  • noaudio: Ignore audio.

  • novideo: Ignore video.

duplicate

Duplicates the stream to a new stream output chain.

Options:

  • dst: A new stream output chain of modules, as described earlier.

  • select: This option allows you to specify which programs or es you wish to stream for the previous dst, if the input stream has several ones.

    Format is "program=program_id" or es="es_id". You can also use ranges, like "program=start_program-end_program". You can select only es of a given type, with :

    • no-audio, noaudio, audio

    • no-video, novideo, video

    • no-spu, nospu, spu

    You may use several selectors, comma-separated

transcode

Changes the codec and/or bitrates for a stream.

Options:

  • acodec: the new audio codec. It can be one of mpga (MPEG audio layer 2), a52 or ac3 (AC3 sound) or vorb (Vorbis).

  • ab: audio bitrate in Kbps.

  • vcodec: the new video codec. It can be one of mp4v (MPEG4), mpgv (MPEG1), DIV1, DIV2, DIV3 (DivX 1,2,3), H263 (H263), I263 (H263I), WMV1 or WMV2 (Windows Media Video 1 or 2), MJPG (MJPEG), MJPB (MJPEGB).

  • width: video width.

  • height: video height.

  • vb: video bitrate in kbps.

  • vt: video bitrate tolerance in bps.

  • deinterlace: deinterlace the stream.

  • croptop: number of pixels removed from the top of the video.

  • cropbottom: number of pixel removed from the bottom of the video.

  • cropleft: number of pixels removed from the left of the video.

  • cropright: number of pixels removed from the right of the video.

  • hq: high quality transcoding (uses more CPU).

  • qmin: minimum video quantiser scale (VBR)

  • qmax: maximum video quantiser scale (VBR).

rtp

Sends a stream over RTP

Options:

  • dst: destination IP address (unicast or multicast).

  • port: destination UDP port.

  • sdp: how to send the sdp file: http://server_ip:server_port/path for http, or rtsp://server_ip:server_port/path for rtsp, where server_ip is the address of one of the server's interface, and path where the sdp file will be accessible on the server. You can also use sap:// to announce your stream by SAP.

Note

When using sdp=rtsp, it is possible not to give any destination address. VLC will then send the stream to any client that connects to it.

es

Make separate Elementary Streams.

Options:

  • access_audio: how to send the audio track: file, udp, rtp or http.

  • access_video: how to send the vidéo track: file, udp, rtp or http.

  • access: if you want the audio and the video tracks to use the same access, use this option instead of the two above.

  • mux_audio: which muxer (ie, which format) will be used for the audio track. It can be one of avi (for AVI format), ogg (for OGG format), ps (for MPEG2-PS format), ts (for MPEG2-TS format).

  • mux_video: which muxer (ie, which format) will be used for the video track. It can be one of avi (for AVI format), ogg (for OGG format), ps (for MPEG2-PS format), ts (for MPEG2-TS format).

  • mux: if you want the audio and the video tracks to use the same muxer, use this option instead of the two above.

  • url_audio: if you use the file access, it will be the location where to store the audio track; if you use another access, it will be the unicast or multicast IP address where you want to stream.

  • url_video: if you use the file access, it will be the location where to store the vidéo track; if you use another access, it will be the unicast or multicast IP address where you want to stream.

  • url: if you want the audio and the video tracks to use the same url, use this option instead of the two above.

Note

In the url options, if you use the file access, you can use the following macros in the filename:

  • %n = stream number

  • %c = FOURCC ;

  • %m = muxer ;

  • %a = access.

Miscellaneous

Here are a few additional global options

  • --sout-all, --no-sout-all Enable streaming of all ES (default disabled). By defaut VLC will only stream one audio ES and one video ES (the first ones). If you enable sout-all, all ES (audio, video and SPU) will be streamed.

  • --sout-keep, --no-sout-keep Keep sout open (default disabled) : use the same sout instance accross the various playlist items, if possible.

  • --no-sout-audio disables audio stream output.

  • --no-sout-video disables video stream output.

The stream output also offers a simplified syntax, with which you can only you use the standard module main options:

% vlc input_stream --sout access/mux:url

where access, mux and url are as defined in the options of the standard module.

Examples

To understand fully the complex syntax of VLC's stream output, please look at the use cases of the VideoLAN HOWTO.

Other Options

Audio options

  • --noaudio disables audio output.

  • --mono forces VLC to treat the stream in mono audio.

  • --volume <integer> sets the level of audio output.

  • --aout-rate <integer> sets the audio output frequency (Hz).

  • --desync <integer> compensates desynchronization of audio (ms).

  • --headphone activates headphone virtual spatialization effect.

  • --headphone-dim sets headphone characteristic dimension.

Video options

  • --novideo disables video output.

  • --greyscale turns video output into greyscale mode.

  • --fullscreen sets fullscreen video.

  • --nooverlay disables hardware acceleration for the video output.

  • --width, --height <integer> sets the video window dimensions.

  • --zoom <float> adds a zoom factor.

  • --aspect-ratio <mode> forces source aspect ratio.

  • --spumargin <integer> forces SPU subtitles postion.

Playlist options

  • --playlist launches playlist on startup.

  • --random plays files randomly forever.

  • --enqueue enqueues items in playlist.

  • --loop loops playlist on end.

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

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

Miscellaneous options

  • --quiet deactivates the console messages.

  • --color displays color messages.

  • --search-path <string> specifies interface default search path.

  • --plugin-path <string> specifies plugin search path.

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

Help options

  • --verbose <verbosity> specifies verbosity level.

  • --help gives you all available options.

  • --longhelp gives you a detailled version of the available options.

  • --version gives you information about the current VLC version.

  • --list displays a list of available plugins.

  • --module <module> displays help about specified module.