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) -- An optional
Options
instance
- matchers: ClassVar[Matchers | None] = None¶
The list of plugin matchers (URL pattern + priority + optional name). This list supports matcher lookups both by matcher index, as well as matcher name, if defined.
Use the
pluginmatcher()
decorator to initialize plugin matchers.
- arguments: ClassVar[Arguments | None] = None¶
The plugin's
Arguments
collection.Use the
pluginargument()
decorator to initialize plugin arguments.
- matcher: Pattern | None = None¶
A reference to the compiled
re.Pattern
of the first matching matcher
- match: 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.
- cache: Cache¶
Plugin cache object, used to store plugin-specific data other than HTTP session cookies
- matches: Matches¶
A list of optional
re.Match
results of all defined matchers. This list supports match lookups both by the respective matcher index, as well as matcher name, if defined.
- property url: str¶
The plugin's input URL. Setting a new value will automatically update the
matches
,matcher
andmatch
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 aStream
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 andStream
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 andStream
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 thedefault_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 (seesave_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
andPlugin.match
attributes on thePlugin
instance. ThePlugin.matchers
andPlugin.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): ...
- @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 astr
value:Plugins built into Streamlink must reference the used argument-type function by name, so the pluginargument data can be JSON-serialized.
type_args
andtype_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 ismyplugin
.- 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 (Dict[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:
- streamlink.plugin.plugin._PLUGINARGUMENT_TYPE_REGISTRY: Dict[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