The CLI can be used to either pipe streams to a video player for playback or download them to a file.
The CLI is designed to be as simple as possible to use, in two or less steps you can start playback of your favorite stream in a desktop video player such as VLC or MPlayer.
Let’s say you want to watch the stream located on http://twitch.tv/day9tv, you start off by telling Livestreamer where to to find information about your stream by giving the URL to livestreamer as the first argument. You do not need to specify the whole URL including http://, just twitch.tv/day9tv will do just fine.
$ livestreamer twitch.tv/day9tv
[cli][info] Found matching plugin justintv for URL twitch.tv/day9tv
Found streams: 240p, 360p, 480p, 720p (best), mobile_high, mobile_low (worst)
Livestreamer will find out what streams are available and print them out for you to choose from. Simply give livestreamer the stream as the second argument and playback will start in your video player of choice.
The words printed next to stream names within a parantheses are synonyms and can be used when selecting stream to play. In this case the best stream is a reference to the stream that is considered to be of highest quality, e.g 720p.
$ livestreamer twitch.tv/day9tv best
[cli][info] Found matching plugin justintv for URL twitch.tv/day9tv
[cli][info] Opening stream: 720p
[cli][info] Starting player: vlc
The default player is VLC, but it can be easily changed using the --player option.
Now that you have a basic grasp of how Livestreamer works, you may want to look into customizing it to your own needs, such as:
Writing the command line options every time is painful, that’s why Livestreamer is capable of reading options from a file instead, a sort of configuration file. Livestreamer will look for this file in different locations depending on your platform:
The file should contain one option per line in the format option[=value], like this:
player=mplayer -cache 2048
player-no-close
twitch-cookie=_twitch_session_id=xxxxxx; persistent=xxxxx;
For a list of all the supported options see Command line options.
It’s possible to access subscription content on Twitch by giving Livestreamer access to your account. There are two methods to authenticate Livestreamer to Twitch: Application authorization via OAuth or re-using your web browsers cookies.
Using the OAuth method is recommended since it is easier and will never expire (unless access is revoked in your Twitch settings or a new access token is created), unlike cookies which may stop working if you log out in your browser.
Application authorization via OAuth
To authenticate Livestreamer with your Twitch account, simply run this command:
$ livestreamer --twitch-oauth-authenticate
This will open a web browser where Twitch will ask you if you want to give Livestreamer permission to access your account, then forward you to a page with further instructions.
Cookies
Cookies should be specified in a key value list separated by a semicolon. In this case only the _twitch_session_id and persistent keys are required by Twitch. For example:
$ livestreamer --twitch-cookie "_twitch_session_id=xxxxxx; persistent=xxxxx" twitch.tv/ignproleague
[plugin.justintv][info] Attempting to authenticate using cookies
[plugin.justintv][info] Successfully logged in as <username>
Extracting cookies from your web browser varies from browser to browser, try googling “<browser name> view cookies”.
It’s recommended to save these cookies in your configuration file rather than specifying them manually every time.
Note
Authenticating with Justin.tv is not possible since their video system overhaul, but may be a unintended bug and could be fixed in the future.
Crunchyroll requires authenticating with a premiun account to access some of their content. To do so, the plugins provides a couple of options to input your information: crunchyroll-username and crunchyroll-password.
You can login doing the following
$ livestreamer --crunchyroll-username=xxxx --crunchyroll-password=xxx http://crunchyroll.com/a-crunchyroll-episode-link...
Note
If you omit the password, livestreamer gonna ask for it later
Once logged, the plugin makes sure to save the session credentials to avoid asking your username and password again.
Neverthless, this credentials are valid for a limited amount of time, so it’s recomended to persist your username and password in your configuration file to avoid having to type them again each time the credentials expires.
Warning
The API this plugin uses isn’t supposed to be available to use it on computers. The plugin tries to blend in as a valid device using custom headers and following the API usual flow (e.g. reusing credentials), but this does not assure that your account will be safe from being spotted for unusual behavior.
You can use livestreamer’s http-proxy and https-proxy options (you need both since the plugin uses both protocols) to access the Crunchyroll servers through a proxy and be able to stream region locked content. When doing this, is very probable that you will get denied to access the stream; this occurs because the session and credentials used by the plugin where obtained when logged from your own region, and the server still assumes you’re in that region. For this, the plugin provides the crunchyroll-purge-credentials option, which removes your saved session and credentials and tries to log in again using your username and password.
Livestreamer will attempt to load plugins from these directories:
Note
If a plugin is added with the same name as a built-in plugin then the added plugin will take precedence. This is useful if you want to upgrade plugins independently of the Livestreamer version.
There are many types of streaming protocols used by services today and Livestreamer implements most of them. It is possible to tell Livestreamer to access a streaming protocol directly instead of relying on a plugin to find the information for you.
A protocol can be accessed directly by specifying it in the URL format: protocol://path key=value.
For example, to access a RTMP stream which requires parameters to be passed along to the stream:
$ livestreamer "rtmp://streaming.server.net/playpath live=1 swfVfy=http://server.net/flashplayer.swf"
Most streaming technologies simply requires you to pass a HTTP URL, this is an Adobe HDS stream:
$ livestreamer hds://http://streaming.server.net/playpath/manifest.f4m
Livestreamer currently supports these protocols:
Name | Prefix |
---|---|
Adobe HTTP Dynamic Streaming | hds:// |
Akamai HD Adaptive Streaming | akamaihd:// |
Apple HTTP Live Streaming | hls:// hlvsvariant:// |
Real Time Messaging Protocol | rtmp:// rtmpe:// rtmps:// rtmpt:// rtmpte:// |
Progressive HTTP, HTTPS, etc | httpstream:// |
Show help message and exit
Show program’s version number and exit
Print all currently installed plugins
Set log level, valid levels: none, error, warning, info, debug
Alias for --loglevel none
Output JSON instead of the normal text output and disable log output, useful for external scripting
Do not check for new Livestreamer releases
New in version 1.8.0.
Will retry fetching streams until streams are found while waiting <delay> (seconds) between each attempt
New in version 1.8.0.
Will try <attempts> to open the stream until giving up
New in version 1.8.0.
A comma-delimited list of stream types to allow. The order will be used to separate streams when there are multiple streams with the same name and different stream types. Default is rtmp,hls,hds,http,akamaihd
Fine tune best/worst synonyms by excluding unwanted streams. Uses a filter expression in the format [operator]<value>. For example the filter >480p will exclude streams ranked higher than ‘480p’. Valid operators are >, >=, < and <=. If no operator is specified then equality is tested.
Multiple filters can be used by separating each expression with a comma. For example >480p,>mobile_medium will exclude streams from two quality types.
Use the ‘best’ stream if no stream is specified.
New in version 1.8.0.
Specify a HTTP proxy to use for all HTTP requests
New in version 1.7.0.
Specify a HTTPS proxy to use for all HTTPS requests
New in version 1.7.0.
A semi-colon (;) delimited list of cookies to add to each HTTP request, e.g. foo=bar;baz=qux
New in version 1.8.0.
A semi-colon (;) delimited list of headers to add to each HTTP request, e.g. foo=bar;baz=qux
New in version 1.8.0.
A semi-colon (;) delimited list of query parameters to add to each HTTP request, e.g. foo=bar;baz=qux
New in version 1.8.0.
Ignore HTTP settings set in the environment, such as environment variables (HTTP_PROXY, etc) and ~/.netrc authentication
New in version 1.8.0.
Don’t verify SSL certificates. Usually a bad idea!
New in version 1.8.0.
SSL certificate to use (pem)
New in version 1.8.0.
SSL certificate to use (crt and key)
New in version 1.8.0.
General timeout used by all HTTP requests except the ones covered by other options, default is 20.0
New in version 1.8.0.
Player command-line to start, by default VLC will be used if it is installed
The arguments passed to the player. These formatting variables are available: filename. Default is '{filename}'
New in version 1.6.0.
Show all player console output
Make the player read the stream through a named pipe (useful if your player can’t read from stdin)
Make the player read the stream using HTTP (useful if your player can’t read from stdin)
New in version 1.6.0.
Make the player read the stream using HTTP, but unlike --player-http will continuously try to open the stream if the player requests it. This makes it possible to handle stream disconnects if your player is capable of reconnecting to a HTTP stream, e.g 'vlc --repeat'
New in version 1.6.0.
A comma-delimited list of stream types to pass to the player as a filename rather than piping the data. Make sure your player can handle the stream type when using this. Supported stream types are: hls, http, rtmp
New in version 1.6.0.
By default Livestreamer will close the player when the stream ends. This option will let the player decide when to exit.
New in version 1.7.0.
Write stream to file instead of playing it
Always write to file even if it already exists
Write stream to stdout instead of playing it
How many segments from the end to start live HLS streams on, default is 3
New in version 1.8.0.
How many attempts should be done to download each HLS segment, default is 3
New in version 1.8.0.
HLS segment connect and read timeout, default is 10.0
New in version 1.8.0.
Timeout for reading data from HLS streams, default is 60.0
New in version 1.8.0.
Specify the time live HDS streams will start from the edge of stream, default is 10.0
How many attempts should be done to download each HDS segment, default is 3
New in version 1.8.0.
HDS segment connect and read timeout, default is 10.0
New in version 1.8.0.
Timeout for reading data from HDS streams, default is 60.0
New in version 1.8.0.
Timeout for reading data from HTTP streams, default is 60.0
New in version 1.8.0.
Specify a maximum size (bytes) for the ringbuffer used by some stream types, default is 16777216 (16MB).
Specify a proxy (SOCKS) that RTMP streams will use
Specify location of the rtmpdump executable used by RTMP streams, e.g. /usr/local/bin/rtmpdump
Timeout for reading data from RTMP streams, default is 60.0
New in version 1.8.0.
Print command-line used internally to play stream, this is only available for RTMP streams
Log possible errors from internal subprocesses to a temporary file, use when debugging rtmpdump related issues
Attempts to load plugins from these directories. Multiple directories can be used by separating them with a semicolon (;)
Specify Twitch/Justin.tv cookies to allow access to subscription channels, e.g '_twitch_session_id=xxxxxx; persistent=xxxxx;'
Use this to access password protected streams.
New in version 1.6.0.
Specify a OAuth token to allow Livestreamer to access Twitch using your account.
New in version 1.7.2.
Opens a web browser where you can grant Livestreamer access to your Twitch account.
New in version 1.7.2.
Specify Crunchyroll username to allow access to streams
New in version 1.7.3.
Specify Crunchyroll password to allow access to restricted streams (if left blank you will be prompted)
New in version 1.7.3.
Purge Crunchyroll credentials to initiate a new session and reauthenticate.
New in version 1.7.3.
Specify Livestation account email to access restricted streams or Premium Quality streams.
New in version 1.8.0.
Specify Livestation password for account specified.
New in version 1.8.0.