0
# Session Management
1

2
The Streamlink session system provides centralized management of plugins, HTTP configuration, and stream extraction. The `Streamlink` class is the primary interface for advanced usage, while the `streams()` convenience function provides simple access for basic use cases.
3

4
## Capabilities
5

6
### Streamlink Session Class
7

8
The main session class that coordinates plugin loading, URL resolution, and stream extraction with configurable options.
9

10
```python { .api }
11
class Streamlink:
12
    def __init__(self, options=None, *, plugins_builtin=True, plugins_lazy=True):
13
        """
14
        Initialize a new Streamlink session.
15
        
16
        Parameters:
17
        - options: Custom options dict, Mapping, or Options instance
18
        - plugins_builtin: Whether to load built-in plugins (default: True)
19
        - plugins_lazy: Load built-in plugins lazily for faster startup (default: True)
20
        """
21
```
22

23
The session manages three key components accessible as properties:
24

25
```python { .api }
26
@property
27
def http(self) -> HTTPSession:
28
    """HTTPSession instance for HTTP requests"""
29

30
@property  
31
def options(self) -> StreamlinkOptions:
32
    """Session options with getter/setter mappings"""
33

34
@property
35
def plugins(self) -> StreamlinkPlugins:
36
    """Plugin management and loading"""
37

38
@property
39
def version(self) -> str:
40
    """Package version string"""
41

42
@property
43
def localization(self) -> Localization:
44
    """Localization instance for language support"""
45
```
46

47
### Option Management
48

49
Configure session behavior through the options system with validation and type checking.
50

51
```python { .api }
52
def set_option(self, key: str, value) -> None:
53
    """
54
    Set a session option.
55
    
56
    Parameters:
57
    - key: Option name (underscores converted to hyphens)
58
    - value: Option value with type validation
59
    """
60

61
def get_option(self, key: str):
62
    """
63
    Get current option value.
64
    
65
    Parameters:
66
    - key: Option name
67
    
68
    Returns:
69
    Current option value or None if not set
70
    """
71
```
72

73
### URL Resolution
74

75
Resolve URLs to matching plugins for stream extraction.
76

77
```python { .api }
78
def resolve_url(self, url: str, follow_redirect: bool = True) -> tuple[str, type[Plugin], str]:
79
    """
80
    Find a plugin that can handle the given URL.
81
    
82
    Parameters:
83
    - url: URL to resolve (https:// added if no scheme)
84
    - follow_redirect: Whether to follow HTTP redirects (default: True)
85
    
86
    Returns:
87
    Tuple of (plugin_name, plugin_class, resolved_url)
88
    
89
    Raises:
90
    NoPluginError: If no plugin matches the URL
91
    """
92

93
def resolve_url_no_redirect(self, url: str) -> tuple[str, type[Plugin], str]:
94
    """
95
    Find a plugin without following redirects.
96
    
97
    Parameters:
98
    - url: URL to resolve
99
    
100
    Returns:
101
    Tuple of (plugin_name, plugin_class, resolved_url)
102
    
103
    Raises:
104
    NoPluginError: If no plugin matches the URL
105
    """
106
```
107

108
### Stream Extraction
109

110
Extract streams from URLs using the resolved plugin.
111

112
```python { .api }
113
def streams(self, url: str, options=None, **params) -> dict[str, Stream]:
114
    """
115
    Extract streams from URL using matched plugin.
116
    
117
    Parameters:
118
    - url: URL to extract streams from
119
    - options: Optional Options instance for the plugin
120
    - **params: Additional parameters passed to plugin.streams()
121
    
122
    Returns:
123
    Dictionary mapping quality names to Stream instances
124
    
125
    Raises:
126
    NoPluginError: If no plugin matches URL
127
    PluginError: If plugin fails to extract streams
128
    """
129
```
130

131
### Convenience Function
132

133
Simple stream extraction without explicit session management.
134

135
```python { .api }
136
def streams(url: str, **params) -> dict[str, Stream]:
137
    """
138
    Extract streams using a default Streamlink session.
139
    
140
    Parameters:
141
    - url: URL to extract streams from  
142
    - **params: Parameters passed to session.streams()
143
    
144
    Returns:
145
    Dictionary mapping quality names to Stream instances
146
    
147
    Raises:
148
    NoPluginError: If no plugin matches URL
149
    """
150
```
151

152
## Usage Examples
153

154
### Basic Session Usage
155

156
```python
157
from streamlink import Streamlink
158

159
# Create session with custom options
160
session = Streamlink()
161
session.set_option('http-timeout', 30)
162
session.set_option('http-headers', {
163
    'User-Agent': 'My Custom User Agent'
164
})
165

166
# Configure stream preferences
167
session.set_option('stream-timeout', 60)
168
session.set_option('hls-timeout', 60)
169

170
# Extract streams
171
url = "https://www.twitch.tv/example"
172
streams_dict = session.streams(url)
173

174
if streams_dict:
175
    print("Available streams:")
176
    for quality, stream in streams_dict.items():
177
        print(f"  {quality}: {stream}")
178
```
179

180
### URL Resolution
181

182
```python
183
session = Streamlink()
184

185
try:
186
    plugin_name, plugin_class, resolved_url = session.resolve_url(
187
        "https://www.youtube.com/watch?v=example"
188
    )
189
    print(f"Matched plugin: {plugin_name}")
190
    print(f"Resolved URL: {resolved_url}")
191
except streamlink.NoPluginError:
192
    print("No plugin found for this URL")
193
```
194

195
### Plugin Loading Control
196

197
```python
198
# Create session without built-in plugins
199
session = Streamlink(plugins_builtin=False)
200

201
# Load plugins manually
202
session.plugins.load_builtin()
203

204
# Load custom plugins from directory
205
session.plugins.load_path("/path/to/custom/plugins")
206

207
# Check loaded plugins
208
loaded = session.plugins.get_loaded()
209
print(f"Loaded {len(loaded)} plugins")
210
```