Open Source FFV1 video capture workflow for MacOS

I thought I’d document our leap into open source software here at the Media Archive for Central England (MACE).  We’ve been capturing SD PAL video to v210 uncompressed MOV on a Mac Pro 5,1 since around 2011.  The Mac has a Black Magic Decklink Duo (1) card and software that includes Black Magic Media Express and Premiere Pro for capturing our Serial Digital Interface (SDI) feed.  In recent months we’ve made this move to open source tools following a decision to encode our digital video assets to FFV1 version 3 in a Matroska wrapper.  This decision was informed in part by the BFI’s lead to use this codec and wrapper for their forthcoming mass video tape digitisation project, and research and light testing I had already carried out into FFmpeg/FFV1, informed by the following documents:

• Indiana University Media Digitization and Preservation Initiative
• VIAA Preservation Reformatting, by Jérôme Martinez and Dave Rice

FFV1 is an amazing lossless video codec developed by the maker of FFmpeg that saves around 40-50% (sometimes up to 70%) file size without losing any valuable data. For a more thorough explanation read the Wikipedia FFV1 page or take a look at FIAF’s recommended FFV1 reading list.   The additional brilliance of the codec is its ability to store CRC32 checksums in every slice of a frame.  To perform a fixity check of the file you just need to decode the video with FFmpeg again, and to display any FFV1 CRC mismatches in the terminal window use a command like the example below (credit and full instruction available at ffmprovisr).

ffmpeg -report -i input_file.mkv -f null -

Matroska is a really successful wrapper that can store an insanely high number of video, audio and subtitle streams as one file.  The principal interest for me is it allows embedding of capture log files when used with vrecord.  It’s an open format with a proven reputation like FFmpeg, and has alternative versions that can handle audio only files (mka), subtitles (mks) and stereoscopic video (mk3d).  We’ve only used .mkv so far.

Vendors we’ve used traditionally, such as Adobe and Black Magic, don’t support FFV1 natively – yet – though you can get a plug in for Premiere called DirectShow but I’ve not tried it.  That aside, for sustainability reasons it’s logical to participate and support the free and open source software (FOSS) community who create excellent archival tools across the board.  In this blog I’ll discuss installation and basic usage of the following tools:

• Homebrew – package installation manager
• FFmpeg – super fast encoding
• QCTools – quality control tools for video
• vrecord – AMIA Open Source video capture
• MPV – cross-platform media player
• Shotcut – cross-platform video editor

Some experience with command line and Terminal is required for installing the software, and operating FFmpeg and vrecord.  QCTools, MPV and Shotcut can be used via Terminal or entirely GUI based, and are very user friendly.  My MPV configuration requires command line operation and is a little more work, due to a really good GitLab plugin called excerpt.lua – more later.

Following are three chapters that cover the steps taken to implement our new FOSS capture workflow:

• Mac 5,1 upgrade and installations
  – Including separate installation instructions
  – Learn to love GitHub
• The Workflow
• Conclusion

Mac Pro 5,1 upgrade and installations

Everyone knows the MacPro 5,1 ‘cheese grater’ is the best Mac ever! Prior to installing the new software we upgraded both of our office’s Macs to High Sierra 10.13.  We immediately noticed decreased processor performance that included dropping frames mid-capture using Black Magic Media Express, but vrecord has been capturing really well with only occasional dropped frames. Following conversations with members of the MacProUpgrade group on Facebook (excellent resource if you want to upgrade your 5,1 tower) we’ve decided to prioritise upgrading the CPUs to x5680s which will double processing power.  Hopefully this will happen in coming weeks, with SSD boot disks and GPU upgrades to follow in time.

I’ve broken up the installation processes below to make them easier to navigate depending on what you do, and don’t need to know.  Please note this blog will age and the install codes that follow will inevitably get updated elsewhere, so you should double check with GitHub or AMIA Open Source sites for latest install data. Links to the development sites are given with each item.

Install Homebrew

Homebrew is a package manager that makes installing via command line really simple, with little to no experience needed.  For Mac OS all you need to do is open terminal (found in the Applications/Utilities folder) and type the following code:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

To double check this install code visit the Hombrew site.  When you use it to install something using the simple command ‘brew install…’ the first action of Terminal will be to update Homebrew. Don’t worry about this as it’s a brilliant feature that means you don’t have to worry about staying on top of the software’s currency.  Installing Homebrew first is a must for the following installs.

Install FFmpeg

I added FFmpeg using the code recommended on ffmprovisr (Feb 2019), a wonderful guide to FFmpeg developed for archivists, by archivists:

brew install varenc/ffmpeg/ffmpeg --with-openjpeg --with-rubberband --with-tesseract

QCTools, vrecord, Shotcut and MPV all rely on FFmpeg being present on your Mac, so ideally you should make this the next install after Homebrew.  For alternative install instructions for all operating systems take a look at the official FFmpeg guide.

Learning to love GitHub

Before using the following items I had to bite the bullet and sign up to GitHub (QCTools GitHub page shown below) so that I could follow developments to the open source software I was about to download.  Owing to the nature of open source being free to use and develop, code can change quite frequently. Bugs appear and get fixed, new and better GUIs appear, general improvements occur.  I didn’t realise this at first, but you should try to follow developments to ensure you’re always using the best version of your software.  Don’t be put off though, it’s actually a great way to learn how open source works by following conversations between testers and developers.

If you experience any issues while using the software yourself you can report this to the developers in the form of raising an ‘Issue’.  To follow developments ‘Watch’ a project and you’ll receive email notifications every time something is developed or amended. I still find it intimidating to use and I’m very aware of the holes in my technical understanding and vocabulary when trying to raise an issue, but my experience has always been positive and developers really appreciate your input.  Bonus, I’ve found that they’re a really great bunch of people!

Install QCTools

This is a simple four word command in terminal:

brew cask install qctools

Hit return after you’ve typed this and Terminal will start installing the software. Don’t close the Terminal window at any point when installing or operating commands. When it has finished you’ll be returned to blank prompt which is your Mac name and ends with $ symbol.  Caskroom installation to /usr/local/ required a password verification (see terminal display below) which you type blind into the terminal window.  Once installed I dragged an alias of the QCTools software from the Applications folder to my pop up and now I can launch the GUI any time.  For install support see the QCTools GitHub.

Install vrecord

vrecord requires a few lines of code. The first taps the homebrew recipes of the AMIA Open Source GitHub amiaos, and the second installs vrecord and additional software required to run all vrecord features.  I wait for the first to finish before starting the second line of code.

brew tap amiaopensource/amiaos
brew install vrecord

Next you need to separately install gnuplot which outputs a JPEG image of a QC graph (you really want this jpeg so make sure you don’t skip this part):

brew install gnuplot --without-lua

[Update 3rd April, 2019: To illustrate the fluidity of open source, this command has just been updated in vrecord by Reto Kromer, due to changes in HomeBrew. The code needed now is just “brew install gnuplot”. See the GitHub issue no. 421 raised by Callie Holmes for more info here].

And finally the vrecord install guidelines recommend running an upgrade command to make sure you have the latest version of the software:

brew upgrade vrecord

Vrecord wont provide you with an icon to load the GUI, you will need to launch the GUI from command line using:

vrecord -g

Install MPV

The first stage of installing MPV is straightforward:

brew cask install mpv

Installation has had two outcomes on two different Macs for me, which I’ve discovered is to do with the use of cask in the install command. You can install it with the standard brew install mpv, but it wont appear in your Applications folder, so make sure you include cask if you want to launch it from desktop.  In researching this blog I’ve learnt that adding cask allows management of graphical applications through the Cask project. Full install instructions can be found at https://mpv.io/installation/.

For using MPV as a basic editing tool I had to also install excerpt_lua (GitLab page shown above) which requires command line for operation and is a little more complicated.  You also need to have MPV and FFmpeg already installed before beginning.  I downloaded the source code zip file using the cloud symbol at the top right of the page, next to Find file.  I unzipped the folder and copied it to /usr/local/bin (you can navigate to this using Finder > Go > Go to folder) and then had to edit two files.  You can unpack this folder and operate the commands anywhere, I just like it in this location as it’s neat.  Firstly I opened excerpt_lua in a text editor and looked for the “.mp4” on line 126 of the file and changed it to “.mkv”.  Secondly I opened the excerpt_copy file in a text editor and changed this line of code

ffmpeg -y -nostdin -ss $BEGIN -i "$SRC" -t $DURATION -codec:v copy -codec:a copy -codec:d copy \

to

ffmpeg -y -nostdin -ss $BEGIN -i "$SRC" -t $DURATION -c copy -map 0 \

This basically tells the encoder to make a straight copy of the file and the -map 0 call ensure that all streams of the file and wrapper are mapped to the new file.

Install Shotcut

brew cask install shotcut

A nice simple install this one, Shotcut will add an icon to your Applications folder which you can easily launch and run.  As with other open source software, Shotcut is undergoing constant code review, there’s even a warning currently on their GitHub site so make sure you run an upgrade command from time to time.

The workflow

We have multiple players whose composite video and audio feeds are routed through a Kramer AV Matrix switcher into a Crystal Vision digital converter, and output as an SDI signal.  These exclusively standard definition players include One Inch, Umatic, S-VHS, VHS, Betamax, BetacamSP and DigiBeta.  Sadly we have no processing amplifier, or similar, that allows us to adjust levels at the analogue stage and quite a few of our video tapes appear outside of broadcast range when viewed in QCTools. [Note: if you know of any proc-amps in need of a new home PLEASE contact us]. 

This standard definition SDI signal feeds directly into the back of the Mac’s Decklink Duo (1) card. Traditionally this would be captured straight to v210 uncompressed using Media Express, before being transferred to a second Mac for trimming, image correction, and export for clients and preservation on LTO6 tape storage (for more on our LTO workflow visit our LTO6 blog post).  We also have a DVCam player but this routes directly into the Mac’s firewire port for capture to DV format via Premiere, so doesn’t become part of the FFV1 workflow. In addition we sometimes route our Hi8 and Video8 playback through the DVCam deck and capture via firewire. We haven’t tried this method with vrecord yet, but I hope we will soon. 8mm video tapes I’ve handled recently seem so vulnerable to snapping and shedding, and feel a bit unloved right now.

Following is a brief guide to our new FFV1 workflow with the open source software.  It’s still in development so don’t be alarmed if I update this in the future.

 

Step 1.  Launch vrecord using command line instruction

vrecord -g

This command launches the GUI immediately, but you can launch with just vrecord and it will take you to the Edit Settings. There are a few other commands including:

-e enter Edit Settings mode
-p enter Passthrough mode
-a enter Audio Passthrough mode
-x reset configuration
-v run ffmpeg with ‘-loglevel debug’
-h loads the help menu and lists all the commands

The GUI (right) gives you six options including Record, Passthrough, Audio Check, Edit Settings, Help and Documentation. We use the Passthrough to cue the tape we’re capturing. The window is virtually the same as audio check, but there’s a small horizontal audio scale at the top left of the screen, which is a little awkward for the capture technician compared to earlier NLE equivalents. At present when there’s some difficulty gauging audio levels my colleague will use Media Express to set levels before launching vrecord to make the capture.

You’ll want to edit settings before starting to record (see image below).  The FFmpeg capture settings for FFV1 using the current version of vrecord is:

-c:v ffv1 -level 3 -g 1 -slices 16 -slicecrc 1

Swiftly translated this means codec for video is ffv1, version 3. Gop is set to 1 ensuring that the compression is strictly intra-frame, multithreading slices are set to 16 and slicecrc checksums are selected.  Following some basic testing at MACE I discovered that FFV1 assets with 24 slices have marginally better playback on MACE’s quality control laptops installed with VLC, and very little size increase.  An easy little hack was required to vrecord’s code to make the change from 16 to 24 – a fact I have to remember when I next upgrade the software!   I’ve added an Issue request to vrecord’s GitHub for an option to select your FFV1 slice settings prior to capture, so watch this space. [Update 4th April, 2019: This change has been implemented by Dave Rice in vrecord and I look forward to testing slice options in the new vrecord release. Screen grab updates to follow].

Other settings we opt for include embedding digitisation logs in the matroska wrapper, creating frame level md5 checksums, and creating QCTools xml file either concurrently with the capture or afterward if your processing power is a little low.  There are two features I love about vrecord capture: a button which can scan to identify what your timecode type is; and a selection of viewing windows during record/passthrough mode. I always prefer the Broadcast Range Visual window which fills in the areas outside of broadcast range with yellow shading (see image right).  It’s a really quick way to see if your file will need any post-capture image adjustments.  You just need to add your capture and log file directories next and you can hit OK to start capture.

When you return to the GUI, hit the red record button (which closes the GUI) and wait before you press play on the tape drive as there’s some data entry requests in Terminal to deal with first.  These include specifying a name of the file and the name of the technician.  vrecord then prompts you to press enter when you’re ready to start copying, so now would be the time to start your cued tape.  Capture is in real time and there is a short period post-capture when the file’s QCTools xml is written, if you have that setting choice.

Besides all the built-in asset analysis and validation checks of the software, there’s one extra treat at the end of the process – the vrecord WARNING Cow (right) who is very happy to draw your attention to the potential faults of your capture file, be that saturation or broadcast levels out of range, or any dropped frames.  I love this cow!

---

Step 2. Access and analyse your file

Now captured the files are stored in a HDD on our capture Mac and at this point there’s some housekeeping to attend to, organising the MKV file into a folder with the sidecar logs and renaming assets. I then access the finished folder from our editing Mac, in a separate room to the capture decks. Currently I delete the VITC timecode log that’s generated as we seem unable to capture any timecode information – the fault in part is due to the first generation Decklink Duo card.  I’ve managed to test a Decklink 4K card recently and have received VITC vrecord capture from a direct SDI feed from a digibeta machine. Sadly we still can’t receive VITC from any of the decks that require composite routing through a Kramer AV Matrix Switcher or a Crystal Vision SDI converter, but this is a topic for another blog.

Following on from WARNING Cow’s advice, there’s a really helpful QCTool JPEG data graph generated during capture (see right), particularly helpful for me as I handle assets that were captured in a different room by a different technician. This provides a visual timeline of the capture file’s audio and video quality, and I generally scan Broadcast Range, Saturation Range and Peak Levels (dB) to make sure everything is sound.  If there are significant issues then I’ll load up the file into QCTools and examine the file frame by frame. Though the quality control tools available in this software are epic they far exceed my current limited understanding.  Make sure you check out the Filters view which isn’t an immediately obvious feature of the software. Here you can playback a file while watching the broadcast safety range (similar to the vrecord feature), waveform monitor, bit plane, histogram and many more.  There’s excellent accompanying documentation for this software that I need to read more thoroughly.

---

Step 3. Editing with MPV and excerpt.lua

MACE like to keep one second handlebars at the beginning and end of a video tape sequence to ensure that an asset hasn’t been accidentally cropped mid-flow.  After viewing the file in MPV to get the in/out timecode I tried editing the files in a few different softwares such as Shotcut, iFFmpeg, Premiere, but none of them preserved the capture logs embedded in the MKV wrapper.  So for a short while I used FFmpeg to edit the capture sequences using the ‘-c copy -map 0’ commands to preserve the logs. This method was really time consuming. Thankfully, I caught a casual conversation on Twitter about gapless audio support, MPV and excerpt.lua came up (thanks to @lsde @BMahol @kieranjol) and discovered that the excerpt code could be edited to make it use the ‘-c copy -map 0’ command and preserve my precious logs. Such a happy accident! To launch the MPV software though you can’t use the application icon, but need to launch it with a call on the excerpt.lua file in Terminal:

mpv --script=/path/to/excerpt.lua -fs --script-opts=osc-layout=bottombar path_to_file.mkv

The window launches as usual, but has a few extra features including the ability to allow frame by frame advancing using the arrow keys. To mark an in point press the ‘i’ and out press the ‘o’, and to start the editing process press the ‘x’ key.  You will receive this message on the screen that tells you the destination file name.  The destination of the excerpt_000.mkv will be wherever you start your command line from, so most of the time your home directory. If you want to have it in a specific place then you just need to run a command similar to this before the MPV call shown above.

cd /Volumes/Folder_of_choice/

If you inspect this file alongside the original you’ll find that the metadata is almost identical, missing only encoding date information, and the embedded log files are present shown highlighted blue.

---

Step 4. Making Shotcut mezzanine copies

I’ll keep this section brief, as I’m sure most readers of this blog will have non-linear editing (NLE) experience, and Shotcut is quite similar to a standard NLE.  To make the mezzanine file I just load the excerpt000.mkv into Shotcut which handles the FFV1 codec no problem as the software uses FFmpeg codec libraries.  In Shotcut I will fix any small problems I’ve discovered with QCTools as best I can (possibly in Da Vinci Resolve if the issues are major), and edit the audio so that it’s more viewer friendly. We really need the processing amplifier to fix the analogue signal at capture point, but this must suffice for now. Editing, trimming, adding audio and video filters are all fairly straightforward and very user friendly.

When it comes to exporting, under Presets/intermediate, at the very bottom is a begrudgingly included ProRes setting (it just feels a little unloved down there).  Selecting ProRes loads its export setting in the panel to the right of the presets, which need editing to export to 422HQ.  Make sure Format is set to MOV if that’s what you want, sometimes I’ve noticed it carries over the last wrapper extension you were using.  Beneath this there are four options Video, Codec, Audio and Other (see right).  In Video I make sure resolution is SD with correct aspect ratio and fps. Make sure interlacing is selected and set to upper for non-DV video.  Under Codec I make sure prores_ks is selected as this is the best encoder for ProRes provided by FFmpeg.  Audio settings are usually fine but worth checking they conform to your standards.   The final panel Other needs a few changes (see above): first I change vprofile=2 to vprofile=3 by clicking on it and editing, which choses the level of ProRes you want to use: 1 is LT, 2 is Standard and 3 is HQ;  second I add in map=0 at the top to ensure all streams are mapped across as needed; and third I make sure pix_fmt=yuv422p10le which ensures the file is 422 with a supported Apple pixel format.  Definitely create new presets for your codec exports though, as these alterations to the standard presets take time!

[Note: I’ve tried messing with these settings for FFV1 captures, to see if I can carry over the embedded mkv log files. Not had any luck yet!  If anyone is successful with this let me know and I’ll happily skip the MPV excerpt.lua stage for future processing all in Shotcut.]

I do like the way the exports stack up in the Jobs window, top right hand corner of the Shotcut GUI.  You can keep an eye on progress, stack up your work and watch them go.  I’ve not had too many problems working with this software, a few crashes but it’s quick to reboot and set up again. A couple of times I’ve had audio and video exports from Shotcut that are out of sync by two frames. I have had this problem with the previous v210 workflow, but would usually pick it up when the asset is on the timeline in Premiere Pro. After inspecting the asset back in Shotcut’s timeline the item has played back fine and it’s not been easy to spot the sync issue, so I am not sure where the error is occurring yet.  Either way, this led me to find a way to correct the issue with FFmpeg and I generated the code following – it slips the video stream only two frames on a 25fps timeline – having found similar solutions in blogs online:

ffmpeg -i input.mov -itsoffset 0.125 -i input.mov -map 0:v -map 1:a -c copy output.mov

If you need to use it then check out the full command instructions that I’ve added to  ffmprovisr here, which has options to slip a video stream instead of the video.

Post-Shotcut we make one more mezzanine file from the edited ProRes by dropping the files into software called iFFmpeg.  I’ve made presets to make H264 mpeg 4 viewing copies with MACE watermarks overlaid.  This software relies on FFmpeg again – but sadly it’s not free so I’ll let you discover it for yourself.

---

Conclusion

The new workflow definitely consumes a little more time than our earlier v210 workflow, but the benefits to archive practise unquestionably outweigh this small time increase. My colleagues at MACE, who more frequently capture video tape, were initially concerned about using the command line environment but have found it easier than anticipated. The one reservation is the clarity of the audio level checking, and it’s a shame to have to use Media Express for this. Perhaps there’s a function we’ve missed with vrecord that will make it easier, or there may be an alternative open source tool out there to be researched.

To have files half their uncompressed size when writing to LTO6 is a major bonus financially, and in time saved by transferring files between storage locations.  Having the potential to run fixity checks on the FFV1 codec is a big reassurance that can be executed quickly with one line of code.  Because of the relatively good playback experience on our QC laptops I’d like to think one day MACE can do away with the ProRes mezzanine level of digitised video tape assets, but this would also need a broader uptake of FFV1 by NLE vendors, so our clients can accept this format easily.

I am sure that all of the processes I’ve described above could be easily achieved using vendor software equivalents. Funding limitations experienced by many in the archiving sector means that using FOSS tools and codecs is increasingly becoming a ‘no brainer’ decision.  As I mentioned during an FFV1 roundtable at the No Time To Wait!3 conference, for me the FFV1 codec feels like a rock emerging in a sea of codec turbulence.  Sorry for the cheesy simile, but in my five years working at MACE I’ve had to re-encode up to a hundred AVI assets created in 2011 using the YUY2 codec, now only supported by one of MACE’s aging HP Z200, and no longer available anywhere online. More recently Apple’s wobble over supporting ProRes encoding on Windows systems has left many uncomfortable about their long-term choice of ProRes mezzanine copies. Personally I feel it’s a hugely positive development within the archive sector that smaller charitable archives such as MACE have a chance to adopt a lossless codec as good as FFV1, that is open source. Thousands of open source encoded digital files wont need emergency re-encoding when a vendor decides to pull the plug, and we will always be able to decode a file back to a lossless uncompressed file format – such as v210 – or find a technician somewhere who can.

More important than anything else is the sense of satisfaction you feel knowing that by using these amazing open source assets you’re helping ensure their development and survival for many years to come.  A massive thank you to all the developers whose hours of dedication have led to the creation of these excellent tools, that we are proud to be using here at the Media Archive for Central England.

With thanks to my colleagues at MACE, Dave Rice, Kieran O’Leary, Ashley Blewer, Stephen McConnachie, Andrew Sergeant, Peter Bubestinger-Steindl, Jérôme Martinez, Reto Kromer, Kieran Kunhya, Ben Turkus, and the unnamed @lsde and @ffmpeg from Twitter.  All feedback welcomed!

Additional Links

If you’re not ready to commit to copying direct to FFV1 using vrecord but want to convert from uncompressed mov using FFmpeg then take a look at Peter Bubestinger-Steindl FFV1 cheat sheet.

I’m still in the process of learning to work with the Python scripts created by Kieran O’Leary and the Irish Film Institute, but among their many excellent free python scripts is one called Normalise.py. This script transcodes single files to FFV1 Matroska and performs framemd5 validations, and displays a lossless report following transcode. More data about this amazing free resource can be found at their GitHub page here.

FFV1 is also being used for the storage of DPX scanned film using open source RAWcooked software developed by Jérôme Martinez of Media Area. Here at MACE we’ve conducted tests and the results are amazing. We hope to adopt it permanently in the very near future when final testing phases have been completed. The Irish Film Institute’s Kieran O’Leary has written a great blog  Introduction to FFV1 and Matroska for Film Scans, and the official page is available at Media Area’s site.

An excellent document written about FFV1/Matroska in 2016 by two wonderful open source gurus, Ashley Blewer and Dave Rice: Status of CELLAR: Update from an IETF Working Group for Matroska and FFV1

This link has a really nice evaluation of why you should use FFV1, should you need to compose a compelling argument: The archivist’s video codec and container FAQ

If you’re interested in any of the themes covered in this blog then you really need to attend the No Time To Wait! 4 Conference which has been scheduled to celebrate Matroska’s 17th birthday between 4th and 6th December 2019, in Budapest.

Now that you love GitHub make sure you visit AMIA Open Source’s page where there are some amazing open source tools, workflow documents, projects and people. It’s a must see if you’re from the archiving world.

MediaArea has an excellent Events page here which links to videos, slides and other content generated by some of the best archiving open source developers today.