0
# Stream Processing
1

2
Advanced stream manipulation including concatenation, splitting, trimming, timestamp adjustment, and custom filter application for complex multimedia workflows.
3

4
## Capabilities
5

6
### Stream Concatenation
7

8
Join multiple video and audio streams together sequentially.
9

10
```python { .api }
11
def concat(*streams, **kwargs) -> Stream:
12
    """
13
    Concatenate audio and video streams, joining them one after another.
14
    
15
    Parameters:
16
    - *streams: Stream objects to concatenate
17
    - v: int, number of video streams per segment (default: 1)
18
    - a: int, number of audio streams per segment (default: 0)
19
    - n: int, number of segments (automatically calculated)
20
    - unsafe: bool, do not fail if segments have different formats
21
    
22
    Returns:
23
    Stream object with concatenated content
24
    
25
    Note: All segments must start at timestamp 0 and have the same
26
    parameters (resolution, codec settings, etc.)
27
    """
28
```
29

30
**Usage Example:**
31
```python
32
# Concatenate video clips
33
clip1 = ffmpeg.input('part1.mp4')
34
clip2 = ffmpeg.input('part2.mp4')
35
clip3 = ffmpeg.input('part3.mp4')
36

37
concatenated = ffmpeg.concat(clip1, clip2, clip3)
38

39
# Concatenate with both video and audio
40
concatenated_av = ffmpeg.concat(
41
    clip1.video, clip1.audio,
42
    clip2.video, clip2.audio,
43
    v=1, a=1
44
)
45

46
# Mixed content concatenation
47
video_only = ffmpeg.concat(
48
    ffmpeg.input('clip1.mp4'),
49
    ffmpeg.input('clip2.mp4'), 
50
    ffmpeg.input('clip3.mp4')
51
)
52
```
53

54
### Stream Splitting
55

56
Split single streams into multiple identical streams for parallel processing.
57

58
```python { .api }
59
def split(stream) -> FilterNode:
60
    """
61
    Split video stream into multiple identical streams.
62
    
63
    Parameters:
64
    - stream: Stream, input video stream to split
65
    
66
    Returns:
67
    FilterNode that can generate multiple output streams
68
    """
69

70
def asplit(stream) -> FilterNode:
71
    """
72
    Split audio stream into multiple identical streams.
73
    
74
    Parameters:
75
    - stream: Stream, input audio stream to split
76
    
77
    Returns:
78
    FilterNode that can generate multiple output streams
79
    """
80
```
81

82
**Usage Example:**
83
```python
84
input_stream = ffmpeg.input('input.mp4')
85

86
# Split video for multiple outputs
87
split_video = input_stream.video.split()
88
stream1 = split_video.stream(0)  # First copy
89
stream2 = split_video.stream(1)  # Second copy
90

91
# Process each copy differently
92
processed1 = stream1.hflip()
93
processed2 = stream2.vflip()
94

95
# Multiple outputs
96
output1 = ffmpeg.output(processed1, 'flipped_h.mp4')
97
output2 = ffmpeg.output(processed2, 'flipped_v.mp4')
98
```
99

100
### Stream Trimming
101

102
Extract specific time ranges from input streams.
103

104
```python { .api }
105
def trim(stream, **kwargs) -> Stream:
106
    """
107
    Trim input to contain one continuous subpart.
108
    
109
    Parameters:
110
    - stream: Stream, input stream to trim
111
    - start: str/float, start time in seconds
112
    - end: str/float, end time in seconds
113
    - start_pts: int, start timestamp in timebase units
114
    - end_pts: int, end timestamp in timebase units
115
    - duration: str/float, maximum duration in seconds
116
    - start_frame: int, first frame number to include
117
    - end_frame: int, first frame number to exclude
118
    
119
    Returns:
120
    Stream object with specified time range
121
    """
122
```
123

124
**Usage Example:**
125
```python
126
# Trim by time (seconds)
127
trimmed = ffmpeg.input('long_video.mp4').trim(start=30, duration=60)
128

129
# Trim by frame numbers
130
frame_trimmed = ffmpeg.input('video.mp4').trim(start_frame=100, end_frame=500)
131

132
# Trim with precise timestamps
133
precise_trim = ffmpeg.input('video.mp4').trim(
134
    start='00:01:30.500',
135
    end='00:02:45.750'
136
)
137
```
138

139
### Timestamp Manipulation
140

141
Adjust presentation timestamps for synchronization and timing control.
142

143
```python { .api }
144
def setpts(stream, expr: str) -> Stream:
145
    """
146
    Change presentation timestamp (PTS) of input frames.
147
    
148
    Parameters:
149
    - stream: Stream, input stream to modify
150
    - expr: str, expression evaluated for each frame timestamp
151
    
152
    Returns:
153
    Stream object with modified timestamps
154
    
155
    Common expressions:
156
    - 'PTS-STARTPTS': Reset timestamps to start from zero
157
    - '0.5*PTS': Double playback speed (half duration)
158
    - '2.0*PTS': Half playback speed (double duration)
159
    - 'PTS+10/TB': Add 10 timebase units delay
160
    """
161
```
162

163
**Usage Example:**
164
```python
165
# Reset timestamps to start from zero
166
reset_pts = ffmpeg.input('video.mp4').setpts('PTS-STARTPTS')
167

168
# Double playback speed
169
fast_video = ffmpeg.input('video.mp4').setpts('0.5*PTS')
170

171
# Slow motion (half speed)
172
slow_video = ffmpeg.input('video.mp4').setpts('2.0*PTS')
173

174
# Complex timing adjustment
175
delayed = ffmpeg.input('video.mp4').setpts('PTS+5/TB')
176
```
177

178
### Custom Filters
179

180
Apply any FFmpeg filter with custom parameters when specific filter functions are not available.
181

182
```python { .api }
183
def filter(stream_spec, filter_name: str, *args, **kwargs) -> Stream:
184
    """
185
    Apply custom FFmpeg filter with one output.
186
    
187
    Parameters:
188
    - stream_spec: Stream, list of Streams, or label-to-Stream dictionary
189
    - filter_name: str, FFmpeg filter name
190
    - *args: positional arguments passed to FFmpeg verbatim
191
    - **kwargs: keyword arguments passed to FFmpeg verbatim
192
    
193
    Returns:
194
    Stream object with filter applied
195
    """
196

197
def filter_(stream_spec, filter_name: str, *args, **kwargs) -> Stream:
198
    """
199
    Alternate name for filter() to avoid collision with Python built-in.
200
    
201
    Same parameters and behavior as filter().
202
    """
203

204
def filter_multi_output(stream_spec, filter_name: str, *args, **kwargs) -> FilterNode:
205
    """
206
    Apply custom FFmpeg filter that can produce multiple outputs.
207
    
208
    Parameters:
209
    - stream_spec: Stream, list of Streams, or label-to-Stream dictionary  
210
    - filter_name: str, FFmpeg filter name
211
    - *args: positional arguments passed to FFmpeg verbatim
212
    - **kwargs: keyword arguments passed to FFmpeg verbatim
213
    
214
    Returns:
215
    FilterNode that can generate multiple output streams
216
    """
217
```
218

219
**Usage Example:**
220
```python
221
# Apply custom filter with parameters
222
blurred = ffmpeg.input('input.mp4').filter('boxblur', '10:1')
223

224
# Complex custom filter
225
sharpened = ffmpeg.input('input.mp4').filter(
226
    'unsharp', 
227
    luma_msize_x=5,
228
    luma_msize_y=5,
229
    luma_amount=1.5
230
)
231

232
# Multi-output filter
233
input_stream = ffmpeg.input('input.mp4')
234
histogram = input_stream.filter_multi_output('histogram')
235
hist_video = histogram.stream(0)
236
hist_data = histogram.stream(1)
237

238
# Using filter_ to avoid name collision
239
filtered = ffmpeg.input('input.mp4').filter_('scale', 640, 480)
240
```
241

242
## Advanced Stream Processing Patterns
243

244
### Complex Filter Graphs
245

246
```python
247
# Create complex processing pipeline
248
input_video = ffmpeg.input('input.mp4')
249

250
# Split for parallel processing  
251
split_node = input_video.split()
252
stream_a = split_node.stream(0)
253
stream_b = split_node.stream(1)
254

255
# Process each stream differently
256
processed_a = stream_a.hflip().filter('blur', '5')
257
processed_b = stream_b.vflip().filter('sharpen', '1')
258

259
# Concatenate processed streams
260
final = ffmpeg.concat(processed_a, processed_b)
261
```
262

263
### Time-based Processing
264

265
```python
266
# Extract specific scenes and process
267
scene1 = ffmpeg.input('movie.mp4').trim(start=0, duration=30)
268
scene2 = ffmpeg.input('movie.mp4').trim(start=120, duration=45)
269
scene3 = ffmpeg.input('movie.mp4').trim(start=300, duration=60)
270

271
# Process each scene
272
enhanced_scene1 = scene1.filter('eq', brightness=0.1)
273
enhanced_scene2 = scene2.hue(s=1.2)
274
enhanced_scene3 = scene3.filter('unsharp', '5:5:1.0')
275

276
# Combine into highlight reel
277
highlights = ffmpeg.concat(enhanced_scene1, enhanced_scene2, enhanced_scene3)
278
```
279

280
### Stream Synchronization
281

282
```python
283
# Synchronize audio and video streams
284
video = ffmpeg.input('video.mp4').video.setpts('PTS-STARTPTS')
285
audio = ffmpeg.input('audio.mp3').audio.filter('asetpts', 'PTS-STARTPTS')
286

287
# Combine synchronized streams
288
synchronized = ffmpeg.output(video, audio, 'synced.mp4')
289
```