Skip to content
Back to top
View this page
Edit this page

# Session

class streamlink.session.Streamlink(options=None, *, plugins_builtin=True, plugins_lazy=True)

  Bases: `object`

  The Streamlink session is used to load and resolve plugins, and to store options used by plugins and stream implementations.

  Parameters:

    - options (Mapping[str, Any] | Options | None) -- Custom options

    - plugins_builtin (bool) -- Whether to load built-in plugins or not

    - plugins_lazy (bool) -- Load built-in plugins lazily. This option falls back to loading all built-in plugins if the pre-built plugin JSON metadata is not available (e.g. in editable installs) or is invalid.

  http: HTTPSession

    An instance of Streamlink's `requests.Session` subclass. Used for any kind of HTTP request made by plugin and stream implementations.

  options: StreamlinkOptions

    Options of this session instance. `StreamlinkOptions` is a subclass of `Options` with special getter/setter mappings.

  plugins: StreamlinkPlugins

    Plugins of this session instance.

  set_option(key, value)

    Sets general options used by plugins and streams originating from this session object.

    This is a convenience wrapper for `self.options.set()`.

    Please see `StreamlinkOptions` for the available options.

    Parameters:

      - key (str) -- key of the option

      - value (Any) -- value to set the option to

    Return type:

      None

  get_option(key)

    Returns the current value of the specified option.

    This is a convenience wrapper for `self.options.get()`.

    Please see `StreamlinkOptions` for the available options.

    Parameters:

      key (str) -- key of the option

    Return type:

      Any

  resolve_url(url, follow_redirect=True)

    Attempts to find a plugin that can use this URL.

    The default protocol (https) will be prefixed to the URL if not specified.

    Return values of this method are cached via `functools.lru_cache()`.

    Parameters:

      - url (str) -- a URL to match against loaded plugins

      - follow_redirect (bool) -- follow redirects

    Raises:

      NoPluginError -- on plugin resolve failure

    Returns:

      A tuple of plugin name, plugin class and resolved URL

    Return type:

      tuple[str, type[Plugin], str]

  resolve_url_no_redirect(url)

    Attempts to find a plugin that can use this URL.

    The default protocol (https) will be prefixed to the URL if not specified.

    Parameters:

      url (str) -- a URL to match against loaded plugins

    Raises:

      NoPluginError -- on plugin resolve failure

    Returns:

      A tuple of plugin name, plugin class and resolved URL

    Return type:

      tuple[str, type[Plugin], str]

  streams(url, options=None, **params)

    Attempts to find a plugin and extracts streams from the url if a plugin was found.

    Parameters:

      - url (str) -- a URL to match against loaded plugins

      - options (Options | None) -- Optional options instance passed to the resolved plugin

      - params -- Additional keyword arguments passed to `Plugin.streams()`

    Raises:

      NoPluginError -- on plugin resolve failure

    Returns:

      A `dict` of stream names and `Stream` instances

  get_plugins()

    Returns the loaded plugins of this session.

    Deprecated in favor of `plugins.get_loaded()`.

  load_builtin_plugins()

    Loads Streamlink's built-in plugins.

    Deprecated in favor of using the `plugins_builtin` keyword argument.

  load_plugins(path)

    Loads plugins from a specific path.

    Deprecated in favor of `plugins.load_path()`.

    Parameters:

      path (str)

    Return type:

      bool

class streamlink.session.options.StreamlinkOptions(session)

  Bases: `Options`

  Streamlink's session options.

  The following options can be accessed using the `Streamlink.get_option()` and `Streamlink.set_option()` methods, as well as the regular `get()` and `set()` methods of this `Options` subclass.

  key | type | default | description
  --- | --- | --- | ---
  user-input-requester | `UserInputRequester | None` | `None` | Instance of `UserInputRequester` to collect input from the user at runtime
  no-plugin-cache | `bool` | `False` | Disable the plugin key-value store
  locale | `str` | system locale | Locale setting, in the RFC 1766 format, e.g. `en_US` or `es_ES`
  interface | `str | None` | `None` | Network interface name or address.
  ipv4 | `bool` | `False` | Resolve address names to IPv4 only, overrides `ipv6`
  ipv6 | `bool` | `False` | Resolve address names to IPv6 only, overrides `ipv4`
  http-proxy | `str | None` | `None` | Proxy address for all HTTP/HTTPS requests
  https-proxy (deprecated) | `str | None` | `None` | Proxy address for all HTTP/HTTPS requests
  http-cookies | `dict[str, str] | str` | `{}` | A `dict` or a semicolon `;` delimited `str` of cookies to add to each HTTP/HTTPS request, e.g. `foo=bar;baz=qux`
  http-cookies-files | `list[str]` | `[]` | A `list` of Netscape HTTP Cookie Files whose data will be added to HTTP/HTTPS requests
  http-headers | `dict[str, str] | str` | `{}` | A `dict` or a semicolon `;` delimited `str` of headers to add to each HTTP/HTTPS request, e.g. `foo=bar;baz=qux`
  http-query-params | `dict[str, str] | str` | `{}` | A `dict` or an ampersand `&` delimited `str` of query string parameters to add to each HTTP/HTTPS request, e.g. `foo=bar&baz=qux`
  http-trust-env | `bool` | `True` | Trust HTTP settings set in the environment, such as environment variables (`HTTP_PROXY`, etc.) and `~/.netrc` authentication
  http-ssl-verify | `bool` | `True` | Verify TLS/SSL certificates
  http-disable-dh | `bool` | `False` | Disable TLS/SSL Diffie-Hellman key exchange
  http-ssl-cert | `str | tuple | None` | `None` | TLS/SSL certificate to use, can be either a .pem file (`str`) or a .crt/.key pair (`tuple`)
  http-timeout | `float` | `20.0` | General timeout used by all HTTP/HTTPS requests, except the ones covered by other options
  ringbuffer-size | `int` | `16777216` (16 MiB) | The size of the internal ring buffer used by most stream types
  mux-subtitles | `bool` | `False` | Make supported plugins mux available subtitles into the output stream
  stream-segment-attempts | `int` | `3` | Number of segment download attempts in segmented streams
  stream-segment-threads | `int` | `1` | The size of the thread pool used to download segments in parallel
  stream-segment-timeout | `float` | `10.0` | Segment connect and read timeout
  stream-segmented-duration | `float` | `0.0` | Limit the playback duration of segmented streams, rounded to the nearest segment
  stream-segmented-queue-deadline | `float` | `3` | Multiplication factor of the deadline for new segments to be queued
  stream-timeout | `float` | `60.0` | Timeout for reading data from stream
  stream-passthrough-encrypted | `bool` | `False` | Pass through encrypted stream segments without attempting decryption
  hls-live-edge | `int` | `3` | Number of segments from the live position of the HLS stream to start reading
  hls-live-restart | `bool` | `False` | Skip to the beginning of a live HLS stream, or as far back as possible
  hls-start-offset | `float` | `0.0` | Number of seconds to skip from the beginning of the HLS stream, interpreted as a negative offset for livestreams
  hls-duration (deprecated) | `float` | `0.0` | See `stream-segmented-duration`
  hls-playlist-reload-attempts | `int` | `3` | Max number of HLS playlist reload attempts before giving up

  hls-playlist-reload-time

  `str | float`

  `"default"`

  Override the HLS playlist reload time, either in seconds (`float`) or as a `str` keyword:

  - `segment`: duration of the last segment

  - `live-edge`: sum of segment durations of the `hls-live-edge` value minus one

  - `default`: the playlist's target duration

  hls-segment-queue-threshold (deprecated) | `float` | `3` | See `stream-segmented-queue-deadline`
  hls-segment-stream-data | `bool` | `False` | Stream data of HLS segment downloads to the output instead of waiting for the full response
  hls-segment-ignore-names | `List[str]` | `[]` | List of HLS segment names without file endings which should get filtered out
  hls-segment-key-uri | `str | None` | `None` | Override the address of the encrypted HLS stream's key, with support for the following string template variables: `{url}`, `{scheme}`, `{netloc}`, `{path}`, `{query}`
  hls-audio-select | `List[str]` | `[]` | Select a specific audio source or sources when multiple audio sources are available, by language code or name, or `"*"` (asterisk)
  dash-manifest-reload-attempts | `int` | `3` | Max number of DASH manifest reload attempts before giving up
  ffmpeg-ffmpeg | `str | None` | `None` | Override for the `ffmpeg`/`ffmpeg.exe` binary path, which by default gets looked up via the `PATH` env var
  ffmpeg-no-validation | `bool` | `False` | Disable FFmpeg validation and version logging
  ffmpeg-validation-timeout | `float` | `4.0` | Timeout in seconds for FFmpeg version validation
  ffmpeg-verbose | `bool` | `False` | Append FFmpeg's stderr stream to the Python's stderr stream
  ffmpeg-verbose-path | `str | None` | `None` | Write FFmpeg's stderr stream to the filesystem at the specified path
  ffmpeg-loglevel | `str | None` | `None` | Set FFmpeg's `-loglevel` value
  ffmpeg-fout | `str | None` | `None` | Set the output format of muxed streams, e.g. `"matroska"`
  ffmpeg-video-transcode | `str | None` | `None` | The codec to use if transcoding video when muxing streams, e.g. `"h264"`
  ffmpeg-audio-transcode | `str | None` | `None` | The codec to use if transcoding video when muxing streams, e.g. `"aac"`
  ffmpeg-copyts | `bool` | `False` | Don't shift input stream timestamps when muxing streams
  ffmpeg-start-at-zero | `bool` | `False` | When `ffmpeg-copyts` is `True`, shift timestamps to zero
  webbrowser | `bool` | `True` | Enable or disable support for Streamlink's webbrowser API
  webbrowser-executable | `str | None` | `None` | Path to the web browser's executable
  webbrowser-timeout | `float` | `20.0` | The maximum amount of time which the webbrowser can take to launch and execute
  webbrowser-cdp-host | `str | None` | `None` | Custom host for the Chrome Devtools Protocol (CDP) interface
  webbrowser-cdp-port | `int | None` | `None` | Custom port for the Chrome Devtools Protocol (CDP) interface
  webbrowser-cdp-timeout | `float` | `2.0` | The maximum amount of time for waiting on a single CDP command response
  webbrowser-headless | `bool` | `False` | Whether to launch the webbrowser in headless mode or not

  Parameters:

    session (Streamlink)

  get(key)

    Get the stored value of a specific key

    Parameters:

      key (str)

    Return type:

      Any

  set(key, value)

    Set the value for a specific key

    Parameters:

      - key (str)

      - value (Any)

    Return type:

      None

class streamlink.session.plugins.StreamlinkPlugins(builtin=True, lazy=True)

  Bases: `object`

  Streamlink's session-plugins implementation. This class is responsible for loading plugins and resolving them from URLs.

  See the `Streamlink.plugins` attribute.

  Unless disabled by the user, Streamlink will try to load built-in plugins lazily, when accessing them for the first time while resolving input URLs. This is done by reading and interpreting serialized data of each plugin's `pluginmatcher` and `pluginargument` data from a pre-built plugins JSON file which is included in Streamlink's wheel packages.

  Plugins which are sideloaded, either from specific user directories or custom input directories, always have a higher priority than built-in plugins.

  Parameters:

    - builtin (bool)

    - lazy (bool)

  __getitem__(item)

    Access a loaded plugin class by name

    Parameters:

      item (str)

    Return type:

      type[Plugin]

  __setitem__(key, value)

    Add/override a plugin class by name

    Parameters:

      - key (str)

      - value (type[Plugin])

    Return type:

      None

  __delitem__(key)

    Remove a loaded plugin by name

    Parameters:

      key (str)

    Return type:

      None

  __contains__(item)

    Check if a plugin is loaded

    Parameters:

      item (str)

    Return type:

      bool

  get_names()

    Get a list of the names of all available plugins

    Return type:

      list[str]

  get_loaded()

    Get a mapping of all loaded plugins

    Return type:

      dict[str, type[Plugin]]

  load_builtin()

    Load Streamlink's built-in plugins

    Return type:

      bool

  load_path(path)

    Load plugins from a custom directory

    Parameters:

      path (str | Path)

    Return type:

      bool

  update(plugins)

    Add/override loaded plugins

    Parameters:

      plugins (Mapping[str, type[Plugin]])

  clear()

    Remove all loaded plugins from the session

  iter_arguments()

    Iterate through all plugins and their `Arguments`

    Return type:

      Iterator[tuple[str, Arguments]]

  iter_matchers()

    Iterate through all plugins and their `Matchers`

    Return type:

      Iterator[tuple[str, Matchers]]

  match_url(url)

    Find a matching plugin by URL and load plugins which haven't been loaded yet

    Parameters:

      url (str)

    Return type:

      tuple[str, type[Plugin]] | None