WCAP Tools
WCAP is the video capture format used by Weston (Weston CAPture).
It's a simple, lossless format, that encodes the difference between
frames as run-length ecoded rectangles. It's a variable framerate
format, that only records new frames along with a timestamp when
something actually changes.
Recording in Weston is started by pressing MOD+R and stopped by
pressing MOD+R again. Currently this leaves a capture.wcap file in
the cwd of the weston process. The file format is documented below
and Weston comes with the wcap-decode tool to convert the wcap file
into something more usable:
- Extract single or all frames as individual png files. This will
produce a lossless screenshot, which is useful if you're trying to
screenshot a brief glitch or something like that that's hard to
capture with the screenshot tool.
wcap-decode takes a number of options and a wcap file as its
arguments. Without anything else, it will show the screen size and
number of frames in the file. Pass --frame=<frame> to extract a
single frame or pass --all to extract all frames as png files:
[krh@minato weston]$ wcap-snapshot capture.wcap
wcap file: size 1024x640, 176 frames
[krh@minato weston]$ wcap-snapshot capture.wcap 20
wrote wcap-frame-20.png
wcap file: size 1024x640, 176 frames
- Decode and the wcap file and dump it as a YUV4MPEG2 stream on
stdout. This format is compatible with most video encoders and can
be piped directly into a command line encoder such as vpxenc (part
of libvpx, encodes to a webm file) or theora_encode (part of
libtheora, encodes to a ogg theora file).
Using vpxenc to encode a webm file would look something like this:
[krh@minato weston]$ wcap-decode --yuv4mpeg2 ../capture.wcap |
vpxenc --target-bitrate=1024 --best -t 4 -o foo.webm -
where we select target bitrate, pass -t 4 to let vpxenc use
multiple threads. To encode to Ogg Theora a command line like this
works:
[krh@minato weston]$ wcap-decode ../capture.wcap --yuv4mpeg2 |
theora_encode - -o cap.ogv
WCAP File format
The file format has a small header and then just consists of the
indivial frames. The header is
uint32_t magic
uint32_t format
uint32_t width
uint32_t height
all CPU endian 32 bit words. The magic number is
#define WCAP_HEADER_MAGIC 0x57434150
and makes it easy to recognize a wcap file and verify that it's the
right endian. There are four supported pixel formats:
#define WCAP_FORMAT_XRGB8888 0x34325258
#define WCAP_FORMAT_XBGR8888 0x34324258
#define WCAP_FORMAT_RGBX8888 0x34325852
#define WCAP_FORMAT_BGRX8888 0x34325842
Each frame has a header:
uint32_t msecs
uint32_t nrects
which specifies a timestamp in ms and the number of rectangles that
changed since previous frame. The timestamps are typically just a raw
system timestamp and the first frame doesn't start from 0ms.
A frame consists of a list of rectangles, each of which represents the
component-wise difference between the previous frame and the current
using a run-length encoding. The initial frame is decoded against a
previous frame of all 0x00000000 pixels. Each rectangle starts out
with
int32_t x1
int32_t y1
int32_t x2
int32_t y2
followed by (x2 - x1) * (y2 - y1) pixels, run-length encoded. The
run-length encoding uses the 'X' channel in the pixel format to encode
the length of the run. That is for WCAP_FORMAT_XRGB8888, for example,
the length of the run is in the upper 8 bits. For X values 0-0xdf,
the length is X + 1, for X above or equal to 0xe0, the run length is 1
<< (X - 0xe0 + 7). That is, a pixel value of 0xe3000100, means that
the next 1024 pixels differ by RGB(0x00, 0x01, 0x00) from the previous
pixels.
