B-Roller User Guide

Video Culling Tool for macOS

B-Roller is a video culling tool for macOS. It takes you from card dump to a folder of selects you can hand to your editor (or pull into your own NLE) without sitting through a clunky import-and-organize step first. The whole flow is keyboard-driven once you're past the import.

1. Getting Started

Open the DMG and drag B-Roller to your Applications folder. First launch, macOS will ask you to confirm. Click Open.

Apple Silicon only. B-Roller uses AVFoundation for all video work, which on Apple Silicon means GPU-accelerated playback and transcode for HEVC, ProRes, XAVC HS, and the rest of the modern camera codecs.

There's no API key, no account, no subscription. Your project files stay on your machine.

Concepts

A project is a .broller file that records every video you've imported, every rating, every subclip, and every export. It auto-saves continuously while you work.

A whole clip is a complete imported video. A subclip is a marked-in/marked-out range inside a whole clip. You can have as many subclips per video as you want, each with its own label, each independently selectable for export.

The S key flags an item for export. The R key flags it as reviewed. The X key rejects it. Rejecting clears the export flag automatically — rejected things shouldn't ship.

2. Basic Workflow

  1. Create a project. New Project → name it, pick a location.
  2. Import footage. Cmd-I → point at a folder or pick files. Copy or in-place.
  3. Cull in Review. Watch, rate, mark subclips, flag selects. Mostly keyboard.
  4. Export. Cmd-E → fast-copy or accurate-transcode → Start. You get a folder of selects plus a manifest JSON.

3. Home

New Project opens the setup form. Open Project… picks an existing .broller file. The recent-projects list shows everything you've opened, newest first.

4. Creating a Project

Project name is required. It's the default base name for the "Project name and number" export preset.

Shoot date is optional but useful as a filename token.

Client or series, Location, and Notes are free-text reference fields.

Create project folder is checked by default. It wraps your .broller file in a folder named after the project, which gives Export a sensible default destination (<projectFolder>/selects/) and keeps thumbnails / filmstrip frames in a .broller-cache/ folder next to it.

5. Importing Footage

Press Cmd-I or click Import. The import wizard has four stages.

Sources

Choose Folder… picks a folder full of clips. Choose Files… picks individual files. Scan subfolders recursively descends into every subfolder. System bundles (.fcpbundle, .photoslibrary, .git, node_modules) are skipped automatically.

Results

Every video found is listed, plus any sidecar files (.xml, .xmp, .json) that match a video by basename — including Sony's M\d\d suffix pattern (so C0020.MP4 pairs with C0020M01.XML).

Use files in place references videos at their original paths. Faster import, no extra disk usage. Right when the footage lives on a stable drive that's staying connected.

Copy to project folder copies files into a destination. Right when the originals live on a card you're going to eject, or when you want a self-contained shoot folder.

The preview list shows proposed destination filenames and flags conflicts. You can toggle rows off or override.

Importing

Per-file byte progress bar. Crash-safe: each file writes to a .tmp.<pid>.<ext> companion and atomically renames to its final name on success. A crash or power loss mid-copy leaves no half-written files at the destination.

Done

Summary screen. After import, B-Roller automatically runs a metadata and thumbnail pass: AVFoundation reads dimensions, fps, codec, and duration; AVAssetImageGenerator pulls a thumbnail from about 10% into each clip.

6. The Review View

The layout is sidebar on the left (clips + filters + search) and player on the right (video + scrubber + filmstrip + transport + inspector). Click any sidebar row to load it.

Filters (cumulative)

The pills at the top of the sidebar are AND-combined: a clip has to satisfy every active filter to be visible.

The search field matches anywhere in: filenames, notes, tags, subclip labels, subclip notes. Case-insensitive.

Keyboard shortcuts

Transport:

KeyAction
SpacePlay / pause
J / K / LRewind / pause / fast-forward (NLE-style)
, / .Step one frame back / forward
← / →Jump 5 seconds

Subclip marking:

KeyAction
iMark in-point
oMark out-point
Shift-i / Shift-oNudge in/out by one frame
EnterCommit the draft as a subclip
EscClear draft
[ / ]Jump to last subclip's in-point / out-point

Ratings:

KeyAction
0 – 5Set rating

Flags:

KeyAction
fToggle favorite
sToggle selected-for-export
rToggle reviewed
xToggle rejected (also clears S)

When a subclip is the active selection (subclip mode — see below), s, f, and 0–5 route to the subclip itself. r and x always target the parent clip — subclips don't carry reviewed/rejected flags in the schema.

The keyboard does not fire when a text field has focus (search, notes, tag entry, subclip rename) — type freely without triggering player actions.

Reviewed cascade

Any decision-action (rating > 0, favorite, selected-for-export, rejected, or creating a subclip) automatically sets the clip's R flag. Filters can then hide things you've already decided on.

Subclip mode

Click any subclip — in the sidebar, the inspector list, or the colored bars above the scrubber — and the player enters subclip mode:

Three ways to exit subclip mode:

While in subclip mode, marking new in/out points (i/o/Enter) still creates regular subclips on the parent — subclips never nest, and stored timestamps stay in absolute parent-clip coordinates.

Sidebar density

The Large thumbnails checkbox above the sidebar list flips between two layouts:

The HD badge appears next to a clip's flags when the project file points at a 1080p sibling produced by Selects Handoff (see §8).

7. Exporting

Press Cmd-E or click Export. The wizard has three stages: configure, running, done.

Configure

Output folder defaults to <projectFolder>/selects/. Choose another folder if you want.

Mode:

Output:

Include lets you toggle whole-clip selects, subclip selects, and "Export new only" (which skips already-exported items).

Subclip handles add extra time before the in-point and after the out-point. Useful for room tone or NLE re-trim. Skipped for whole-clip rows.

Naming:

The manifest preview shows every row with proposed and original filenames.

Running

Outer progress bar = overall % across rows. Inner % = current row.

Cancel is two-stage. First click is graceful: in-flight row finishes; no new rows start. Second click is hard: AVAssetExportSession.cancelExport() fires immediately and tmp files are cleaned up.

Done

Per-row Reveal in Finder. Manifest sidecar at <outputFolder>/manifest-<batchId>.json listing every attempted row's status, destination, and (where applicable) HD output and HD status.

8. Selects Handoff

Press Shift-Cmd-E or click Handoff in the header bar. Different artifact than Export: Handoff produces a portable .broller package — a complete miniature project (project file + media + cache) you can move to another machine, hand to a collaborator, or open standalone in B-Roller.

What lands in the package

<destination>/<projectName> - Selects/
├── <projectName> - Selects.broller
├── media/
│   └── <copies of selected source media + extracted subclips>
├── media/HD/                       (only when "Primary + HD" is on)
│   └── <1080p H.264 siblings>
└── .broller-cache/
    ├── thumbnails/                 (one per clip in the new project)
    ├── <videoId>/filmstrip/        (15-frame strip per new clip)
    └── subclip-thumbs/             (preserved per-subclip thumbnails)

How selects map to the new project

Source stateOutput in handoff
Clip has S flagParent clip lands as a VideoItem with all its subclip metadata preserved
Subclip has S flagSubclip is extracted as its own standalone media file with its own VideoItem (new id, fresh thumbnail + filmstrip)
Both clip + some subclips have SParent VideoItem (with all sub metadata) plus one standalone VideoItem per S-flagged sub
Only subclips have S (parent doesn't)Just the extracted-subclip VideoItems — no parent in the new project

This gives you flexibility: hand off whole rushes, hand off individual selects as standalone clips, or both. The new .broller opens in B-Roller as a normal project — extracted subclips show up in the sidebar as if they were imported.

Configure-stage options

The contents summary line shows X clips, Y subclips → Z outputs, ~size.

Source project is never modified. Handoff is purely additive — it copies / extracts from your originals.

The handle matters most for fast copy mode where GOP-snap might trim too tight. It's also useful when you're handing subclips to an editor and want to give them a little trim room on either side.

Naming

Three presets:

Keep original is the default. Whole clips keep their source filename. Subclips become <source>_subclip-N.mp4 (or the source extension under fast copy).

Project name and number renames everything sequentially. <projectName>_001.mp4, <projectName>_002.mp4, and so on. The numbering increments across the entire manifest, so a batch with 3 whole clips and 5 subclips numbers 001 through 008.

Custom exposes the granular controls if you need them: include shoot date, include detected file number (Sony C0004-style), append the original filename stem, choose between sequential and detected numbering. Most users won't need this. It's there for the cases where you do.

The preview panel updates with every change so you can see exactly what you're going to get.

Export New Selects Only

Checkbox above the manifest preview, on by default.

When on, items that have already been exported (where exportedAt is set in the project) are dimmed in the preview and excluded from the run. This is the setting that lets you cull more clips later, hit Export again, and only ship the new ones.

9. Auto-Save and Project Safety

Auto-save runs after a 250ms idle window with a 2-second hard ceiling. Saves are atomic (.tmp + rename) so a crash mid-save leaves the previous version intact.

Pre-operation backups run before Import and Export. A timestamped <projectName>.<timestamp>.broller.bak lands next to the project file. The most recent 3 backups are kept. Selects Handoff doesn't take a backup — it's purely additive.

10. Auto-Update

B-Roller checks for updates via Sparkle. The check runs at launch and weekly thereafter; you can also trigger it manually from the B-Roller menu. Updates are signed and notarized DMGs.

11. Help Menu

The Help menu has B-Roller Help which opens this guide. Useful when you're on a location shoot without internet. The cyan book icon in the header bar opens the same window.

12. Tips and Conventions

The .broller file is plain JSON. You can open it in a text editor to inspect or hand-edit (back it up first).

The .broller-cache/ folder follows your project. Thumbnails and filmstrip frames live there. Move the project, the cache moves with it. Delete the cache, B-Roller regenerates it on next open.

Sidecar files are case-preserving. A C0004.XML (uppercase) sidecar exports as <basename>.XML, not lowercased.

Rejecting clears the export flag. If you've decided not to use something, it shouldn't ship.

There's no undo for subclip deletion. Deleting a subclip is permanent. Be deliberate.

13. Troubleshooting

Import scan finds zero files

Check that the folder actually contains video files, that "Scan subfolders recursively" matches what you want, and that the files have recognized extensions (.mp4, .mov, .m4v, .mts, .mxf, .avi, .wmv, .flv, .webm).

Thumbnail or filmstrip missing

The first time a clip loads, AVFoundation generates the thumbnail and 15 filmstrip frames. If the source file is unreadable or the codec isn't supported, you'll get a placeholder. Check the source plays in QuickTime first.

Export fails with "Source asset is not compatible with preset"

The clip's codec or container doesn't pair with the AVAssetExportSession preset you picked. Try the other Mode option. ProRes RAW and some exotic 10-bit color profiles aren't all transcode-compatible yet — fast-copy works for them.

Cancel doesn't seem to do anything

Clicking Cancel once is graceful — the current row finishes. If you want immediate cancellation, click again ("Force Cancel"). The encoder kills mid-row and tmp files are cleaned up.

14. Get in Touch

B-Roller is built and maintained by Brian Paris at Sounds and Colors. If you run into something this guide doesn't cover, find a bug, or have a feature you'd like to see, send a note to ….

Real feedback from people using this in production is how the app gets better. Don't hesitate.