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.

braw-decode -v -t 4 -c bgra sample.braw | ffmpeg -i sample.braw -thread_queue_size 20 $(braw-decode -c bgra -f sample.braw) \
             -map 1:v:0 -map 0:a:0 -c:a copy \
             -c:v dnxhd -vf "scale=1920:1080,format=yuv422p" -b:v 36M "$(basename -s .braw "sample.braw").mov"

Note: There is something odd with DNxHD's color format but using bgra as the source fixes it which is fine anyway because it's a smaller data format

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

As an aside, you can also copy the BRAW timecode by running ffprobe before on the BRAW file and then setting it with ffmpeg:

# timecode parsing line
timecode="$(ffprobe $file 2>&1 | grep timecode | awk '{print $3}'| sed '1q;d')"

             # ffmpeg line, can be used with proxies and archives
             -timecode "$timecode" -metadata timecode="$timecode" \

braw-decode has two main purposes in the conversion process.

1. Decode the *.braw file into a format FFMpeg can read
2. 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 ffmpeg that 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 ffmpeg to read the data from stdin
• Optional -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 -h:

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.
        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 stderr as 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. It is also more performant than FFmpeg scaling.

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.

Currently 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.

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

1. Extract the downloaded Blackmagic_RAW_Linux_..tar.gz | tar -xzf Blackmagic_RAW_Linux*.tar.gz
2. Open the Blackmagic RAW folder and extract the rpm | cd Blackmagic\ RAW && rpm2cpio *.rpm | cpio -idmv
3. Go to usr/lib64/blackmagic/BlackmagicRAWSDK/Linux/ | cd usr/lib64/blackmagic/BlackmagicRAWSDK/Linux/
4. Copy the contents of the Include and Libraries folders to the one for braw-decode

You are now ready to build braw-decode. The only step needed is:

make

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 /usr/lib64/brawsdk/ or /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.