### Install Streamlink on openSUSE Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install the package using the zypper package manager. ```bash sudo zypper install streamlink ``` -------------------------------- ### Install Streamlink on Solus Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install the package using the eopkg package manager. ```bash sudo eopkg install streamlink ``` -------------------------------- ### Install Streamlink on Void Linux Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install the package using the xbps-install package manager. ```bash sudo xbps-install streamlink ``` -------------------------------- ### Install Streamlink on NixOS Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install the package using the nix-env environment manager. ```bash nix-env -iA nixos.streamlink ``` -------------------------------- ### Install Streamlink on Gentoo Linux Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install the package using the emerge package manager. ```bash sudo emerge net-misc/streamlink ``` -------------------------------- ### Install Streamlink on ALT Linux Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install Streamlink using apt-get on ALT Linux Sisyphus. ```bash sudo apt-get install streamlink ``` -------------------------------- ### Streamlink Main Configuration Example Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/config.rst This example shows how to configure player options in the main Streamlink configuration file. Ensure the file is placed in the correct location for your operating system. ```bash # Player options player=mpv player-args=--cache 2048 player-no-close ``` -------------------------------- ### Install Streamlink on Fedora Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install the package using the dnf package manager. ```bash sudo dnf install streamlink ``` -------------------------------- ### Install Streamlink via VCS Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install the development version of Streamlink directly from a Git repository. ```bash pip install -U git+https://github.com/USERNAME/streamlink.git@REVISION ``` -------------------------------- ### Install Streamlink via Scoop Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Add the extras bucket and install Streamlink using the Scoop package manager. ```bash scoop bucket add extras scoop install streamlink ``` -------------------------------- ### Install Streamlink and dependencies Source: https://github.com/streamlink/streamlink/blob/master/docs/developing.rst Upgrades pip, installs the project in editable mode, and installs all required dependency groups. ```bash # upgrade to the latest version of pip python -m pip install -U pip # install Streamlink in "editable" mode python -m pip install -U --upgrade-strategy=eager -e . # install additional dependencies (see pyproject.toml for individual dependency groups) python -m pip install -U --upgrade-strategy=eager --group all # validate that Streamlink is working streamlink --loglevel=debug ``` -------------------------------- ### Clone and configure repository Source: https://github.com/streamlink/streamlink/blob/master/CONTRIBUTING.md Initial setup for a local development environment by cloning the fork and adding the upstream remote. ```bash git clone git@github.com:YOUR-USERNAME/streamlink.git cd streamlink git remote add upstream https://github.com/streamlink/streamlink.git ``` -------------------------------- ### Install Streamlink using venv Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Create an isolated Python environment and install Streamlink within it. ```bash # Create a new environment python -m venv ~/myenv # Activate the environment # note: non-POSIX compliant shells like FISH or PowerShell have different activation script file names # note: on Windows, the `bin` subdirectory is called `Scripts` source ~/myenv/bin/activate # *Either* install the latest Streamlink release from PyPI in the virtual environment pip install --upgrade streamlink # *Or*, install the most up-to-date development version from master on GitHub pip install --upgrade git+https://github.com/streamlink/streamlink.git # Use Streamlink in the environment streamlink ... # Deactivate the environment deactivate # Use Streamlink without activating the environment ~/myenv/bin/streamlink ... ``` -------------------------------- ### Install Streamlink on Arch Linux Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install the official Streamlink package using pacman. ```bash sudo pacman -S streamlink ``` -------------------------------- ### Install Streamlink via Homebrew Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Use Homebrew to install Streamlink on macOS. ```bash brew install streamlink ``` -------------------------------- ### Install Streamlink via Winget Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Use the Windows Package Manager to install Streamlink. ```bat winget install streamlink ``` -------------------------------- ### Install Streamlink using pipx Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install Streamlink in an isolated environment using pipx, which manages both virtual environments and package installation. ```bash # *Either* install the latest Streamlink release from PyPI in a virtual environment pipx install streamlink # *Or*, install the most up-to-date development version from master on GitHub pipx install git+https://github.com/streamlink/streamlink.git # Use Streamlink streamlink ... ``` -------------------------------- ### Streamlink CLI Usage Example Source: https://github.com/streamlink/streamlink/blob/master/docs/index.rst This example shows the basic command-line usage of Streamlink to play a stream from Twitch. It demonstrates how to specify the service, channel, and desired stream quality. ```console $ streamlink twitch.tv/CHANNEL best [cli][info] Found matching plugin twitch for URL twitch.tv/CHANNEL [cli][info] Available streams: audio_only, 160p (worst), 360p, 480p, 720p, 720p60, 1080p60 (best) [cli][info] Opening stream: 1080p60 (hls) [cli][info] Starting player: vlc ``` -------------------------------- ### Install Streamlink on Debian Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Update package lists and install Streamlink on Debian sid or testing. ```bash sudo apt update sudo apt install streamlink ``` -------------------------------- ### Install Streamlink from AUR Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Clone the AUR repository and build the package manually or via the GitHub mirror. ```bash git clone https://aur.archlinux.org/streamlink-git.git cd streamlink-git makepkg -si # alternatively, get the PKGBUILD from the AUR mirror on GitHub git clone --single-branch --branch streamlink-git https://github.com/archlinux/aur.git streamlink-git ``` -------------------------------- ### Install Streamlink on Debian via Backports Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Use these commands to install the backported version of Streamlink on Debian. ```bash sudo apt update sudo apt -t trixie-backports install streamlink ``` -------------------------------- ### Install Streamlink via MSYS2 Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Use pacman to search for and install the Streamlink package within the MSYS2 environment. ```bat pacman -Ss streamlink pacman -S mingw-w64-x86_64-streamlink ``` -------------------------------- ### Commit Message Format Examples Source: https://github.com/streamlink/streamlink/blob/master/docs/developing.rst Examples of commit messages following the project's conventional commit variation. ```text session.http: fix set_interface on macOS plugins.twitch: switch to usher v2 endpoints ci.github: run preview-builds on uv.lock updates ``` -------------------------------- ### Install Streamlink via Chocolatey Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Use the Chocolatey package manager to install Streamlink on Windows. ```bat choco install streamlink ``` -------------------------------- ### Streamlink Player Configuration Source: https://github.com/streamlink/streamlink/blob/master/docs/_man.rst Specify a custom player and its arguments. This example uses mpv with specific window and aspect ratio settings. ```console streamlink --player mpv --player-args '--no-border --no-keepaspect-window' twitch.tv/CHANNEL 1080p60 ``` -------------------------------- ### Install Streamlink on Alpine Linux Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Install Streamlink using the apk package manager on Alpine Linux edge. ```bash sudo apk add streamlink ``` -------------------------------- ### Install Streamlink via pip Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Commands for installing various versions of Streamlink using the Python package manager. ```bash pip install -U streamlink ``` ```bash pip install -U git+https://github.com/streamlink/streamlink.git ``` ```bash pip install -U git+https://github.com/streamlink/streamlink.git@refs/pull/PULL-REQUEST-ID/head ``` -------------------------------- ### Example JSON Metadata Output Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/metadata.rst This is an example of the JSON output for stream metadata when using the --json argument. ```json { "id": "49163597677", "author": "BobRoss", "category": "Art", "title": "A Happy Little Weekend Marathon!" } ``` -------------------------------- ### Streamlink Debugging Example Source: https://github.com/streamlink/streamlink/blob/master/docs/_man.rst Run Streamlink with debug logging enabled to troubleshoot issues. This is useful for identifying problems with stream resolution or plugin interactions. ```console streamlink --loglevel debug youtu.be/VIDEO-ID best ``` -------------------------------- ### Basic Schema Validation Example Source: https://github.com/streamlink/streamlink/blob/master/docs/api/validate.rst Demonstrates validating an input value against a simple schema that checks for equality. Raises `ValidationError` if the value does not match the schema. ```python schema = validate.Schema(123) assert schema.validate(123) == 123 assert schema.validate(123.0) == 123.0 schema.validate(456) # raises ValidationError schema.validate(None) # raises ValidationError ``` -------------------------------- ### Configure Debian Backports for Streamlink Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Add the trixie-backports repository to your sources list to install Streamlink on Debian stable. ```bash # If you don't have Debian backports already (see link below): echo "deb http://deb.debian.org/debian trixie-backports main" | sudo tee "/etc/apt/sources.list.d/streamlink.list" ``` -------------------------------- ### Verify Python and pip versions Source: https://github.com/streamlink/streamlink/blob/master/docs/developing.rst Checks the installed versions of Python and pip to ensure compatibility. ```bash python --version pip --version ``` -------------------------------- ### Streamlink HLS Live Edge and Threads Source: https://github.com/streamlink/streamlink/blob/master/docs/_man.rst Configure HLS specific options like live edge and stream segment threads. This example sets the live edge to 5 and uses 5 threads for segment processing. ```console streamlink --hls-live-edge 5 --stream-segment-threads 5 'hls://https://host/playlist.m3u8' best ``` -------------------------------- ### MPlayer Youtube Live Error Example Source: https://github.com/streamlink/streamlink/blob/master/docs/players.rst This console output shows an error encountered when MPlayer has issues playing Youtube Live streams, often resolved by switching to mpv. ```console Cannot seek backward in linear streams! Seek failed ``` -------------------------------- ### Windows Batch URL Quoting Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/tutorial.rst Provides examples for Windows Batch scripting, showing how to handle special characters like percent signs and ampersands using double quotes and caret escaping. ```bat streamlink "https://example/path?a=$one&b=%"two"%&c=*three*;&" ``` ```bat streamlink https://example/path?a=$one^&b=^%two^%^&c=*three*^;^& ``` -------------------------------- ### Handle Validation Errors Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/validate.rst Illustrates how Schema.validate() raises PluginError when validation fails, wrapping underlying ValidationErrors. This shows examples of equality and type validation failures. ```python >>> schema_one.validate(123) streamlink.exceptions.PluginError: Unable to validate result: ValidationError(equality): 123 does not equal '123' ``` ```python >>> schema_three.validate(123.0) streamlink.exceptions.PluginError: Unable to validate result: ValidationError(type): Type of 123.0 should be int, but is float ``` -------------------------------- ### Streamlink Twitch Low Latency and Cache Source: https://github.com/streamlink/streamlink/blob/master/docs/_man.rst Enable Twitch low latency mode and configure player cache settings. This example uses mpv with a 2GB cache size. ```console streamlink --twitch-low-latency -p mpv -a '--cache=yes --demuxer-max-back-bytes=2G' twitch.tv/CHANNEL best ``` -------------------------------- ### Streamlink External HTTP Player Source: https://github.com/streamlink/streamlink/blob/master/docs/_man.rst Configure Streamlink to use an external HTTP server for the player, specifying the port. Useful for custom streaming setups. ```console streamlink --player-external-http --player-external-http-port 8888 URL STREAM ``` -------------------------------- ### Initialize Plugin with Options Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/quickstart.rst Resolve a URL to a plugin and initialize it with custom plugin options. This is useful when specific plugin behaviors need to be configured. ```python >>> plugin_name, plugin_class, resolved_url = session.resolve_url("URL") >>> plugin = plugin_class(session, resolved_url, options={"plugin-option": 123}) >>> streams = plugin.streams() ``` -------------------------------- ### Create and activate a virtual environment Source: https://github.com/streamlink/streamlink/blob/master/docs/developing.rst Sets up an isolated Python environment and provides activation commands for different shells. ```bash # replace ~/venvs/streamlink with your path of choice and give it a proper name python -m venv ~/venvs/streamlink ``` ```bash source ~/venvs/streamlink/bin/activate # non-POSIX shells have their own activation script, e.g. FISH source ~/venvs/streamlink/bin/activate.fish ``` ```pwsh # on Windows, activation scripts are located in the Scripts/ subdirectory instead of bin/ ~\venvs\streamlink\Scripts\Activate.ps1 ``` -------------------------------- ### Initialize Twitch Plugin with Options Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/quickstart.rst Import a specific plugin directly and initialize it with custom options, such as disabling ads or enabling low-latency streaming for Twitch. The input URL must match the plugin's URL matchers. ```python >>> from streamlink.plugins.twitch import __plugin__ as Twitch >>> plugin = Twitch(session, "https://twitch.tv/CHANNEL", options={"disable-ads": True, "low-latency": True}) >>> streams = plugin.streams() ``` -------------------------------- ### Clone the Streamlink repository Source: https://github.com/streamlink/streamlink/blob/master/docs/developing.rst Initializes the local repository, sets up remotes, and fetches all branches. ```bash mkdir streamlink cd streamlink git clone --origin=upstream 'https://github.com/streamlink/streamlink.git' . git remote add fork 'git@github.com:/streamlink.git' git remote -v git fetch --all ``` -------------------------------- ### Configure Streaming Protocol Behavior Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/protocols.rst Parameters such as start_offset, duration, and force_restart can be used to directly configure the behavior of the streaming protocol implementation. ```console $ streamlink "hls://https://streamingserver/path start_offset=123 duration=321 force_restart=True" ``` -------------------------------- ### Create Simple Validation Schemas Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/validate.rst Demonstrates the creation of basic Schema instances for equality and type validation. These schemas can validate single conditions or multiple conditions sequentially. ```python >>> from streamlink.plugin.api import validate >>> schema_one = validate.Schema("123") >>> schema_two = validate.Schema(123) >>> schema_three = validate.Schema(int, 123.0) ``` ```python >>> schema_one.validate("123") '123' >>> schema_two.validate(123) 123 >>> schema_three.validate(123) 123 ``` -------------------------------- ### Create a topic branch Source: https://github.com/streamlink/streamlink/blob/master/CONTRIBUTING.md Initialize a new branch for specific features or fixes. ```bash git checkout -b TOPIC-BRANCH-NAME ``` -------------------------------- ### Streamlink CLI Basic Usage Source: https://github.com/streamlink/streamlink/blob/master/docs/cli.rst This is the basic syntax for using the Streamlink command-line tool. Specify options, the URL of the stream, and optionally a specific stream quality. ```console $ streamlink [OPTIONS] [STREAM] ``` -------------------------------- ### List Available Streams Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/tutorial.rst Use this command to discover available streams for a given URL. Streamlink will identify the plugin and list stream qualities. ```console $ streamlink twitch.tv/CHANNEL [cli][info] Found matching plugin twitch for URL twitch.tv/CHANNEL Available streams: audio_only, 160p (worst), 360p, 480p, 720p60, 1080p60 (best) ``` -------------------------------- ### Run Streamlink AppImage Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Execute the Streamlink AppImage with command-line arguments. ```bash ./streamlink-7.0.0-1-cp312-cp312-manylinux_2_28_x86_64.AppImage --loglevel=debug ``` -------------------------------- ### Make AppImage Executable Source: https://github.com/streamlink/streamlink/blob/master/docs/install.rst Set the executable permission on the downloaded AppImage file using chmod. ```bash # AppImage file names include the release version, # the Python version, platform name and CPU architecture chmod +x streamlink-7.0.0-1-cp312-cp312-manylinux_2_28_x86_64.AppImage ``` -------------------------------- ### Streamlink CLI Synopsis Source: https://github.com/streamlink/streamlink/blob/master/docs/_man.rst The basic command structure for using the Streamlink CLI. Specify options, the URL of the stream, and optionally a specific stream quality. ```console streamlink [OPTIONS] [STREAM] ``` -------------------------------- ### Access Streaming Protocol Directly Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/protocols.rst Specify the protocol and URL directly to access a stream. Parameters can be appended as key=value pairs. ```console $ streamlink "protocol://https://streamingserver/path key1=value1 key2=value2" ``` -------------------------------- ### Initialize Streamlink Session Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/quickstart.rst Create a Streamlink session object to manage options and efficiently extract streams multiple times. You can pass initial options during instantiation. ```python from streamlink import Streamlink session = Streamlink({"optional-session-option": 123}) ``` -------------------------------- ### Migrated Plugin URL Matching (Python) Source: https://github.com/streamlink/streamlink/blob/master/docs/deprecations.rst Shows the modern, declarative way to define plugin URL matching using the `@pluginmatcher` decorator. This replaces the deprecated `can_handle_url` and `priority` classmethods. ```python import re from streamlink.plugin import HIGH_PRIORITY, Plugin, pluginmatcher @pluginmatcher(re.compile( r"https?://pattern-(?Pone)" )) @pluginmatcher(priority=HIGH_PRIORITY, pattern=re.compile(r""" https?://pattern-(?Ptwo) """, re.VERBOSE)) class MyPlugin(Plugin): def _get_streams(self): param = self.match.group("param") if self.matches[0]: yield ... ``` -------------------------------- ### Configure SOCKS5h Proxy Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/proxy.rst Use the --http-proxy option with the 'socks5h' scheme to specify a SOCKS5 proxy server. This scheme ensures DNS lookups are performed by the proxy server. ```console $ streamlink --http-proxy "socks5h://address:port" ``` -------------------------------- ### Use Protocol Parameters for HTTP Requests Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/protocols.rst Parameters like method, params, and json can be passed to configure HTTP requests. Values can be interpreted as Python literals. ```console $ streamlink "httpstream://https://streamingserver/path method=POST params={'abc':123} json=['foo','bar','baz']" ``` ```python method="POST" params={"key": 123} json=["foo", "bar", "baz"] ``` -------------------------------- ### Configure HTTP Proxy Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/proxy.rst Use the --http-proxy option to specify an HTTP proxy server for all requests. This includes HTTP and HTTPS traffic. ```console $ streamlink --http-proxy "http://address:port" ``` -------------------------------- ### Configure SOCKS4a Proxy Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/proxy.rst Use the --http-proxy option with the 'socks4a' scheme to specify a SOCKS4 proxy server. This scheme ensures DNS lookups are performed by the proxy server. ```console $ streamlink --http-proxy "socks4a://address:port" ``` -------------------------------- ### Migrate Plugin Options Management Source: https://github.com/streamlink/streamlink/blob/master/docs/migrations.rst Before Streamlink 5.3.0, plugin options were set globally on the session. Now, options should be initialized with an Options object and passed to the streams method or plugin constructor. ```python from streamlink.session import Streamlink session = Streamlink() session.set_plugin_option("twitch", "api-header", [("Authorization", "OAuth TOKEN")]) streams = session.streams("twitch.tv/...") ``` ```python from streamlink.options import Options from streamlink.session import Streamlink session = Streamlink() options = Options() options.set("api-header", [("Authorization", "OAuth TOKEN")]) streams = session.streams("twitch.tv/ப்புகளை", options) ``` ```python from streamlink.options import Options from streamlink.session import Streamlink session = Streamlink() pluginname, Pluginclass, resolved_url = session.resolve_url("twitch.tv/...") options = Options() options.set("api-header", [("Authorization", "OAuth TOKEN")]) plugin = Pluginclass(session, resolved_url, options) streams = plugin.streams() ``` -------------------------------- ### Deprecated Plugin URL Matching (Python) Source: https://github.com/streamlink/streamlink/blob/master/docs/deprecations.rst Illustrates the old method of defining plugin URL matching using classmethods `can_handle_url` and `priority`. This approach is deprecated in favor of declarative matching. ```python import re from streamlink.plugin import Plugin from streamlink.plugin.plugin import HIGH_PRIORITY, NORMAL_PRIORITY class MyPlugin(Plugin): _re_url_one = re.compile( r"https?://pattern-(?Pone)" ) _re_url_two = re.compile(r""" https?://pattern-(?Ptwo) """, re.VERBOSE) @classmethod def can_handle_url(cls, url: str) -> bool: return cls._re_url_one.match(url) is not None \ or cls._re_url_two.match(url) is not None @classmethod def priority(cls, url: str) -> int: if cls._re_url_two.match(url) is not None: return HIGH_PRIORITY else: return NORMAL_PRIORITY def _get_streams(self): match_one = self._re_url_one.match(self.url) match_two = self._re_url_two.match(self.url) match = match_one or match_two param = match.group("param") if match_one: yield ... elif match_two: yield ... __plugin__ = MyPlugin ``` -------------------------------- ### Record Stream with Custom Filename Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/metadata.rst Utilize metadata variables to create a structured recording path and filename, including author, category, stream ID, and a formatted timestamp. ```console $ streamlink --output "~/recordings/{author}/{category}/{id}-{time:%Y%m%d%H%M%S}.ts" [STREAM] ``` -------------------------------- ### Set Streamlink Session Options Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/quickstart.rst Configure session-specific options like stream timeouts. Refer to StreamlinkOptions for all available settings. ```python session.set_option("stream-timeout", 30) session.options.set("stream-timeout", 30) ``` -------------------------------- ### Push branch to fork Source: https://github.com/streamlink/streamlink/blob/master/CONTRIBUTING.md Upload the local topic branch to the remote fork. ```bash git push origin TOPIC-BRANCH-NAME ``` -------------------------------- ### Basic Streamlink Usage Source: https://github.com/streamlink/streamlink/blob/master/README.md This is the basic command to pipe a stream from a given URL to the default video player (VLC). Replace 'STREAMURL' with the actual stream URL. ```sh streamlink "STREAMURL" best ``` -------------------------------- ### Fetch Streams using Session Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/quickstart.rst Use the session object to fetch streams from a URL. This method allows for automatic plugin selection. ```python streams = session.streams("URL") ``` -------------------------------- ### Retrieve Metadata with --json Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/metadata.rst Use the --json argument to output stream metadata, which can then be processed with tools like jq. ```console $ streamlink --json twitch.tv/bobross | jq .metadata ``` -------------------------------- ### Configure HTTPS Proxy Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/proxy.rst Use the --http-proxy option with an HTTPS URL to specify an HTTPS proxy server for all requests. This includes HTTP and HTTPS traffic. ```console $ streamlink --http-proxy "https://address:port" ``` -------------------------------- ### Streamlink Output to File Source: https://github.com/streamlink/streamlink/blob/master/docs/_man.rst Save the stream directly to a file using the --output option and set an HTTP timeout. Ensure the specified path is writable. ```console streamlink --output /path/to/file --http-timeout 60 URL STREAM ``` -------------------------------- ### Validate changes locally Source: https://github.com/streamlink/streamlink/blob/master/docs/developing.rst Runs tests, linting, formatting, and documentation builds to ensure code quality before submission. ```bash # run automated tests pytest # or just run a subset of all tests pytest path/to/test-file.py::TestClassName::test_method_name ... # check code for linting errors ruff check . # check code for formatting errors ruff format --diff . # check code for typing errors ty check mypy # build the documentation make --directory=docs clean html # check the documentation python -m http.server 8000 --bind '127.0.0.1' --directory 'docs/_build/html/' "${BROWSER}" http://127.0.0.1:8000/ ``` -------------------------------- ### Test plugin URL matching Source: https://github.com/streamlink/streamlink/blob/master/docs/developing.rst Use this class to define URL matching patterns and groups for plugin validation. ```python from streamlink.plugins.pluginfile import MyPluginClassName from tests.plugins import PluginCanHandleUrl class TestPluginCanHandleUrlMyPluginClassName(PluginCanHandleUrl): __plugin__ = MyPluginClassName should_match = [ "https://host/path/one", ("specific-path-matcher", "https://host/path/two"), ] should_match_groups = [ ("https://host/stream/123", {"stream": "123"}), ("https://host/stream/456/foo", ("456", "foo")), (("user-matcher", "https://host/user/one"), {"user": "one"}), (("user-matcher", "https://host/user/two"), ("two", None)), (("user-matcher", "https://host/user/two/foo"), ("two", "foo")), ] should_not_match = [ "https://host/path/three", ] ``` -------------------------------- ### Configure Twitch Authorization in Config File Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/plugins/twitch.rst Add the authorization header to the Streamlink configuration file without requiring quotes. ```text twitch-api-header=Authorization=OAuth abcdefghijklmnopqrstuvwxyz0123 ``` -------------------------------- ### Plugin Metadata Header Format Source: https://github.com/streamlink/streamlink/blob/master/docs/developing.rst Required header comment format for new plugin files to ensure proper documentation generation. ```python """ $description A brief description of the website, streaming service, etc. $url A URL which matches the plugin. No http:// or https:// scheme prefixes allowed. $url Multiple URLs can be set. Duplicates are not allowed. $type The type of content. Needs to be either "live", "vod", or "live, vod", without quotes. $region A comma-separated list of countries if region-lock applies. (optional) $account A brief note about account or subscription requirements. (optional) $notes Further short notes that may be useful. (optional) """ ``` -------------------------------- ### Open Stream for Reading Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/quickstart.rst Opens a stream for reading and returns a file-like object. Ensure to close the file descriptor after use to release resources. Errors during opening raise a StreamError. ```python fd = streams["best"].open() data = fd.read(1024) fd.close() ``` -------------------------------- ### Manage Git branches for pull requests Source: https://github.com/streamlink/streamlink/blob/master/docs/developing.rst Standard workflow for creating a new feature or bugfix branch from the master branch. ```bash git checkout master git pull upstream master git checkout -b new/feature/or/bugfix/branch git add ./foo git commit git push fork new/feature/or/bugfix/branch ``` -------------------------------- ### NoPluginError Source: https://github.com/streamlink/streamlink/blob/master/docs/api/exceptions.rst Raised when no plugin can be found for a given URL. ```APIDOC ## NoPluginError ### Description Raised when no plugin can be found for a given URL. ### Exception `streamlink.exceptions.NoPluginError` ``` -------------------------------- ### Play Stream with Specific Quality Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/tutorial.rst Select a specific stream quality to play. If not specified, 'best' or 'worst' can be used to automatically select the highest or lowest quality stream, respectively. ```console $ streamlink twitch.tv/CHANNEL 1080p60 [cli][info] Found matching plugin twitch for URL twitch.tv/CHANNEL [cli][info] Opening stream: 1080p60 (hls) [cli][info] Starting player: vlc ``` -------------------------------- ### Streamlink Session Options Source: https://github.com/streamlink/streamlink/blob/master/docs/api/session.rst Manages configuration options for the Streamlink session. ```APIDOC ## Class: streamlink.session.options.StreamlinkOptions Provides methods to get and set session-specific options. ### Methods * **get(key)**: Retrieves the value of a specific session option. * **set(key, value)**: Sets the value of a specific session option. ``` -------------------------------- ### Extract Streams from URL Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/quickstart.rst Use this to extract available streams from a given URL. It automatically finds a plugin and extracts streams. If no plugin is found, a NoPluginError is raised. Errors during fetching raise a PluginError. ```python import streamlink streams = streamlink.streams("hls://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8") ``` -------------------------------- ### Plugin Decorators Source: https://github.com/streamlink/streamlink/blob/master/docs/api/plugin.rst Decorators used to define how plugins are matched and how arguments are handled. ```APIDOC ## Plugin Decorators ### `pluginmatcher` Decorator to mark a method as a plugin matcher. ### `pluginargument` Decorator to define and register plugin arguments. ``` -------------------------------- ### Set Stream Title with Metadata Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/metadata.rst Use metadata variables to dynamically set the stream title in the CLI. ```console $ streamlink --title "{author} - {category} - {title}" [STREAM] ``` -------------------------------- ### Regex Schema Validation Source: https://github.com/streamlink/streamlink/blob/master/docs/api/validate.rst Demonstrates how to use a compiled regex pattern with `validate.Schema` to validate string or bytes input. It shows successful matches, non-matches, and type validation errors. ```APIDOC ## Schema Validation with Regex ### Description Validates an input value against a compiled regular expression pattern. This method utilizes the `re.Pattern.search()` method internally. It distinguishes between `re.Pattern` objects and `RegexSchema` validation. ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Method Not applicable (Python method) ### Endpoint Not applicable (Python method) ### Request Example ```python import re from streamlink.validate import Schema schema = Schema( re.compile(r"^Hello, (?P\\w+)!$"), ) # Successful validation match_result = schema.validate("Hello, world!") print(match_result["name"]) # Unsuccessful validation (returns None) print(schema.validate("Does not match")) # Raises ValidationError for incorrect type try: schema.validate(123) except ValidationError as e: print(e) try: schema.validate(b"Hello, world!") except ValidationError as e: print(e) ``` ### Response #### Success Response - **match_result** (:class:`re.Match` or ``None``) - The resulting match object if the value matches the schema, otherwise ``None``. #### Response Example ```json { "name": "world" } ``` ### Errors - **ValidationError**: Raised if the input `value` is not an instance of `str` or `bytes`. - **ValidationError**: Raised if the type of `value` does not match the expected `str` or `bytes` type for the schema. ``` -------------------------------- ### Streamlink Pipe to FFmpeg Source: https://github.com/streamlink/streamlink/blob/master/docs/_man.rst Stream output directly to stdout and pipe it to FFmpeg for further processing. This is common for recording or re-encoding streams. ```console streamlink --stdout URL STREAM | ffmpeg -i pipe:0 ... ``` -------------------------------- ### PluginError Source: https://github.com/streamlink/streamlink/blob/master/docs/api/exceptions.rst Base exception for errors occurring within plugins. ```APIDOC ## PluginError ### Description Base exception for errors occurring within plugins. ### Exception `streamlink.exceptions.PluginError` ``` -------------------------------- ### Update HTTPStream and HLSStream Constructors Source: https://github.com/streamlink/streamlink/blob/master/docs/migrations.rst The constructors for HTTPStream and HLSStream, and the HLSStream.parse_variant_playlist classmethod, now require the Streamlink session instance as a positional argument or with the 'session' keyword. ```python from streamlink.session import Streamlink from streamlink.stream import HTTPStream session = Streamlink() # Before: # stream = HTTPStream(url, session_=session) # After: stream = HTTPStream(url, session) ``` ```python from streamlink.session import Streamlink from streamlink.stream import HLSStream session = Streamlink() # Before: # playlist = HLSStream.parse_variant_playlist(url, session_=session) # After: playlist = HLSStream.parse_variant_playlist(url, session) ``` -------------------------------- ### Update local repository Source: https://github.com/streamlink/streamlink/blob/master/CONTRIBUTING.md Sync the local master branch with the latest changes from the upstream repository. ```bash git checkout master git pull upstream master ``` -------------------------------- ### HTML Parsing and XPath Query Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/validate.rst Demonstrates parsing HTML content and extracting a specific attribute value using an XPath query. This is useful for retrieving data embedded within HTML elements. ```pycon >>> schema.validate(""" ... ...
... """) None ``` ```pycon >>> schema.validate(""" ... ...
... ... ...
... """) None ``` ```pycon >>> schema.validate(""" ... ...
... ... ...
... """) 'https://host/hls-playlist.m3u8' ``` -------------------------------- ### Set Twitch Authorization Header via CLI Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/plugins/twitch.rst Use the --twitch-api-header argument to pass the OAuth token to Streamlink. Ensure the value is quoted to handle the space character. ```console $ streamlink "--twitch-api-header=Authorization=OAuth abcdefghijklmnopqrstuvwxyz0123" twitch.tv/CHANNEL best ``` -------------------------------- ### POSIX Shell URL Quoting Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/tutorial.rst Demonstrates quoting and escaping for POSIX-compliant shells like Bash and Zsh. Use single quotes for literal strings or escape special characters with a backslash. ```sh streamlink 'https://example/path?a=$one&b=%two%&c=*three*;&' ``` ```sh streamlink "https://example/path?a=\$one&b=%two%&c=*three*;&" ``` ```sh streamlink https://example/path?a=\$one\&b=%two%\&c=*three*\;\& ``` -------------------------------- ### Streamlink Session Plugins Source: https://github.com/streamlink/streamlink/blob/master/docs/api/session.rst Handles the management and access of plugins within the Streamlink session. ```APIDOC ## Class: streamlink.session.plugins.StreamlinkPlugins Manages plugins for the Streamlink session, allowing for dictionary-like access and manipulation. ### Special Members * **__getitem__(key)**: Accesses a plugin by its key. * **__setitem__(key, value)**: Adds or updates a plugin. * **__delitem__(key)**: Removes a plugin. * **__contains__(key)**: Checks if a plugin exists. ``` -------------------------------- ### Access Global Plugin Arguments Source: https://github.com/streamlink/streamlink/blob/master/docs/migrations.rst Global plugin arguments are no longer accessed via Plugin.options. Use Streamlink.get_option() instead. ```python from streamlink.session import Streamlink session = Streamlink() # Access global argument using get_option() # global_arg = session.get_option("global_argument_name") ``` -------------------------------- ### Plugin Argument Type Registry Source: https://github.com/streamlink/streamlink/blob/master/docs/api/plugin.rst The internal registry for plugin argument types. ```APIDOC ## Plugin Data ### `streamlink.plugin.plugin._PLUGINARGUMENT_TYPE_REGISTRY` Internal data structure that holds the registered types for plugin arguments. ``` -------------------------------- ### Streamlink Custom HTTP Headers Source: https://github.com/streamlink/streamlink/blob/master/docs/_man.rst Include custom HTTP headers, such as Authorization and Referer, when connecting to the stream. This is often required for authenticated or specific referer-based streams. ```console streamlink --http-header 'Authorization=OAuth TOKEN' --http-header 'Referer=URL' URL STREAM ``` -------------------------------- ### Play Local HLS Playlist Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/tutorial.rst Streamlink can play local files using supported protocols like HLS. Ensure the file path is correctly formatted with forward slashes. ```console $ streamlink hls://file://C:/hls/playlist.m3u8 [cli][info] Found matching plugin stream for URL hls://file://C:/hls/playlist.m3u8 Available streams: 180p (worst), 272p, 408p, 554p, 818p, 1744p (best) ``` -------------------------------- ### WebbrowserError Source: https://github.com/streamlink/streamlink/blob/master/docs/api/exceptions.rst Base exception for errors related to the webbrowser module. ```APIDOC ## WebbrowserError ### Description Base exception for errors related to the webbrowser module. ### Exception `streamlink.webbrowser.exceptions.WebbrowserError` ``` -------------------------------- ### URL Validation with Path Constraint Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/validate.rst Illustrates a validation scenario where a URL is expected to have a path ending with '.m3u8'. If the condition is not met, a ValidationError is raised. ```pycon >>> schema.validate(""" ... ...
... ... ...
... """) streamlink.exceptions.PluginError: Unable to validate result: ValidationError(NoneOrAllSchema): ValidationError(dict): Unable to validate value of key 'url' Context(url): Unable to validate URL attribute 'path' Context(endswith): '/dash-manifest.mpd' does not end with '.m3u8' ``` -------------------------------- ### Replace plugin.api.validate.text with str Source: https://github.com/streamlink/streamlink/blob/master/docs/migrations.rst The alias 'plugin.api.validate.text' for 'str' has been removed. Replace all occurrences with 'str'. ```python from streamlink.plugin.api import validate # Before: # data = validate.text(some_value) # After: data = str(some_value) ``` -------------------------------- ### Access HLS and DASH Streams Directly Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/protocols.rst The explicit protocol scheme can be omitted for common stream types like HLS (.m3u8) and DASH (.mpd). ```console $ streamlink "https://streamingserver/playlist.m3u8" ``` ```console $ streamlink "https://streamingserver/manifest.mpd" ``` -------------------------------- ### NoStreamsError Source: https://github.com/streamlink/streamlink/blob/master/docs/api/exceptions.rst Raised when no streams are available for a given URL. ```APIDOC ## NoStreamsError ### Description Raised when no streams are available for a given URL. ### Exception `streamlink.exceptions.NoStreamsError` ``` -------------------------------- ### CDPError Source: https://github.com/streamlink/streamlink/blob/master/docs/api/exceptions.rst Base exception for errors related to the Chrome DevTools Protocol (CDP) module. ```APIDOC ## CDPError ### Description Base exception for errors related to the Chrome DevTools Protocol (CDP) module. ### Exception `streamlink.webbrowser.cdp.exceptions.CDPError` ``` -------------------------------- ### Rebase topic branch Source: https://github.com/streamlink/streamlink/blob/master/CONTRIBUTING.md Update a topic branch with the latest master changes using an interactive rebase. ```bash git checkout master git pull upstream master git checkout TOPIC-BRANCH-NAME git rebase --interactive master ``` -------------------------------- ### Validate Dictionary with Any Key Match Source: https://github.com/streamlink/streamlink/blob/master/docs/api/validate.rst Use Schema({validate.any(key1, key2): type}) to validate dictionaries where keys can match any of the specified options. All key-value pairs in the input are validated against the schema's key-value pair. Extra keys in the input will raise a ValidationError. ```python schema = validate.Schema({ validate.any("a", "b"): int, }) assert schema.validate({}) == {} assert schema.validate({"a": 1}) == {"a": 1} assert schema.validate({"b": 2}) == {"b": 2} assert schema.validate({"a": 1, "b": 2}) == {"a": 1, "b": 2} schema.validate({"a": 1, "b": 2, "other": 0}) # raises ValidationError schema.validate({"a": None}) # raises ValidationError ``` -------------------------------- ### HTTP Stream Class Source: https://github.com/streamlink/streamlink/blob/master/docs/api/stream.rst Represents a stream delivered over HTTP. ```APIDOC ## HTTPStream ### Description Represents a stream delivered over HTTP. ### Class streamlink.stream.http.HTTPStream ``` -------------------------------- ### Inspect Stream URL Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/quickstart.rst Access the direct URL of a stream, useful for inspecting stream properties like HLS manifest URLs. ```python streams["best"].url ``` -------------------------------- ### Schema Class Source: https://github.com/streamlink/streamlink/blob/master/docs/api/validate.rst The main public interface for creating and managing validation schemas. Use its `validate` method to perform data validation. ```APIDOC ## class streamlink.plugin.api.validate.Schema ### Description Represents a validation schema used for validating input values. ### Methods #### validate(self, value) Validates the given input `value` against the schema. :param Any value: The input value to validate. :return Any: The validated value, potentially transformed by the schema. :raise ValidationError: If the value fails validation. ``` -------------------------------- ### Regex Pattern Validation with Schema Source: https://github.com/streamlink/streamlink/blob/master/docs/api/validate.rst Use this schema to validate input against a compiled regular expression pattern. It returns None for non-matches and the match object for successful matches. Invalid types will raise a ValidationError. ```python schema = validate.Schema( re.compile(r"^Hello, (?P\w+)!$"), ) assert schema.validate("Does not match") is None assert schema.validate("Hello, world!")["name"] == "world" schema.validate(123) # raises ValidationError schema.validate(b"Hello, world!") # raises ValidationError ``` -------------------------------- ### PowerShell URL Quoting Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/tutorial.rst Illustrates URL quoting and escaping for PowerShell. PowerShell uses backticks (`) to escape special characters, including the dollar sign. ```pwsh streamlink 'https://example/path?a=$one&b=%two%&c=*three*;&' ``` ```pwsh streamlink "https://example/path?a=`$one&b=%two%&c=*three*;&" ``` ```pwsh streamlink https://example/path?a=`$one`&b=%two%`&c=*three*`;`& ``` -------------------------------- ### FISH Shell URL Quoting Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/tutorial.rst Shows URL quoting and escaping for the FISH shell. Similar to POSIX, single quotes are used for literal strings, and backslashes escape special characters. ```fish streamlink 'https://example/path?a=$one&b=%two%&c=*three*;&' ``` ```fish streamlink "https://example/path?a=\$one&b=%two%&c=*three*;&" ``` ```fish streamlink https://example/path\?a=\$one&b=%two%&c=\*three\*\;& ``` -------------------------------- ### Plugin Override Log Message Source: https://github.com/streamlink/streamlink/blob/master/docs/cli/plugin-sideloading.rst When a sideloaded plugin overrides a built-in plugin, a debug log message is generated indicating the plugin name, the file path, and its checksum. ```text [session][debug] Plugin PLUGINNAME is being overridden by PATH-TO-PLUGIN-FILE (sha256:CHECKSUM) ``` -------------------------------- ### FatalPluginError Source: https://github.com/streamlink/streamlink/blob/master/docs/api/exceptions.rst Indicates a fatal error within a plugin that prevents further processing. ```APIDOC ## FatalPluginError ### Description Indicates a fatal error within a plugin that prevents further processing. ### Exception `streamlink.exceptions.FatalPluginError` ``` -------------------------------- ### Streamlink Session Class Source: https://github.com/streamlink/streamlink/blob/master/docs/api/session.rst The main Streamlink session class, providing core functionality for managing streams. ```APIDOC ## Class: streamlink.session.Streamlink This class represents the main Streamlink session, managing core functionalities and configurations. ``` -------------------------------- ### HLS Stream Class Source: https://github.com/streamlink/streamlink/blob/master/docs/api/stream.rst Represents a stream using the HTTP Live Streaming (HLS) protocol. ```APIDOC ## HLSStream ### Description Represents a stream using the HTTP Live Streaming (HLS) protocol. ### Class streamlink.stream.hls.HLSStream ``` -------------------------------- ### Validate HLS URL from HTML Source: https://github.com/streamlink/streamlink/blob/master/docs/api_guide/validate.rst Use this schema to extract an HLS URL from HTML content. It validates that the URL path ends with ".m3u8". The schema returns `None` if the URL is missing or invalid. ```python import re from streamlink.plugin import Plugin, pluginmatcher from streamlink.plugin.api import validate from streamlink.stream.hls import HLSStream @pluginmatcher(re.compile(r"https://example\.tld/")) class ExamplePlugin(Plugin): def _get_streams(): hls_url = self.session.http.get(self.url, schema=validate.Schema( validate.parse_html(), validate.xml_xpath_string(".//*[@data-player][1]/@data-player"), validate.none_or_all( validate.parse_json(), { validate.optional("url"): validate.url( path=validate.endswith(".m3u8"), ), }, validate.get("url"), ), )) if not hls_url: return None return HLSStream.parse_variant_playlist(self.session, hls_url) __plugin__ = ExamplePlugin ``` -------------------------------- ### Validate Dictionary with Optional Keys Source: https://github.com/streamlink/streamlink/blob/master/docs/api/validate.rst Use Schema({"key": type, validate.optional("opt"): type}) to validate dictionaries. Keys not present in the schema are ignored. Optional keys can be omitted from the input value. Raises ValidationError for missing required keys or type mismatches. ```python schema = validate.Schema({ "key": str, validate.optional("opt"): 123, }) assert schema.validate({"key": "val", "other": 123}) == {"key": "val"} assert schema.validate({"key": "val", "opt": 123}) == {"key": "val", "opt": 123} schema.validate(None) # raises ValidationError schema.validate({}) # raises ValidationError schema.validate({"key": 123}) # raises ValidationError schema.validate({"key": "val", "opt": 456}) # raises ValidationError ``` -------------------------------- ### Muxed HLS Stream Class Source: https://github.com/streamlink/streamlink/blob/master/docs/api/stream.rst Represents an HLS stream that has been muxed. ```APIDOC ## MuxedHLSStream ### Description Represents an HLS stream that has been muxed. ### Class streamlink.stream.hls.MuxedHLSStream ``` -------------------------------- ### DASH Stream Class Source: https://github.com/streamlink/streamlink/blob/master/docs/api/stream.rst Represents a stream using the Dynamic Adaptive Streaming over HTTP (DASH) protocol. ```APIDOC ## DASHStream ### Description Represents a stream using the Dynamic Adaptive Streaming over HTTP (DASH) protocol. ### Class streamlink.stream.dash.DASHStream ``` -------------------------------- ### Validate Sequence Items with Schema Source: https://github.com/streamlink/streamlink/blob/master/docs/api/validate.rst Use Schema([item_schemas]) to validate sequences like lists, tuples, sets, and frozensets. Each item in the input value must be validated against any of the provided item schemas. This differs from ListSchema and raises ValidationError for type mismatches or extra items. ```python schema = validate.Schema([1, 2, 3]) assert schema.validate([]) == [] assert schema.validate([1, 2]) == [1, 2] assert schema.validate([3, 2, 1]) == [3, 2, 1] schema.validate({1, 2, 3}) # raises ValidationError schema.validate([1, 2, 3, 4]) # raises ValidationError ``` -------------------------------- ### Muxed Stream Class Source: https://github.com/streamlink/streamlink/blob/master/docs/api/stream.rst Represents a stream that has been muxed, typically with audio and video components combined. ```APIDOC ## MuxedStream ### Description Represents a stream that has been muxed, typically with audio and video components combined. ### Class streamlink.stream.ffmpegmux.MuxedStream ``` -------------------------------- ### StreamlinkError Source: https://github.com/streamlink/streamlink/blob/master/docs/api/exceptions.rst The base exception class for all Streamlink-specific errors. ```APIDOC ## StreamlinkError ### Description Base exception for all Streamlink errors. ### Exception `streamlink.exceptions.StreamlinkError` ``` -------------------------------- ### _validate_sequence Source: https://github.com/streamlink/streamlink/blob/master/docs/api/validate.rst Validates lists, tuples, sets, and frozensets. Each item in the value is validated against any of the items in the schema sequence. ```APIDOC ## _validate_sequence ### Description List, tuple, set and frozenset validation. Each item of ``value`` gets validated against **any** of the items of ``schema``. Please note the difference between :class:`list ` and the :class:`ListSchema <_schemas.ListSchema>` validation. ### Parameters #### Path Parameters - **schema** (Union[list, tuple, set, frozenset]) - Required - A sequence of validation schemas - **value** (Any) - Required - The input value ### Response #### Success Response (200) - **value** (Any) - A new sequence of the same type as ``schema`` with each item of ``value`` being validated ### Request Example ```python schema = validate.Schema([1, 2, 3]) assert schema.validate([]) == [] assert schema.validate([1, 2]) == [1, 2] assert schema.validate([3, 2, 1]) == [3, 2, 1] schema.validate({1, 2, 3}) # raises ValidationError schema.validate([1, 2, 3, 4]) # raises ValidationError ``` ### Response Example ```json { "example": "[1, 2]" } ``` *Note: This function is included for documentation purposes only! (singledispatch overload)* ```