1 @TEMPLATE encoder_tmpl.c 2 Simple Encoder 3 ============== 4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION 5 This is an example of a simple encoder loop. It takes an input file in 6 YV12 format, passes it through the encoder, and writes the compressed 7 frames to disk in IVF format. Other decoder examples build upon this 8 one. 9 10 The details of the IVF format have been elided from this example for 11 simplicity of presentation, as IVF files will not generally be used by 12 your application. In general, an IVF file consists of a file header, 13 followed by a variable number of frames. Each frame consists of a frame 14 header followed by a variable length payload. The length of the payload 15 is specified in the first four bytes of the frame header. The payload is 16 the raw compressed data. 17 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION 18 19 20 Standard Includes 21 ----------------- 22 For encoders, you only have to include `vpx_encoder.h` and then any 23 header files for the specific codecs you use. In this case, we're using 24 vp8. The `VPX_CODEC_DISABLE_COMPAT` macro can be defined to ensure 25 strict compliance with the latest SDK by disabling some backwards 26 compatibility features. Defining this macro is encouraged. 27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INCLUDES 28 @DEFAULT 29 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INCLUDES 30 31 32 Getting The Default Configuration 33 --------------------------------- 34 Encoders have the notion of "usage profiles." For example, an encoder 35 may want to publish default configurations for both a video 36 conferencing appliction and a best quality offline encoder. These 37 obviously have very different default settings. Consult the 38 documentation for your codec to see if it provides any default 39 configurations. All codecs provide a default configuration, number 0, 40 which is valid for material in the vacinity of QCIF/QVGA. 41 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_DEF_CFG 42 @DEFAULT 43 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_DEF_CFG 44 45 46 Updating The Configuration 47 --------------------------------- 48 Almost all applications will want to update the default configuration 49 with settings specific to their usage. Here we set the width and height 50 of the video file to that specified on the command line. We also scale 51 the default bitrate based on the ratio between the default resolution 52 and the resolution specified on the command line. 53 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_SET_CFG 54 @DEFAULT 55 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_SET_CFG 56 57 58 Initializing The Codec 59 ---------------------- 60 The encoder is initialized by the following code. 61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INIT 62 @DEFAULT 63 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INIT 64 65 66 Encoding A Frame 67 ---------------- 68 The frame is read as a continuous block (size width * height * 3 / 2) 69 from the input file. If a frame was read (the input file has not hit 70 EOF) then the frame is passed to the encoder. Otherwise, a NULL 71 is passed, indicating the End-Of-Stream condition to the encoder. The 72 `frame_cnt` is reused as the presentation time stamp (PTS) and each 73 frame is shown for one frame-time in duration. The flags parameter is 74 unused in this example. The deadline is set to VPX_DL_REALTIME to 75 make the example run as quickly as possible. 76 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENCODE_FRAME 77 @DEFAULT 78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENCODE_FRAME 79 80 Processing The Encoded Data 81 --------------------------- 82 Each packet of type `VPX_CODEC_CX_FRAME_PKT` contains the encoded data 83 for this frame. We write a IVF frame header, followed by the raw data. 84 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_FRAME 85 @DEFAULT 86 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_FRAME 87 88 89 Cleanup 90 ------- 91 The `vpx_codec_destroy` call frees any memory allocated by the codec. 92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DESTROY 93 @DEFAULT 94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DESTROY 95 96 97 Error Handling 98 -------------- 99 This example does not special case any error return codes. If there was 100 an error, a descriptive message is printed and the program exits. With 101 few exeptions, vpx_codec functions return an enumerated error status, 102 with the value `0` indicating success. 103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DIE_CODEC 104 @DEFAULT 105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DIE_CODEC 106
