0
# Input and Output Operations
1

2
Core functionality for creating input streams from media files, URLs, or pipes, and defining output destinations with format specifications and encoding parameters.
3

4
## Capabilities
5

6
### Input Stream Creation
7

8
Create input streams from media files, URLs, devices, or pipes. Supports format specification, input options, and FFmpeg input parameters.
9

10
```python { .api }
11
def input(filename: str, **kwargs) -> Stream:
12
    """
13
    Input file URL (ffmpeg -i option).
14
    
15
    Parameters:
16
    - filename: str, input file path, URL, or 'pipe:' for stdin
17
    - f: str, input format (alias for 'format')
18
    - format: str, input format specification
19
    - video_size: tuple, video dimensions for raw input (width, height)
20
    - t: str/int/float, duration to read from input
21
    - ss: str/int/float, start time offset
22
    - r: str/int/float, input frame rate
23
    - Any other FFmpeg input options as keyword arguments
24
    
25
    Returns:
26
    Stream object representing the input
27
    """
28
```
29

30
**Usage Example:**
31
```python
32
# Basic file input
33
input_stream = ffmpeg.input('video.mp4')
34

35
# Input with format and options
36
raw_input = ffmpeg.input('pipe:', format='rawvideo', pix_fmt='rgb24', s='640x480')
37

38
# Input with time range
39
trimmed_input = ffmpeg.input('long_video.mp4', ss=30, t=60)  # Start at 30s, duration 60s
40
```
41

42
### Output Stream Creation
43

44
Create output streams with destination files, encoding parameters, and output format specifications.
45

46
```python { .api }
47
def output(*streams_and_filename, **kwargs) -> Stream:
48
    """
49
    Output file URL.
50
    
51
    Parameters:
52
    - *streams_and_filename: Stream objects followed by output filename
53
    - filename: str, output file path or 'pipe:' for stdout
54
    - f: str, output format (alias for 'format')
55
    - format: str, output format specification
56
    - video_bitrate: int, video bitrate (-b:v parameter)
57
    - audio_bitrate: int, audio bitrate (-b:a parameter)
58
    - video_size: str/tuple, output video dimensions
59
    - vcodec: str, video codec
60
    - acodec: str, audio codec
61
    - Any other FFmpeg output options as keyword arguments
62
    
63
    Returns:
64
    Stream object representing the output
65
    """
66
```
67

68
**Usage Example:**
69
```python
70
# Single stream output
71
stream = ffmpeg.input('input.mp4').hflip()
72
output = ffmpeg.output(stream, 'output.mp4')
73

74
# Multiple streams to single output
75
video = ffmpeg.input('video.mp4').video
76
audio = ffmpeg.input('audio.mp3').audio
77
output = ffmpeg.output(video, audio, 'combined.mp4')
78

79
# Output with encoding parameters
80
output = ffmpeg.output(
81
    stream, 
82
    'output.mp4',
83
    vcodec='libx264',
84
    acodec='aac',
85
    video_bitrate=1000,
86
    audio_bitrate=128
87
)
88
```
89

90
### Multiple Output Management
91

92
Merge multiple outputs into a single FFmpeg command to improve efficiency and avoid temporary files.
93

94
```python { .api }
95
def merge_outputs(*streams) -> Stream:
96
    """
97
    Include all given outputs in one ffmpeg command line.
98
    
99
    Parameters:
100
    - *streams: OutputStream objects to merge
101
    
102
    Returns:
103
    Stream object representing merged outputs
104
    """
105
```
106

107
**Usage Example:**
108
```python
109
input_stream = ffmpeg.input('input.mp4')
110

111
# Create multiple outputs
112
output1 = ffmpeg.output(input_stream.video, 'video_only.mp4')
113
output2 = ffmpeg.output(input_stream.audio, 'audio_only.mp3')
114
output3 = ffmpeg.output(input_stream, 'copy.mp4')
115

116
# Merge into single command
117
merged = ffmpeg.merge_outputs(output1, output2, output3)
118
ffmpeg.run(merged)
119
```
120

121
### Global Command Options
122

123
Add global FFmpeg command-line arguments that apply to the entire command.
124

125
```python { .api }
126
def overwrite_output(stream) -> Stream:
127
    """
128
    Overwrite output files without asking (ffmpeg -y option).
129
    
130
    Parameters:
131
    - stream: OutputStream to modify
132
    
133
    Returns:
134
    Stream object with overwrite flag
135
    """
136

137
def global_args(stream, *args) -> Stream:
138
    """
139
    Add extra global command-line arguments.
140
    
141
    Parameters:
142
    - stream: OutputStream to modify
143
    - *args: Global arguments to add
144
    
145
    Returns:
146
    Stream object with global arguments
147
    """
148
```
149

150
**Usage Example:**
151
```python
152
# Overwrite existing output files
153
stream = (
154
    ffmpeg
155
    .input('input.mp4')
156
    .output('output.mp4')
157
    .overwrite_output()
158
)
159

160
# Add custom global arguments
161
stream = (
162
    ffmpeg
163
    .input('input.mp4')
164
    .output('output.mp4')
165
    .global_args('-progress', 'progress.txt', '-loglevel', 'debug')
166
)
167
```
168

169
## Common Patterns
170

171
### Pipe-based Processing
172

173
```python
174
# Read from stdin, write to stdout
175
(
176
    ffmpeg
177
    .input('pipe:', format='rawvideo', pix_fmt='rgb24', s='640x480')
178
    .output('pipe:', format='rawvideo', pix_fmt='yuv420p')
179
    .run(pipe_stdin=True, pipe_stdout=True)
180
)
181
```
182

183
### Format Conversion
184

185
```python
186
# Convert between formats
187
(
188
    ffmpeg
189
    .input('input.avi')
190
    .output('output.mp4', vcodec='libx264', acodec='aac')
191
    .run()
192
)
193
```
194

195
### Quality Control
196

197
```python
198
# High quality encoding
199
(
200
    ffmpeg
201
    .input('input.mp4')
202
    .output(
203
        'high_quality.mp4',
204
        vcodec='libx264',
205
        video_bitrate=5000,
206
        acodec='aac',
207
        audio_bitrate=320
208
    )
209
    .run()
210
)
211
```