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

# Plugin

class streamlink.plugin.Plugin(session, url, options=None)

  Bases: `object`

  Plugin base class for retrieving streams and metadata from the URL specified.

  Parameters:

    - session (Streamlink) -- The Streamlink session instance

    - url (str) -- The input URL used for finding and resolving streams

    - options (Mapping[str, Any] | Options | None) -- An optional `Options` instance

  matchers: ClassVar[Matchers] = []

    The list of plugin matchers (URL pattern + priority + optional name). Supports matcher lookups by the matcher index or the optional matcher name.

    Use the `pluginmatcher()` decorator to initialize plugin matchers.

  arguments: ClassVar[Arguments] = {}

    The plugin's `Arguments` collection.

    Use the `pluginargument()` decorator to initialize plugin arguments.

  matcher: re.Pattern[str] = None

    A reference to the compiled `re.Pattern` of the first matching matcher.

  match: re.Match[str] = None

    A reference to the `re.Match` result of the first matching matcher.

  id: str | None = None

    Metadata 'id' attribute: unique stream ID, etc.

  title: str | None = None

    Metadata 'title' attribute: the stream's short descriptive title.

  author: str | None = None

    Metadata 'author' attribute: the channel or broadcaster name, etc.

  category: str | None = None

    Metadata 'category' attribute: name of a game being played, a music genre, etc.

  options: Options

    Plugin options, initialized with the user-set values of the plugin's arguments.

  cache: Cache

    Plugin cache object, used to store plugin-specific data other than HTTP session cookies.

  session: Streamlink

    The Streamlink session which this plugin instance belongs to, with access to its `HTTPSession`.

  matches: Matches

    A list of optional `re.Match` results of all defined matchers. Supports match lookups by the matcher index or the optional matcher name.

  property url: str

    The plugin's input URL. Setting a new value will automatically update the `matches`, `matcher` and `match` data.

  streams(stream_types=None, sorting_excludes=None)

    Attempts to extract available streams.

    Returns a `dict` containing the streams, where the key is the name of the stream (most commonly the quality name), with the value being a `Stream` instance.

    The result can contain the synonyms best and worst which point to the streams which are likely to be of highest and lowest quality respectively.

    If multiple streams with the same name are found, the order of streams specified in stream_types will determine which stream gets to keep the name while the rest will be renamed to "<name>_<stream type>".

    The synonyms can be fine-tuned with the sorting_excludes parameter, which can be one of these types:

    > - A list of filter expressions in the format `[operator]<value>`. For example the filter ">480p" will exclude streams ranked higher than "480p" from the list used in the synonyms ranking. Valid operators are `>`, `>=`, `<` and `<=`. If no operator is specified then equality will be tested.

    > - A function that is passed to `filter()` with a list of stream names as input.

    Parameters:

      - stream_types -- A list of stream types to return

      - sorting_excludes -- Specify which streams to exclude from the best/worst synonyms

    Returns:

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

  _get_streams()

    Implement the stream and metadata retrieval here.

    Needs to return either a dict of `Stream` instances mapped by stream name, or needs to act as a generator which yields tuples of stream names and `Stream` instances.

  save_cookies(cookie_filter=None, default_expires=604800)

    Store the cookies from `session.http` in the plugin cache until they expire. The cookies can be filtered by supplying a filter method. e.g. `lambda c: "auth" in c.name`. If no expiry date is given in the cookie then the `default_expires` value will be used.

    Parameters:

      - cookie_filter (Callable[[Cookie], bool] | None) -- a function to filter the cookies

      - default_expires (int) -- time (in seconds) until cookies with no expiry will expire

    Returns:

      list of the saved cookie names

    Return type:

      list[str]

  load_cookies()

    Load any stored cookies for the plugin that have not expired.

    Returns:

      list of the restored cookie names

    Return type:

      list[str]

  clear_cookies(cookie_filter=None)

    Removes all saved cookies for this plugin. To filter the cookies that are deleted specify the `cookie_filter` argument (see `save_cookies()`).

    Parameters:

      cookie_filter (function) -- a function to filter the cookies

    Returns:

      list of the removed cookie names

    Return type:

      list[str]

## Plugin decorators

@streamlink.plugin.pluginmatcher(pattern, priority=20, name=None)

  Decorator for plugin URL matchers.

  A matcher consists of a compiled regular expression pattern for the plugin's input URL, a priority value and an optional name. The priority value determines which plugin gets chosen by `Streamlink.resolve_url()` if multiple plugins match the input URL. The matcher name can be used for accessing it and its matching result when multiple matchers are defined.

  Plugins must at least have one matcher. If multiple matchers are defined, then the first matching one according to the order of which they have been defined (top to bottom) will be responsible for setting the `Plugin.matcher` and `Plugin.match` attributes on the `Plugin` instance. The `Plugin.matchers` and `Plugin.matches` attributes are affected by all defined matchers, and both support referencing matchers and matches by matcher index and name.

      import re

      from streamlink.plugin import HIGH_PRIORITY, Plugin, pluginmatcher

      @pluginmatcher(re.compile("https?://example:1234/(?:foo|bar)/(?P<name>[^/]+)"))
      @pluginmatcher(priority=HIGH_PRIORITY, pattern=re.compile("""
          https?://(?:
               sitenumberone
              |adifferentsite
              |somethingelse
          )
          /.+\.m3u8
      """, re.VERBOSE))
      class MyPlugin(Plugin):
          ...

  Parameters:

    - pattern (re.Pattern)

    - priority (int)

    - name (str | None)

  Return type:

    Callable[[type[Plugin]], type[Plugin]]

@streamlink.plugin.pluginargument(name, action=None, nargs=None, const=None, default=None, type=None, type_args=None, type_kwargs=None, choices=None, required=False, help=None, metavar=None, dest=None, requires=None, prompt=None, sensitive=False, argument_name=None)

  Decorator for plugin arguments. Takes the same arguments as `Argument`.

  One exception is the `type` argument, which also accepts a `str` value:

  Plugins built into Streamlink must reference the used argument-type function by name, so the pluginargument data can be JSON-serialized. `type_args` and `type_kwargs` can be used to parametrize the type-argument function, but their values must only consist of literal objects.

  The available functions are defined in the `_PLUGINARGUMENT_TYPE_REGISTRY`.

      from streamlink.plugin import Plugin, pluginargument

      @pluginargument(
          "username",
          requires=["password"],
          metavar="EMAIL",
          help="The username for your account.",
      )
      @pluginargument(
          "password",
          sensitive=True,
          metavar="PASSWORD",
          help="The password for your account.",
      )
      class MyPlugin(Plugin):
          ...

  This will add the `--myplugin-username` and `--myplugin-password` arguments to the CLI, assuming the plugin's module name is `myplugin`.

  Parameters:

    - name (str)

    - action (str | None)

    - nargs (int | Literal['?', '*', '+'] | None)

    - const (Any)

    - default (Any)

    - type (str | Callable[[Any], _TChoices | Any] | None)

    - type_args (list | tuple | None)

    - type_kwargs (Mapping[str, Any] | None)

    - choices (_TChoices | None)

    - required (bool)

    - help (str | None)

    - metavar (str | list[str] | tuple[str, ...] | None)

    - dest (str | None)

    - requires (str | list[str] | tuple[str, ...] | None)

    - prompt (str | None)

    - sensitive (bool)

    - argument_name (str | None)

  Return type:

    Callable[[type[Plugin]], type[Plugin]]

streamlink.plugin.plugin._PLUGINARGUMENT_TYPE_REGISTRY: Mapping[str, Callable[[Any], Any]] = {'bool': <function boolean>, 'comma_list': <function comma_list>, 'comma_list_filter': <class 'streamlink.utils.args.comma_list_filter'>, 'filesize': <function filesize>, 'float': <class 'float'>, 'hours_minutes_seconds': <streamlink.utils.times._HoursMinutesSeconds object>, 'hours_minutes_seconds_float': <streamlink.utils.times._HoursMinutesSeconds object>, 'int': <class 'int'>, 'keyvalue': <function keyvalue>, 'num': <class 'streamlink.utils.args.num'>}

  See the `pluginargument()` decorator