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

Metadata¶

Variables¶

Streamlink supports a number of metadata variables that can be used in the following CLI arguments:

Metadata variables are surrounded by curly braces and can be escaped by doubling the curly brace characters, e.g. {variable} and {{not-a-variable}}.

Warning

The availability of each variable depends on the used plugin and whether that plugin supports this kind of metadata (check the metadata availability of each plugin here). Be aware that depending on the stream, certain metadata might not be available (yet), despite the plugin's implementation.

If no metadata is available for a specific variable, then its substitution will either be a short placeholder text (--title) or an empty string (--output, --record, --record-and-pipe).

Conditional variables

Variable	Description
`id`	The unique ID of the stream, e.g. an internal numeric ID or randomized string.
`author`	The stream's author, e.g. a channel or broadcaster name.
`category`	The stream's category, e.g. the name of a game being played, a music genre, etc.
`game`	Alias for `category`.
`title`	The stream's title, usually a short descriptive text.

Generic variables

Variable	Description
`plugin`	The name of the resolved plugin. See Plugins for the name of each built-in plugin.
`url`	The resolved URL of the stream.
`time`	The current timestamp. Can optionally be formatted via `{time:format}`. The format parameter string is passed to Python's datetime.strftime() method, so all the usual time directives are available. The default format is `%Y-%m-%d_%H-%M-%S`.

Variable

Description

plugin

The name of the resolved plugin. See Plugins for the name of each built-in plugin.

url

The resolved URL of the stream.

time

The current timestamp. Can optionally be formatted via {time:format}.

The format parameter string is passed to Python's datetime.strftime() method, so all the usual time directives are available.

The default format is %Y-%m-%d_%H-%M-%S.

Examples¶

$ streamlink --title "{author} - {category} - {title}" <URL> [STREAM]
$ streamlink --output "~/recordings/{author}/{category}/{id}-{time:%Y%m%d%H%M%S}.ts" <URL> [STREAM]

The --json argument always lists the conditional metadata.

$ streamlink --json twitch.tv/bobross | jq .metadata

{
  "id": "49163597677",
  "author": "BobRoss",
  "category": "Art",
  "title": "A Happy Little Weekend Marathon!"
}

Note

Streamlink is not designed as a tool for general-purpose metadata retrieval. If your goal is to extract metadata from specific streaming sites, then it's usually a better idea to implement this metadata retrieval yourself using the available APIs of those sites or other means.