0
# Pipeline API
1

2
High-level streaming interface that simplifies RealSense camera usage by providing automatic device selection, stream configuration, and synchronized frame delivery. The Pipeline API is the recommended entry point for most applications.
3

4
## Capabilities
5

6
### Pipeline
7

8
Main streaming interface that manages device lifecycle and provides coherent framesets.
9

10
```python { .api }
11
class pipeline:
12
    def __init__(context=None):
13
        """
14
        Create a pipeline for streaming.
15
        
16
        Args:
17
            context (context, optional): Custom context for device management
18
        """
19
    
20
    def start() -> pipeline_profile:
21
        """
22
        Start streaming with default configuration.
23
        
24
        Returns:
25
            pipeline_profile: Active pipeline configuration
26
        """
27
    
28
    def start(config) -> pipeline_profile:
29
        """
30
        Start streaming with specified configuration.
31
        
32
        Args:
33
            config (config): Stream configuration
34
            
35
        Returns:
36
            pipeline_profile: Active pipeline configuration
37
        """
38
    
39
    def start(callback_function) -> pipeline_profile:
40
        """
41
        Start streaming with frame callback.
42
        
43
        Args:
44
            callback_function: Function called for each frameset
45
            
46
        Returns:
47
            pipeline_profile: Active pipeline configuration
48
        """
49
    
50
    def start(config, callback_function) -> pipeline_profile:
51
        """
52
        Start streaming with configuration and callback.
53
        
54
        Args:
55
            config (config): Stream configuration
56
            callback_function: Function called for each frameset
57
            
58
        Returns:
59
            pipeline_profile: Active pipeline configuration
60
        """
61
    
62
    def start(frame_queue) -> pipeline_profile:
63
        """
64
        Start streaming into a frame queue.
65
        
66
        Args:
67
            frame_queue (frame_queue): Queue for frame buffering
68
            
69
        Returns:
70
            pipeline_profile: Active pipeline configuration
71
        """
72
    
73
    def start(config, frame_queue) -> pipeline_profile:
74
        """
75
        Start streaming with configuration into frame queue.
76
        
77
        Args:
78
            config (config): Stream configuration
79
            frame_queue (frame_queue): Queue for frame buffering
80
            
81
        Returns:
82
            pipeline_profile: Active pipeline configuration
83
        """
84
    
85
    def stop():
86
        """Stop streaming and release resources."""
87
    
88
    def wait_for_frames(timeout_ms=5000) -> frameset:
89
        """
90
        Wait for the next set of coherent frames.
91
        
92
        Args:
93
            timeout_ms (int): Maximum wait time in milliseconds
94
            
95
        Returns:
96
            frameset: Synchronized frames from all active streams
97
            
98
        Raises:
99
            rs.error: If timeout expires or device error occurs
100
        """
101
    
102
    def poll_for_frames() -> frameset:
103
        """
104
        Try to get the next frameset without blocking.
105
        
106
        Returns:
107
            frameset: Available frames or None if no frames ready
108
        """
109
    
110
    def try_wait_for_frames(timeout_ms=5000) -> tuple[bool, frameset]:
111
        """
112
        Try to wait for frames with timeout.
113
        
114
        Args:
115
            timeout_ms (int): Maximum wait time in milliseconds
116
            
117
        Returns:
118
            tuple: (success, frameset) - success indicates if frames were obtained
119
        """
120
    
121
    def get_active_profile() -> pipeline_profile:
122
        """
123
        Get the currently active pipeline configuration.
124
        
125
        Returns:
126
            pipeline_profile: Current configuration
127
        """
128
    
129
    def set_device(device):
130
        """
131
        Set a specific device for the pipeline to use.
132
        
133
        Args:
134
            device (device): Device to use for streaming
135
        """
136
```
137

138
### Configuration
139

140
Stream and device configuration for pipeline.
141

142
```python { .api }
143
class config:
144
    def enable_stream(stream_type):
145
        """
146
        Enable stream with default parameters.
147
        
148
        Args:
149
            stream_type (stream): Stream type to enable
150
        """
151
    
152
    def enable_stream(stream_type, stream_index):
153
        """
154
        Enable specific stream instance.
155
        
156
        Args:
157
            stream_type (stream): Stream type
158
            stream_index (int): Stream index for multi-instance streams
159
        """
160
    
161
    def enable_stream(stream_type, format, framerate):
162
        """
163
        Enable stream with format and framerate.
164
        
165
        Args:
166
            stream_type (stream): Stream type
167
            format (format): Data format
168
            framerate (int): Frames per second
169
        """
170
    
171
    def enable_stream(stream_type, width, height, format, framerate):
172
        """
173
        Enable video stream with full parameters.
174
        
175
        Args:
176
            stream_type (stream): Stream type
177
            width (int): Frame width in pixels
178
            height (int): Frame height in pixels
179
            format (format): Data format
180
            framerate (int): Frames per second
181
        """
182
    
183
    def enable_stream(stream_type, stream_index, width, height, format, framerate):
184
        """
185
        Enable specific video stream instance with full parameters.
186
        
187
        Args:
188
            stream_type (stream): Stream type
189
            stream_index (int): Stream index for multi-instance streams
190
            width (int): Frame width in pixels
191
            height (int): Frame height in pixels
192
            format (format): Data format
193
            framerate (int): Frames per second
194
        """
195
    
196
    def enable_all_streams():
197
        """Enable all available streams with default parameters."""
198
    
199
    def disable_stream(stream_type, index=-1):
200
        """
201
        Disable specific stream.
202
        
203
        Args:
204
            stream_type (stream): Stream type to disable
205
            index (int): Stream index (-1 for all instances)
206
        """
207
    
208
    def disable_all_streams():
209
        """Disable all previously enabled streams."""
210
    
211
    def enable_device(serial_number):
212
        """
213
        Specify device to use by serial number.
214
        
215
        Args:
216
            serial_number (str): Device serial number
217
        """
218
    
219
    def enable_device_from_file(filename, repeat_playback=True):
220
        """
221
        Enable playback from recorded file.
222
        
223
        Args:
224
            filename (str): Path to recorded .bag file
225
            repeat_playback (bool): Loop playback when file ends
226
        """
227
    
228
    def enable_record_to_file(filename):
229
        """
230
        Enable recording to file.
231
        
232
        Args:
233
            filename (str): Output .bag file path
234
        """
235
    
236
    def resolve(pipeline) -> pipeline_profile:
237
        """
238
        Resolve configuration against pipeline.
239
        
240
        Args:
241
            pipeline (pipeline): Pipeline to resolve against
242
            
243
        Returns:
244
            pipeline_profile: Resolved configuration
245
            
246
        Raises:
247
            rs.error: If configuration cannot be resolved
248
        """
249
    
250
    def can_resolve(pipeline) -> bool:
251
        """
252
        Check if configuration can be resolved.
253
        
254
        Args:
255
            pipeline (pipeline): Pipeline to check against
256
            
257
        Returns:
258
            bool: True if configuration is valid
259
        """
260
```
261

262
### Pipeline Profile
263

264
Active pipeline configuration and device information.
265

266
```python { .api }
267
class pipeline_profile:
268
    def get_streams() -> list[stream_profile]:
269
        """
270
        Get all active stream profiles.
271
        
272
        Returns:
273
            list[stream_profile]: Active stream configurations
274
        """
275
    
276
    def get_stream(stream_type, stream_index=-1) -> stream_profile:
277
        """
278
        Get specific stream profile.
279
        
280
        Args:
281
            stream_type (stream): Stream type
282
            stream_index (int): Stream index (-1 for any)
283
            
284
        Returns:
285
            stream_profile: Stream configuration
286
            
287
        Raises:
288
            rs.error: If stream not found
289
        """
290
    
291
    def get_device() -> device:
292
        """
293
        Get the device used by this pipeline.
294
        
295
        Returns:
296
            device: Associated device
297
        """
298
```
299

300
## Usage Examples
301

302
### Basic Depth Streaming
303

304
```python
305
import pyrealsense2 as rs
306
import numpy as np
307

308
# Create pipeline and configure depth stream
309
pipeline = rs.pipeline()
310
config = rs.config()
311
config.enable_stream(rs.stream.depth, 640, 480, rs.format.z16, 30)
312

313
# Start streaming
314
profile = pipeline.start(config)
315

316
try:
317
    for _ in range(100):
318
        frames = pipeline.wait_for_frames()
319
        depth_frame = frames.get_depth_frame()
320
        
321
        if not depth_frame:
322
            continue
323
            
324
        # Convert to numpy array
325
        depth_data = np.asanyarray(depth_frame.get_data())
326
        
327
        # Process depth data
328
        print(f"Frame {depth_frame.get_frame_number()}: "
329
              f"Mean depth = {np.mean(depth_data)} units")
330
              
331
finally:
332
    pipeline.stop()
333
```
334

335
### Multi-Stream Configuration
336

337
```python
338
import pyrealsense2 as rs
339

340
pipeline = rs.pipeline()
341
config = rs.config()
342

343
# Enable multiple streams
344
config.enable_stream(rs.stream.depth, 640, 480, rs.format.z16, 30)
345
config.enable_stream(rs.stream.color, 640, 480, rs.format.bgr8, 30)
346
config.enable_stream(rs.stream.infrared, 1, 640, 480, rs.format.y8, 30)
347
config.enable_stream(rs.stream.infrared, 2, 640, 480, rs.format.y8, 30)
348

349
# Start with configuration
350
profile = pipeline.start(config)
351

352
# Get device info
353
device = profile.get_device()
354
print(f"Using device: {device.get_info(rs.camera_info.name)}")
355

356
try:
357
    while True:
358
        frames = pipeline.wait_for_frames()
359
        
360
        depth = frames.get_depth_frame()
361
        color = frames.get_color_frame()
362
        ir1 = frames.get_infrared_frame(1)
363
        ir2 = frames.get_infrared_frame(2)
364
        
365
        if depth and color and ir1 and ir2:
366
            print(f"Got complete frameset at {frames.get_timestamp()}")
367
            
368
finally:
369
    pipeline.stop()
370
```
371

372
### Asynchronous Processing with Callback
373

374
```python
375
import pyrealsense2 as rs
376
import threading
377

378
frame_count = 0
379
frame_lock = threading.Lock()
380

381
def frame_callback(frames):
382
    global frame_count
383
    with frame_lock:
384
        frame_count += 1
385
        if frame_count % 30 == 0:  # Print every second at 30fps
386
            depth = frames.get_depth_frame()
387
            if depth:
388
                print(f"Processed {frame_count} framesets")
389

390
pipeline = rs.pipeline()
391
config = rs.config()
392
config.enable_stream(rs.stream.depth, 640, 480, rs.format.z16, 30)
393

394
# Start with callback
395
pipeline.start(config, frame_callback)
396

397
try:
398
    # Let it run for 10 seconds
399
    time.sleep(10)
400
finally:
401
    pipeline.stop()
402
```
403

404
### Recording Session
405

406
```python
407
import pyrealsense2 as rs
408

409
pipeline = rs.pipeline()
410
config = rs.config()
411

412
# Configure streams and recording
413
config.enable_stream(rs.stream.depth, 640, 480, rs.format.z16, 30)
414
config.enable_stream(rs.stream.color, 640, 480, rs.format.bgr8, 30)
415
config.enable_record_to_file("session.bag")
416

417
# Start recording
418
pipeline.start(config)
419

420
try:
421
    for i in range(300):  # Record 10 seconds at 30fps
422
        frames = pipeline.wait_for_frames()
423
        print(f"Recording frame {i}")
424
finally:
425
    pipeline.stop()
426
    print("Recording saved to session.bag")
427
```
428

429
### Playback from File
430

431
```python
432
import pyrealsense2 as rs
433

434
# Configure playback
435
config = rs.config()
436
config.enable_device_from_file("session.bag", repeat_playback=False)
437

438
pipeline = rs.pipeline()
439
profile = pipeline.start(config)
440

441
# Get playback device
442
device = profile.get_device()
443
playback = device.as_playback()
444

445
print(f"Playing back {playback.file_name()}")
446
print(f"Duration: {playback.get_duration() / 1e9:.1f} seconds")
447

448
try:
449
    while True:
450
        frames = pipeline.wait_for_frames()
451
        depth = frames.get_depth_frame()
452
        
453
        if depth:
454
            timestamp = frames.get_timestamp()
455
            print(f"Playback timestamp: {timestamp / 1000:.3f}s")
456
            
457
except rs.error:
458
    print("Playback finished")
459
finally:
460
    pipeline.stop()
461
```
462

463
## Common Patterns
464

465
### Error Handling
466

467
```python
468
import pyrealsense2 as rs
469

470
pipeline = rs.pipeline()
471
config = rs.config()
472

473
try:
474
    # Attempt to configure streams
475
    config.enable_stream(rs.stream.depth, 1920, 1080, rs.format.z16, 60)  # May not be supported
476
    
477
    # Check if configuration is valid
478
    if config.can_resolve(pipeline):
479
        profile = pipeline.start(config)
480
    else:
481
        print("Configuration not supported, using defaults")
482
        profile = pipeline.start()
483
        
484
except rs.error as e:
485
    print(f"RealSense error: {e}")
486
    # Fallback to safe configuration
487
    config.disable_all_streams()
488
    config.enable_stream(rs.stream.depth)  # Use defaults
489
    profile = pipeline.start(config)
490
```
491

492
### Device Selection
493

494
```python
495
import pyrealsense2 as rs
496

497
# Discover available devices
498
ctx = rs.context()
499
devices = ctx.query_devices()
500

501
if len(devices) == 0:
502
    print("No RealSense devices found")
503
    exit()
504

505
# Use specific device
506
device = devices[0]
507
serial = device.get_info(rs.camera_info.serial_number)
508

509
config = rs.config()
510
config.enable_device(serial)
511
config.enable_stream(rs.stream.depth)
512

513
pipeline = rs.pipeline()
514
pipeline.start(config)
515
```