0
# Stream Access
1

2
Streamlink provides multiple stream types for different protocols and use cases. All streams inherit from the base `Stream` class and provide methods for opening connections and accessing stream data.
3

4
## Capabilities
5

6
### Base Stream Class
7

8
The abstract base class that all stream types inherit from.
9

10
```python { .api }
11
class Stream:
12
    def __init__(self, session):
13
        """
14
        Initialize stream with Streamlink session.
15
        
16
        Parameters:
17
        - session: Streamlink session instance
18
        """
19

20
    def open(self) -> StreamIO:
21
        """
22
        Open stream connection for reading.
23
        
24
        Returns:
25
        StreamIO object for data access
26
        
27
        Raises:
28
        StreamError: If stream cannot be opened
29
        """
30

31
    def to_url(self) -> str:
32
        """
33
        Convert stream to direct URL if supported.
34
        
35
        Returns:
36
        Direct stream URL
37
        
38
        Raises:
39
        TypeError: If stream type doesn't support URL conversion
40
        """
41

42
    def to_manifest_url(self) -> str:
43
        """
44
        Convert stream to manifest URL if supported.
45
        
46
        Returns:
47
        Manifest URL (e.g., M3U8 or MPD)
48
        
49
        Raises:
50
        TypeError: If stream type doesn't support manifest URLs
51
        """
52

53
    @classmethod
54
    def shortname(cls) -> str:
55
        """
56
        Get stream type identifier.
57
        
58
        Returns:
59
        Short name identifying the stream type
60
        """
61

62
    @property
63
    def json(self) -> str:
64
        """JSON representation of stream metadata"""
65
```
66

67
### Stream I/O Base Class
68

69
Base class for stream data access with file-like interface.
70

71
```python { .api }
72
class StreamIO:
73
    """Base class for stream I/O operations with file-like interface"""
74
```
75

76
### HTTP Streams
77

78
Direct HTTP streams for simple video/audio files served over HTTP.
79

80
```python { .api }
81
class HTTPStream(Stream):
82
    def __init__(self, session, url, buffered=True, **kwargs):
83
        """
84
        Initialize HTTP stream.
85
        
86
        Parameters:
87
        - session: Streamlink session
88
        - url: HTTP URL to stream
89
        - buffered: Whether to use buffered I/O (default: True)
90
        - **kwargs: Additional request arguments (headers, params, etc.)
91
        """
92

93
    @property
94
    def url(self) -> str:
95
        """Prepared request URL"""
96

97
    @property  
98
    def args(self) -> dict:
99
        """Request arguments dictionary"""
100
```
101

102
### HLS Streams
103

104
HTTP Live Streaming (HLS) support for adaptive bitrate streaming.
105

106
```python { .api }
107
class HLSStream(Stream):
108
    """
109
    HTTP Live Streaming implementation supporting:
110
    - M3U8 playlist parsing
111
    - Adaptive bitrate streaming  
112
    - AES encryption
113
    - Subtitle tracks
114
    """
115

116
class MuxedHLSStream(Stream):
117
    """
118
    HLS stream combining multiple tracks (video, audio, subtitles).
119
    
120
    Automatically muxes separate video and audio streams into
121
    a single output stream using FFmpeg.
122
    """
123
```
124

125
### DASH Streams
126

127
Dynamic Adaptive Streaming over HTTP for modern adaptive streaming.
128

129
```python { .api }
130
class DASHStream(Stream):
131
    """
132
    DASH (Dynamic Adaptive Streaming over HTTP) implementation supporting:
133
    - MPD manifest parsing
134
    - Multi-period content
135
    - Multiple representations
136
    - Audio/video track selection
137
    """
138
```
139

140
### Muxed Streams
141

142
Generic muxed streams combining multiple input streams using FFmpeg.
143

144
```python { .api }
145
class MuxedStream(Stream):
146
    def __init__(self, session, *substreams, **options):
147
        """
148
        Combine multiple streams into a single output.
149
        
150
        Parameters:
151
        - session: Streamlink session
152
        - *substreams: Input streams to mux together
153
        - **options: FFmpeg options and stream mapping
154
        """
155
```
156

157
### Stream Wrappers
158

159
Utility classes for adapting different data sources to the StreamIO interface.
160

161
```python { .api }
162
class StreamIOWrapper:
163
    """Wraps non-IOBase file-like objects to provide consistent interface"""
164

165
class StreamIOIterWrapper:
166
    """Wraps iterators as file-like objects for streaming data"""
167

168
class StreamIOThreadWrapper:
169
    """Adds threading support to stream I/O operations"""
170
```
171

172
## Usage Examples
173

174
### Basic Stream Access
175

176
```python
177
import streamlink
178

179
# Get streams for a URL
180
streams = streamlink.streams("https://www.twitch.tv/example")
181

182
if streams:
183
    # Access best quality stream
184
    best_stream = streams['best']
185
    print(f"Stream type: {best_stream.shortname()}")
186
    
187
    # Open stream for reading
188
    with best_stream.open() as stream_fd:
189
        # Read first 1KB
190
        data = stream_fd.read(1024)
191
        print(f"Read {len(data)} bytes")
192
```
193

194
### Stream Quality Selection
195

196
```python
197
streams = streamlink.streams("https://example.com/stream")
198

199
# Check available qualities
200
print("Available streams:")
201
for quality, stream in streams.items():
202
    print(f"  {quality}: {stream}")
203

204
# Select specific quality
205
if '720p' in streams:
206
    selected_stream = streams['720p']
207
elif 'best' in streams:
208
    selected_stream = streams['best']
209
else:
210
    print("No suitable stream found")
211
```
212

213
### HTTP Stream Usage
214

215
```python
216
from streamlink.stream import HTTPStream
217

218
session = streamlink.Streamlink()
219

220
# Create HTTP stream with custom headers
221
http_stream = HTTPStream(
222
    session, 
223
    "https://example.com/video.mp4",
224
    headers={'Referer': 'https://example.com'}
225
)
226

227
# Get direct URL
228
try:
229
    direct_url = http_stream.to_url()
230
    print(f"Direct URL: {direct_url}")
231
except TypeError:
232
    print("Stream doesn't support direct URL access")
233

234
# Read stream data
235
with http_stream.open() as fd:
236
    chunk = fd.read(8192)
237
    while chunk:
238
        # Process chunk
239
        process_data(chunk)
240
        chunk = fd.read(8192)
241
```
242

243
### HLS Stream Features
244

245
```python
246
streams = streamlink.streams("https://example.com/hls_stream")
247

248
for quality, stream in streams.items():
249
    if hasattr(stream, 'to_manifest_url'):
250
        try:
251
            manifest_url = stream.to_manifest_url()
252
            print(f"{quality}: {manifest_url}")
253
        except TypeError:
254
            pass
255
```
256

257
### Muxed Stream Creation
258

259
```python
260
from streamlink.stream import MuxedStream
261

262
# Assuming we have separate video and audio streams
263
video_stream = streams.get('720p_video')
264
audio_stream = streams.get('audio_en')
265

266
if video_stream and audio_stream:
267
    # Create muxed stream
268
    muxed = MuxedStream(
269
        session,
270
        video_stream,
271
        audio_stream,
272
        format='mp4',
273
        acodec='aac',
274
        vcodec='h264'
275
    )
276
    
277
    with muxed.open() as fd:
278
        # Process combined stream
279
        data = fd.read(1024)
280
```
281

282
### Stream Type Detection
283

284
```python
285
streams = streamlink.streams("https://example.com")
286

287
for quality, stream in streams.items():
288
    stream_type = stream.shortname()
289
    
290
    if stream_type == 'hls':
291
        print(f"{quality}: HLS stream")
292
    elif stream_type == 'dash':  
293
        print(f"{quality}: DASH stream")
294
    elif stream_type == 'http':
295
        print(f"{quality}: HTTP stream")
296
    elif stream_type == 'muxed':
297
        print(f"{quality}: Muxed stream")
298
```