You are reading the documentation for the in-development version of Streamlink.

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 (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 | None = None¶: A reference to the compiled re.Pattern of the first matching matcher.

match: re.Match | None = 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 (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