This is a project that uses the official Blackmagic Raw SDK to decode a
*.braw file in a way that can be read by FFmpeg. The goal of the project is to allow unattended, headless, conversion of
*.braw files into other file formats.
I'll start right off by showing you some examples of how the
braw-decode program may be used.
Generate proxy editing files:
braw-decode -s 2 sample.braw | ffmpeg -y -i sample.braw $(braw-decode -s 2 -f sample.braw) \ -map 1:v:0 -map 0:a:0 -c:a copy \ -c:v dnxhd -vf "scale=1280:720,format=yuv422p" -b:v 60M output.mov
Convert to 10b 32Mbps h265 for archiving using NVENC using 16 bit source:
braw-decode -v -c 16pl sample.braw | ffmpeg -y -i sample.braw $(braw-decode -c 16pl -f sample.braw) \ -map 1:v:0 -map 0:a:0 -c:a copy \ -c:v hevc_nvenc -b:v 32M -profile:v rext output.mov
braw-decode has two main purposes in the conversion process.
- Decode the
*.brawfile into a format FFMpeg can read
- Provide FFmpeg with the parameters to interpret the decoded data
The first stage of
braw-decode will read a
*.braw as pure RGB data out to the standard CLI output. This is intended to be piped directly to FFmpeg. Running
braw-decode without piping it to FFmpeg will have unintended consequences as it will print all command characters that happen to be in the
*.braw file without escaping them.
The second stage prints the parameters needed for FFmpeg to read them decoded data. The program controls the following parameters:
-f rawvideo: Tells
ffmpegthat it will be decoding a raw data stream
-pixel_format: The layout and bit depth of the data stream
-s: The intended resolution of the incoming data stream
-r: The intended frame rate of the incoming data stream
-i pipe:0: Tells
ffmpegto read the data from
-filter:v colorchannelmixer=0:1:0:0:0:0:1:0:1:0:0:0: Needed to correct color channels*
*FFmpeg does not have a planar 16 bit format in RGB channel sequence. The
colorchannelmixer is used to correct the colors as a filter stage
You may choose not to use
braw-decode to control the input parameters but you will need to specify them manually in its place.
braw-decode does nothing with audio at all as it is not needed.
*.braw files use the
mov container format and a standard
pcm_s24le audio stream. This can be read directly by FFmpeg without conversion by using a
*.braw file as an input and mapping its audio channel to the output. The examples demonstrate this.
Some options of the Blackmagic Raw SDK that control the decoding of
*.braw files have been exposed as arguments for
braw-decode. The following complete listing of the arguments may be printed at any time by running
braw-decode - BRAW file decoder Usage: braw-decode sample.braw | ffmpeg -y $(braw-decode -f sample.braw) -c:v hevc_nvenc output.mov -n, --info Print details of clip -v, --verbose Print more information to CERR while processing -f, --ff-format Print FFmpeg arguments for processing decoded video Example: '-f rawvideo -pixel_format rgba -s 3840x2160 -r 60 -i pipe:0` -h, --help Print help text -c, --color-format [VALUE] Bit depth and order of color information to be output: Options: rgba - Unsigned 8bit interleaved RGBA (FFmpeg format: rgba) bgra - Unsigned 8bit interleaved BGRA (FFmpeg format: bgra) 16il - Unsigned 16bit interleaved RGB (FFmpeg format: rgb48le) 16pl - Unsigned 16bit planar RGB (FFmpeg format: gbrp16le) f32s - Floating point interleaved RGB f32p - Floating point planar RGB f32a - Floating point interleaved BGRA -t, --threads [VALUE] Number of CPU threads to use for decoding -i, --in [VALUE] Start frame index for decoding -o, --out [VALUE] End frame index for decoding -s, --scale [VALUE] Scale input video down by this factor. WARNING: Only the 8bit color formats at half scale seem to work Options: 1 2 4 8
Most of these are well enough documented there but some could use additional information:
Verbose mode in
braw-decode must print messages to
stdout is used to send data to FFmpeg. Additionally it will print real time information about the current frame and active number of CPU threads on a single line intended to provide more information alongside the normal FFmpeg encoding status.
All supported methods of decoding
*.braw files supported by the SDK have been made available, but not all are compatible with FFmpeg.
rawvideo sources must be explicitly decoded in specific ways. While FFmpeg has support for 32 bit floats, in my testing none of the available formats match those used in the SDK. As such they should be considered non-functional when using
braw-decode with FFmpeg.
Additionally, as mentioned in Usage, the 16 bit planar format that FFmpeg supports is BGR formatted while the SDK outputs in RGB. This can be corrected after encoding or as a filter stage though so it has been marked as compatible. I felt this to be important as the 16 bit planar format is faster than the interleaved format based on my testing.
The scale option is handled by the SDK which is important because it means less data is sent over
stdout improving performance. But in my testing the scale feature has issues with all color formats except the 8 bit ones and only 2 or half scaling works with that. As such I consider the scaling option really only usable for generating proxy files due to the lower quality, but this still has real world use so it has been left in.
The remaining scale factors have been included in the program in the hopes that an updated SDK revision will correct the issues.
Decoding Compute Source and Platforms Supported
The Blackmagic Raw SDK supports CPU, OpenCL, CUDA, and Metal decoding. As of right now
braw-decode only supports CPU decoding. The SDK does not come with examples that demonstrate OpenCL or Metal configurations and I have been told by Blackmagic that the CUDA sample is not configured correctly. Once an sample of how to configure the hardware accelerated decoding methods is available it will be added.
braw-decode has only been compiled for and tested with Linux. It should be possible to build versions for Windows and MacOS as the SDK is available for both platforms. I will be starting development and testing on a Windows version when time is available. I cannot produce and test a MacOS version as I do not own a sufficiently new enough Apple computer to work with.
Compiling and Setting Up
The Blackmagic Raw SDK is the only dependency needed to compile
braw-decode. It is available from Blackmagic here: https://www.blackmagicdesign.com/products/blackmagicraw
braw-decode was developed using Version 2.2 of the SDK and the it has changed multiple times so the following may need to be updated for later versions.
Setting up the SDK
- Extract the downloaded Blackmagic_RAW_Linux_..tar.gz |
tar -xzf Blackmagic_RAW_Linux*.tar.gz
- Open the Blackmagic RAW folder and extract the rpm |
cd Blackmagic\ RAW && rpm2cpio *.rpm | cpio -idmv
- Go to usr/lib64/blackmagic/BlackmagicRAWSDK/Linux/ |
- Copy the contents of the Include and Libraries folders to the one for
You are now ready to build
braw-decode. The only step needed is:
You should now have a
braw-decode executable to run!
A note though, by default
braw-decode looks for the "Libraries" folder in the path that it is called from. So if you don't run it from the folder with "Libraries" in it it will crash. If you want make the program for from anywhere you need to copy contents of the Libraries folder somewhere like
/opt/brawsdk/ and change the path in
braw.h that is assigned to
lib on line 113 and recompile. With a full path it can find the files from anywhere.