1 <!-- Author's note; this was intended to become a home page at some point,
2 but I'm not interested enough in grokking HTML right now, so it became
3 the README instead. Most of it should be valid Markdown. -->
8 Movit is the Modern Video Toolkit, notwithstanding that anything that's
9 called “modern” usually isn't, and it's really not a toolkit.
11 Movit aims to be a _high-quality_, _high-performance_, _open-source_
12 library for video filters.
15 TL;DR, please give me download link and system demands
16 ======================================================
20 * A C++11 compiler. GCC will do. (I haven't tried Windows, but it
21 works fine on Linux and OS X, and Movit is not very POSIX-bound.)
23 * A GPU capable of running OpenGL 3.0 or newer. GLES3 (for mobile devices)
25 * The [Eigen 3], [FFTW3] and [Google Test] libraries. (The library itself
26 does not depend on the latter, but you probably want to run the unit tests.)
27 If you also have the Google microbenchmark library, you can get some
29 * The [epoxy] library, for dealing with OpenGL extensions on various
32 Movit has been tested with various Intel, AMD and NVIDIA GPUs, on Linux
33 and Windows. Again, most likely, GPU compatibility shouldn't be a big issue.
34 See below for performance estimates.
37 Still TL;DR, please give me the list of filters
38 ===============================================
40 Blur, diffusion, FFT-based convolution, glow, lift/gamma/gain (color
41 correction), mirror, mix (add two inputs), luma mix (use a map to wipe between
42 two inputs), overlay (the Porter-Duff “over” operation), scale (bilinear and
43 Lanczos), sharpen (both by unsharp mask and by Wiener filters), saturation
44 (or desaturation), vignette, white balance, and a deinterlacer (YADIF).
46 Yes, that's a short list. But they all look great, are fast and don't give
47 you any nasty surprises. (I'd love to include denoise and
48 framerate up-/downconversion to the list, but doing them well are
49 all research-grade problems, and Movit is currently not there.)
52 TL;DR, but I am interested in a programming example instead
53 ===========================================================
55 Assuming you have an OpenGL context already set up (either a classic OpenGL
56 context, a GL 3.x forward-compatible or core context, or a GLES3 context):
59 using namespace movit;
60 EffectChain chain(1280, 720);
62 ImageFormat inout_format;
63 inout_format.color_space = COLORSPACE_sRGB;
64 inout_format.gamma_curve = GAMMA_sRGB;
65 FlatInput *input = new FlatInput(inout_format, FORMAT_BGRA_POSTMULTIPLIED_ALPHA, GL_UNSIGNED_BYTE, 1280, 720));
66 chain.add_input(input);
68 Effect *saturation_effect = chain.add_effect(new SaturationEffect());
69 saturation_effect->set_float("saturation", 0.7f);
71 Effect *lift_gamma_gain_effect = chain.add_effect(new LiftGammaGainEffect());
72 const float gain[] = { 0.8f, 1.0f, 1.0f };
73 lift_gamma_gain_effect->set_vec3("gain", &gain);
75 chain.add_output(inout_format, OUTPUT_ALPHA_FORMAT_POSTMULTIPLIED);
79 // Do whatever you need here to decode the next frame into <pixels>.
80 input->set_pixel_data(pixels);
81 chain.render_to_screen();
86 OK, I can read a bit. What do you mean by “modern”?
87 ===================================================
89 Backwards compatibility is fine and all, but sometimes we can do better
90 by observing that the world has moved on. In particular:
92 * It's 2018, so people want to edit HD video.
93 * It's 2018, so everybody has a GPU.
94 * It's 2018, so everybody has a working C++ compiler.
95 (Even Microsoft fixed theirs around 2003!)
97 While from a programming standpoint I'd love to say that it's 2018
98 and interlacing does no longer exist, but that's not true (and interlacing,
99 hated as it might be, is actually a useful and underrated technique for
100 bandwidth reduction in broadcast video). Movit may eventually provide
101 limited support for working with interlaced video; it has a deinterlacer,
102 but cannot currently process video in interlaced form.
105 What do you mean by “high-performance”?
106 =======================================
108 Today, you can hardly get a _cellphone_ without a multi-core, SIMD-capable
109 CPU, and a GPU. Yet, almost all open-source pixel processing I've seen
110 is written using straight-up single-threaded, scalar C! Clearly there is
111 room for improvement here, and that improvement is sorely needed.
112 We want to edit 1080p video, not watch slideshows.
114 Movit has chosen to run all pixel processing on the GPU, mostly using GLSL
115 fragment shaders. While “run on the GPU” does not equal “infinite speed”,
116 GPU programming is probably the _simplest_ way of writing highly parallel code,
117 and it also frees the CPU to do other things like video decoding.
119 Although compute shaders are supported, and can be used for speedups if
120 available (currently, only the deinterlacer runs as a compute shader), it is
121 surprisingly hard to get good performance for compute shaders for anything
122 nontrivial. This is also one of the primary reasons why Movit uses GLSL and
123 not any of the major GPU compute frameworks (CUDA and OpenCL), although it
124 is also important that it is widely supported (unlike CUDA) and driver quality
125 generally is fairly good (unlike OpenCL).
127 Exactly what speeds you can expect is of course highly dependent on
128 your GPU and the exact filter chain you are running. As a rule of thumb,
129 you can run a reasonable filter chain (a lift/gamma/gain operation,
130 a bit of diffusion, maybe a vignette) at 720p in around 30 fps on a four-year-old
131 Intel laptop. If you have a somewhat newer Intel card, you can do 1080p
132 video without much problems. And on a low-range nVidia card of today
133 (GTX 550 Ti), you can probably process 4K movies directly.
136 What do you mean by “high-quality”?
137 ===================================
139 Movit aims to be high-quality in two important aspects, namely _code quality_
140 and _output quality_. (Unfortunately, documentation quality is not on the
147 Movit works internally in linear floating-point all the way, strongly
148 reducing interim round-off and clipping errors. Furthermore, Movit is
149 (weakly) colorspace-aware. Why do colorspaces matter? Well, here's a video frame from a typical
150 camera, which records in Rec. 709 (the typical HDTV color space), and here's the
151 same frame misinterpreted as Rec. 601 (the typical SDTV color space):
153 [insert picture here]
155 The difference might be subtle, but would you like that color cast?
156 Maybe you could correct for it manually, but what if it happened on output
157 instead of on input? And I can promise you that once we move to more
158 wide-gamut color spaces, like the one in Rec. 2020 (used for UHDTV), the
159 difference will be anything but subtle. As of [why working in linear
160 light matters](http://www.4p8.com/eric.brasseur/gamma.html),
161 others have explained it better than I can; note also that this makes Movit
162 future-proof when the world moves towards 10- and 12-bit color precision
163 (although the latter requires Movit to change from 16-bit to 32-bit floating
164 point, it is a simple switch). The extra power from the GPU makes all of this
165 simple, so do we not need to make too many concessions for the sake of speed.
167 Movit does not currently do ICC profiles or advanced gamut mapping;
168 if you have out-of-gamut colors, they will clip. Sorry.
171 OK, and high-quality code?
172 ==========================
174 Image processing code can be surprisingly subtle; it's easy to write
175 code that looks right, but that makes subtle artifacts that explode
176 when processed further in a later step. (Or code that simply never
177 worked, just that nobody cared to look at the output when a given
178 parameter was set. I've seen that, too.)
180 Movit tries to counteract this by three different strategies:
182 * First, _look at the output_. Does it look good? Really?
183 Even if you zoom in on the results? Don't settle for “meh, I'm
184 sure that's the best it can get”.
185 * Second, _keep things simple_. Movit does not aim for including
186 every possible video effect under the sun (there are [others out there]
187 that want that); the [YAGNI] principle is applied quite strongly throughout
188 the code. It's much better to write less code but actually
189 understand what it does; whenever I can replace some magic matrix
190 or obscure formula from the web with a clean calculation and a descriptive
191 comment on top, it makes me a bit happier. (Most of the time,
192 it turns out that I had used the matrix or formula in a wrong
193 way anyway. My degree is in multimedia signal processing, but it
194 does not mean I have a deep understanding of everything people do
196 * Third, _have unit tests_. Tests are boring, but they are unforgiving
197 (much more unforgiving than your eye), and they keep stuff from breaking
198 afterwards. Almost every single test I wrote has uncovered bugs in Movit,
199 so they have already paid for themselves.
201 There is, of course, always room for improvement. I'm sure you can find
202 things that are stupid, little-thought-out, or buggy. If so, please let me
206 What do you mean by “open-source”?
207 ==================================
209 Movit is licensed under the [GNU GPL](http://www.gnu.org/licenses/gpl.html),
210 either version 2 or (at your option) any later version. You can find the full
211 text of the license in the COPYING file, included with Movit.