AVC / H.264 Annex B Encoder (Run)¶
This article explains how you can use Transcoder.Run to encode a raw YUV video file to AVC / H.264 Annex B elementary stream format.
The code snippets in this article are from the enc_avc_file sample.
Source Video¶
For source we use the foreman_qcif.yuv file from the AVBlocks Assets repository. After downloading and unzipping you will find foreman_qcif.yuv in the vid subdirectory.
Code¶
This code takes a raw YUV video file and encodes it to compressed H.264 Annex B format.
Initialize AVBlocks¶
The first step in any AVBlocks application is to initialize the library. This must be done before using any other AVBlocks functionality. The Library.Initialize() method sets up the internal state and loads necessary codecs. Always remember to call Library.Shutdown() at the end of your program to properly clean up resources and release any allocated memory.
static int Main(string[] args)
{
var opt = new Options();
if (!opt.Prepare(args))
return opt.Error ? (int)ExitCodes.OptionsError : (int)ExitCodes.Success;
Library.Initialize();
// Set license information. To run AVBlocks in demo mode, comment the next line out
// Library.SetLicense("<license-string>");
bool encAvcFileResult = Encode(opt);
Library.Shutdown();
return encAvcFileResult ? (int)ExitCodes.Success : (int)ExitCodes.EncodingError;
}
Configure Input Socket¶
The input socket defines the source raw YUV video data. We need to specify the video parameters including frame dimensions, frame rate, color format, and scan type. These parameters must match the actual properties of the input YUV file. In this example, we’re reading QCIF resolution (176x144) YUV 4:2:0 progressive video at 30 frames per second.
static MediaSocket CreateInputSocket(Options opt)
{
MediaSocket socket = new MediaSocket();
socket.StreamType = StreamType.UncompressedVideo;
socket.File = opt.InputFile;
MediaPin pin = new MediaPin();
socket.Pins.Add(pin);
VideoStreamInfo vsi = new VideoStreamInfo();
pin.StreamInfo = vsi;
vsi.StreamType = StreamType.UncompressedVideo;
vsi.ScanType = ScanType.Progressive;
vsi.FrameWidth = opt.Width;
vsi.FrameHeight = opt.Height;
vsi.ColorFormat = opt.Color.Id;
vsi.FrameRate = opt.Fps;
return socket;
}
Configure Output Socket¶
The output socket defines where and how the encoded H.264 video data will be written. We configure it to output an H.264 Annex B elementary stream file. The socket represents the output destination, while the pin represents the specific video stream within that destination. By setting StreamSubType.AvcAnnexB, we ensure the output uses the Annex B format with start codes, which is suitable for elementary streams and broadcasting applications.
static MediaSocket CreateOutputSocket(Options opt)
{
MediaSocket socket = new MediaSocket();
socket.File = opt.OutputFile;
socket.StreamType = StreamType.H264;
socket.StreamSubType = StreamSubType.AvcAnnexB;
MediaPin pin = new MediaPin();
socket.Pins.Add(pin);
VideoStreamInfo vsi = new VideoStreamInfo();
pin.StreamInfo = vsi;
vsi.StreamType = StreamType.H264;
vsi.StreamSubType = StreamSubType.AvcAnnexB;
return socket;
}
Configure Transcoder and Encode¶
This is the main encoding function that ties everything together. First, we create an input socket that points to the YUV file we want to encode. Then we create the output socket using our helper method. The transcoder is the core component that performs the actual encoding - it takes the uncompressed YUV data from the input and converts it to compressed H.264 data for the output.
The AllowDemoMode = true setting allows the transcoder to work even without a valid license (useful for testing, but not recommended for production). We then add our input and output sockets to the transcoder, open it to prepare for processing, run the actual transcoding operation, and finally close it to clean up.
static bool Encode(Options opt)
{
DeleteFile(opt.OutputFile);
MediaSocket inSocket = CreateInputSocket(opt);
MediaSocket outSocket = CreateOutputSocket(opt);
// create Transcoder
using (Transcoder transcoder = new Transcoder())
{
transcoder.AllowDemoMode = true;
transcoder.Inputs.Add(inSocket);
transcoder.Outputs.Add(outSocket);
bool res = transcoder.Open();
PrintError("Transcoder open", transcoder.Error);
if (!res)
return false;
res = transcoder.Run();
PrintError("Transcoder run", transcoder.Error);
if (!res)
return false;
transcoder.Close();
PrintError("Transcoder close", transcoder.Error);
if (!res)
return false;
}
return true;
}
Complete C# Code¶
Here’s the complete working example that demonstrates H.264 encoding using AVBlocks. This code combines all the previous snippets into a functional program that can be compiled and run. The Main method handles command-line argument parsing, initializes AVBlocks, performs the encoding operation, and properly shuts down the library before exiting.
using System;
using PrimoSoftware.AVBlocks;
namespace CliSample
{
class Program
{
static int Main(string[] args)
{
var opt = new Options();
if (!opt.Prepare(args))
return opt.Error ? (int)ExitCodes.OptionsError : (int)ExitCodes.Success;
Library.Initialize();
// Set license information. To run AVBlocks in demo mode, comment the next line out
// Library.SetLicense("<license-string>");
bool encAvcFileResult = Encode(opt);
Library.Shutdown();
return encAvcFileResult ? (int)ExitCodes.Success : (int)ExitCodes.EncodingError;
}
static bool Encode(Options opt)
{
DeleteFile(opt.OutputFile);
MediaSocket inSocket = CreateInputSocket(opt);
MediaSocket outSocket = CreateOutputSocket(opt);
// create Transcoder
using (Transcoder transcoder = new Transcoder())
{
transcoder.AllowDemoMode = true;
transcoder.Inputs.Add(inSocket);
transcoder.Outputs.Add(outSocket);
bool res = transcoder.Open();
PrintError("Transcoder open", transcoder.Error);
if (!res)
return false;
res = transcoder.Run();
PrintError("Transcoder run", transcoder.Error);
if (!res)
return false;
transcoder.Close();
PrintError("Transcoder close", transcoder.Error);
if (!res)
return false;
}
return true;
}
static void DeleteFile(string filename)
{
try
{
if (System.IO.File.Exists(filename))
System.IO.File.Delete(filename);
}
catch { }
}
static MediaSocket CreateInputSocket(Options opt)
{
MediaSocket socket = new MediaSocket();
socket.StreamType = StreamType.UncompressedVideo;
socket.File = opt.InputFile;
MediaPin pin = new MediaPin();
socket.Pins.Add(pin);
VideoStreamInfo vsi = new VideoStreamInfo();
pin.StreamInfo = vsi;
vsi.StreamType = StreamType.UncompressedVideo;
vsi.ScanType = ScanType.Progressive;
vsi.FrameWidth = opt.Width;
vsi.FrameHeight = opt.Height;
vsi.ColorFormat = opt.Color.Id;
vsi.FrameRate = opt.Fps;
return socket;
}
static MediaSocket CreateOutputSocket(Options opt)
{
MediaSocket socket = new MediaSocket();
socket.File = opt.OutputFile;
socket.StreamType = StreamType.H264;
socket.StreamSubType = StreamSubType.AvcAnnexB;
MediaPin pin = new MediaPin();
socket.Pins.Add(pin);
VideoStreamInfo vsi = new VideoStreamInfo();
pin.StreamInfo = vsi;
vsi.StreamType = StreamType.H264;
vsi.StreamSubType = StreamSubType.AvcAnnexB;
return socket;
}
static void PrintError(string action, ErrorInfo e)
{
if (action != null)
{
Console.Write("{0}: ", action);
}
if (ErrorFacility.Success == e.Facility)
{
Console.WriteLine("Success");
return;
}
else
{
Console.WriteLine("{0}, facility:{1} code:{2} hint:{3}", e.Message ?? "", e.Facility, e.Code, e.Hint ?? "");
}
}
enum ExitCodes : int
{
Success = 0,
OptionsError = 1,
EncodingError = 2,
}
}
}
How to Run¶
See the build instructions for Windows, macOS, and Linux, and the enc_avc_file sample for details.
Command Line¶
enc_avc_file --frame <width>x<height> --rate <fps> --color <color> --input <file.yuv> --output <file.h264> [--colors]
Examples¶
List options:
./bin/net10.0/enc_avc_file --help
enc_avc_file 1.0.0.0
Copyright (C) 2023 Primo Software
-i, --input input YUV file
-o, --output output AVC / H.264 file
-r, --rate input frame rate
-f, --frame input frame size
-c, --color input color space. Use --colors to list all supported input color spaces.
--colors list supported input color spaces
--help Display this help screen.
--version Display version information.
List supported color spaces for input:
./bin/net10.0/enc_avc_file --colors
COLORS
---------
yv12 Planar Y, V, U (4:2:0) (note V,U order!)
nv12 Planar Y, merged U->V (4:2:0)
yuy2 Composite Y->U->Y->V (4:2:2)
uyvy Composite U->Y->V->Y (4:2:2)
yuv411 Planar Y, U, V (4:1:1)
yuv420 Planar Y, U, V (4:2:0)
yuv422 Planar Y, U, V (4:2:2)
yuv444 Planar Y, U, V (4:4:4)
y411 Composite Y, U, V (4:1:1)
y41p Composite Y, U, V (4:1:1)
bgr32 Composite B->G->R
bgra32 Composite B->G->R->A
bgr24 Composite B->G->R
bgr565 Composite B->G->R, 5 bit per B & R, 6 bit per G
bgr555 Composite B->G->R->A, 5 bit per component, 1 bit per A
bgr444 Composite B->G->R->A, 4 bit per component
gray Luminance component only
yuv420a Planar Y, U, V, Alpha (4:2:0)
yuv422a Planar Y, U, V, Alpha (4:2:2)
yuv444a Planar Y, U, V, Alpha (4:4:4)
yvu9 Planar Y, V, U, 9 bits per sample
The following example encodes input file ./assets/vid/foreman_qcif.yuv into output file foreman_qcif.h264:
# Linux and macOS
mkdir -p ./output/enc_avc_file
./bin/net10.0/enc_avc_file \
--input ./assets/vid/foreman_qcif.yuv \
--output ./output/enc_avc_file/foreman_qcif.h264 \
--frame 176x144 --rate 30 --color yuv420
# Windows
mkdir -Force -Path ./output/enc_avc_file
./bin/net10.0/enc_avc_file `
--input ./assets/vid/foreman_qcif.yuv `
--output ./output/enc_avc_file/foreman_qcif.h264 `
--frame 176x144 --rate 30 --color yuv420