1.. _cli: 2 3Command-Line Interface 4====================== 5 6Tutorial 7-------- 8 9Livestreamer is command-line application, this means the commands described 10here should be typed into a terminal. On Windows this means you should open 11the `command prompt`_ or `PowerShell`_, on Mac OS X open the `Terminal`_ app 12and if you're on Linux or BSD you probably already know the drill. 13 14The way Livestreamer works is that it's only a means to extract and transport 15the streams, and the playback is done by an external video player. Livestreamer 16works best with `VLC`_ or `mpv`_, which are also cross-platform, but other players 17may be compatible too, see the :ref:`Players` page for a complete overview. 18 19Now to get into actually using Livestreamer, let's say you want to watch the 20stream located on http://twitch.tv/day9tv, you start off by telling Livestreamer 21where to attempt to extract streams from. This is done by giving the URL to the 22command :command:`livestreamer` as the first argument: 23 24.. code-block:: console 25 26 $ livestreamer twitch.tv/day9tv 27 [cli][info] Found matching plugin twitch for URL twitch.tv/day9tv 28 Available streams: audio, high, low, medium, mobile (worst), source (best) 29 30 31.. note:: 32 You don't need to include the protocol when dealing with HTTP URLs, 33 e.g. just ``twitch.tv/day9tv`` is enough and quicker to type. 34 35 36This command will tell Livestreamer to attempt to extract streams from the URL 37specified, and if it's successful, print out a list of available streams to choose 38from. 39 40To select a stream and start playback, we simply add the stream name as a second 41argument to the :command:`livestreamer` command: 42 43.. sourcecode:: console 44 45 $ livestreamer twitch.tv/day9tv source 46 [cli][info] Found matching plugin twitch for URL twitch.tv/day9tv 47 [cli][info] Opening stream: source (hls) 48 [cli][info] Starting player: vlc 49 50 51The stream you chose should now be playing in the player. It's a common use case 52to just want start the highest quality stream and not be bothered with what it's 53named. To do this just specify ``best`` as the stream name and Livestreamer will 54attempt to rank the streams and open the one of highest quality. You can also 55specify ``worst`` to get the lowest quality. 56 57Now that you have a basic grasp of how Livestreamer works, you may want to look 58into customizing it to your own needs, such as: 59 60- Creating a :ref:`configuration file <cli-livestreamerrc>` of options you 61 want to use 62- Setting up your player to :ref:`cache some data <issues-player_caching>` 63 before playing the stream to help avoiding buffering issues 64 65 66.. _command prompt: http://windows.microsoft.com/en-us/windows/command-prompt-faq#1TC=windows-8 67.. _PowerShell: http://www.microsoft.com/powershell 68.. _Terminal: http://en.wikipedia.org/wiki/Terminal_(OS_X) 69.. _VLC: http://videolan.org/ 70.. _mpv: http://mpv.io/ 71 72 73.. _cli-livestreamerrc: 74 75Configuration file 76------------------ 77 78Writing the command-line options every time is inconvenient, that's why Livestreamer 79is capable of reading options from a configuration file instead. 80 81Livestreamer will look for config files in different locations depending on 82your platform: 83 84================= ==================================================== 85Platform Location 86================= ==================================================== 87Unix-like (POSIX) - $XDG_CONFIG_HOME/livestreamer/config 88 - ~/.livestreamerrc 89Windows %APPDATA%\\livestreamer\\livestreamerrc 90================= ==================================================== 91 92You can also specify the location yourself using the :option:`--config` option. 93 94.. note:: 95 96 - `$XDG_CONFIG_HOME` is ``~/.config`` if it has not been overridden 97 - `%APPDATA%` is usually ``<your user directory>\Application Data`` 98 99.. note:: 100 101 On Windows there is a default config created by the installer but on any 102 other platform you must create the file yourself. 103 104 105Syntax 106^^^^^^ 107 108The config file is a simple text file and should contain one 109:ref:`command-line option <cli-options>` (omitting the dashes) per 110line in the format:: 111 112 option=value 113 114or for a option without value:: 115 116 option 117 118.. note:: 119 Any quotes used will be part of the value, so only use when the value needs them, 120 e.g. specifiying a player with a path containing spaces. 121 122Example 123^^^^^^^ 124 125.. code-block:: bash 126 127 # Player options 128 player=mpv --cache 2048 129 player-no-close 130 131 # Authenticate with Twitch 132 twitch-oauth-token=mytoken 133 134 135Plugin specific configuration file 136---------------------------------- 137 138You may want to use specific options for some plugins only. This 139can be accomplished by placing those settings inside a plugin specific 140config file. Options inside these config files will override the main 141config file when a URL matching the plugin is used. 142 143Livestreamer expects this config to be named like the main config but 144with ``.<plugin name>`` attached to the end. 145 146Examples 147^^^^^^^^ 148 149================= ==================================================== 150Platform Location 151================= ==================================================== 152Unix-like (POSIX) - $XDG_CONFIG_HOME/livestreamer/config\ **.twitch** 153 - ~/.livestreamerrc\ **.ustreamtv** 154Windows %APPDATA%\\livestreamer\\livestreamerrc\ **.youtube** 155================= ==================================================== 156 157Have a look at the :ref:`list of plugins <plugin_matrix>` to see 158the name of each built-in plugin. 159 160 161Plugin specific usage 162--------------------- 163 164Authenticating with Twitch 165^^^^^^^^^^^^^^^^^^^^^^^^^^ 166 167It's possible to access subscription content on Twitch by giving Livestreamer 168access to your account. 169 170Authentication is done by creating an OAuth token that Livestreamer will 171use to access your account. It's done like this: 172 173.. sourcecode:: console 174 175 $ livestreamer --twitch-oauth-authenticate 176 177 178This will open a web browser where Twitch will ask you if you want to give 179Livestreamer permission to access your account, then forwards you to a page 180with further instructions on how to use it. 181 182 183Authenticating with Crunchyroll 184^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 185 186Crunchyroll requires authenticating with a premium account to access some of 187their content. To do so, the plugin provides a couple of options to input your 188information, :option:`--crunchyroll-username` and :option:`--crunchyroll-password`. 189 190You can login like this: 191 192.. sourcecode:: console 193 194 $ livestreamer --crunchyroll-username=xxxx --crunchyroll-password=xxx http://crunchyroll.com/a-crunchyroll-episode-link 195 196.. note:: 197 198 If you omit the password, livestreamer will ask for it. 199 200Once logged in, the plugin makes sure to save the session credentials to avoid 201asking your username and password again. 202 203Neverthless, these credentials are valid for a limited amount of time, so it 204might be a good idea to save your username and password in your 205:ref:`configuration file <cli-livestreamerrc>` anyway. 206 207.. warning:: 208 209 The API this plugin uses isn't supposed to be available to use it on 210 computers. The plugin tries to blend in as a valid device using custom 211 headers and following the API usual flow (e.g. reusing credentials), but 212 this does not assure that your account will be safe from being spotted for 213 unusual behavior. 214 215HTTP proxy with Crunchyroll 216^^^^^^^^^^^^^^^^^^^^^^^^^^^ 217You can use the :option:`--http-proxy` **and** :option:`--https-proxy` 218options (you need both since the plugin uses both protocols) to access the 219Crunchyroll servers through a proxy to be able to stream region locked content. 220 221When doing this, it's very probable that you will get denied to access the 222stream; this occurs because the session and credentials used by the plugin 223where obtained when logged from your own region, and the server still assumes 224you're in that region. 225 226For this, the plugin provides the :option:`--crunchyroll-purge-credentials` 227option, which removes your saved session and credentials and tries to log 228in again using your username and password. 229 230Sideloading plugins 231------------------- 232 233Livestreamer will attempt to load standalone plugins from these directories: 234 235================= ==================================================== 236Platform Location 237================= ==================================================== 238Unix-like (POSIX) $XDG_CONFIG_HOME/livestreamer/plugins 239Windows %APPDATA%\\livestreamer\\plugins 240================= ==================================================== 241 242.. note:: 243 244 If a plugin is added with the same name as a built-in plugin then 245 the added plugin will take precedence. This is useful if you want 246 to upgrade plugins independently of the Livestreamer version. 247 248 249Playing built-in streaming protocols directly 250--------------------------------------------- 251 252There are many types of streaming protocols used by services today and 253Livestreamer supports most of them. It's possible to tell Livestreamer 254to access a streaming protocol directly instead of relying on a plugin 255to extract the streams from a URL for you. 256 257A protocol can be accessed directly by specifying it in the URL format:: 258 259 protocol://path [key=value] 260 261Accessing a stream that requires extra parameters to be passed along 262(e.g. RTMP): 263 264.. code-block:: console 265 266 $ livestreamer "rtmp://streaming.server.net/playpath live=1 swfVfy=http://server.net/flashplayer.swf" 267 268 269Most streaming technologies simply requires you to pass a HTTP URL, this is 270a Adobe HDS stream: 271 272.. code-block:: console 273 274 $ livestreamer hds://streaming.server.net/playpath/manifest.f4m 275 276 277Supported streaming protocols 278^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 279 280============================== ================================================= 281Name Prefix 282============================== ================================================= 283Adobe HTTP Dynamic Streaming hds:// 284Akamai HD Adaptive Streaming akamaihd:// 285Apple HTTP Live Streaming hls:// hlsvariant:// 286Real Time Messaging Protocol rtmp:// rtmpe:// rtmps:// rtmpt:// rtmpte:// 287Progressive HTTP, HTTPS, etc httpstream:// 288============================== ================================================= 289 290 291.. _cli-options: 292 293Command-line usage 294------------------ 295 296.. code-block:: console 297 298 $ livestreamer [OPTIONS] [URL] [STREAM] 299 300 301.. argparse:: 302 :module: livestreamer_cli.argparser 303 :attr: parser 304