0
# Codec Operations (Encoding/Decoding)
1

2
Audio and video encoding/decoding operations with support for all major codecs including H.264, H.265, VP9, AV1, AAC, MP3, and many others.
3

4
## Capabilities
5

6
### Codec Discovery
7

8
#### Finding Codecs
9

10
```java { .api }
11
/**
12
 * Find a registered encoder with matching codec ID
13
 * @param id Codec ID to search for
14
 * @return AVCodec encoder or null if not found
15
 */
16
AVCodec avcodec_find_encoder(int id);
17

18
/**
19
 * Find a registered decoder with matching codec ID
20
 * @param id Codec ID to search for  
21
 * @return AVCodec decoder or null if not found
22
 */
23
AVCodec avcodec_find_decoder(int id);
24

25
/**
26
 * Find encoder by name
27
 * @param name Codec name
28
 * @return AVCodec encoder or null if not found
29
 */
30
AVCodec avcodec_find_encoder_by_name(String name);
31

32
/**
33
 * Find decoder by name
34
 * @param name Codec name
35
 * @return AVCodec decoder or null if not found
36
 */
37
AVCodec avcodec_find_decoder_by_name(String name);
38

39
/**
40
 * Iterate over all registered codecs
41
 * @param opaque Iterator state (pass null initially)
42
 * @return Next codec or null when done
43
 */
44
AVCodec av_codec_iterate(Pointer opaque);
45
```
46

47
**Usage Example:**
48

49
```java
50
import org.bytedeco.ffmpeg.avcodec.*;
51
import static org.bytedeco.ffmpeg.global.avcodec.*;
52

53
// Find H.264 encoder
54
AVCodec h264Encoder = avcodec_find_encoder(AV_CODEC_ID_H264);
55
if (h264Encoder == null) {
56
    throw new RuntimeException("H.264 encoder not available");
57
}
58

59
// Find AAC decoder by name
60
AVCodec aacDecoder = avcodec_find_decoder_by_name("aac");
61
if (aacDecoder != null) {
62
    System.out.println("AAC decoder: " + aacDecoder.long_name().getString());
63
}
64
```
65

66
### Context Management
67

68
#### Codec Context Operations
69

70
```java { .api }
71
/**
72
 * Allocate an AVCodecContext and set its fields to default values
73
 * @param codec Codec to allocate context for (can be null)
74
 * @return Allocated context or null on failure
75
 */
76
AVCodecContext avcodec_alloc_context3(AVCodec codec);
77

78
/**
79
 * Free codec context and everything associated with it
80
 * @param avctx Pointer to context to free
81
 */
82
void avcodec_free_context(@ByPtrPtr AVCodecContext avctx);
83

84
/**
85
 * Initialize codec context to use the given codec
86
 * @param avctx Context to initialize
87
 * @param codec Codec to use
88
 * @param options Dictionary of codec options
89
 * @return Zero on success, negative error code on failure
90
 */
91
int avcodec_open2(AVCodecContext avctx, AVCodec codec, PointerPointer options);
92

93
/**
94
 * Close codec context and free all data associated with it
95
 * @param avctx Context to close
96
 * @return Zero on success
97
 */
98
int avcodec_close(AVCodecContext avctx);
99
```
100

101
### Parameter Handling
102

103
#### Codec Parameters
104

105
```java { .api }
106
/**
107
 * Copy codec parameters from codec context to codec parameters
108
 * @param par Destination codec parameters
109
 * @param codec Source codec context
110
 * @return >= 0 on success
111
 */
112
int avcodec_parameters_from_context(AVCodecParameters par, AVCodecContext codec);
113

114
/**
115
 * Copy codec parameters to codec context
116
 * @param codec Destination codec context
117
 * @param par Source codec parameters
118
 * @return >= 0 on success
119
 */
120
int avcodec_parameters_to_context(AVCodecContext codec, AVCodecParameters par);
121

122
/**
123
 * Copy codec parameters
124
 * @param dst Destination parameters
125
 * @param src Source parameters
126
 * @return >= 0 on success
127
 */
128
int avcodec_parameters_copy(AVCodecParameters dst, AVCodecParameters src);
129
```
130

131
### Decoding Operations
132

133
#### Decoding Audio/Video
134

135
```java { .api }
136
/**
137
 * Supply raw packet data as input to a decoder
138
 * @param avctx Codec context
139
 * @param avpkt Input packet (null to signal end of stream)
140
 * @return 0 on success, negative AVERROR on failure
141
 */
142
int avcodec_send_packet(AVCodecContext avctx, AVPacket avpkt);
143

144
/**
145
 * Return decoded frame from decoder
146
 * @param avctx Codec context
147
 * @param frame Frame to fill with decoded data
148
 * @return 0 on success, AVERROR(EAGAIN) if more input needed
149
 */
150
int avcodec_receive_frame(AVCodecContext avctx, AVFrame frame);
151

152
/**
153
 * Reset internal codec state
154
 * @param avctx Codec context to reset
155
 */
156
void avcodec_flush_buffers(AVCodecContext avctx);
157
```
158

159
**Usage Example:**
160

161
```java
162
// Set up decoder context
163
AVCodecContext decoderContext = avcodec_alloc_context3(null);
164
avcodec_parameters_to_context(decoderContext, stream.codecpar());
165

166
AVCodec decoder = avcodec_find_decoder(decoderContext.codec_id());
167
int result = avcodec_open2(decoderContext, decoder, (PointerPointer)null);
168

169
AVFrame frame = av_frame_alloc();
170
AVPacket packet = av_packet_alloc();
171

172
// Decode loop
173
while (av_read_frame(formatContext, packet) >= 0) {
174
    if (packet.stream_index() == videoStreamIndex) {
175
        // Send packet to decoder
176
        result = avcodec_send_packet(decoderContext, packet);
177
        if (result < 0) {
178
            System.err.println("Error sending packet to decoder");
179
            continue;
180
        }
181
        
182
        // Receive decoded frames
183
        while (result >= 0) {
184
            result = avcodec_receive_frame(decoderContext, frame);
185
            if (result == AVERROR_EAGAIN() || result == AVERROR_EOF()) {
186
                break;
187
            } else if (result < 0) {
188
                System.err.println("Error during decoding");
189
                break;
190
            }
191
            
192
            // Process decoded frame
193
            System.out.println("Decoded frame: " + frame.width() + "x" + frame.height());
194
            av_frame_unref(frame);
195
        }
196
    }
197
    av_packet_unref(packet);
198
}
199

200
// Cleanup
201
av_frame_free(frame);
202
av_packet_free(packet);
203
avcodec_free_context(decoderContext);
204
```
205

206
### Encoding Operations
207

208
#### Encoding Audio/Video
209

210
```java { .api }
211
/**
212
 * Supply raw frame data as input to an encoder
213
 * @param avctx Codec context
214
 * @param frame Input frame (null to signal end of stream)
215
 * @return 0 on success, negative AVERROR on failure
216
 */
217
int avcodec_send_frame(AVCodecContext avctx, AVFrame frame);
218

219
/**
220
 * Read encoded data from encoder
221
 * @param avctx Codec context
222
 * @param avpkt Packet to fill with encoded data
223
 * @return 0 on success, AVERROR(EAGAIN) if more input needed
224
 */
225
int avcodec_receive_packet(AVCodecContext avctx, AVPacket avpkt);
226
```
227

228
**Usage Example:**
229

230
```java
231
// Set up encoder context
232
AVCodecContext encoderContext = avcodec_alloc_context3(null);
233
encoderContext.codec_id(AV_CODEC_ID_H264);
234
encoderContext.codec_type(AVMEDIA_TYPE_VIDEO);
235
encoderContext.width(1920);
236
encoderContext.height(1080);
237
encoderContext.time_base(av_make_q(1, 30)); // 30 FPS
238
encoderContext.framerate(av_make_q(30, 1));
239
encoderContext.pix_fmt(AV_PIX_FMT_YUV420P);
240

241
AVCodec encoder = avcodec_find_encoder(AV_CODEC_ID_H264);
242
int result = avcodec_open2(encoderContext, encoder, (PointerPointer)null);
243

244
AVFrame inputFrame = av_frame_alloc();
245
AVPacket outputPacket = av_packet_alloc();
246

247
// Encode frames
248
for (int i = 0; i < 100; i++) {
249
    // Fill frame with data
250
    inputFrame.width(1920);
251
    inputFrame.height(1080);
252
    inputFrame.format(AV_PIX_FMT_YUV420P);
253
    inputFrame.pts(i);
254
    
255
    // Send frame to encoder
256
    result = avcodec_send_frame(encoderContext, inputFrame);
257
    if (result < 0) {
258
        System.err.println("Error sending frame to encoder");
259
        break;
260
    }
261
    
262
    // Receive encoded packets
263
    while (result >= 0) {
264
        result = avcodec_receive_packet(encoderContext, outputPacket);
265
        if (result == AVERROR_EAGAIN() || result == AVERROR_EOF()) {
266
            break;
267
        } else if (result < 0) {
268
            System.err.println("Error during encoding");
269
            break;
270
        }
271
        
272
        // Write packet to output
273
        System.out.println("Encoded packet size: " + outputPacket.size());
274
        av_packet_unref(outputPacket);
275
    }
276
}
277

278
// Flush encoder
279
avcodec_send_frame(encoderContext, null);
280
while (avcodec_receive_packet(encoderContext, outputPacket) == 0) {
281
    // Handle final packets
282
    av_packet_unref(outputPacket);
283
}
284

285
// Cleanup
286
av_frame_free(inputFrame);
287
av_packet_free(outputPacket);
288
avcodec_free_context(encoderContext);
289
```
290

291
### Packet Operations
292

293
#### Packet Management
294

295
```java { .api }
296
/**
297
 * Allocate an AVPacket and set its fields to default values
298
 * @return Allocated packet or null on failure
299
 */
300
AVPacket av_packet_alloc();
301

302
/**
303
 * Free packet and its contents
304
 * @param pkt Pointer to packet to free
305
 */
306
void av_packet_free(AVPacket pkt);
307

308
/**
309
 * Create a reference to packet data
310
 * @param dst Destination packet
311
 * @param src Source packet
312
 * @return 0 on success, negative AVERROR on failure
313
 */
314
int av_packet_ref(AVPacket dst, AVPacket src);
315

316
/**
317
 * Unreference packet data
318
 * @param pkt Packet to unreference
319
 */
320
void av_packet_unref(AVPacket pkt);
321

322
/**
323
 * Create new packet with copy of data
324
 * @param pkt Packet to clone
325
 * @return New packet or null on failure
326
 */
327
AVPacket av_packet_clone(AVPacket pkt);
328
```
329

330
### Hardware Acceleration
331

332
#### Hardware Acceleration Support
333

334
```java { .api }
335
/**
336
 * Iterate over supported hardware configurations
337
 * @param codec Codec to query
338
 * @param index Configuration index
339
 * @return Hardware configuration or null
340
 */
341
AVCodecHWConfig avcodec_get_hw_config(AVCodec codec, int index);
342

343
/**
344
 * Create hardware device context
345
 * @param device_ctx Pointer to receive context
346
 * @param type Hardware device type
347
 * @param device Device identifier (optional)
348
 * @param opts Options dictionary
349
 * @param flags Creation flags
350
 * @return >= 0 on success
351
 */
352
int av_hwdevice_ctx_create(AVBufferRef device_ctx, int type, String device, 
353
    AVDictionary opts, int flags);
354

355
/**
356
 * Allocate hardware frame
357
 * @param hwframe_ctx Hardware frame context
358
 * @param frame Frame to allocate
359
 * @param flags Allocation flags
360
 * @return >= 0 on success
361
 */
362
int av_hwframe_get_buffer(AVBufferRef hwframe_ctx, AVFrame frame, int flags);
363
```
364

365
### Codec Information
366

367
#### Codec Properties and Capabilities
368

369
```java { .api }
370
/**
371
 * AVCodec structure containing codec information
372
 */
373
class AVCodec extends Pointer {
374
    /** Codec name */
375
    BytePointer name();
376
    
377
    /** Descriptive codec name */
378
    BytePointer long_name();
379
    
380
    /** Codec type (video, audio, etc.) */
381
    int type();
382
    
383
    /** Codec ID */
384
    int id();
385
    
386
    /** Codec capabilities flags */
387
    int capabilities();
388
    
389
    /** Supported sample rates (for audio) */
390
    IntPointer supported_samplerates();
391
    
392
    /** Supported pixel formats (for video) */
393
    IntPointer pix_fmts();
394
    
395
    /** Supported sample formats (for audio) */
396
    IntPointer sample_fmts();
397
}
398

399
/**
400
 * AVCodecContext structure for encoding/decoding
401
 */
402
class AVCodecContext extends Pointer {
403
    /** Codec information */
404
    AVCodec codec();
405
    
406
    /** Codec type */
407
    int codec_type();
408
    
409
    /** Codec ID */
410
    int codec_id();
411
    
412
    /** Video dimensions */
413
    int width();
414
    int height();
415
    
416
    /** Pixel format */
417
    int pix_fmt();
418
    
419
    /** Audio sample rate */
420
    int sample_rate();
421
    
422
    /** Number of audio channels */
423
    int channels();
424
    
425
    /** Audio sample format */
426
    int sample_fmt();
427
    
428
    /** Bitrate */
429
    long bit_rate();
430
    
431
    /** Time base */
432
    AVRational time_base();
433
    
434
    /** Frame rate */
435
    AVRational framerate();
436
}
437
```
438

439
## Constants
440

441
### Codec IDs
442

443
```java { .api }
444
// Video codecs
445
int AV_CODEC_ID_H264 = 27;
446
int AV_CODEC_ID_HEVC = 173;
447
int AV_CODEC_ID_VP8 = 139;
448
int AV_CODEC_ID_VP9 = 167;
449
int AV_CODEC_ID_AV1 = 225;
450
int AV_CODEC_ID_MPEG4 = 12;
451
int AV_CODEC_ID_H263 = 5;
452

453
// Audio codecs  
454
int AV_CODEC_ID_AAC = 86018;
455
int AV_CODEC_ID_MP3 = 86017;
456
int AV_CODEC_ID_AC3 = 86019;
457
int AV_CODEC_ID_OPUS = 86076;
458
int AV_CODEC_ID_VORBIS = 86021;
459
int AV_CODEC_ID_FLAC = 86028;
460
int AV_CODEC_ID_PCM_S16LE = 65536;
461
```
462

463
### Codec Capabilities
464

465
```java { .api }
466
// Codec capability flags
467
int AV_CODEC_CAP_DRAW_HORIZ_BAND = 0x0001;    // Decoder can use draw_horiz_band callback
468
int AV_CODEC_CAP_DR1 = 0x0002;                // Codec uses get_buffer() for allocating buffers
469
int AV_CODEC_CAP_TRUNCATED = 0x0008;          // Input bitstream might be truncated
470
int AV_CODEC_CAP_DELAY = 0x0020;              // Encoder or decoder requires flushing
471
int AV_CODEC_CAP_SMALL_LAST_FRAME = 0x0040;  // Encoder supports small last frame
472
int AV_CODEC_CAP_SUBFRAMES = 0x0100;          // Codec can output multiple frames per packet
473
int AV_CODEC_CAP_EXPERIMENTAL = 0x0200;      // Codec is experimental
474
int AV_CODEC_CAP_CHANNEL_CONF = 0x0400;      // Codec should fill in channel configuration
475
int AV_CODEC_CAP_FRAME_THREADS = 0x1000;     // Codec supports frame-level multithreading
476
int AV_CODEC_CAP_SLICE_THREADS = 0x2000;     // Codec supports slice-level multithreading
477
int AV_CODEC_CAP_PARAM_CHANGE = 0x4000;      // Codec supports parameter changes during decoding
478
int AV_CODEC_CAP_AUTO_THREADS = 0x8000;      // Codec supports automatic thread selection
479
int AV_CODEC_CAP_VARIABLE_FRAME_SIZE = 0x10000; // Audio encoder supports variable frame sizes
480
```
481

482
### Subtitle Processing
483

484
#### Subtitle Structures
485

486
```java { .api }
487
/**
488
 * Subtitle data structure containing decoded subtitle information
489
 */
490
class AVSubtitle extends Pointer {
491
    /**
492
     * Format of subtitle: 0 = graphics, 1 = text
493
     */
494
    int format();
495
    
496
    /**
497
     * Relative start time (in milliseconds, 0 = now)
498
     */
499
    int start_display_time();
500
    
501
    /**
502
     * Relative end time (in milliseconds, 0 = duration unknown)
503
     */
504
    int end_display_time();
505
    
506
    /**
507
     * Number of subtitle rectangles
508
     */
509
    int num_rects();
510
    
511
    /**
512
     * Array of subtitle rectangles
513
     */
514
    AVSubtitleRect rects(int i);
515
    
516
    /**
517
     * Duration in pts units (0 if unknown)
518
     */
519
    long pts();
520
}
521

522
/**
523
 * Subtitle rectangle containing text or graphics data
524
 */
525
class AVSubtitleRect extends Pointer {
526
    /**
527
     * Position and dimensions
528
     */
529
    int x();
530
    int y(); 
531
    int w();
532
    int h();
533
    
534
    /**
535
     * Number of colors in palette (for graphics)
536
     */
537
    int nb_colors();
538
    
539
    /**
540
     * Subtitle type (graphics or text)
541
     */
542
    int type();
543
    
544
    /**
545
     * Text content (for text subtitles)
546
     */
547
    BytePointer text();
548
    
549
    /**
550
     * ASS formatted text (for advanced subtitles)
551
     */
552
    BytePointer ass();
553
    
554
    /**
555
     * Bitmap data (for graphics subtitles)
556
     */
557
    PointerPointer data();
558
    IntPointer linesize();
559
}
560
```
561

562
#### Subtitle Decoding
563

564
```java { .api }
565
/**
566
 * Decode subtitle packet
567
 * @param avctx Codec context
568
 * @param sub Subtitle structure to fill
569
 * @param got_sub_ptr Pointer to set if subtitle was decoded
570
 * @param avpkt Input packet
571
 * @return Number of bytes consumed or negative error code
572
 */
573
int avcodec_decode_subtitle2(AVCodecContext avctx, AVSubtitle sub,
574
                             IntPointer got_sub_ptr, AVPacket avpkt);
575

576
/**
577
 * Free subtitle structure contents
578
 * @param sub Subtitle to free
579
 */
580
void avsubtitle_free(AVSubtitle sub);
581
```
582

583
**Subtitle Decoding Example:**
584

585
```java
586
// Decode subtitle packets
587
AVCodecContext subtitleCtx = /* subtitle decoder context */;
588
AVSubtitle subtitle = new AVSubtitle();
589
IntPointer gotSubtitle = new IntPointer(1);
590

591
int result = avcodec_decode_subtitle2(subtitleCtx, subtitle, gotSubtitle, packet);
592

593
if (result >= 0 && gotSubtitle.get() != 0) {
594
    System.out.println("Subtitle decoded:");
595
    System.out.println("  Start: " + subtitle.start_display_time() + "ms");
596
    System.out.println("  End: " + subtitle.end_display_time() + "ms");
597
    
598
    // Process subtitle rectangles
599
    for (int i = 0; i < subtitle.num_rects(); i++) {
600
        AVSubtitleRect rect = subtitle.rects(i);
601
        
602
        if (rect.text() != null) {
603
            System.out.println("  Text: " + rect.text().getString());
604
        }
605
        
606
        if (rect.ass() != null) {
607
            System.out.println("  ASS: " + rect.ass().getString());
608
        }
609
    }
610
    
611
    // Free subtitle when done
612
    avsubtitle_free(subtitle);
613
}
614
```
615

616
### Error Codes
617

618
```java { .api }
619
// Common codec error codes
620
int AVERROR_EAGAIN();     // Resource temporarily unavailable
621
int AVERROR_EOF();        // End of file
622
int AVERROR_INVALIDDATA(); // Invalid data found
623
int AVERROR_PATCHWELCOME(); // Feature not implemented
624
```