Motivation

The plugin matrix is and always has been a total mess.

• https://github.com/streamlink/streamlink/blame/3.1.1/docs/plugin_matrix.rst
• https://streamlink.github.io/plugin_matrix.html

The table that's defined via restructured-text is ugly, restrictive, limited in space and requires footnote workarounds for long URLs. Adding new entries is always cumbersome and prone to errors, and with the usage of the Furo theme for the rendered HTML docs, the navigation menu on the right is also completely empty, as it relies on sections and subsections in the document content. A table is not the right fit for this.

Lots of valuable info is also missing, like proper plugin descriptions/introductions, or other things like the type of returned streams and what not.

Solution

A solution which I've had on the radar for a long time now would be having a mandatory block comment at the top of each plugin file which contains annotations for all this plugin metadata. The static table could then be replaced by a custom sphinx extension which parses the AST of each plugin file and yields ReST sections for each plugin with a short datalist generated from the available metadata in the header block comment, similar to the datalist here, except without line breaks:
https://streamlink.github.io/applications.html

This would enable a navigation via the sidebar on the right (due to the sections) and listing multiple/long URLs would be much easier without having to rely on workarounds (due to the datalists). And the most important thing is that the space limitation of the table would be gone (due to datalists and an arbitrary number of entries - no columns anymore).

A dynamically generated plugins page from parsed plugin ASTs could also link to each plugin's CLI arguments without having to specify them in the metadata.

Plugin metadata format

How would this header block comment look like? The annotation format should not conflict with other already existing formats, so this is what I would suggest:

"""
$key value
$key value
$key value
"""

import ...

The parser could then simply split the comment via this regex:

\n\$([a-z]+) ([^\n]+)

Metadata fields

The plugin matrix currently has the "name", "urls", "live", "vod", and "notes" columns. Since we're not bound to a certain number of columns with this, we can organize this a bit differently.

• description (required, needs to be defined first)
  A short plugin description, eg. some kind of platform name or a name for a TV/news network, etc.
• url (required, can be set multiple times)
  One of the supported URLs. Similar to the current style of the plugin matrix, so no scheme or paths (if not required otherwise)
• type (required)
  Must be either live, vod or live, vod
• region (optional)
  A list of countries/regions (separated by comma), or "various"
• account (optional)
  A short description when an account or subscription is needed
• notes (optional, needs to be defined last)
  A short text with additional notes/hints

Alternatives:

• info instead of description, as it's shorter
• Have separate live and vod fields with value "Yes" or "No"
• authentication instead of account, as "account" doesn't always fit the description

I've already moved all the metadata from the table of the plugin matrix to each plugin file in my local repo, but before I continue with this and start writing the parser, I need to open this thread and ask for a format which we can agree on.

Another issue is that almost no plugin currently has the "description" text which I defined as mandatory above, so I'd suggest that this should be added later. I surely don't want to look up all this now.

The tests also need to get updated, as well as the "developing" page in the docs.