wcap/README

   1 WCAP Tools
   2
   3 WCAP is the video capture format used by Weston (Weston CAPture).
   4 It's a simple, lossless format, that encodes the difference between
   5 frames as run-length ecoded rectangles.  It's a variable framerate
   6 format, that only records new frames along with a timestamp when
   7 something actually changes.
   8
   9 Recording in Weston is started by pressing MOD+R and stopped by
  10 pressing MOD+R again.  Currently this leaves a capture.wcap file in
  11 the cwd of the weston process.  The file format is documented below
  12 and Weston comes with the wcap-decode tool to convert the wcap file
  13 into something more usable:
  14
  15  - Extract single or all frames as individual png files.  This will
  16    produce a lossless screenshot, which is useful if you're trying to
  17    screenshot a brief glitch or something like that that's hard to
  18    capture with the screenshot tool.
  19
  20    wcap-decode takes a number of options and a wcap file as its
  21    arguments.  Without anything else, it will show the screen size and
  22    number of frames in the file.  Pass --frame=<frame> to extract a
  23    single frame or pass --all to extract all frames as png files:
  24
  25         [krh@minato weston]$ wcap-snapshot capture.wcap
  26         wcap file: size 1024x640, 176 frames
  27         [krh@minato weston]$ wcap-snapshot capture.wcap 20
  28         wrote wcap-frame-20.png
  29         wcap file: size 1024x640, 176 frames
  30
  31  - Decode and the wcap file and dump it as a YUV4MPEG2 stream on
  32    stdout.  This format is compatible with most video encoders and can
  33    be piped directly into a command line encoder such as vpxenc (part
  34    of libvpx, encodes to a webm file) or theora_encode (part of
  35    libtheora, encodes to a ogg theora file).
  36
  37    Using vpxenc to encode a webm file would look something like this:
  38
  39         [krh@minato weston]$ wcap-decode  --yuv4mpeg2 ../capture.wcap |
  40                 vpxenc --target-bitrate=1024 --best -t 4 -o foo.webm  -
  41
  42    where we select target bitrate, pass -t 4 to let vpxenc use
  43    multiple threads.  To encode to Ogg Theora a command line like this
  44    works:
  45
  46         [krh@minato weston]$ wcap-decode ../capture.wcap  --yuv4mpeg2 |
  47                 theora_encode - -o cap.ogv
  48
  49
  50 WCAP File format
  51
  52 The file format has a small header and then just consists of the
  53 indivial frames.  The header is
  54
  55         uint32_t        magic
  56         uint32_t        format
  57         uint32_t        width
  58         uint32_t        height
  59
  60 all CPU endian 32 bit words.  The magic number is
  61
  62         #define WCAP_HEADER_MAGIC       0x57434150
  63
  64 and makes it easy to recognize a wcap file and verify that it's the
  65 right endian.  There are four supported pixel formats:
  66
  67         #define WCAP_FORMAT_XRGB8888    0x34325258
  68         #define WCAP_FORMAT_XBGR8888    0x34324258
  69         #define WCAP_FORMAT_RGBX8888    0x34325852
  70         #define WCAP_FORMAT_BGRX8888    0x34325842
  71
  72 Each frame has a header:
  73
  74         uint32_t        msecs
  75         uint32_t        nrects
  76
  77 which specifies a timestamp in ms and the number of rectangles that
  78 changed since previous frame.  The timestamps are typically just a raw
  79 system timestamp and the first frame doesn't start from 0ms.
  80
  81 A frame consists of a list of rectangles, each of which represents the
  82 component-wise difference between the previous frame and the current
  83 using a run-length encoding.  The initial frame is decoded against a
  84 previous frame of all 0x00000000 pixels.  Each rectangle starts out
  85 with
  86
  87         int32_t         x1
  88         int32_t         y1
  89         int32_t         x2
  90         int32_t         y2
  91
  92 followed by (x2 - x1) * (y2 - y1) pixels, run-length encoded.  The
  93 run-length encoding uses the 'X' channel in the pixel format to encode
  94 the length of the run.  That is for WCAP_FORMAT_XRGB8888, for example,
  95 the length of the run is in the upper 8 bits.  For X values 0-0xdf,
  96 the length is X + 1, for X above or equal to 0xe0, the run length is 1
  97 << (X - 0xe0 + 7).  That is, a pixel value of 0xe3000100, means that
  98 the next 1024 pixels differ by RGB(0x00, 0x01, 0x00) from the previous
  99 pixels.