examples/simple_encoder.txt

   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