How to Use avformat_alloc_output_context2 in FFmpeg

This guide explains how to allocate an AVFormatContext for muxing and output operations using the avformat_alloc_output_context2 function in the FFmpeg C API. You will learn the function's parameter requirements, how FFmpeg deduces the output container format, how to handle errors, and how to properly free allocated memory.

Function Signature and Parameters

The avformat_alloc_output_context2 function is declared in <libavformat/avformat.h> as follows:

int avformat_alloc_output_context2(AVFormatContext **ctx,
                                   const AVOutputFormat *oformat,
                                   const char *format_name,
                                   const char *filename);

The parameters function as follows:

  • ctx: A pointer to the AVFormatContext* pointer that will be created and populated by the function. If allocation fails, *ctx is set to NULL.
  • oformat: A pointer to an existing AVOutputFormat struct. Pass NULL if you want FFmpeg to determine the format automatically.
  • format_name: A string representing the short name of the container format (such as "mp4", "matroska", or "flv"). Pass NULL to rely on the file extension instead.
  • filename: The destination file path or URL (such as "output.mp4"). FFmpeg can infer the format from the file extension if oformat and format_name are set to NULL.

At least one of oformat, format_name, or filename must be provided.

Format Deduction Priority

FFmpeg resolves the container format using the following order of precedence:

  1. If oformat is provided, it is used directly.
  2. If oformat is NULL but format_name is provided, FFmpeg searches for a matching registered output format.
  3. If both oformat and format_name are NULL, FFmpeg parses the file extension in filename using av_guess_format.

Complete Implementation Example

The following example demonstrates how to initialize the output context, verify that the format was found, and cleanly free the resources:

#include <stdio.h>
#include <libavformat/avformat.h>

int main(void) {
    AVFormatContext *out_ctx = NULL;
    const char *filename = "output.mp4";

    // Allocate the output context using the filename extension
    int ret = avformat_alloc_output_context2(&out_ctx, NULL, NULL, filename);
    if (ret < 0 || !out_ctx) {
        fprintf(stderr, "Could not deduce output format from file extension.\n");
        return ret;
    }

    // Context is successfully allocated and ready for stream creation
    printf("Format allocated: %s (%s)\n", 
           out_ctx->oformat->name, 
           out_ctx->oformat->long_name);

    // Free the context when finished
    avformat_free_context(out_ctx);
    out_ctx = NULL;

    return 0;
}

Specifying an Explicit Format Name

If your output file has a non-standard extension or is streaming over a network (such as raw UDP or custom protocols), specify the format name explicitly:

AVFormatContext *out_ctx = NULL;

// Force MPEG-TS format regardless of the URL pattern
int ret = avformat_alloc_output_context2(&out_ctx, NULL, "mpegts", "udp://127.0.0.1:1234");
if (ret < 0 || !out_ctx) {
    fprintf(stderr, "Failed to create output context for mpegts\n");
    return ret;
}

Memory Management and Cleanup

Always release the context using avformat_free_context(out_ctx) when processing is complete or if an error occurs later in the pipeline. Do not use standard free() or av_free(), as avformat_free_context cleans up internal format structures, streams, and private muxer options associated with the AVFormatContext.