blob: 0c0d0f0ced8c17ccbaad60464db105076e10b5b6 [file] [log] [blame]
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -04001WCAP Tools
2
3WCAP is the video capture format used by Weston (Weston CAPture).
4It's a simple, lossless format, that encodes the difference between
Peng Wu3cd1f862013-07-11 15:19:53 +08005frames as run-length encoded rectangles. It's a variable framerate
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -04006format, that only records new frames along with a timestamp when
7something actually changes.
8
9Recording in Weston is started by pressing MOD+R and stopped by
10pressing MOD+R again. Currently this leaves a capture.wcap file in
11the cwd of the weston process. The file format is documented below
Kristian Høgsbergc12efd02012-07-18 11:39:05 -040012and Weston comes with the wcap-decode tool to convert the wcap file
13into something more usable:
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -040014
Kristian Høgsbergc12efd02012-07-18 11:39:05 -040015 - 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.
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -040019
Kristian Høgsbergc12efd02012-07-18 11:39:05 -040020 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:
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -040024
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
Kristian Høgsbergc12efd02012-07-18 11:39:05 -040031 - 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).
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -040036
Kristian Høgsbergc12efd02012-07-18 11:39:05 -040037 Using vpxenc to encode a webm file would look something like this:
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -040038
Kristian Høgsbergc12efd02012-07-18 11:39:05 -040039 [krh@minato weston]$ wcap-decode --yuv4mpeg2 ../capture.wcap |
40 vpxenc --target-bitrate=1024 --best -t 4 -o foo.webm -
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -040041
Kristian Høgsbergc12efd02012-07-18 11:39:05 -040042 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:
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -040045
Kristian Høgsbergc12efd02012-07-18 11:39:05 -040046 [krh@minato weston]$ wcap-decode ../capture.wcap --yuv4mpeg2 |
47 theora_encode - -o cap.ogv
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -040048
49
50WCAP File format
51
52The file format has a small header and then just consists of the
Abdur Rehman1580e702017-01-01 19:46:45 +050053individual frames. The header is
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -040054
55 uint32_t magic
56 uint32_t format
57 uint32_t width
58 uint32_t height
59
60all CPU endian 32 bit words. The magic number is
61
62 #define WCAP_HEADER_MAGIC 0x57434150
63
64and makes it easy to recognize a wcap file and verify that it's the
65right 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
72Each frame has a header:
73
74 uint32_t msecs
75 uint32_t nrects
76
77which specifies a timestamp in ms and the number of rectangles that
78changed since previous frame. The timestamps are typically just a raw
79system timestamp and the first frame doesn't start from 0ms.
80
81A frame consists of a list of rectangles, each of which represents the
Kristian Høgsberg86aa5fb2012-05-30 13:00:54 -040082component-wise difference between the previous frame and the current
Kristian Høgsbergdb0623a2012-05-29 11:36:27 -040083using a run-length encoding. The initial frame is decoded against a
84previous frame of all 0x00000000 pixels. Each rectangle starts out
85with
86
87 int32_t x1
88 int32_t y1
89 int32_t x2
90 int32_t y2
91
92followed by (x2 - x1) * (y2 - y1) pixels, run-length encoded. The
93run-length encoding uses the 'X' channel in the pixel format to encode
94the length of the run. That is for WCAP_FORMAT_XRGB8888, for example,
95the length of the run is in the upper 8 bits. For X values 0-0xdf,
96the 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
98the next 1024 pixels differ by RGB(0x00, 0x01, 0x00) from the previous
99pixels.