0
# Format Handling (Muxing/Demuxing)
1

2
Container format operations for reading and writing media files with support for all major formats including MP4, AVI, MKV, MOV, WebM, and streaming protocols.
3

4
## Capabilities
5

6
### Input Format Operations
7

8
#### Opening Input Files
9

10
```java { .api }
11
/**
12
 * Open an input stream and read the header
13
 * @param ps Pointer to user-allocated AVFormatContext
14
 * @param filename Name of stream/file to open, or null for default
15
 * @param fmt Input format to use, or null for auto-detection
16
 * @param options Dictionary of options
17
 * @return 0 on success, negative AVERROR on failure
18
 */
19
int avformat_open_input(@ByPtrPtr AVFormatContext ps, String filename, AVInputFormat fmt, @ByPtrPtr AVDictionary options);
20

21
/**
22
 * Read packets of a media file to get stream information
23
 * @param ic Media file handle
24
 * @param options Dictionary of options
25
 * @return >= 0 if OK, AVERROR_xxx on error
26
 */
27
int avformat_find_stream_info(AVFormatContext ic, PointerPointer options);
28

29
/**
30
 * Close an opened input AVFormatContext
31
 * @param s Pointer to AVFormatContext to close
32
 */
33
void avformat_close_input(@ByPtrPtr AVFormatContext s);
34
```
35

36
**Usage Example:**
37

38
```java
39
import org.bytedeco.ffmpeg.avformat.*;
40
import static org.bytedeco.ffmpeg.global.avformat.*;
41

42
AVFormatContext formatContext = new AVFormatContext(null);
43

44
// Open input file
45
int result = avformat_open_input(formatContext, "input.mp4", null, null);
46
if (result < 0) {
47
    throw new RuntimeException("Cannot open input file");
48
}
49

50
// Analyze streams
51
result = avformat_find_stream_info(formatContext, (PointerPointer)null);
52
if (result < 0) {
53
    throw new RuntimeException("Cannot find stream information");
54
}
55

56
// Print format information
57
av_dump_format(formatContext, 0, "input.mp4", 0);
58

59
// Cleanup
60
avformat_close_input(formatContext);
61
```
62

63
### Output Format Operations
64

65
#### Creating Output Files
66

67
```java { .api }
68
/**
69
 * Allocate an AVFormatContext for an output format
70
 * @param ctx Pointer to receive the allocated context
71
 * @param oformat Format to use for allocating the context
72
 * @param format_name Format name if oformat is null
73
 * @param filename Filename to use for context if oformat is null
74
 * @return >= 0 in case of success, negative AVERROR code in case of failure
75
 */
76
int avformat_alloc_output_context2(@ByPtrPtr AVFormatContext ctx, AVOutputFormat oformat, 
77
    String format_name, String filename);
78

79
/**
80
 * Add a new stream to a media file
81
 * @param s Media file context
82
 * @param c Codec context (deprecated, pass null)
83
 * @return New stream, or null on error
84
 */
85
AVStream avformat_new_stream(AVFormatContext s, AVCodec c);
86

87
/**
88
 * Allocate the stream private data and write the stream header
89
 * @param s Media file context
90
 * @param options Dictionary of options
91
 * @return 0 on success, negative AVERROR on failure
92
 */
93
int avformat_write_header(AVFormatContext s, PointerPointer options);
94

95
/**
96
 * Write the stream trailer and free the file private data
97
 * @param s Media file context
98
 * @return 0 if OK, AVERROR_xxx on error
99
 */
100
int av_write_trailer(AVFormatContext s);
101
```
102

103
**Usage Example:**
104

105
```java
106
AVFormatContext outputContext = new AVFormatContext(null);
107

108
// Allocate output context
109
int result = avformat_alloc_output_context2(outputContext, null, null, "output.mp4");
110
if (result < 0) {
111
    throw new RuntimeException("Cannot allocate output context");
112
}
113

114
// Add video stream
115
AVStream videoStream = avformat_new_stream(outputContext, null);
116
if (videoStream == null) {
117
    throw new RuntimeException("Cannot create video stream");
118
}
119

120
// Set up codec parameters
121
videoStream.codecpar().codec_type(AVMEDIA_TYPE_VIDEO);
122
videoStream.codecpar().codec_id(AV_CODEC_ID_H264);
123
videoStream.codecpar().width(1920);
124
videoStream.codecpar().height(1080);
125

126
// Open output file
127
if ((outputContext.oformat().flags() & AVFMT_NOFILE) == 0) {
128
    AVIOContext ioContext = new AVIOContext(null);
129
    result = avio_open(ioContext, "output.mp4", AVIO_FLAG_WRITE);
130
    if (result < 0) {
131
        throw new RuntimeException("Cannot open output file");
132
    }
133
    outputContext.pb(ioContext);
134
}
135

136
// Write header
137
result = avformat_write_header(outputContext, (PointerPointer)null);
138
if (result < 0) {
139
    throw new RuntimeException("Cannot write header");
140
}
141

142
// Write frames (not shown)
143

144
// Finalize
145
av_write_trailer(outputContext);
146
avformat_free_context(outputContext);
147
```
148

149
### Packet Operations
150

151
#### Reading and Writing Packets
152

153
```java { .api }
154
/**
155
 * Return the next frame of a stream
156
 * @param s Media file context
157
 * @param pkt Packet to fill with data
158
 * @return 0 if OK, < 0 on error or end of file
159
 */
160
int av_read_frame(AVFormatContext s, AVPacket pkt);
161

162
/**
163
 * Write a packet to output media file
164
 * @param s Media file context
165
 * @param pkt Packet to write
166
 * @return < 0 on error, 0 on success
167
 */
168
int av_write_frame(AVFormatContext s, AVPacket pkt);
169

170
/**
171
 * Write a packet to output media file ensuring correct interleaving
172
 * @param s Media file context  
173
 * @param pkt Packet to write
174
 * @return < 0 on error, 0 on success
175
 */
176
int av_interleaved_write_frame(AVFormatContext s, AVPacket pkt);
177

178
/**
179
 * Seek to keyframe at timestamp
180
 * @param s Media file context
181
 * @param stream_index Stream index (-1 for default)
182
 * @param timestamp Target timestamp
183
 * @param flags Seek flags
184
 * @return >= 0 on success
185
 */
186
int av_seek_frame(AVFormatContext s, int stream_index, long timestamp, int flags);
187
```
188

189
### Stream Information
190

191
#### Accessing Stream Data
192

193
```java { .api }
194
/**
195
 * AVFormatContext stream access
196
 */
197
class AVFormatContext extends Pointer {
198
    /** Number of streams in the file */
199
    int nb_streams();
200
    
201
    /** Array of streams */
202
    PointerPointer streams();
203
    
204
    /** Input format information */
205
    AVInputFormat iformat();
206
    
207
    /** Output format information */  
208
    AVOutputFormat oformat();
209
    
210
    /** File duration in AV_TIME_BASE units */
211
    long duration();
212
    
213
    /** Total stream bitrate */
214
    long bit_rate();
215
    
216
    /** Metadata dictionary */
217
    AVDictionary metadata();
218
}
219

220
/**
221
 * Individual stream information
222
 */
223
class AVStream extends Pointer {
224
    /** Stream index in AVFormatContext.streams[] */
225
    int index();
226
    
227
    /** Stream ID */
228
    int id();
229
    
230
    /** Codec parameters */
231
    AVCodecParameters codecpar();
232
    
233
    /** Time base for stream timestamps */
234
    AVRational time_base();
235
    
236
    /** Stream duration in time_base units */
237
    long duration();
238
    
239
    /** Number of frames if known */
240
    long nb_frames();
241
    
242
    /** Stream metadata */
243
    AVDictionary metadata();
244
}
245
```
246

247
### Format Detection
248

249
#### Input Format Discovery
250

251
```java { .api }
252
/**
253
 * Guess file format based on filename
254
 * @param filename Filename to analyze
255
 * @param mime_type MIME type (optional)
256
 * @return Detected input format or null
257
 */
258
AVInputFormat av_find_input_format(String short_name);
259

260
/**
261
 * Probe input format from data
262
 * @param pd Probe data containing buffer and filename
263
 * @param is_opened Whether file is already opened
264
 * @return Probe score (higher = more likely)
265
 */
266
int av_probe_input_format(AVProbeData pd, int is_opened);
267

268
/**
269
 * Get list of all supported input formats
270
 * @return Iterator for input formats
271
 */
272
AVInputFormat av_demuxer_iterate(Pointer opaque);
273

274
/**
275
 * Get list of all supported output formats  
276
 * @return Iterator for output formats
277
 */
278
AVOutputFormat av_muxer_iterate(Pointer opaque);
279
```
280

281
### I/O Context Operations
282

283
#### Custom I/O Handling
284

285
```java { .api }
286
/**
287
 * Allocate and initialize an AVIOContext for buffered I/O
288
 * @param s Pointer to receive allocated context
289
 * @param url URL to open
290
 * @param flags Access flags (AVIO_FLAG_READ, AVIO_FLAG_WRITE)
291
 * @return >= 0 on success
292
 */
293
int avio_open(AVIOContext s, String url, int flags);
294

295
/**
296
 * Close AVIOContext and free resources
297
 * @param s Pointer to AVIOContext to close
298
 * @return 0 on success
299
 */
300
int avio_closep(AVIOContext s);
301

302
/**
303
 * Create custom I/O context
304
 * @param buffer User-allocated buffer
305
 * @param buffer_size Buffer size
306
 * @param write_flag 1 for write, 0 for read
307
 * @param opaque User data pointer
308
 * @param read_packet Custom read function
309
 * @param write_packet Custom write function
310
 * @param seek Custom seek function
311
 * @return Allocated AVIOContext
312
 */
313
AVIOContext avio_alloc_context(BytePointer buffer, int buffer_size, int write_flag,
314
    Pointer opaque, Read_packet_Pointer_BytePointer_int read_packet,
315
    Write_packet_Pointer_BytePointer_int write_packet, 
316
    Seek_Pointer_long_int seek);
317
```
318

319
### Metadata Operations
320

321
#### Reading and Writing Metadata
322

323
```java { .api }
324
/**
325
 * Set metadata entry in dictionary
326
 * @param pm Pointer to dictionary
327
 * @param key Metadata key
328
 * @param value Metadata value
329
 * @param flags Control flags
330
 * @return >= 0 on success
331
 */
332
int av_dict_set(AVDictionary pm, String key, String value, int flags);
333

334
/**
335
 * Get metadata entry from dictionary
336
 * @param m Dictionary to search
337
 * @param key Key to find
338
 * @param prev Previous entry for iteration
339
 * @param flags Search flags
340
 * @return Dictionary entry or null if not found
341
 */
342
AVDictionaryEntry av_dict_get(AVDictionary m, String key, AVDictionaryEntry prev, int flags);
343
```
344

345
**Usage Example:**
346

347
```java
348
// Read metadata from input file
349
AVFormatContext formatContext = /* ... opened context ... */;
350
AVDictionaryEntry entry = null;
351

352
// Iterate through all metadata
353
while ((entry = av_dict_get(formatContext.metadata(), "", entry, AV_DICT_IGNORE_SUFFIX)) != null) {
354
    System.out.println(entry.key().getString() + ": " + entry.value().getString());
355
}
356

357
// Set metadata for output
358
AVDictionary metadata = new AVDictionary(null);
359
av_dict_set(metadata, "title", "My Video", 0);
360
av_dict_set(metadata, "artist", "My Name", 0);
361
outputContext.metadata(metadata);
362
```
363

364
## Constants
365

366
### Format Flags
367

368
```java { .api }
369
// AVFormatContext flags
370
int AVFMT_NOFILE = 0x0001;      // Demuxer will use a custom I/O
371
int AVFMT_NEEDNUMBER = 0x0002;  // Needs number in filename
372
int AVFMT_SHOW_IDS = 0x0008;    // Show format stream IDs
373
int AVFMT_GLOBALHEADER = 0x0040; // Format wants global header
374
int AVFMT_NOTIMESTAMPS = 0x0080; // Format does not need timestamps
375
int AVFMT_VARIABLE_FPS = 0x0400; // Format allows variable fps
376

377
// I/O flags
378
int AVIO_FLAG_READ = 1;         // Read-only access
379
int AVIO_FLAG_WRITE = 2;        // Write-only access
380
int AVIO_FLAG_READ_WRITE = 3;   // Read-write access
381

382
// Seek flags  
383
int AVSEEK_FLAG_BACKWARD = 1;   // Seek backwards
384
int AVSEEK_FLAG_BYTE = 2;       // Seek by bytes
385
int AVSEEK_FLAG_ANY = 4;        // Seek to any frame
386
int AVSEEK_FLAG_FRAME = 8;      // Seek by frame number
387
```
388

389
### Common Media Types
390

391
```java { .api }
392
// Media types
393
int AVMEDIA_TYPE_UNKNOWN = -1;
394
int AVMEDIA_TYPE_VIDEO = 0;
395
int AVMEDIA_TYPE_AUDIO = 1; 
396
int AVMEDIA_TYPE_DATA = 2;
397
int AVMEDIA_TYPE_SUBTITLE = 3;
398
int AVMEDIA_TYPE_ATTACHMENT = 4;
399
```