| 41 | | [[BR]] |
| 42 | | FFmpeg stores all these properties in the [https://ffmpeg.org/doxygen/trunk/structAVFrame.html AVFrame] struct: |
| 43 | | |
| 44 | | - The format (type and bit-depth), in AVFrame->[https://ffmpeg.org/doxygen/trunk/structAVFrame.html#aed14fa772ce46881020fd1545c86432c format] |
| 45 | | - The signal range, in AVFrame->[https://ffmpeg.org/doxygen/trunk/structAVFrame.html#a853afbad220bbc58549b4860732a3aa5 color_range] |
| 46 | | - The YUV/RGB transformation matrix, in AVFrame->[https://ffmpeg.org/doxygen/trunk/structAVFrame.html#a9262c231f1f64869439b4fe587fe1710 colorspace] |
| 47 | | - The linearization function (a.k.a. transformation characteristics), in AVFrame->[https://ffmpeg.org/doxygen/trunk/structAVFrame.html#ab09abb126e3922bc1d010cf044087939 color_trc] |
| 48 | | - The RGB/XYZ matrix, in AVFrame->[https://ffmpeg.org/doxygen/trunk/structAVFrame.html#a59a3f830494f2ed1133103a1bc9481e7 color_primaries] |
| 49 | | |
| 50 | | == How to convert between colorspaces using FFmpeg? == |
| 51 | | |
| 52 | | Conversion between RGB/YUV is typically done using swscale. Conversion between different color properties (bit-depth, range, matrix, transfer characteristics, primaries) can be done using the [https://ffmpeg.org/ffmpeg-filters.html#colorspace colorspace] or [https://ffmpeg.org/ffmpeg-filters.html#colormatrix colormatrix] video filter. There's also a filter using the external library [https://ffmpeg.org/ffmpeg-filters.html#zscale zscale]. (for both aforementioned purposes) ^(...and seems to be a more reliable choice for all these swscale hazards)^ |
| 53 | | [[BR]] |
| 54 | | [[BR]] |
| 55 | | [[BR]] |
| 56 | | Video filter `colorspace`, `colormatrix` have the following relationship: |
| 57 | | |
| 58 | | - They both do only YUV to YUV colorspace conversion; YUV to RGB, and scaling requires swscale. |
| 59 | | - `colormatrix` supports only 8bpc (8-bit per component) pixel formats, whereas `colorspace` supports 10bpc, 12bpc also. |
| 60 | | - `colormatrix` does not apply gamma and primaries (i.e. which exact color "red", "green", and "blue" each is) correction, whereas `colorspace` does (it has an option `fast=1` to disable this if you want faster conversion, or compatible output with that produced by `colormatrix`).[[BR]]Note: the examples are significantly worse with `fast=0` than with `fast=1`. This is because screenshot sRGB is incorrectly specified as BT. 601, while it should have been `ispace=bt709:itrc=srgb`. Don't repeat this mistake! |
| 61 | | - `colormatrix` is C only, whereas `colorspace` uses x86 SIMD (i.e. it's faster). |
| 62 | | [[BR]] |
| 63 | | Anyway the major difference between them is `colormatrix` produces horrible quality for anything > 8bpc (8-bit per component)... while `colorspace` produces something decent, at least for 10bpc (for 8bpc they both produce similar bad quality... probably due to improper design in the algorithms). ^(floor instead of round on color approximation?..)^[[BR]] |
| 64 | | Anyway for 8bpc... `colorspace` still seems to produce slightly better quality than `colormatrix` (while it's pointless... as doing things in 10bpc first, then 10bpc -> 8bpc seems to be a better approach... if you don't mind dithering). ^([https://trac.ffmpeg.org/ticket/4614 dithering is enforced in swscale YUV 10bpc -> 8bpc])^ |
| 65 | | |
| 66 | | Read the filters' respective documentation to read up exactly on how to use them. |
| 67 | | |
| 68 | | === `-colorspace` and friends === |
| 69 | | The easiest way to use these filters is to ensure that the input AVFrames have all relevant struct members set to the appropriate values. On ffmpeg command-line this is what options such as `-colorspace` and `color_trc` do; you can also put them on the output side to modify what space the output is in. |
| 70 | | |
| 71 | | If everything goes well, `swscale` figures out how to do the conversion and you can avoid calling the filter manually. However, AVFrames does not cover every option needed, so advanced use will go back to `-vf colorspace` or `-vf zscale`. |
| | 38 | |
| | 39 | FFmpeg stores these properties in the [https://ffmpeg.org/doxygen/trunk/structAVFrame.html AVFrame] struct: |
| | 40 | |
| | 41 | - The format (type and bit-depth)->[https://ffmpeg.org/doxygen/trunk/structAVFrame.html#aed14fa772ce46881020fd1545c86432c format] |
| | 42 | - The signal range->[https://ffmpeg.org/doxygen/trunk/structAVFrame.html#a853afbad220bbc58549b4860732a3aa5 color_range] |
| | 43 | - The YUV/RGB transformation matrix->[https://ffmpeg.org/doxygen/trunk/structAVFrame.html#a9262c231f1f64869439b4fe587fe1710 colorspace] |
| | 44 | - The linearization function (a.k.a. transformation characteristics)->[https://ffmpeg.org/doxygen/trunk/structAVFrame.html#ab09abb126e3922bc1d010cf044087939 color_trc] |
| | 45 | - The RGB/XYZ matrix->[https://ffmpeg.org/doxygen/trunk/structAVFrame.html#a59a3f830494f2ed1133103a1bc9481e7 color_primaries] |
| | 46 | |
| | 47 | == How to use FFmpeg to convert the colorspace == |
| | 48 | |
| | 49 | Pixel format conversion is often performed by [https://ffmpeg.org/libswscale.html libswscale], which you will most likely access through the [https://ffmpeg.org/ffmpeg-scaler.html FFmpeg Scaler] or the scale [https://ffmpeg.org/ffmpeg-filters.html#scale-1 video filter]. |
| | 50 | |
| | 51 | Other video filters include: |
| | 52 | - `colormatrix` ([https://ffmpeg.org/ffmpeg-filters.html#colormatrix native]) |
| | 53 | - `colorspace` ([https://ffmpeg.org/ffmpeg-filters.html#colorspace native]) |
| | 54 | - `zscale` ([https://ffmpeg.org/ffmpeg-filters.html#zscale z.lib library]) |
| | 55 | |
| | 56 | === Comparing and contrasting `colorspace`, `colormatrix`, libswscale, and `zscale` === |
| | 57 | |
| | 58 | - `colorspace` and `colormatrix` can only convert YUV to YUV |
| | 59 | - libswscale can convert between YUV and RGB |
| | 60 | - `colormatrix` only supports 8bpc (8-bit per component) pixel formats |
| | 61 | - `colorspace` supports 8bpc, 10bpc, and 12bpc |
| | 62 | - `colormatrix` does not apply gamma and primaries correction (i.e. which exact color "red", "green", and "blue" each is) |
| | 63 | - `colorspace` applies gamma and primaries correction by default. (Use `fast=1` to disable this for faster conversion or to make output compatible with output produced by `colormatrix`.) |
| | 64 | - `colormatrix` is C only, whereas `colorspace` uses x86 SIMD so it's faster |
| | 65 | - `colormatrix` produces horrible quality for 10bpc and 12bpc |
| | 66 | - `colorspace` produces something decent for 10bpc |
| | 67 | - For 8bpc, `colorspace` seems to produce slightly better quality than `colormatrix` |
| | 68 | - `zscale` produces better results at all bit depths |
| | 69 | |
| | 70 | === `colorspace` and friends === |
| | 71 | The easiest way to use these filters is to ensure that the input AVFrames have all relevant struct members set to the appropriate values. On ffmpeg command-line this is what options such as `colorspace` and `color_trc` do; you can also put them on the output side to modify what space the output is in. |
| | 72 | |
| | 73 | If everything goes well, libswscale figures out how to do the conversion and you can avoid calling the filter manually. However, AVFrames does not cover every option needed, so advanced use will go back to `colorspace` or `zscale`. |
