0
# Streamlink
1
2
A command-line utility and Python library for extracting video streams from various streaming services (Twitch, YouTube, etc.) and piping them into video players. Streamlink provides a plugin-based architecture that allows easy addition of support for new streaming services, advanced stream quality selection, and both CLI and API interfaces for different use cases.
3
4
## Package Information
5
6
- **Package Name**: streamlink
7
- **Language**: Python
8
- **Installation**: `pip install streamlink`
9
- **Requirements**: Python >= 3.9
10
11
## Core Imports
12
13
```python
14
import streamlink
15
```
16
17
Common for direct stream extraction:
18
19
```python
20
from streamlink import streams
21
```
22
23
For advanced usage with sessions:
24
25
```python
26
from streamlink import Streamlink
27
```
28
29
## Basic Usage
30
31
```python
32
import streamlink
33
34
# Simple stream extraction using the convenience function
35
url = "https://www.twitch.tv/example_channel"
36
streams_dict = streamlink.streams(url)
37
38
# Select best quality stream
39
if streams_dict:
40
best_stream = streams_dict['best']
41
print(f"Stream URL: {best_stream.url}")
42
43
# Open stream for reading
44
with best_stream.open() as stream_io:
45
data = stream_io.read(1024)
46
print(f"Read {len(data)} bytes")
47
48
# Advanced usage with session configuration
49
session = streamlink.Streamlink()
50
session.set_option('http-timeout', 30)
51
session.set_option('http-headers', {'User-Agent': 'My Custom Agent'})
52
53
streams_dict = session.streams(url)
54
```
55
56
## Architecture
57
58
Streamlink's architecture centers around these key components:
59
60
- **Session**: The main `Streamlink` class manages plugins, HTTP sessions, and configuration options
61
- **Plugins**: Extensible plugin system with URL pattern matching for different streaming services
62
- **Streams**: Different stream types (HTTP, HLS, DASH, Muxed) handle various streaming protocols
63
- **Options**: Flexible configuration system with validation and type checking
64
- **Validation**: Schema-based validation system for parsing and data validation
65
66
This design allows Streamlink to support hundreds of streaming services through a unified interface while providing both simple convenience functions and advanced customization capabilities.
67
68
## Capabilities
69
70
### Session Management
71
72
Central session management for configuring HTTP behavior, plugin loading, and stream extraction. The `Streamlink` class coordinates all operations and maintains state across plugin interactions.
73
74
```python { .api }
75
class Streamlink:
76
def __init__(self, options=None, *, plugins_builtin=True, plugins_lazy=True): ...
77
def set_option(self, key: str, value): ...
78
def get_option(self, key: str): ...
79
def resolve_url(self, url: str, follow_redirect=True): ...
80
def resolve_url_no_redirect(self, url: str): ...
81
def streams(self, url: str, options=None, **params): ...
82
83
# Properties
84
@property
85
def version(self): ...
86
@property
87
def localization(self): ...
88
89
# Session attributes
90
http: HTTPSession
91
options: StreamlinkOptions
92
plugins: StreamlinkPlugins
93
94
class StreamlinkOptions(Options): ...
95
96
def streams(url: str, **params):
97
"""Convenience function using default session"""
98
```
99
100
[Session Management](./session-management.md)
101
102
### Stream Access
103
104
Multiple stream types supporting different protocols including HTTP streams, HLS (HTTP Live Streaming), DASH (Dynamic Adaptive Streaming), and muxed streams combining multiple tracks.
105
106
```python { .api }
107
class Stream:
108
def open(self): ...
109
def to_url(self): ...
110
111
class StreamIO(io.IOBase): ...
112
113
class HTTPStream(Stream):
114
def __init__(self, session, url, buffered=True, **kwargs): ...
115
116
class HLSStream(Stream): ...
117
class MuxedHLSStream(Stream): ...
118
class DASHStream(Stream): ...
119
class MuxedStream(Stream):
120
def __init__(self, session, *substreams, **options): ...
121
122
# Stream IO Wrappers
123
class StreamIOWrapper: ...
124
class StreamIOIterWrapper(StreamIOWrapper): ...
125
class StreamIOThreadWrapper(StreamIOWrapper): ...
126
```
127
128
[Stream Access](./stream-access.md)
129
130
### Plugin System
131
132
Extensible plugin architecture for adding support for new streaming services. Plugins use decorators to define URL patterns and command-line arguments.
133
134
```python { .api }
135
class Plugin:
136
def __init__(self, session, url, options=None): ...
137
def streams(self, stream_types=None, sorting_excludes=None): ...
138
139
def pluginmatcher(pattern, priority=20, name=None): ...
140
def pluginargument(name, **kwargs): ...
141
142
# Plugin configuration classes
143
class PluginArguments: ...
144
class PluginOptions(Options): ...
145
146
# Priority constants
147
HIGH_PRIORITY = 30
148
NORMAL_PRIORITY = 20
149
LOW_PRIORITY = 10
150
NO_PRIORITY = 0
151
```
152
153
[Plugin System](./plugin-system.md)
154
155
### Options and Configuration
156
157
Flexible options system for configuring HTTP behavior, stream preferences, and plugin settings with getter/setter mappings and validation.
158
159
```python { .api }
160
class Options(dict):
161
def __init__(self, defaults=None): ...
162
def get(self, key: str): ...
163
def set(self, key: str, value): ...
164
def update(self, options): ...
165
def clear(self): ...
166
```
167
168
[Options and Configuration](./options-configuration.md)
169
170
### Data Validation
171
172
Schema-based validation system for parsing HTML, JSON, XML and validating data structures with combinators and type-specific validators.
173
174
```python { .api }
175
def validate(obj, schema): ...
176
177
# Schema combinators
178
def all(*schemas): ...
179
def any(*schemas): ...
180
def none_or_all(*schemas): ...
181
def optional(schema): ...
182
def transform(func, *schemas): ...
183
def list(schema): ...
184
def union(*schemas): ...
185
def union_get(*schemas): ...
186
def regex(pattern, **kwargs): ...
187
def xml_element(tag=None, **kwargs): ...
188
189
# Data access validators
190
def attr(attr, schema, default=None): ...
191
def get(item, schema, default=None): ...
192
193
# String validators
194
def contains(item): ...
195
def startswith(prefix): ...
196
def endswith(suffix): ...
197
def length(min_len, max_len=None): ...
198
def getattr(attr, default=None): ...
199
def hasattr(attr): ...
200
def filter(func): ...
201
def map(func): ...
202
203
# Parsing validators
204
def url(**kwargs): ...
205
def parse_html(**kwargs): ...
206
def parse_json(**kwargs): ...
207
def parse_xml(**kwargs): ...
208
def parse_qsd(**kwargs): ...
209
210
# XML validators
211
def xml_find(tag): ...
212
def xml_findall(tag): ...
213
def xml_findtext(tag): ...
214
def xml_xpath(expression): ...
215
def xml_xpath_string(expression): ...
216
```
217
218
[Data Validation](./data-validation.md)
219
220
### Utilities
221
222
URL manipulation, parsing utilities, caching, and system integration functions for common operations in plugin development.
223
224
```python { .api }
225
# URL utilities
226
def absolute_url(base, url): ...
227
def update_qsd(url, **params): ...
228
def update_scheme(scheme, url, force=False): ...
229
230
# Parsing utilities
231
def parse_html(data, **kwargs): ...
232
def parse_json(data, **kwargs): ...
233
def search_dict(obj, key): ...
234
235
# System utilities
236
class NamedPipe: ...
237
class LRUCache: ...
238
```
239
240
[Utilities](./utilities.md)
241
242
## Exception Hierarchy
243
244
```python { .api }
245
class StreamlinkError(Exception): ...
246
class PluginError(StreamlinkError): ...
247
class FatalPluginError(PluginError): ...
248
class NoPluginError(StreamlinkError): ...
249
class NoStreamsError(StreamlinkError): ...
250
class StreamError(StreamlinkError): ...
251
class StreamlinkWarning(UserWarning): ...
252
class StreamlinkDeprecationWarning(StreamlinkWarning): ...
253
```
254
255
All Streamlink-specific exceptions inherit from `StreamlinkError`, allowing for comprehensive error handling in applications using the library.