Eric Ransom Writing Projects Other Stuff Contact

Short Intro to the VLC Media Player Command Line

VLC remains the best open source, cross-platform media player available, but wading through all the available options and features can be daunting. One of the more under-utilized features is being able to invoke VLC from the command line with various options.

Being able to invoke VLC from the terminal allows for batch operations that would be difficult with the GUI and also provides the opportunity to invoke VLC in shell scripts. Some tasks are just easier with the terminal as well (see #3 below, for instance).

These have all been tested with Powershell (Windows 10), and some have been tested with bash in Ubuntu Linux as well.

For Windows, you will need to ensure that your VLC executable's directory is listed in your environmental Path variable. To do so, go to Control Panel > Search for “Edit System Environmental Variables” > click “Environment Variables” > Select the Path variable in the top menu > click “Edit” > click “Browse” > navigate to the directory where the VLC folder is located (likely C:\Program Files\VideoLAN\VLC) > hit “OK” on all the open menus, and you should be good.

Getting started

Initial setup options

Before getting started with using the command line, there is one useful option we should check using the GUI. Go to Tools > Preferences and look in the category called “Playlist and Instances” on the Interface tab. Ensure that the options “Allow only one instance”, “Use only one instance when started from file manager” and “Enqueue items into playlist in one instance mode” are checked.

This will ensure that all of our commands behave as expected. We generally will not want multiple VLC windows to open if we are just trying to enqueue additional media into an existing open playlist, for instance.

You can also use the –one-instance and –one-instance-when-started-from-file options in the command line to toggle these settings for your individual commands if you really want to.

Setting up logging

By default, logging is disabled in VLC. You will probably want to set up a log file, especially if you will be running vlc from scripts/batch and want to be able to troubleshoot more easily.

This can either be done in the GUI Preferences menu (Show Settings: All > Advanced Menu > Logger) or by using the command line:
```
> vlc --file-logging --logfile=<filename> 
--logmode=<text/html> --log-verbose=<0-2>
```
where logfile is the output file for the log, logmode is the format for the file, and log-verbose specifies how detailed the log will be. The options are 0, 1, and 2, where higher numbers indicate increasing detail.

Back up VLC config/preferences file

After tweaking all the VLC options to your liking, I recommend saving the configuration file so it can be restored on reinstall/used on other machines/etc. All preferences/config options in VLC are stored in a single file located in Linux at:
```
> ~/.config/vlc/vlcrc
```
and in Windows at:
```
> C:\Users\<username>\AppData\Roaming\vlc\vlcrc
```

Get a full list of VLC command line options and dump them into a text file in the current directory:
```
> vlc -H
```
This is a useful way to get a searchable text file of all command-line options when you're looking for something specific. The file is 5000+ lines long, though, so browsing through it randomly might not get you too far.

Creating a complete playlist of your music library with a single command

Starting in the current directory, open VLC and add all files from all subdirectories recursively to the playlist. Begin playing this playlist immediately with the “Random” and “Loop Forever” options enabled:
```
> vlc ./ -ZL --no-repeat --recursive=expand
```
This is probably the terminal command I use the most. I have a large collection of music stored locally, and I have had trouble doing this from the GUI interface efficiently. Sometimes when using the GUI, folders don't get extracted properly, and entire folders appear intact in the playlist instead of their contents. This command line option avoids that and other issues I have encountered and properly extracts all subfolders (and nested subfolders) to the playlist.

Wait until the playlist fully populates before you start moving things around, or you might get some unexpected behavior. You can then save the playlist to a file so that you do not have to run the command again until the contents of your music folder change.

If you do add to or edit your music collection with any frequency, however, this command line tool makes it easy to generate a new playlist based on the new contents.

Stream (and save) a video via HTTP

VLC has the ability to stream videos from Youtube or other sources online via HTTP. This can be done using the command:
```
> vlc -vvv http://www.youtube.com/fullURLtovideohere
```
You can also do this through the GUI, but as mentioned earlier, the command line allows for use in scripts.

You can also theoretically save the stream to a file by using the –sout option in the format:
```
> vlc -vvv http://www.youtube.com/fullURLtovideohere --sout 
file/<muxer>:filename.mp4
```
where muxer can be one of the supported VLC container formats: ogg , ps , or ts.

While I have never had issues with video playback, I have run into problems when trying to output the stream to a file. This occasionally causes VLC to hang for me or get in a strange loop for some reason, so it may take some a little experimenting to get this working properly.

It should also be noted that some of this streaming capability is made possible by a set of Lua scripts located in the install directory/lua/playlist folder. If your streams are not working for some reason, these may need to be updated to the latest versions. For instance, to get Youtube streams working properly, I had to go to the VLC Github page to grab the latest version of the youtube.lua file before youtube streaming would work properly.

VLC is quite powerful, but as mentioned above, it may take some tinkering to get this stuff working.

I should mention that if you have python installed on your machine and want a more full-featured and dedicated utility for saving online video content, you should definitely check out youtube-dl.

Convert audio or video files to a different format

VLC can convert audio and video files into most formats, and you can use command line tools to create scripts and complete batch conversions of whole directories. There are quite a few optional parameters here, so you will need to check the documentation to be sure you get the desired output.

The basic format for these conversions is:
```
> vlc -I dummy ".\mediafile.mp3" 
--sout=#transcode{configurable options for audio and video}
```
The details of setting up all the options to get the exact output you want are beyond the scope of this article, but the specifics and examples can be found on the VLC Wiki Page. Also see this helpful Stack Overflow answer on the topic.

The -I dummy parameter

Since most of the utility of using the command line comes from invoking batch operations through scripts, we will generally not want the GUI to pop up every time VLC is executed. This option will prevent that from happening.

Summary

This is just a short intro to using the VLC command line. It will take a little time and practice to learn about the various options and to create scripts using your own OS's shell or in another scripting language, but it's definitely worth the time to learn when you'll be doing file conversions and other tasks frequently.

There are certainly other tools that do some of the individual jobs better (see the note about youtube-dl above for saving http-streamed content), but VLC is a powerful, all-purpose tool that can provide a lot of value beyond simply being a media player.

Published: October 13, 2020.

Last updated: October 14, 2020

Correction and Edit History:

October 14, 2020: Fixed formatting problem and a couple minor typos.