1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
Metadata
========
Variables
---------
Streamlink supports a number of metadata variables that can be used in the following CLI arguments:
- :option:`--title`
- :option:`--output`
- :option:`--record`
- :option:`--record-and-pipe`
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
(:ref:`check the metadata availability of each plugin here <plugins:Plugins>`). 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
(:option:`--title`) or an empty string (:option:`--output`, :option:`--record`, :option:`--record-and-pipe`).
**Conditional variables**
.. list-table::
:header-rows: 1
:class: table-custom-layout table-custom-layout-platform-locations
* - 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**
.. list-table::
:header-rows: 1
:class: table-custom-layout table-custom-layout-platform-locations
* - Variable
- Description
* - ``plugin``
- The name of the resolved plugin. See :ref:`Plugins <plugins: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``.
.. _datetime.strftime(): https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes
Examples
--------
.. code-block:: console
$ streamlink --title "{author} - {category} - {title}" <URL> [STREAM]
$ streamlink --output "~/recordings/{author}/{category}/{id}-{time:%Y%m%d%H%M%S}.ts" <URL> [STREAM]
The :option:`--json` argument always lists the conditional metadata.
.. code-block:: console
$ streamlink --json twitch.tv/bobross | jq .metadata
.. code-block:: json
{
"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.
|
