0
# Options and Configuration
1

2
Streamlink's options system provides flexible configuration for HTTP behavior, stream preferences, and plugin settings. The system supports default values, type validation, and getter/setter mappings for advanced option handling.
3

4
## Capabilities
5

6
### Options Base Class
7

8
The core Options class provides key-value storage with defaults and automatic key normalization.
9

10
```python { .api }
11
class Options(dict):
12
    def __init__(self, defaults=None):
13
        """
14
        Initialize options with optional defaults.
15
        
16
        Parameters:
17
        - defaults: Dictionary of default option values
18
        
19
        Note: Option keys are normalized by replacing "_" with "-"
20
        """
21

22
    def get(self, key: str):
23
        """
24
        Get option value with getter mapping support.
25
        
26
        Parameters:
27
        - key: Option name (normalized automatically)
28
        
29
        Returns:
30
        Option value after applying any getter mapping
31
        """
32

33
    def set(self, key: str, value) -> None:
34
        """
35
        Set option value with setter mapping support.
36
        
37
        Parameters:
38
        - key: Option name (normalized automatically)  
39
        - value: Option value (processed by setter mapping if defined)
40
        """
41

42
    def update(self, options) -> None:
43
        """
44
        Update multiple options from dict, Mapping, or Options instance.
45
        
46
        Parameters:
47
        - options: Source of option updates
48
        """
49

50
    def clear(self) -> None:
51
        """Reset all options to their default values"""
52

53
    @property
54
    def defaults(self) -> dict:
55
        """Dictionary of default option values"""
56
```
57

58
### Streamlink Session Options
59

60
The `StreamlinkOptions` class extends `Options` with mappings for Streamlink-specific configuration.
61

62
Key option categories include:
63

64
**HTTP Configuration:**
65
- `http-proxy` - HTTP/HTTPS proxy URL
66
- `http-timeout` - Request timeout in seconds  
67
- `http-headers` - Dictionary of HTTP headers
68
- `http-cookies` - Cookie jar or cookie dictionary
69
- `http-ssl-verify` - SSL certificate verification
70
- `http-disable-dh` - Disable Diffie-Hellman key exchange
71

72
**Stream Configuration:**
73
- `stream-timeout` - Stream read timeout
74
- `stream-retry-max` - Maximum retry attempts
75
- `stream-retry-open` - Retry attempts for opening streams
76
- `hls-timeout` - HLS segment timeout
77
- `hls-segment-attempts` - HLS segment retry attempts
78
- `dash-manifest-reload-attempts` - DASH manifest reload attempts
79

80
**Network Configuration:**
81
- `ipv4` - Force IPv4 connections
82
- `ipv6` - Force IPv6 connections  
83
- `interface` - Network interface to bind to
84

85
**Plugin Configuration:**
86
- `plugin-dir` - Additional plugin directories
87
- `plugin-timeout` - Plugin execution timeout
88

89
### Argument Classes
90

91
Classes for defining command-line arguments with validation and type conversion.
92

93
```python { .api }
94
class Argument:
95
    """
96
    Definition of a command-line argument with validation.
97
    
98
    Supports all argparse.ArgumentParser.add_argument() parameters
99
    plus additional validation and transformation options.
100
    """
101

102
class Arguments:
103
    """
104
    Collection of Argument instances for command-line parsing.
105
    
106
    Provides methods for adding arguments and generating
107
    argparse-compatible argument definitions.
108
    """
109
```
110

111
## Usage Examples
112

113
### Basic Options Usage
114

115
```python
116
from streamlink.options import Options
117

118
# Create options with defaults
119
opts = Options({
120
    'timeout': 30,
121
    'retries': 3,
122
    'quality': 'best'
123
})
124

125
# Get values
126
timeout = opts.get('timeout')  # 30
127
retries = opts.get('retries')   # 3
128

129
# Set values (key normalization)
130
opts.set('max_retries', 5)     # Same as 'max-retries'
131
opts.set('max-retries', 5)     # Direct key
132

133
# Update multiple options
134
opts.update({
135
    'timeout': 60,
136
    'user_agent': 'Custom Agent'
137
})
138

139
# Reset to defaults
140
opts.clear()
141
```
142

143
### Session Options Configuration
144

145
```python
146
import streamlink
147

148
session = streamlink.Streamlink()
149

150
# HTTP configuration
151
session.set_option('http-timeout', 30)
152
session.set_option('http-headers', {
153
    'User-Agent': 'Custom Streamlink Client',
154
    'Referer': 'https://example.com'
155
})
156

157
# Proxy configuration  
158
session.set_option('http-proxy', 'http://proxy.example.com:8080')
159

160
# SSL configuration
161
session.set_option('http-ssl-verify', False)  # Disable SSL verification
162

163
# Stream configuration
164
session.set_option('stream-timeout', 60)
165
session.set_option('hls-timeout', 30)
166
session.set_option('stream-retry-max', 5)
167

168
# Quality preferences
169
session.set_option('stream-sorting-excludes', ['audio_only', '160p'])
170

171
# Get current options
172
timeout = session.get_option('http-timeout')
173
headers = session.get_option('http-headers')
174
```
175

176
### Advanced HTTP Configuration
177

178
```python
179
import requests
180

181
session = streamlink.Streamlink()
182

183
# Configure HTTP session with custom settings
184
session.set_option('http-timeout', 45)
185
session.set_option('http-headers', {
186
    'User-Agent': 'Mozilla/5.0 (compatible; Streamlink)',
187
    'Accept-Language': 'en-US,en;q=0.9'
188
})
189

190
# Cookie handling
191
cookie_jar = requests.cookies.RequestsCookieJar()
192
cookie_jar.set('session_id', 'abc123', domain='example.com')
193
session.set_option('http-cookies', cookie_jar)
194

195
# SSL configuration for problematic sites
196
session.set_option('http-ssl-verify', '/path/to/custom/ca-bundle.crt')
197
session.set_option('http-ssl-cert', ('/path/to/client.crt', '/path/to/client.key'))
198

199
# Network interface binding
200
session.set_option('interface', '192.168.1.100')  # Bind to specific IP
201
```
202

203
### Stream Quality Configuration
204

205
```python
206
session = streamlink.Streamlink()
207

208
# Stream sorting and filtering
209
session.set_option('stream-sorting-excludes', [
210
    'audio_only',    # Exclude audio-only streams
211
    '160p', '240p'   # Exclude low-quality streams
212
])
213

214
# HLS-specific options
215
session.set_option('hls-segment-stream-data', True)
216
session.set_option('hls-segment-attempts', 3)
217
session.set_option('hls-segment-timeout', 10)
218
session.set_option('hls-timeout', 60)
219

220
# DASH-specific options  
221
session.set_option('dash-manifest-reload-attempts', 3)
222

223
# Retry configuration
224
session.set_option('stream-retry-max', 5)
225
session.set_option('stream-retry-open', 3)
226
```
227

228
### Plugin-Specific Options
229

230
```python
231
# Set options that plugins can access
232
session.set_option('twitch-disable-ads', True)
233
session.set_option('youtube-api-key', 'your-api-key')
234
session.set_option('http-headers', {
235
    'X-Custom-Header': 'value'
236
})
237

238
# Options with validation and transformation
239
from streamlink.options import Options
240

241
plugin_opts = Options({
242
    'quality': 'best',
243
    'username': None,
244
    'password': None
245
})
246

247
# Plugin can access these through self.options
248
plugin_opts.set('quality', '720p')
249
plugin_opts.set('username', 'user@example.com')
250
```
251

252
### Custom Options with Validation
253

254
```python
255
from streamlink.options import Options
256

257
class CustomOptions(Options):
258
    # Custom getter mapping
259
    _MAP_GETTERS = {
260
        'custom-timeout': lambda self, key: max(1, self.get(key, 30))
261
    }
262
    
263
    # Custom setter mapping  
264
    _MAP_SETTERS = {
265
        'custom-timeout': lambda self, key, value: setattr(self, key, int(value))
266
    }
267

268
# Usage
269
opts = CustomOptions({'custom-timeout': 15})
270
opts.set('custom-timeout', '45')  # Converted to int
271
timeout = opts.get('custom-timeout')  # Minimum value enforced
272
```
273

274
### Options in Configuration Files
275

276
```python
277
# Load options from configuration file
278
import json
279

280
with open('streamlink_config.json') as f:
281
    config = json.load(f)
282

283
session = streamlink.Streamlink()
284

285
# Apply configuration
286
for key, value in config.items():
287
    session.set_option(key, value)
288

289
# Example config file format:
290
config_example = {
291
    "http-timeout": 30,
292
    "http-headers": {
293
        "User-Agent": "Custom Client"
294
    },
295
    "stream-retry-max": 3,
296
    "hls-segment-attempts": 5
297
}
298
```
299

300
### Environment Variable Integration
301

302
```python
303
import os
304

305
session = streamlink.Streamlink()
306

307
# Use environment variables for sensitive options
308
if os.getenv('HTTP_PROXY'):
309
    session.set_option('http-proxy', os.getenv('HTTP_PROXY'))
310

311
if os.getenv('STREAMLINK_HTTP_TIMEOUT'):
312
    session.set_option('http-timeout', int(os.getenv('STREAMLINK_HTTP_TIMEOUT')))
313

314
# Plugin credentials from environment
315
twitch_token = os.getenv('TWITCH_OAUTH_TOKEN')
316
if twitch_token:
317
    session.set_option('twitch-oauth-token', twitch_token)
318
```