MediaFlowSwift

This manual is generated from the Help inside MediaFlowSwift (Help → MediaFlowSwift Help), so the two always say the same thing. It describes the current release.

MediaFlowSwift Manual

For video creators. This guide is generated from the app’s own Help (Help → MediaFlow Help), so the two always say the same thing. To change a sentence here, change it in Help and regenerate.

Contents

Getting Started

What Is MediaFlow?

What MediaFlow does for a video creator, the basic workflow from card to archive, and where to find help.

MediaFlow keeps track of the footage from a shoot. You import clips from cards, phones and folders, sort them into categories, review them, and copy them into a tidy folder structure at the project’s destination folder, ready for editing and archiving.

Key Capabilities

Basic Workflow

  1. Create or open a project
  2. Import media from your cards, phones and folders
  3. Categorize and review your clips
  4. Organize the clips to the project’s destination folder
  5. Generate a report for your editor, then archive the project

The pipeline strip under the toolbar follows these steps and always offers the next one.

First-Run Setup

The first time you open MediaFlow, a short tour explains the app. A Setup Wizard follows it with three questions: your NAS, a shared database, and where organized media goes. You can skip any of them. To answer them later, choose Settings › General › Run Setup Again…

Where to Get Help

See also: Setting Up MediaFlow, Creating a New Project, Opening an Existing Project, Understanding the Pipeline Strip, Keyboard Shortcuts Reference

Creating a New Project

Create a new empty project, or build one from a folder of media you already have without copying anything.

A project is a .vpm file that records your clips and everything you know about them. Start an empty project for a new shoot, or build one from a folder that already holds media.

New Empty Project

  1. Choose File → New Project (Cmd+N)
  2. Enter a descriptive project name
  3. Check Project location — the folder the new project folder is created in. It starts at the last location you used, or your Documents folder; click Choose… to pick another
  4. Check “Organized media goes to” — the destination Organize Media copies clips to. It starts as the new project folder; click Change… to pick another folder, or Use project folder to go back
  5. Click Create

MediaFlow creates a folder named after the project and saves the .vpm project file inside it.

An orange “This folder is on this Mac’s own drive” note appears when the destination is on this Mac’s own disk rather than an external or network volume. If that is where you want your organized media, you can ignore it.

Create from Existing Folder

  1. Choose File → Create Project From Folder (Cmd+Shift+N)
  2. Select a folder that already contains media files
  3. Choose where to save the project file. The suggested name is the folder’s name
  4. MediaFlow scans the folder, including its subfolders, and adds every supported media file to the project

The files stay where they are — nothing is copied or moved. The project takes the folder’s name, and its destination is set to the folder you saved the project file in. You can change the destination later from the sidebar.

Tip: Use Create Project From Folder when your media is already laid out the way you want and you only need MediaFlow to catalog it.

See also: Opening an Existing Project, Saving Projects, Change destination folder

Opening an Existing Project

Open a saved project from its file, from the Open Recent menu, or from the Project Browser.

Open from File

  1. Choose File → Open (Cmd+O)
  2. Navigate to the .vpm project file
  3. Click Open

Open Recent

The File → Open Recent submenu lists your recently opened projects for quick access. Choose Clear Menu at the bottom of the submenu to empty the list.

Project Browser

The Project Browser shows all known projects, including those registered in the shared database. Access it via Projects → Browse Projects (Cmd+Shift+P) or from the main screen when no project is open.

See also: Creating a New Project, Deleting a Project

Understanding the Interface

A tour of the main window: pipeline strip, sidebar, media list, preview panel and metadata panel.

The main window is divided into five areas:

Pipeline Strip (Top)

Media List (Center)

Preview Panel

Metadata Panel

Rearranging Panels

See also: What Is MediaFlow?, Understanding the Pipeline Strip, Table and Grid Views, Filtering and Searching

Understanding the Pipeline Strip

The row under the toolbar that shows how far the project has come and offers the one next action.

The pipeline strip shows the seven steps of a shoot and how much work each one still has. It runs across the top of the window whenever a project is open. Every segment is a button.

The Seven Segments

Clicking a Segment

Clicking a segment filters the media list to that step’s remaining work and reveals its one primary button on the right. Import shows all media, Categorize shows the uncategorized clips, Review shows the unrated ones and Organize shows the Not at destination smart group. Free up space, Archive and Eject leave the current filter alone because their work is not a subset of the list.

Until you click one, the strip follows the first step that still has work to do. A finished step shows a green check instead of its icon.

The Organize count turns orange once 10 or more clips are still waiting and the project has a destination.

The Old Screens

Workflow → Plan & Deliver → Project status (legacy)… and Workflow → Plan & Deliver → Project Checklist (legacy)… still open the earlier overview screens. They count categorized, organized and verified clips with the same rules the strip uses, so the three always agree.

See also: Understanding the Interface, Organizing Media to Storage, Freeing Up Space, Smart Notifications

What Things Are Called Now

One word per concept: the names that changed this release, and the old names they answer to.

The same thing used to have several names and the same name used to mean several things. This release settles on one word per concept. Nothing stored in your projects changed — a .vpm file written before this release loads unchanged, and one written after it still opens in an older build. Only the words on screen moved.

The Table

Where the Workflow Menu Went

Tip: Searching this help for an old name still works. Type Organize Media, Sync Folder Layout, Reconnect Destination, Refresh Storage Locations, Batch Queue, Rapid Review, Kill or Circle Take and you will land on the topic that replaced it.

See also: The Analyze Hub, Organizing Media to Storage, Star Ratings & Selects

The Analyze Hub

Workflow → Analyze… lists every optional analysis pass with why you would run it, what it needs and when it last ran.

The Analyze hub is one sheet that holds every optional analysis pass, so you can see what each one is for and whether this project has what it needs. Open it with Workflow → Analyze… The passes were separate Workflow menu items in earlier versions.

Each row gives the tool, one line on what running it buys you, a prerequisite counted from the project you have open — for example “needs GPS — 38 of 212 clips have it” — and the date it last ran. Click Run on a row to start that pass; its results open in the pass’s own review sheet.

The Passes

Tip: The last-run date is per project and per pass, and is recorded when you press Run. It is a preference, not project data — it never touches the .vpm file or the database.

See also: What Things Are Called Now, GPS Scene Detection, Auto-Suggest Categories

Progress and Messages

The panel in the bottom-right corner where every long operation and every outcome appears.

Anything that takes more than a moment — an import, an organize, a relink, a project move, and every analysis pass — opens a row in the progress panel at the bottom-right of the window. The row names the operation, shows a progress bar when the work can be counted, and disappears when the work is done.

Outcomes Stay Put

The result of an operation waits for you instead of fading away. “Ejected CARD_A”, “Relinked 12 of 14 files” and “Audio analysis complete” stay in the progress panel until you click the × on them, and some carry the obvious next step as a button — Import Next Card after an eject, Review Ratings after Smart Selects.

What Each Kind Looks Like

Failed Operations

An operation that fails keeps its row, tinted red, with the reason in place of the progress bar. It stays until you dismiss it, so a failure that happened while you were away is still there when you come back.

While a Sheet Is Open

Messages raised inside a sheet — the Import sheet’s “No card selected”, a folder scan that failed — appear inside that sheet, next to the button that caused them, instead of behind the sheet, where you could not read them.

Tip: When no project is open the same status appears in the centre of the window instead, where there is nothing else to look at.

See also: Understanding the Interface, Understanding the Pipeline Strip, Smart Notifications

Setup & Network

Setting Up MediaFlow

The welcome tour explains the app; the Setup Wizard then asks three questions, and you can skip any of them.

A new copy of MediaFlow knows nothing about your equipment: no NAS, no shared database, no destination. Two things greet you on first launch. The welcome tour explains the app. The Setup Wizard then asks three questions so the app can find your storage.

You do not have to answer anything. MediaFlow works without a NAS and without a database, and every answer can be changed later in Settings.

The welcome tour

Four pages: Welcome, the workflow, your workspace, and a closing page of tips. Use Next to move on, Skip to leave, and Get Started on the last page. Help → Getting Started Guide opens it again at any time.

The Setup Wizard

The wizard opens when the tour closes, if nothing is set up yet. It does not open when your saved setup was put back at launch.

  1. Your NAS — shares that are connected now are listed with a Use this button. Look for servers searches the network, and Connect to… opens a server in Finder so you can sign in and mount a share. Use this takes effect as soon as you click it
  2. Shared database — choose None, SQLite file or PostgreSQL server. For a SQLite file, click Choose… to pick the file. For a server, fill in the connection fields
  3. Where organized media goes — click Choose… to pick the default destination for new projects. A project can always use a different one

Skipping

Running it again

Choose Settings › General › Run Setup Again…. The wizard opens showing your current settings, not an empty form. Choosing None on the database step turns the shared database off.

See also: Choosing and Connecting Your NAS, SQLite File or PostgreSQL Server?, Saved Setup: A Copy of Your Settings, The Settings Window, Tab by Tab, What Is MediaFlow?

Choosing and Connecting Your NAS

Settings › Network is where you tell MediaFlow which network share holds your projects and media.

MediaFlow has no built-in NAS. Until you choose one, Settings › Network reads “No NAS chosen yet” and nothing is assumed. A NAS is optional: you can organize to any folder, including a drive attached to this Mac.

When you do choose a share, MediaFlow uses it as the starting point for file pickers, as the suggested place for the shared database file, as the host offered for a PostgreSQL server, and as the place it looks for app updates. It also reconnects the share after sleep.

Choose a share

  1. Open Settings › Network
  2. If the share is already connected, it appears in the list. Click Use this beside it. The button reads In use for the share you have chosen
  3. If it is not listed, click Look for servers, then pick the server from the Connect to… menu. The server opens in Finder, which asks for the password and shows its shares
  4. Mount the share you want in Finder, return to Settings, and click Use this

Picking a mounted share fills in both the share name and its address, so there is nothing to type. If you prefer, open “Type the address instead” and enter an smb:// address. A name ending in .local keeps working when the NAS gets a new network address.

Passwords

macOS asks for the NAS password, not MediaFlow. MediaFlow never sees or stores it. If you let macOS remember the password, macOS keeps it in your Keychain and uses it to reconnect.

Connect now and Forget

No servers found

Check that the NAS is switched on and on the same network. Also check that MediaFlow is allowed to use the local network: System Settings › Privacy & Security › Local Network.

See also: Setting Up MediaFlow, Updating MediaFlow, SQLite File or PostgreSQL Server?, Database Connection Issues, NAS ‘Resource Busy’ Errors

Saved Setup: A Copy of Your Settings

MediaFlow keeps a copy of your settings outside macOS preferences and puts it back if the settings are ever lost.

The saved setup is a small file that holds your MediaFlow settings. It lives apart from the macOS preferences file, so a lost or reset preferences file does not take your setup with it. You do not need to do anything: it is written every time you quit, when you finish the Setup Wizard, and before an update installs.

Passwords and API keys are never in it. They stay in your Keychain.

What it holds

What it never holds

API keys and the database password. They stay in your Keychain. The saved setup is a plain file, and a secret copied into it would be readable by anyone who opened it. After a restore on a Mac with an empty Keychain, enter those again.

When it is restored automatically

Only at launch, and only into a copy of MediaFlow that has nothing configured: no NAS, no database file, no server and no default destination. It never overwrites settings you are already using.

Doing it by hand

Warning: Restore Saved Setup overwrites the settings on this Mac with the saved ones. It asks you to confirm first. The saved copy is normally the one written when you last quit.

See also: Setting Up MediaFlow, Updating MediaFlow, The Settings Window, Tab by Tab, Connecting to a PostgreSQL Server

Updating MediaFlow

MediaFlow updates itself from a copy of the app on your NAS or in a folder you choose, and keeps your settings.

MediaFlow does not download updates from the internet. It compares itself with a newer copy of the app that you keep in one place, normally on your NAS, and installs that copy when you say so. Your settings and projects are not touched by an update.

Where updates come from

Settings › General › Updates shows the source. Until you choose something else, it follows the NAS chosen in Settings › Network and looks for the app in the MediaFlowSwift folder on that share.

Who may sign an update

An update is installed only if it was signed by the maker of the copy you are running, or by MediaFlowSwift’s Apple Developer ID. Nothing else in that folder can be handed to you as an update. From MediaFlowSwift 1.10.18 the app is moving to the Developer ID: after the first update signed with it, macOS treats the app as one it knows, so a new version no longer needs the Local Network switch turned off and on, and your Keychain asks once more and then not again.

Automatic checks

With “Check for new versions automatically” on, MediaFlow looks shortly after launch and when the Mac wakes. Checking reads one small file. A newer version appears as a banner, never a dialog, and never while an import or organize is running.

Installing

  1. Choose Check for Updates… in the app menu, or click Install… on the banner
  2. Click Install Update. The button is unavailable while a background operation is running; wait for it to finish
  3. MediaFlow copies the new version, checks that it is genuine and from the same maker as the one you are running, closes, puts it in place of the old one and reopens. It reopens only once the old copy has fully closed, which can take some seconds while the shared database is saved. Do not quit or reopen it yourself while it works

Your settings are written to disk and to the saved setup before the app restarts.

MediaFlow looks for a new version a few seconds after launch, again every minute until it can reach the place new versions come from, and then every few hours, as well as after the Mac wakes. If anything about the new version does not check out, nothing is changed and the version you had reopens. The version you updated from is kept beside the app as “MediaFlowswift (previous)” for Revert. Because every version is the same signed app to macOS, permissions you have given MediaFlow, such as reaching your local network, carry over from one update to the next. What the installer did is written to Library/Logs/MediaFlow/update.log in your home folder.

Going back

After an update, the Software Update window shows Revert to Previous Version (or Revert to a named version). It puts the version you had before back in place and relaunches.

See also: Choosing and Connecting Your NAS, Saved Setup: A Copy of Your Settings, The Settings Window, Tab by Tab

The Settings Window, Tab by Tab

A map of the eight Settings tabs, so you know which one holds the setting you are looking for.

Settings has eight tabs. Each holds one subject. Most changes take effect as you make them.

Cmd+, — Open Settings

General

Run Setup Again…, the saved copy of your settings (Save Setup Now, Restore Saved Setup), where app updates come from and whether to check automatically, and the version you are running.

Network

Which NAS share MediaFlow uses: shares connected now, Look for servers, Connect now and Forget. There is no built-in NAS; nothing is assumed until you choose one.

Storage

The shared database: Enable Central Database, the Store (SQLite file or PostgreSQL server), its file or connection fields, and copying records between the two. Below it, the default destination for new projects and “Verify organized copies by reading them back”.

Cameras

The open project’s camera list (add, rename, remove), “Suggest import when a camera or card is connected”, and camera identities: the rules that turn a serial number or model into the camera name you use.

Categories

The open project’s category list (add, rename, retire, restore, remove), Also use for new projects, and Category Learning with Reset Pattern Memory.

Analysis

“Use a model to suggest categories” with its provider, model, API key and daily spending limit. Below it, Import Analysis: proposing a category, camera and scene after an import, and the optional Tier 1 pass that looks at pictures and listens to speech.

Privacy

Everything that can leave this Mac for a company outside your network, with what is sent and to whom. Each outside service has its own switch and is off until you turn it on.

Notifications

One switch for each kind of Smart Notification.

Tip: The camera and category lists belong to the project, not to the app. With no project open, those two tabs show Open a Project… instead of a list.

See also: Setting Up MediaFlow, Choosing and Connecting Your NAS, Saved Setup: A Copy of Your Settings, Updating MediaFlow, SQLite File or PostgreSQL Server?, Adding, Renaming, Retiring and Removing Categories, Using a Model to Suggest Categories, Privacy: What Leaves This Mac, How MediaFlow Verifies Copies, Smart Notifications

Privacy: What Leaves This Mac

MediaFlow works on this Mac and your own network; each service that reaches an outside company is off until you turn it on.

MediaFlow has no account, collects no usage data and contacts no server of its own. Your media, projects and shared database stay on this Mac and on your own network.

A few features need a service run by another company. Settings › Privacy lists every one: what is sent, to whom, and what it is for. Each is off until you turn it on, and you can turn it off again at any time.

The switches

A model that suggests categories

This one is set up in Settings › Analysis, and then ticked for each import you want it for. With a paid provider (Anthropic, OpenAI or Google) it sends three frames from each clip, your category list, the clip’s camera, duration and place name, the opening words of any speech, and your recent corrections. With a model on this Mac, nothing leaves it.

The local model’s Server address may be this Mac or another computer on your own network. An address on the internet is refused, and a redirect from the server is never followed, so frames go only to the computer you named.

What stays on your network

Things that open your browser

Buttons such as a provider’s API-key page or the Ollama download open a web page only when you click them. MediaFlow itself sends nothing.

Tip: A saved setup keeps your Privacy switches, but they are not restored automatically on a new install — only when you choose Restore Saved Setup…, which says so before it does.

macOS may separately ask permission for speech recognition or for finding devices on your local network. Those prompts come from macOS and are managed in System Settings › Privacy & Security.

See also: The Settings Window, Tab by Tab, Using a Model to Suggest Categories, Running a Model on This Mac, Speech Transcription, Historical Weather Lookup, Interactive Shoot Map, Saved Setup: A Copy of Your Settings

Importing Media

Importing from a Card, Drive or Folder

Pick a card, drive or folder, choose the files and the camera that shot them, and copy them into your project.

An import copies media from a card, a drive or a folder into your project’s working folder on this Mac and adds the clips to the project. The original files are not changed.

  1. Choose File → Import… (File → Import from Folder… opens the same sheet with the Folder segment selected)
  2. Pick a source at the top of the sheet: Cards & drives lists the SD cards and USB drives MediaFlow has detected; Folder lets you browse to any directory
  3. For a card, choose it from the Choose Card… menu (a single connected card is picked for you; Rescan looks again). For a folder, click Choose Folder…
  4. MediaFlow scans the source, including subfolders, for supported video, image and audio files
  5. Review the file list and check or uncheck the items to include
  6. Set the Camera picker to the camera that shot the footage; click New camera… to add one that is not listed
  7. Optionally tick “Ask a model to suggest categories” — see below
  8. Click Import Selected

Once the copy starts, the bottom of the sheet shows “Importing to:” with the folder the files are going to.

Duplicates

Files that are already in the project are marked Duplicate in the list. A line at the bottom of the sheet says how many duplicates were detected, and they are skipped when you import.

Disk Space

The working folder’s disk needs room for the selected files plus 10 GB of headroom. If it has less, the import does not start and MediaFlow tells you there is not enough free space.

Cancelling

To stop a long import, click Cancel on the progress window. The copy stops between files, the partly written file is discarded, and every file already copied is added to the project and kept in the working folder.

New camera…

The Camera picker lists the project’s cameras (Camera A, Drone, Phone, …). New camera… adds a name to that list, saves it with the project, and selects it for this import. Typing a name that already exists selects the existing entry rather than adding a duplicate.

Ask a Model to Suggest Categories

This checkbox asks an AI model to look at each imported video clip and propose one of your project’s categories. It is off every time the sheet opens and applies to this import only, so no import uses a model unless you tick the box for it. The model runs in the background after the copy finishes. Its answers arrive as proposals: nothing is applied to a clip until you confirm it.

The checkbox appears only after you turn on “Use a model to suggest categories” and finish setting up a model in Settings › Analysis. It is dimmed when “Propose category, camera and scene after an import” is off in the same tab, because the model refines that proposal.

Warning: A paid provider charges for every clip it looks at, and frames from your footage leave this Mac. Set “Stop after … a day” in Settings › Analysis to cap the spend; MediaFlow checks the limit before each clip and stops when it is reached.

Ejecting or Clearing a Card

When the source is an SD card or USB drive, an Eject button appears next to the Camera picker, and again on the completion card after the import. The same command is available from File → Eject Removable Media. MediaFlow asks you to confirm, shows an “Ejecting…” step while the card is unmounted (do not pull the card yet), and then tells you it is safe to remove. If the eject fails because files on the card are still open, close any app or Finder window using them and click Retry.

A Clear Card… button appears beside Eject. It closes the Import sheet and opens the Clear Card sheet, which deletes only clips that are already organized and verified at the destination.

See also: Importing from iPhone or Camera, The Import Sheet and Completion Card, Clear Card, Clip Classifier, Second Pass (Tier 1)

Importing from iPhone or Camera

Import photos and videos from an iPhone or camera connected over USB, and what to do when clips are missing.

The iPhone segment of the Import sheet copies photos and videos straight from a phone or camera connected by USB into your project’s working folder.

  1. Connect your iPhone or camera via USB. Unlock the iPhone and tap Trust if it asks
  2. Choose File → Import from iPhone…, or choose File → Import… and select the iPhone segment at the top of the sheet
  3. Select your device from the Device picker
  4. Check the items to import in the list. Items already in the project are marked Duplicate and are skipped
  5. Click Import Selected

MediaFlow uses Apple’s Image Capture framework to talk to the device. While an iPhone is locked, the sheet asks you to unlock it and tap Trust.

If Clips Are Missing

Only media stored on the phone itself appears in the list. Photos and videos that iCloud Photos has moved to the cloud are invisible until they are downloaded to the iPhone:

  1. On the iPhone, open Settings → Photos and choose Download and Keep Originals
  2. Keep the iPhone unlocked, on Wi-Fi and on power until the download finishes
  3. Click Refresh in the Import sheet

Disk Space

The import does not start unless the working folder’s disk has at least 10 GB free.

Tip: If the device does not appear, disconnect and reconnect the USB cable, then click Refresh to scan again.

The “Ask a model to suggest categories” checkbox is available here too. See Importing from a Card, Drive or Folder for what it sends and what it costs.

See also: Importing from a Card, Drive or Folder, The Import Sheet and Completion Card, Import Not Detecting Files

The Import Sheet and Completion Card

One Import sheet for every source, its per-import options, and the card that appears when the import finishes.

File → Import… opens a single Import sheet. The segment at the top chooses the source: Cards & drives (detected SD cards and USB drives), iPhone (phones and cameras over USB), or Folder (any directory). Import from Folder… and Import from iPhone… open the same sheet with that segment preselected. The banner that appears when a card or phone is plugged in opens the sheet on Cards & drives.

Ask a Model to Suggest Categories

When a model is set up in Settings › Analysis, the bottom of the sheet offers the checkbox “Ask a model to suggest categories”. It is unticked every time the sheet opens and applies to this import only. A model on this Mac is free and sends nothing off the Mac. A paid provider receives frames from each clip and charges for each one. See Importing from a Card, Drive or Folder for the details.

Completion Card

When an import finishes, the file list is replaced by a card that reads, for example, “Imported 24 clips (8.1 GB) from Camera A”. It offers these actions:

You can also categorize later: choose Workflow → Analyze… and run Categories.

Naming a New Camera

When the import includes clips from a camera MediaFlow could identify only by its make, the card lists each such camera with a name field. Type the name you use for that camera and click Save. MediaFlow remembers the camera and re-labels the clips from this import. If you leave the fields alone, you can name the cameras later in Settings › Cameras.

Tip: Categorize now is the quickest way to get a fresh card into the right categories while you still remember what you shot.

See also: Importing from a Card, Drive or Folder, Importing from iPhone or Camera, Auto-Suggest Categories, The Analyze Hub

Managing Assets

Table and Grid Views

Browse your media as a table with sortable columns or as a grid of thumbnail cards, and switch between them.

The media list shows the clips in the project that match the current filter. Use the Table / Grid control in the toolbar to switch between the two views.

Table View

Grid View

See also: Selecting Clips, Context Menu Actions, Understanding the Where Column

Selecting Clips

Select one clip or many in the media list, and use the selection bar to act on all of them at once.

Most commands act on the selected clips: batch editing, organizing, rating, moving to another project and removing from the project.

The Selection Bar

While anything is selected, a bar at the bottom of the media list shows how many clips are selected and offers Organize Media, Set Category, Toggle Favorite, Rate, Select (Hero, Maybe or Reject) and Remove from Project. When selected clips carry import proposals, it also offers buttons to accept them. Click Deselect All to clear the selection.

See also: Table and Grid Views, Context Menu Actions, Star Ratings & Selects

Context Menu Actions

The actions you get by right-clicking a clip, or a selection of clips, in Table or Grid view.

Right-click a clip to act on it. If the clip is part of a selection, the action applies to every selected clip.

When a File Is Missing

Two more items appear only when the selection includes a clip whose file cannot be found:

See also: Selecting Clips, Filtering and Searching, Relinking Missing Media

Filtering and Searching

Narrow the media list with a filter, and search within it by name, notes, tags, category, camera or scene.

A filter limits the media list to the clips you want to work on. One filter is active at a time; choosing another replaces it.

Searching

Cmd+F — Find Clips

Type in the search field in the toolbar, or press Cmd+F to put the cursor there. The list narrows as you type, in Table and Grid view alike, and a line above it tells you how many clips match out of how many are in the project.

Toolbar Filter Menu

Click the filter menu in the toolbar (its label shows the current filter) to choose:

Clearing a Filter

The active filter appears as a chip under the project name in the sidebar. Click the chip to remove that filter, or Clear All to return to All Media. The pipeline strip also sets filters: clicking a segment shows that step’s remaining clips.

Searching Across Projects

To find a clip in any project, choose Database → Global Search… This needs the shared database.

See also: Table and Grid Views, Understanding the Pipeline Strip, Global Search

Editing Clip Metadata

Change the category, favorite flag, tags and notes of one clip or many from the Edit tab of the metadata panel.

Select one or more clips, then open the Edit tab in the metadata panel.

Single Clip

Retired categories are left out of the Category menu. A clip that already carries a retired category still shows it, so its value is not lost.

The tab also shows the clip’s Camera and Where, which you cannot edit here. To change the camera, right-click the clip and choose Set Camera, or click a proposed camera in the table’s Camera column to accept it.

Batch Edit (Multiple Clips)

When several clips are selected, the Edit tab shows batch operations. Each one applies when you click its button:

Tip: Category, favorite, tag and notes changes can be undone with Edit → Undo (Cmd+Z).

See also: Working with Tags, Working with Categories, Context Menu Actions, Undo and Redo

Star Ratings & Selects

Rate clips 1-5 stars and mark them Hero, Maybe or Reject for fast editorial triage.

Star Ratings

Every clip can have a rating of 1 to 5 stars. Set it by clicking a star in the Rating column or in the inspector, with the keyboard shortcuts below, with Edit → Set Rating, with the Rate menu in the selection bar, or with the number keys in Review. Click the star a clip already has to clear its rating.

Where you see them

Keyboard Shortcuts

Cmd+1-5 — Set star rating (1-5 stars)

Cmd+0 — Clear star rating

Cmd+Shift+H — Mark as Hero

Cmd+Shift+M — Mark as Maybe

Cmd+Shift+K — Mark as Reject

Select Status (Hero / Maybe / Reject)

The select status sorts clips three ways:

Batch Operations

Select multiple clips and use the Rate and Select menus in the selection bar, the Rating and Select rows in the inspector, or Edit → Set Rating and Edit → Select, to apply a rating or a select status to all selected clips at once. All batch operations support undo/redo.

Export Integration

Tip: Press Cmd+0 to clear a rating, or Edit → Set Rating → Clear Rating and Edit → Select → Clear Status to remove ratings or selects from every selected clip.

See also: Selecting Clips, Undo and Redo, Reviewing Clips with the Keyboard

Undo and Redo

Edit → Undo reverses metadata edits such as category, rating and tags. It does not reverse file operations.

Edit → Undo (Cmd+Z) and Edit → Redo (Cmd+Shift+Z) reverse and re-apply metadata edits. The menu item names the step, for example “Undo Set Category ‘B-roll’ on 3 Clips”, “Undo Rate ★4 on 12 Clips”, or “Undo Accept 7 Category Suggestions”.

Undoable

Not Undoable

Undo restores the previous values and saves the project. When the undone step changed the category of an organized clip, MediaFlow also moves the copy at the destination back into the matching folder, in the background.

See also: Editing Clip Metadata, Star Ratings & Selects, Auto-Suggest Categories

Organizing Media

Organizing Media to Storage

Copy clips into Category and Camera folders at the project destination, with every copy checksummed and verified.

Organize Media copies your clips into a tidy folder layout at the project destination. The destination can be any folder: a network share, an external drive, a RAID, or a folder on this Mac. The layout is Destination / Category / Camera / Filename.

Organizing

  1. Choose Workflow → Organize Media…, or right-click clips and choose Organize Media. With clips selected it copies the selection; with nothing selected it copies the whole project. If the project has no destination yet, a folder picker opens first
  2. Check the confirmation. It shows the scope (selection or whole project), the number of clips, the total size, the destination and its free space
  3. To send this copy somewhere else, open the destination menu. It lists the project’s own destination, your default from Settings, places you have organized to before, and Choose… for any other folder
  4. A different destination is a one-off: the project keeps pointing where it did. Tick “Make this the project destination” when you want the change to stick
  5. Click Organize Media. MediaFlow creates the category and camera folders, copies each file, and verifies each copy
  6. When the progress window finishes, click Done. Each copied clip now reads “At destination” in the Where column, with a green check

The confirmation can also warn you. Organize is disabled when the destination does not have enough free space. An orange line reading “This folder is on this Mac’s own drive” appears when the destination is on this Mac’s startup disk rather than a mounted drive or share; if you meant to use a drive, check that it is connected. Another orange line counts clips that still carry an unconfirmed proposal; organizing does not apply proposals.

If the clips came from a memory card, the Clear Card review opens when you click Done. Nothing is deleted unless you confirm it there.

How copies are verified

MediaFlow computes a SHA-256 checksum of each source file as it copies it, then finishes writing the copy to the disk. By default it then reads the whole copy back and compares its SHA-256 with the source. If the check fails, the copy is deleted and made again once; if it fails a second time, that clip is reported as failed and its source is left alone.

Settings › Storage › Organize Media has the switch “Verify organized copies by reading them back (slower, safest)”. With it off, MediaFlow checks the size of the copy plus three 1 MB samples at the start, middle and end. That is much faster over a network, but it does not detect corruption outside the sampled ranges.

The checksum is recorded with the clip. Clear Card relies on it later, so leave read-back verification on if you plan to clear cards.

Organizing again over existing files

If a file with the same name and the same size is already in the target folder, MediaFlow uses it instead of copying again. That file is not read and no checksum is recorded for it, so Clear Card later lists the clip as “Organized, unverifiable”. If a file with the same name has a different size, the new copy is saved with a number added to its name, for example Clip_1.mp4.

Default destination

Settings › Storage › Organize Media › “Default destination for new projects” fills in the destination for a project that has none. A project’s own destination always wins once it has one.

Keeping the folder layout in sync

When you change the category or the camera of an organized clip, MediaFlow moves its copy at the destination into the matching folder. This happens in the background and only interrupts you if a file fails to move. To bring the whole project into line at once, for example after an interrupted move or a relink, choose Workflow → Repair → Re-file folders by category.

Cancelling a long operation

Every long file operation (organize, import, project move, cleanup move and restore, relink, re-file and archive) has a Cancel button on its progress window. Cancelling stops the work between files. The file being written at that moment is discarded, so no half-copied file is left behind. Every file that finished before you cancelled stays where it landed; nothing already copied, moved or deleted is put back. The window then reports what did finish, for example “Cancelled after 12 of 40 files, 6.2 GB copied”, and waits for you to click Done.

Tip: Clips in the Skip (don’t copy) category are never copied. The category is stored as “Do Not Copy” in the .vpm file and the database; only the label changed.

See also: Change destination folder, Re-check files, Freeing Up Space, Clear Card

Change destination folder

Point the project at a different destination folder, and follow organized clips that have moved there. No files are copied or moved.

The project destination is where Organize Media copies clips. It is shown under the project name in the sidebar. Hover over it for the full path; “Not set” appears in orange when there is none. The destination is first chosen when the project is created — see Creating a New Project.

  1. Click Change… next to the destination in the sidebar, or choose Workflow → Repair → Change destination folder…
  2. Choose the new folder
  3. MediaFlow saves the new destination in the project and reports “Destination location updated.”

Changing the destination never copies, moves or deletes a file. On its own it changes only where new organizing goes; clips you organized earlier still point at the files in the old folder unless you accept the offer described next.

If you moved your organized media

When the media itself has moved, for example to a new drive or because a share now mounts under a different path, the clips still point at the old paths and read Missing. After you change the destination, MediaFlow looks for each organized clip in the new destination, in the same folder it had under the old one and with the same size. If it finds any, it asks whether to point the project at them, and tells you how many it found out of how many were organized.

Same folder and same size is not proof that a file is the one you organized: cameras that split long recordings into chapters produce files of exactly the same size. So a clip that has a checksum recorded from when it was organized is read in full, and followed only if its contents are identical. The question tells you how much data that is before you agree. Over a network it can take a while. You can stop the check: clips already checked stay pointed at the new destination, and choosing Change destination folder again with the same folder continues with the rest. Clips with no recorded checksum are followed on folder and size alone.

When it finishes, MediaFlow lists any clip that was in the right place but whose contents differ from what was organized, or that could not be read. Those are left as they were.

  1. Change the destination folder to the new location, as above, and answer Point at New Destination when asked
  2. For clips it did not find, choose Workflow → Repair → Relink Missing Media… and show MediaFlow where they went
  3. Choose Workflow → Repair → Re-check files and confirm in the Where column that nothing still reads Missing

The offer is not made when the new destination is the old one, or when one is inside the other; that is not a move MediaFlow can follow by folder.

See also: Organizing Media to Storage, Re-check files, Relinking Missing Media

Re-check files

Look at every clip’s file on disk again and update the Where column for the whole project.

Re-check files brings the Where column back in step with what is really on disk. Choose Workflow → Repair → Re-check files.

What it checks

It does not read file contents or recompute checksums, so it cannot detect damage that leaves the size unchanged.

What the Where column shows afterwards

Re-check files only looks at recorded paths. It does not search for files that have moved; use Workflow → Repair → Relink Missing Media… for that.

Tip: Run this after reconnecting a drive or moving files by hand, or when the Where column does not match what you expect.

See also: Organizing Media to Storage, Relinking Missing Media, Understanding the Where Column

Freeing Up Space

Free Up Space lists every file before it stages or deletes anything. Know what it checks before you confirm.

After you organize, the imported copies are still in the working folder (Documents → MediaFlow Projects → Imports), and the originals are usually still on the card or in the folder you imported from. Free Up Space reclaims that space in two stages: first it moves files into a Cleanup folder, and only later, when you choose, does it delete them.

Free Up Space

Workflow → Free Up Space… scans the open project and lists three groups. Each has a file count, a total size and an expandable list of the exact files it would touch.

A running “Reclaim” total follows your checkboxes, and one red button applies the selection. When you confirm, MediaFlow acts only on files the sheet listed. A listed file that no longer qualifies is skipped; nothing new is added.

What is checked before a file is moved

Two checks, at two moments. A quick one decides what the sheet lists; a thorough one runs on each file just before it is moved.

Reading the organized copy takes time, more so over a network: expect roughly as long as organizing the same clips took. The progress window shows “Checking and moving” and can be cancelled between files.

Staging and deleting

The first two groups are moved into a Cleanup → <Project Name> folder on the destination volume. They are not deleted, and Restore from Cleanup can bring them back.

The third group is deleted. Selecting it adds a confirmation that restates the file count, the total size and the file types, warns when the volume is a network drive with no Trash to recover from, and has a checkbox you must tick before the delete button enables.

Before MediaFlow deletes a staged file, it checks it again, the same way: a clip in this project must have an organized copy that matches it byte for byte, read at that moment. A staged file whose organized copy is missing, damaged or a different size is kept, and so is any file in the Cleanup folder that does not belong to a clip in the project — delete those in the Finder if you are sure.

Warning: Deleting the staged group removes the files permanently. They are not moved to the Trash.

Restore from Cleanup

Workflow → Restore from Cleanup, also a link inside the Free Up Space sheet, moves staged files back where they came from: the working folder, or the card or source path for files staged from there. Projects staged by earlier versions, in folders named by project ID, are still recognized. Files you deleted from the staged group cannot be restored.

Re-file folders by category

Workflow → Repair → Re-file folders by category (called Sync Folder Layout in earlier versions) moves every organized file at the destination into the folder that matches its current category and camera. Single edits re-file themselves in the background, so you need this only to catch up after an interrupted move or a relink.

The End of Day Wrap template

The End of Day Wrap workflow template has a cleanup step that does not open the Free Up Space sheet. It stages local copies only, using the same check as the first group. It never touches card originals and never deletes.

Cancelling a cleanup run

The Cancel button on the progress window stops a move, a restore, a delete or a re-file between files. Files already staged stay in the Cleanup folder, files already restored stay where they were put back, and anything already deleted is gone. The remaining files are untouched, so you can run the same command again later to finish.

See also: Organizing Media to Storage, Re-check files, Clear Card, Workflow Templates

Clear Card

Delete clips from a memory card only after each one is organized and the card file matches its recorded checksum.

Clear Card empties a memory card safely. It lists every clip on the card, works out which ones already have an organized copy it can vouch for, and lets you delete only those. Clearing is always a separate, deliberate step from importing.

Opening it

What it looks at

Only the card’s DCIM folder is scanned. Nothing else on the card is read or touched. Each file is matched to a clip by the path it was imported from, or by filename and size when the card has mounted under a different name.

With the central database connected, files are matched against the clips of every project. Without it, only the open project is searched, so clips that belong to other projects read “Not imported” and are kept.

The five states

Every kept row is locked, with the reason shown next to it. There is no select-all and no override.

What “verified” proves

The Check menu chooses between two modes.

Neither mode reads the organized copy again. The recorded checksum is the checksum of the source file at organize time. With read-back verification on (the default in Settings › Storage), the organized copy was proven identical to it when it was made. With read-back verification off, the organized copy was checked only by size and sampled ranges, so a Verified result shows that the card file is unchanged and the organized copy is the right size, not that every byte of the copy is intact.

GoPro naming

A .MP4 owns the .LRV proxy and .THM thumbnail that share its name; they are listed and deleted with it. Chaptered recordings (GX010123, GX020123) are separate clips and are verified separately, so a verified chapter never takes an unverified one with it.

Deleting

  1. Review the list. Click Rescan if you have connected the destination or organized more clips since the scan
  2. Click the red Delete button. A confirmation restates the clip count, the file count, the total size and the file types, and has a checkbox you must tick before it enables
  3. MediaFlow checks again that each file is inside the card’s DCIM folder immediately before deleting it
  4. When it finishes, click Eject to eject the card, or Done

A list of everything that was removed is written to the card’s MISC folder as cleared-files-<date and time>.txt. Each cleared clip is also marked in the project so the Import sheet does not offer it again. Emptied folders such as 100GOPRO are left on the card on purpose.

Warning: A memory card has no Trash. Cleared files are erased at once and cannot be recovered. Clear Card will not run while an import, organize, archive, relink or the Proxy queue is running, and it refuses a card that is mounted read-only.

See also: Freeing Up Space, Organizing Media to Storage, The Import Sheet and Completion Card

Proposals: What Import Analysis Suggests

After an import, MediaFlow proposes a category, camera and scene for each clip; nothing is applied until you accept it.

When an import finishes copying, MediaFlow examines each new clip and proposes a category, a camera, a scene and a reject flag. A proposal is a suggestion only. It appears in italic grey in the Category or Camera column with a High, Medium or Low badge, and the clip keeps its real category until you accept. Organize never applies a proposal; its confirmation sheet warns you when clips still carry one.

The switch is Settings › Analysis › “Propose category, camera and scene after an import”. It is on by default. This pass runs on this Mac, four clips at a time at low priority.

The three passes

A later pass refines the proposal. It never lowers a confidence you have already seen and never overrides a fact read from the file.

Accepting

Accepting works like choosing the value yourself: it can be undone, and an organized copy is re-filed.

Rejecting

Choose a different category yourself. The proposal disappears, and a category you have set is never proposed over again.

How your answers improve later suggestions

See also: Clip Classifier, Second Pass (Tier 1), Using a Model to Suggest Categories, Auto-Suggest Categories, What Happens to Files When You Change a Category, Reviewing Clips with the Keyboard

Using a Model to Suggest Categories

An optional model can refine category proposals; it runs only when enabled in Settings and ticked for that import.

A vision model can look at three frames from each clip and pick one of your project’s own categories. It refines the proposals import analysis already makes. Its answers are proposals like any other: shown for review, never applied by themselves.

It is off unless you do two things: turn on “Use a model to suggest categories” in Settings › Analysis, and tick “Ask a model to suggest categories” in the Import sheet for that import. The checkbox always starts unticked and applies to that import only.

Which model

Warning: With a paid provider, MediaFlow sends three small frames from each clip to that company, with a line of clip details, the opening words of any speech, your category names and a few examples of how you labeled similar clips. The provider bills you per clip, separately from any subscription you already pay for. On Google’s free tier, your footage is used to train Google’s models; enable billing on your Google account to avoid that.

Setting up a paid provider

  1. In Settings › Analysis, turn on “Use a model to suggest categories”
  2. Choose the provider under Model runs, then a Model. A note under the picker describes each one
  3. Create an API key using the link shown, paste it into API key and click Save
  4. Set “Stop after” to the most you are willing to spend in a day

The daily limit

The limit is checked before every clip, so it is never exceeded. It starts at $1.00 a day. When it is reached the pass stops; clips it did not reach keep the proposal they had. The line below shows clips and spending today, and Reset sets it back to zero. The amounts are MediaFlow’s estimates; your provider’s bill is the final word.

API keys

Keys are kept in your Keychain, never in preferences or the saved setup. Settings shows a masked key with Replace… and Remove.

If the checkbox is missing or dimmed

Turning the Settings switch off stops a pass that is running.

See also: Privacy: What Leaves This Mac, Running a Model on This Mac, Proposals: What Import Analysis Suggests, Clip Classifier, Second Pass (Tier 1), Saved Setup: A Copy of Your Settings

Running a Model on This Mac

Set up a free, private vision model on this Mac with Ollama; nothing you import leaves the machine.

The Server address may be this Mac or another computer on your own network. An address on the internet is refused, so a local model never sends frames outside your network.

A local model suggests categories without sending anything anywhere and without costing anything. The price is time: about a minute a clip, in the background after the copy. Choose it when privacy matters more than speed. If this Mac is short of memory, a paid provider may suit it better.

MediaFlow talks to a model server running on this Mac. The setup assistant in Settings › Analysis works with Ollama. MediaFlow does not install Ollama for you; the download comes from ollama.com. Once it is installed, everything else happens in Settings.

Set it up

  1. In Settings › Analysis, turn on “Use a model to suggest categories” and set Model runs to On this Mac
  2. Click Download Ollama… and install it, or click Copy Homebrew command and run it in Terminal. Then click Check again
  3. If Ollama is installed but not running, click Start Ollama. It takes about fifteen seconds
  4. Pick a model from the suggestions and click Download. This is a one-time download of several gigabytes
  5. Click Run the check. MediaFlow asks the model one question to confirm it can answer in the format it needs
  6. When the assistant reads “Ready”, tick “Ask a model to suggest categories” in the Import sheet for an import you want it to look at

Choosing a model

The suggestions are sized to this Mac’s memory. The default is comfortable with 16 GB of memory or more; the larger ones judge better and want 24 GB or 32 GB. Each line shows the download size.

If the check fails

Models below about 8 billion parameters usually cannot hold a structured answer. Click Download a different model and try a larger one.

Using another server

Any server that speaks the same protocol works, such as LM Studio. Enter its address in Server and the model’s name in Model. Ollama is on port 11434 and LM Studio on 1234.

See also: Privacy: What Leaves This Mac, Using a Model to Suggest Categories, Proposals: What Import Analysis Suggests, Clip Classifier, Second Pass (Tier 1)

How MediaFlow Verifies Copies

What MediaFlow checks, and when, before it treats an organized copy as safe and lets an original be removed.

MediaFlow checks your files at three moments: when Organize copies a clip, when Clear Card offers to delete it from the card, and when Free Up Space offers to move originals aside. The checks are not equally strong. This topic says exactly what each one proves.

The short version: leave “Verify organized copies by reading them back” on, and empty cards with Clear Card in Verified mode. Together they prove the organized copy matched the original byte for byte when it was made, and that the file you are deleting is that original.

Organize

As MediaFlow copies a clip it computes a checksum of the original (SHA-256, a fingerprint of the file’s contents). It finishes writing the copy to the destination before it checks it. The setting is in Settings › Storage.

If the check fails, the copy is deleted and made again once. A second failure fails that clip and is reported. The original’s checksum is recorded on the clip; Clear Card relies on it later.

One exception: if a file with the same name and the same size is already at the destination, Organize reuses it. It is not copied, not read, and no checksum is recorded for it.

Clear Card

Only files in the state “Verified at destination” can be deleted, and there is no override. In both modes of the Check picker, the clip must have a recorded checksum, and its organized copy must be reachable now and be exactly the size of the card file.

Neither mode reads the organized copy again; it is checked for presence and size only. So Clear Card is as strong as the check made at organize time. With read-back on, the copy was proven identical then. With read-back off, only its size and three samples were.

Free Up Space

This is the step that removes your other copies, so it is the strictest. Files are moved to a Cleanup folder first and deleted only in a separate, confirmed step — and both steps prove the file first.

Unlike Clear Card, this always reads the organized copy again. The checksum recorded at organize time is the checksum of the original; it says the local copy has not changed, not that the copy at the destination is whole. Reading it is the only way to know, which is why Free Up Space takes about as long as organizing did.

See also: Organizing Media to Storage, Clear Card, Freeing Up Space, The Settings Window, Tab by Tab

Format Conformance Checker

Find clips whose frame rate, resolution or codec differs from the rest of the project before they cause trouble in your editor.

The Format Conformance Checker analyzes all video clips in your project and flags format inconsistencies that could cause issues when editing in Final Cut Pro, DaVinci Resolve, or other NLEs.

How to Use

  1. Open your project with imported video clips
  2. Go to Workflow → Analyze… → Format
  3. Click Run Analysis
  4. Review the report showing your project baseline and any detected issues
  5. Click “Select Affected Clips” to highlight problem clips in the media list

Severity Levels

Project Baseline

The checker determines your project’s dominant resolution, frame rate, and codec (the most common values). Clips that differ from the baseline are flagged as potential issues.

Tip: Run this check before exporting to an NLE to catch format mismatches early. It’s much easier to transcode a few clips now than troubleshoot timeline issues later.

Mixed frame rates are the most impactful issue — a 30fps clip on a 24fps timeline will stutter visibly. Always prioritize resolving critical issues first.

See also: Organizing Media to Storage, Generating Reports, Transcode

Workflow Templates

Run a fixed series of operations in order with one command: organize, end-of-day wrap, or relink and repair. Each step finishes before the next begins.

A workflow template runs several operations in order, so you do not have to find each command yourself. Each step is the same operation you would start from the menu, with the same confirmations and the same progress window, and the template waits for it to finish before it starts the next.

How to Use

Cmd+Shift+R — Open Workflow Template Picker

Choose Workflow → Run Workflow Template, select a template, then click Run. When a step needs you — to confirm a copy, choose a folder, or read a result — the template’s own window steps aside and the step’s windows appear as usual. Nothing is copied, moved or deleted until you confirm it there. When you close the step’s last window, the template comes back with what the step did and carries on. The command is unavailable while a template is running.

Built-in Templates

When a step does not finish

Controls During Execution

Summary Report

When the template ends, a summary shows each step with a checkmark, a skip mark or an error, and the header shows the elapsed time. Each line reports what actually happened, taken from the operation itself: how many clips were organized and how many were not, what Free Up Space moved or deleted, how many missing clips were relinked.

Tip: Optional steps (like Format Check in One-click Organize) can be skipped to speed up the workflow when you know your formats are consistent.

See also: Organizing Media to Storage, Format Conformance Checker, Re-check files

GPS Scene Detection

Group clips into suggested scenes by where they were shot, then accept, rename or reject each suggestion.

Place names are looked up only if you turn that on in Settings › Privacy, and the small maps only if Maps is on; otherwise each scene shows its coordinates.

GPS Scene Detection analyzes the geographic coordinates embedded in your clips to suggest logical scene groupings. Clips shot near the same location are clustered together and presented as scene suggestions you can accept, rename, or reject.

How to Use

  1. Open a project with media with GPS data (phone and drone footage typically has GPS data)
  2. Choose Workflow → Analyze… → GPS Scenes and click Run. MediaFlow analyzes at once with the radius and time gap you last used
  3. Review each suggestion: accept, reject, or rename the scene
  4. To try a different radius or time gap, click Re-analyze, change the settings and click Analyze
  5. Click the Apply button to give the accepted clusters their scene names. The button says how many scenes it will apply, and appears once you have accepted at least one

Clustering Radius

Time Gap Threshold

Even if clips are at the same GPS location, a large time gap between them may indicate a different scene. For example, morning and afternoon shoots at the same beach are likely separate scenes. Set the time gap to split same-location clusters that are separated by more than the threshold.

Review Interface

Each suggestion shows a mini map pin, the suggested scene name (editable), clip count, time span, and sample filenames. Use the checkmark to accept or the X to reject. You can accept or reject all at once with the bulk buttons.

Tip: Run Place names first (Workflow → Analyze… → Place names, once called Geocode Locations) so clips have readable place names. GPS Scenes works with raw coordinates too, but named places make the suggestions much easier to review.

Only clips with GPS metadata are analyzed. Clips without it are skipped, and so are clips that already have a scene.

See also: Privacy: What Leaves This Mac, NLE Template Export, Logging Scene, Shot and Take

Sun Position & Shadow Continuity

Calculate sun position for clips with GPS data and detect shadow continuity issues across takes.

Sun Position Analysis calculates the solar azimuth (compass direction) and elevation for every clip with GPS data using the Meeus astronomical algorithm. It then checks for shadow continuity problems where takes of the same scene were shot at different times of day, causing mismatched shadow directions that would be visible when edited together.

How to Use

  1. Open a project with media with GPS data that has timestamps
  2. Choose Workflow → Analyze… → Sun
  3. Review the analysis results: sun position per clip, golden hour clips, and continuity warnings

What Gets Calculated

Shadow Continuity Warnings

When two clips in the same Scene Log scene have sun azimuths more than 30° apart, MediaFlow raises a warning. Clips with no scene produce none. Warnings are rated by severity:

Tip: Golden hour footage has a distinctive warm quality. Use the lighting condition badges to find your golden hour and blue hour clips for color grading.

Sun position requires both GPS coordinates and accurate timestamps. Clips without location data are skipped.

See also: NLE Template Export, Logging Scene, Shot and Take

Interactive Shoot Map

View shooting locations on an interactive map with clip clustering.

The map itself is off until you turn on Maps in Settings › Privacy, or with the Turn On Maps button: showing a map sends the area you are looking at to Apple. Until then the locations are counted without a map.

The Shoot Map displays all clips with GPS data on a map. Clips shot at the same place share one numbered pin. Click a pin to see its clips and select them in the media list.

How to Open

Cmd+Opt+M — Open Shoot Map

Or choose Workflow → Plan & Deliver → Shoot Map from the menu bar.

Map Features

Filters

The sidebar lists all location clusters sorted by clip count. Each entry shows the place name, clip count, sample filenames, and category badges. Click a location to zoom the map to it.

Tip: Use the Shoot Map alongside GPS Scene Detection to visually verify scene groupings before applying them.

See also: Privacy: What Leaves This Mac, GPS Scene Detection, Historical Weather Lookup, Logging Scene, Shot and Take

Historical Weather Lookup

Look up the weather at the place and time each clip with GPS data was shot and store it with the clip.

Weather lookup is off until you turn it on in Settings › Privacy, because it sends each clip’s coordinates and date to Open-Meteo.

Weather Lookup retrieves historical weather conditions for every clip with GPS data from the free Open-Meteo service. It records temperature, sky conditions, wind, and humidity — the same information a script supervisor would note by hand for continuity.

How to Use

  1. Open a project with media with GPS data
  2. Choose Workflow → Analyze… → Weather
  3. Wait for the lookup to finish. It needs an internet connection. The progress HUD then reports how many clips had weather added

Data Retrieved

Where you see it

Both follow the weather switch in Settings › Privacy. With it off, MediaFlow does not look weather up, and it does not show or search weather that an earlier lookup saved. Turn the switch back on and the saved weather reappears; nothing is deleted.

Caching

Results are cached by location (to about 100 m) and hour, so clips shot at the same place within the same hour share one request. The cache lasts until you quit MediaFlow. The weather itself is saved with each clip in the project file.

Warning: Weather Lookup sends data off this Mac. For each lookup it sends the clip’s coordinates, rounded to about 100 m, and the shooting date to the Open-Meteo service. No API key or account is needed.

See also: Privacy: What Leaves This Mac, NLE Template Export

Vision (AI Scene Analysis)

Detect shot type, faces, indoor or outdoor, and on-screen text on this Mac, and suggest a category for each clip.

Vision, once called AI Scene Analysis, uses Apple’s Vision framework to analyze your video clips. It detects shot types, counts faces, classifies indoor/outdoor scenes, and reads on-screen text — all on-device with zero API costs.

How to Use

  1. Open a project with video clips
  2. Choose Workflow → Analyze… → Vision
  3. Wait for analysis to complete (progress shown in the review sheet)
  4. Review suggestions: accept individually or accept all uncategorized

What Gets Detected

Accuracy

The category rules are simple. One or two faces with one of them centered suggests Interview. No faces suggests B-roll outdoors and Establishing Shot otherwise. Anything else, including three or more faces, suggests B-roll. These are suggestions; review them before you accept.

Tip: Vision samples 5 representative frames per clip, not every frame. This keeps analysis fast while providing reliable results.

Vision runs entirely on this Mac. It needs no internet connection and no API key.

See also: Auto-Suggest Categories, Smart Selects

Speech Transcription

Transcribe the speech in your video clips with Apple’s speech recognition; the text is saved with each clip.

Speech is recognized on this Mac. Apple’s online recognition is used only if you turn it on in Settings › Privacy, and only for a language this Mac has no on-device model for.

Transcribe turns the speech in your video clips into text using Apple’s speech recognition. The text is saved with each clip in the project file, and import analysis uses it as one of its signals when it proposes a category. Audio-only files are not transcribed.

How to Transcribe

  1. Open a project with video clips that contain speech
  2. Choose Workflow → Analyze… → Transcribe
  3. Allow speech recognition if macOS asks
  4. Wait for it to finish. The progress HUD reports how many clips were transcribed

To transcribe one clip, select it, open the Transcript tab of the metadata panel and click Transcribe This Clip.

The Transcript tab

Where the Audio Goes

MediaFlow recognizes speech on this Mac when the Mac has an on-device model for your system language. When it does not, nothing is transcribed unless you have turned on online speech recognition in Settings › Privacy; with that on, the audio is sent to Apple. The Transcript tab says which applies before you start. No API key is needed either way.

Tip: Clear speech with little background noise gives the best results.

See also: Privacy: What Leaves This Mac, Clip Classifier, Second Pass (Tier 1), Proposals: What Import Analysis Suggests

Smart Selects

Score each clip for sharpness, exposure, audio and more on this Mac, and suggest a star rating you can accept.

Smart Selects, once called AI Smart Selects, scores every clip on five measures and suggests a star rating. It runs on this Mac and needs no internet connection.

Quality Dimensions

How to Use

  1. Open a project with media clips
  2. Choose Workflow → Analyze… → Smart Selects
  3. Watch the progress row in the feedback HUD at the bottom-right of the window
  4. Review the results sorted by overall quality score
  5. Accept individual ratings or click Accept All to apply all suggestions

Circle Takes

A clip that scores above 85% overall is proposed as a Circle Take. Nothing changes until you Accept that clip or click Accept All. Accepting a Circle Take also marks the clip Hero with five stars.

Sharpness analysis samples a single frame near the start of each clip. Clips that start out of focus but later become sharp may receive a lower sharpness score than expected.

See also: GPS Scene Detection, NLE Template Export

Audio Waveform Sync

Synchronize multi-camera clips by cross-correlating their audio waveforms.

Audio Waveform Sync uses normalized cross-correlation to find the time offset between clips recorded simultaneously from different cameras. By analyzing the audio tracks, it determines exactly how many seconds one clip leads or lags another.

How It Works

  1. Audio is extracted from each video clip and downsampled to 8 kHz mono
  2. A coarse search finds the approximate offset by sliding one waveform over the other
  3. A refinement pass narrows down to sample-accurate alignment
  4. Results show the offset, confidence level, and sync quality for each pair

How to Use

  1. Open a project with at least 2 video clips
  2. Choose Workflow → Analyze… → Audio Sync
  3. Review the results showing offset and confidence for each clip pair
  4. Use the offsets when setting up a multi-camera edit in your NLE

Quality Levels

Tip: For best results, ensure all cameras were recording simultaneously with ambient audio. Clips with very different audio content (for example, one indoors, one outdoors) will produce poor correlation.

Audio sync requires video clips with audio tracks. Photo-only clips are skipped.

See also: Smart Selects, NLE Template Export

Shot List

Plan the shots you need, link captured clips to them, and see coverage gaps.

The Shot List tracks the shots you planned against the clips you captured. Choose Workflow → Plan & Deliver → Shot List…. Each item has a description, an optional scene, an optional shot type (Wide, Medium, Close-Up, Extreme Close-Up, Over the Shoulder, POV, Aerial, Insert, Establishing, Other), and a Required checkbox.

Statuses

The header shows “x/y shots captured” with a progress ring, and the filter bar switches between All, Captured, Pending, and Missing. The footer warns in red when required shots are still not captured.

Overflow Menu (…)

Per-row buttons reset an item to Pending or remove it. Every change is saved to the project file immediately.

Tip: Fill in Scene and Shot in the Scene Log tab as you review footage. Auto-Match Clips then does the linking for you.

See also: Logging Scene, Shot and Take, Storyboard, Project Checklist

Storyboard

Arrange clips into named sections by drag and drop to plan the edit order.

The Storyboard lets you plan the order of the edit before you open your editor. Choose Workflow → Plan & Deliver → Storyboard… to open a board with sections on the left and an Unplaced Clips list on the right. The first time you open it in a project, MediaFlow creates five default sections: Opening, Act 1, Act 2, Act 3, and Closing.

Working the Board

Clip cards show the filename, duration, scene, and star rating. Unplaced Clips lists every video and image clip that is not yet in a section.

The storyboard is stored in the .vpm project file. It is a planning aid only and cannot be exported. To hand structure to your editor, use NLE Template Export or Export FCPXML.

See also: Shot List, NLE Template Export, Star Ratings & Selects

Import Field Notes

Match timestamped notes from a text or CSV file to the clips recorded at that time.

Import Field Notes attaches notes you typed on set to the clips recorded at that moment. Choose Workflow → Plan & Deliver → Import Field Notes… and pick a text or CSV file. Each note is matched to the clip whose creation time is closest.

File Formats

Matching Confidence

If the camera clock and your watch disagree, adjust the TZ offset stepper (−12 to +12 hours); matching re-runs as you change it. Parse errors are listed separately so you can fix the source file.

What Apply Does

See also: Working with Tags, Editing Clip Metadata, Star Ratings & Selects

Clip Classifier, Second Pass (Tier 1)

An optional second pass after import that looks at the pictures and listens to the start of each clip to refine proposals.

After an import finishes copying, MediaFlow proposes a category, camera, scene and reject flag for every clip. The basic pass reads facts from the file: frame rate, recording time, camera make, audio level, one sampled frame. Tier 1 is a second, slower pass that looks at the pictures and listens to the start of the clip, so the proposals are better. Proposals appear in italics and are never applied until you confirm them.

What Tier 1 looks at

Tier 1 weighs your project’s own categories against each other, and the strongest becomes the proposal. It never overrides a Tier 0 verdict that came from a hard fact such as 240 fps, never lowers the confidence Tier 0 reported, and never changes the camera Tier 0 read from the file.

Privacy

The picture analysis (faces, scene labels, signage, motion) runs on this Mac. The speech sample uses Apple’s speech recognition: it runs on this Mac when macOS has an on-device model for your Mac’s language, and otherwise the audio sample is sent to Apple’s speech service. If you refuse speech recognition permission, Tier 1 carries on without the speech signal.

Turning it on

Tier 1 is off by default. The switches are in Settings › Analysis, under Import Analysis:

Turning Tier 1 off while it runs stops it. Whatever it has already proposed stays.

Whole-file transcripts

Tier 1 listens only to the start of a clip. To transcribe whole clips, choose Workflow → Analyze… and click Run on the Transcribe row.

Tip: In Review (Workflow → Review), A accepts the proposal on the clip in front of you and R marks it a reject candidate. Both teach the category suggester.

See also: Privacy: What Leaves This Mac, Auto-Suggest Categories, Vision (AI Scene Analysis), Speech Transcription, Reviewing Clips with the Keyboard

Audio Levels

Flag clips with clipped, quiet, or silent audio before they reach the edit.

The Audio pass finds sound problems before you cut. Choose Workflow → Analyze… and click Run on the Audio row. MediaFlow reads the audio track of every video or audio clip that has not been analyzed yet and records its peak level, average level and a quality flag. Progress shows in the progress HUD.

Flags

The flag appears as an icon in the Table view, and the levels are listed in the Full Metadata tab. Clips with a Clipping, Low or Silent flag are counted as audio issues in the Day Summary and in Project status (legacy). Clips that already carry a flag are skipped; MediaFlow tells you when nothing is left to analyze.

See also: Day Summary, Smart Selects, Audio Waveform Sync, The Analyze Hub

Exposure

Traffic-light exposure ratings and color-cast notes for every clip, grouped by scene.

The Exposure pass gives you a triage list of clips that may be too bright, too dark or off-color. Choose Workflow → Analyze… and click Run on the Exposure row. MediaFlow rates each clip’s exposure, estimates its color balance, and flags clips that do not match the rest of their scene.

Traffic lights

Click a traffic-light count, or use the All / Good / Marginal / Problem filter bar, to narrow the list. Each row shows the scene, a mini histogram, and a note such as “Overexposed — 8.0% highlights blown out · Color: warm (cloudy/shade WB) · ISO 400 · Shutter 1/60 · f/2.8”.

Scene color mismatches

Within a scene that has two or more clips, any clip whose average color differs noticeably from the scene average is flagged, and the header counts the scenes with mismatches. This is useful for spotting a camera left on the wrong white balance.

The ratings are estimated from each clip’s recorded exposure data (ISO, shutter, aperture, white balance), not from the decoded picture. Treat the list as a guide to which clips to look at, and confirm on a monitor.

See also: Smart Selects, Format Conformance Checker, Logging Scene, Shot and Take, The Analyze Hub

Transcode

See which codecs your editing software will struggle with and what to transcode them to.

The Transcode pass tells you which clips to convert before you edit. Choose Workflow → Analyze… and click Run on the Transcode row. MediaFlow groups the project’s video clips by codec and compares them with what the editor you pick handles well: Final Cut Pro, Premiere Pro, DaVinci Resolve or Avid Media Composer. Your choice is remembered.

Priorities

Each card names the target codec (ProRes 422 or ProRes 422 Proxy; DNxHD 175 or DNxHD 36 for Avid), the number of clips affected, and an estimated output size and transcode time. The header sums the totals, or confirms that every clip is already compatible.

This sheet only advises; it does not transcode anything. To make proxies, select the clips and use the Workflow Tools tab, or use your editor’s own media management.

See also: Format Conformance Checker, NLE Template Export, Processing the Proxy Queue, The Analyze Hub

Continuity

A scene-by-angle coverage grid that shows where a camera has no footage or far fewer takes.

The Continuity pass shows whether every scene is covered from every angle, so you can decide on a pickup before you leave a location. Choose Workflow → Analyze… and click Run on the Continuity row. MediaFlow builds a grid of scenes (rows) against cameras (columns) from the Scene Log data on your clips and counts the takes in each cell. The column for a clip comes from its Camera angle in the Scene Log; when that is empty, its camera is used.

Cell colors

Coverage gaps

Below the grid, gaps are listed with missing coverage first and a one-line explanation, for example “Scene 4 only has footage from A — no backup angle”. The header summarizes the counts, or reports full coverage across all scenes and cameras.

Clips without a scene are ignored. If no clip has scene data, the sheet asks you to assign scenes and cameras first.

See also: Logging Scene, Shot and Take, Shot List, Audio Waveform Sync, The Analyze Hub

Logging Scene, Shot and Take

Record scene, shot type, take, camera angle and circle takes for each clip in the Scene Log tab.

The Scene Log records the slate information for a clip, so later tools can group, match and export by scene. Select a single clip and open the Scene Log tab in the metadata panel. Every field saves as you type.

Fields

Ticking Circle Take also marks the clip Hero and rates it five stars, unless the clip already has a select status or a rating. Unticking it does not remove them; change the select status and the rating yourself.

Where It Is Used

Edits made in the Scene Log tab are saved at once and cannot be undone with Edit → Undo, so check the take number before you move on.

See also: Shot List, Continuity, Dailies Report, Reviewing Clips with the Keyboard, NLE Template Export

Video Preview & Playback

Video Playback Controls

Play, pause, scrub and step frame by frame through the selected video in the preview panel.

Select a video clip to load it in the preview panel. The controls appear below the picture:

Tip: Use frame stepping for precise positioning when extracting thumbnails or creating subclips.

See also: Pop-Out Video Window, Extracting Thumbnails and Subclips

Pop-Out Video Window

Open the video preview in a separate, resizable window with its own playback controls.

Click the pop-out button at the right end of the preview controls to open the video in a separate window. The window has its own seek slider, step back, play/pause and step forward controls, and you can resize it freely.

Tip: Use the pop-out window when you want a larger preview while still seeing the media list and metadata panels.

See also: Video Playback Controls

Extracting Thumbnails and Subclips

Save the current video frame as a PNG image, or export part of a clip as an MP4 using in and out points.

Use the Workflow Tools tab in the metadata panel for these operations:

Extract Thumbnail

Saves the current video frame (or the full image for a photo) as a PNG file. Move to the frame you want with the playback controls, click Extract Thumbnail, and choose where to save it.

Create Subclip

Exports part of a video as an MP4 file. Mark in and out points to choose the range, then click Create Subclip and choose where to save it. What is exported depends on the marks:

Marking In/Out Points

In the Workflow Tools tab, click Mark In (I) or Mark Out (O) to set a mark at the current playback position. You can also press I or O after clicking the preview panel, so that it has keyboard focus. The marked range is highlighted on the seek slider, the In, Out and Duration times are listed in the tab, and the Create Subclip button shows the duration. Click Clear in the Workflow Tools tab to remove both marks.

See also: Video Playback Controls, Processing the Proxy Queue

Reviewing Clips with the Keyboard

A keyboard-driven review sheet for playing, rating, rejecting and accepting proposals on clips, one after another.

Rapid Review is a focused review sheet for evaluating clips quickly. Use the keyboard to play, rate, favorite, reject and move through your footage without touching the mouse. Open it from Workflow → Review (Cmd+Opt+R) or from the Rapid Review… button on the pipeline strip’s Review segment. Press ? at any time for an on-screen list of these keys.

Playback Controls

Rating & Tagging

Import Proposals

Both keys do what the menu commands do: you can undo them, MediaFlow re-files an organized copy to match, and the category suggester learns from them. A does nothing on a clip with no proposal, and R never replaces a category you chose yourself.

Display

Auto-Advance

With auto-advance on, rating a clip with 1–5, rejecting it with X, or pressing A or R moves to the next clip after a short delay. Auto-advance starts on; press T to turn it off or on, and MediaFlow remembers your choice. The Auto indicator in the bottom bar is green while it is on.

Review Queue

The review queue is based on your current filters in the main window. Filter by category, scene, camera or smart group before you open Review to focus on a specific subset of clips. The bottom bar shows your progress (for example “12 of 47”) and how many clips have been rated.

Tip: For the fastest selects workflow: click the Review segment of the pipeline strip to show only unrated clips, open Review, and use 1–5 to rate each clip.

See also: Video Playback Controls, Extracting Thumbnails and Subclips, Star Ratings & Selects, Keyboard Shortcuts Reference

Batch Operations

Using the Proxy Queue

Mark clips for thumbnail and proxy generation by adding them to the Proxy queue, and take them out again.

The Proxy queue is a list of clips you have marked for thumbnail and proxy generation. Queue the clips first, then process the whole queue in one go.

Adding to the Queue

Seeing What Is Queued

Select Proxy queue in the sidebar’s Library section, or choose Proxy queue from the toolbar filter menu, to list only the queued clips. The Workflow Tools tab shows the number queued.

Removing from the Queue

Processing does not empty the queue. Clips stay queued until you remove them.

See also: Processing the Proxy Queue

Processing the Proxy Queue

Generate thumbnails and low-resolution proxy videos for every clip in the Proxy queue, and where they are stored.

With clips in the Proxy queue, use the buttons in the Workflow Tools tab of the metadata panel to process them:

A progress bar shows the name of the clip being processed. Click Cancel to stop processing; clips already finished keep their files.

Where the Files Go

Proxies are saved as <name>_proxy.mp4 in MediaFlow’s Application Support folder in your Library, in a Proxies folder for each project. They belong to this Mac: they are not stored in the project folder and do not move with the project. The Metadata tab lists each clip’s Thumbnail and Proxy paths under Generated Files, with a Proxy status line saying whether one has been generated.

What proxies are for

Once a clip has a proxy, the preview, the pop-out player and Review play the proxy instead of the original. It is a much smaller file on this Mac’s own drive, so it starts at once and scrubs smoothly, where a large original on a network drive may not. A small badge at the top-left of the player says Proxy or Original and lets you switch. It switches at the same moment in the clip and keeps your In and Out marks, and your choice holds for the clips you look at next.

Clips on a Network Drive

A clip on a NAS or another network drive is read across the network as it plays, and macOS does not read ahead for a file the way it does for a stream, so a short pause on the network is a pause in the picture. A large clip, such as 4K footage, over a wireless connection is where this shows. When the preview is playing such a clip and it has no proxy, a badge at the top-left says Over the network:

Making a proxy reads the whole clip once, so expect roughly a third of the clip’s length over a wireless connection; after that, playback does not depend on the network. The original is never changed. A wired connection to the drive helps playback of the originals themselves, in MediaFlowSwift and in your editor.

See also: Using the Proxy Queue, Extracting Thumbnails and Subclips

Tags & Categories

Working with Categories

Give each clip one category; the category groups your clips and names the folder Organize Media files them into.

A category says what kind of clip this is. Each clip has one. When you organize media, the category name becomes a folder at the destination.

Default Categories

Assigning a Category

If the project has a destination, MediaFlow then moves the clip’s organized file to the folder for its new category. It does this quietly and tells you only if a file could not be moved.

Changing the List

The Edit tab only offers the categories the project already has. The list belongs to the project and is stored in the project file. To add, rename, retire or remove a category, open the project and go to Settings › Categories. A new category then appears in the Category picker and the Set Category menu.

Tip: Workflow → Analyze… → Categories proposes a category for each uncategorized clip.

See also: Adding, Renaming, Retiring and Removing Categories, What Happens to Files When You Change a Category, Working with Tags, Auto-Suggest Categories, Organizing Media to Storage

Working with Tags

Attach free-form, searchable tags to a clip; a clip has one category but can carry any number of tags.

Tags are free-form labels you can attach to clips. Unlike categories (one per clip), you can have multiple tags per clip.

Adding Tags

Removing Tags

Click the X button on any tag chip to remove it.

Batch Tag Operations

With two or more clips selected, the Edit tab shows three tag buttons:

Tip: The search field above the media list matches tags, and so does Global Search across every project in the shared database.

See also: Working with Categories, Filtering and Searching

Adding, Renaming, Retiring and Removing Categories

Settings › Categories edits the open project’s category list; retire a category to stop using it without touching its clips.

The category list belongs to the project. It is stored in the project file and can differ from shoot to shoot. Settings › Categories shows the list for the open project, with the number of clips in each category. With no project open, it shows Open a Project… instead.

Retire or remove?

Add and rename

Removing a category that has clips

  1. Click the trash button beside the category
  2. The dialog says how many clips still use it
  3. Click “Move clips to…” for the category that should take them. Uncategorized is always offered first

Files that are already organized

Organized clips sit in a folder named after their category. Renaming or removing a category here does not move those files. A note under the list tells you how many files are still in a folder with the old name. Run Workflow → Repair → Re-file folders by category to move them.

Built-in categories

Uncategorized and Skip (don’t copy) are marked “built in”. Organize relies on their exact names, so they cannot be renamed, retired or removed.

Starting new projects with this list

Click Also use for new projects. The next project you create starts with this list instead of the built-in one.

See also: Working with Categories, What Happens to Files When You Change a Category, Auto-Suggest Categories, The Settings Window, Tab by Tab

What Happens to Files When You Change a Category

Changing a clip’s category applies at once and moves its organized copy to the matching folder in the background.

Organize files each clip in a folder named after its category. When you change a clip’s category in the main window, the change applies at once, and MediaFlow then moves the clip’s organized copy into the folder for the new category. You do not start this and you do not confirm it.

When it happens

What you see

A row titled “Filing clips by category” appears in the progress panel while the move runs, then disappears. There is no summary and no Done button when it succeeds.

You hear about it only if it fails. If a file cannot be moved, the row stays and says so until you clear it, and the details are written to the log. The clip keeps its new category; its file is still in the old folder.

Putting things right

Choose Workflow → Repair → Re-file folders by category. It checks every organized file in the project and moves each one into the folder its current category calls for. Use it after a failed move, for example when the destination was not connected, and after renaming a category in Settings › Categories, which does not move files by itself.

When two projects share media

If this project shares its media files with another (see Duplicating a Project), nothing is re-filed. The category changes; the file stays where it is, because moving it would make the clip go missing from the other project. MediaFlow tells you when this happens.

See also: Adding, Renaming, Retiring and Removing Categories, Organizing Media to Storage, Progress and Messages, Working with Categories, Undo and Redo

Auto-Suggest Categories

Let MediaFlow propose a category for every uncategorized clip and learn from your decisions.

The Categories pass saves you from categorizing clips one at a time. Choose Workflow → Analyze… and click Run on the Categories row. MediaFlow examines every clip whose category is empty or Uncategorized and opens a review sheet with a suggested category for each, a confidence badge and the reason.

Signals

Confidence

Reviewing

Every category you assign, by hand or by accepting a suggestion, teaches the suggester. If you pick a different category than it proposed for a camera three times, it stops making that proposal. Settings › Categories › Category Learning shows what it has learned, and Reset Pattern Memory clears it. The Uncategorized Clips smart notification offers an Auto-Suggest button when five or more clips need a category.

See also: Working with Categories, Vision (AI Scene Analysis), The Analyze Hub, Undo and Redo

Shared Database

Shared Database Overview

The optional shared database lets you search and track clips across projects; it is a SQLite file or a PostgreSQL server.

The shared database (the app calls it the Central Database) keeps a record of every project so you can search, compare and track clips across all of them. It is optional. Import, organize, preview and editing all work without it.

The project file (.vpm) is the authority. The database holds a copy of what the project file says, and MediaFlow updates that copy each time you save.

What the Database Adds

File or Server

The database is kept in one of two stores. You choose with the Store picker in Settings › Storage.

Turning It On

  1. Open Settings › Storage and turn on Enable Central Database, or choose Database → Enable & Connect Database
  2. Choose the Store: SQLite file or PostgreSQL server
  3. For a file, click Choose… and pick the database file. If you chose a NAS in Settings › Network, Reset to Default points at MediaFlow/mediaflow.db on it. A file that does not exist yet is created when you connect
  4. For a server, fill in Host, Port, Database, User and Password, then click Test Connection

Moving Between a File and a Server

With PostgreSQL server selected, Settings › Storage offers Copy the SQLite File to This Server… and Copy This Server to a SQLite File…. Both copy every record and leave the source unchanged. Switching the Store picker alone does not move any records.

Working Offline

If the database cannot be reached, keep working. MediaFlow notes which projects changed and syncs them when the connection returns. The status line then reads “Connected”, or “Connected · offline changes still to sync: …” followed by the names of projects that are waiting. Open a named project to finish its sync.

Database Menu

See also: SQLite File or PostgreSQL Server?, Connecting to a PostgreSQL Server, Copying Records Between the File and the Server, Working Offline and Syncing Later, Global Search, Database Connection Issues

Search every project in the shared database by filename, tag or note, then add a result to the open project.

Global Search finds clips in any project the shared database knows about. It needs a connected database; when there is none, the window says “Database not connected” and Search is dimmed.

  1. Choose Database → Global Search (Cmd+Shift+F)
  2. Type a filename, tag or word from a note, then press Return or click Search. Results do not update as you type
  3. Narrow the results with the Category and Camera filters
  4. Each result shows the clip and the project it belongs to
  5. Select a result to see a preview and its details

From a result you can choose Add to Current Project, or Reveal in Finder to find the file on disk.

Tip: If search finds nothing on a database file made by an early version, connect once with this version. MediaFlow rebuilds the search index on its own.

See also: Shared Database Overview, Filtering and Searching, Database Connection Issues

Finding Duplicate Files

List files with identical content across projects and see how much space the extra copies use.

  1. Choose Database → Find Duplicates
  2. MediaFlow looks through every project in the database for files with identical contents
  3. Results are grouped. Each group shows how many copies there are, the size of each, and the space you could reclaim
  4. Each group lists every copy with its location and project

Click Refresh to scan again after you make changes. Find Duplicates needs a connected database. It only reports; it does not delete anything.

See also: Shared Database Overview, Storage Dashboard

Migrating Projects to the Database

Add existing .vpm project files to the shared database so its cross-project tools can see them.

Migrate Projects reads project files and records them in the shared database. Use it for projects made before you turned the database on. It needs a connected database.

  1. Choose Database → Migrate Projects
  2. Click Choose Files to pick .vpm files, or Choose Folder to search a folder and everything inside it
  3. Use Select All, Deselect All and the Filter files… field to decide which files to include. Add Files…, Add from Folder… and Add More… add to the list
  4. Click Migrate Selected
  5. A progress view shows each project as it is read
  6. When it finishes, Per-Project Details shows how many clips were imported and how many were linked to entries the database already had

Tip: Migration does not change your .vpm files. The database stores a copy of what they say.

To move the database itself between a SQLite file and a PostgreSQL server, see Copying Records Between the File and the Server.

See also: Shared Database Overview, Copying Records Between the File and the Server

Storage Dashboard

See how full your shared storage is, how that has changed over time, and what the database holds.

Choose Database → Storage Dashboard. It needs a connected database.

Where Snapshots Come From

When a snapshot is recorded

A snapshot is a reading of how full the volume is. MediaFlow takes one when you open the dashboard, when you click Refresh, and whenever it re-checks a project’s files while the database is connected. The dashboard opens straight away on what it already has and adds the new reading a moment later, so a volume that is asleep or unplugged does not hold it up.

A reading is kept only when it tells you something the last one did not: an hour has passed, or the free space has changed by at least 1 GB (half a percent on a large volume). Two readings are never kept less than a minute apart, however often you click Refresh. A volume that cannot be read records nothing, so a disconnected drive does not show up as a drop to zero.

The bottom of the dashboard says how long ago the volume was last measured. When that is more than a day, it turns orange: the figures describe the volume as it was then. Connect the volume and click Refresh.

The dashboard shows the history of the NAS chosen in Settings › Network. With no NAS chosen, the history is empty.

See also: Shared Database Overview, Finding Duplicate Files, Storage Forecast, Choosing and Connecting Your NAS

SQLite File or PostgreSQL Server?

The shared database is optional and can live in a SQLite file for one Mac or on a PostgreSQL server for several.

The shared database tracks clips across all your projects. It powers Global Search, Find Duplicates, the Storage Dashboard and the project browser. It is optional. Your project files are the authority: every project opens, imports and organizes without a database, and the database is filled from the project files, not the other way round.

If you turn it on, you choose where it keeps its records.

Tip: Choose the SQLite file if you work on one Mac or have no NAS. Choose the server if two or more Macs use MediaFlow at the same time. You can move between them later, with your records.

Choosing or switching

  1. Open Settings › Storage and turn on Enable Central Database
  2. Under Store, pick SQLite file or PostgreSQL server
  3. For a file, click Choose… beside Database and pick the file. For a server, fill in Host, Port, Database, User and Password

Switching the Store reconnects at once; you do not need to relaunch. Switching does not move any records. The other store keeps what it had, and its settings are remembered, so switching back finds it again.

Taking your records with you

With PostgreSQL server selected, two buttons copy every record in either direction: Copy the SQLite File to This Server… and Copy This Server to a SQLite File…. Neither changes its source.

See also: Shared Database Overview, Connecting to a PostgreSQL Server, Copying Records Between the File and the Server, Working Offline and Syncing Later, Setting Up MediaFlow

Connecting to a PostgreSQL Server

Enter the server’s host, port, database, user and password in Settings › Storage, or use the guide to set one up.

A PostgreSQL server lets several Macs use the shared database at the same time. The server keeps the records itself; nothing on this Mac is copied to or from it. If you already have a server, fill in the fields. If you do not, Set Up a Server… walks you through making one in about ten minutes. The button is in Settings › Storage under either store, so you can prepare a server before switching to it. MediaFlow does not install anything on the NAS itself: the guide saves one file, docker-compose.yml, which the NAS’s container app runs. The guide shows the port the server will answer on, which is the one in the Port field, and offers to put it back to 5432 if it is something else; use that same port when you connect.

Warning: The connection to the server is not encrypted. Use it only on a home or studio network you trust, and never forward the server’s port to the internet.

The fields

Changes take effect without restarting: when Test Connection succeeds, and when you close Settings, MediaFlow connects to the server the fields now describe. When a message says the name was found, the Host is right and the Port is what to check: it must be the number the server was started with, the one before the colon on the ports line of docker-compose.yml.

The fields save as you type. On every other Mac, enter the same host, port and password; there is nothing to copy.

Test Connection

A successful test shows the server’s version, such as PostgreSQL 16. A failed test says why:

Set Up a Server…

  1. Click Save docker-compose.yml…. This file describes the server to a container app. It contains the password, so it is saved readable only by you. Keep it private
  2. Put the file in a folder of its own on the NAS or computer that will run the server. The database keeps its data in a folder beside it
  3. Start it: in the NAS’s container app, create a project from that folder. On a computer with Docker, run docker compose up -d in that folder. The first start takes a minute or two
  4. Back in Settings, set Host and click Test Connection

Which password goes in the file

See also: SQLite File or PostgreSQL Server?, Copying Records Between the File and the Server, Choosing and Connecting Your NAS, Database Connection Issues

Copying Records Between the File and the Server

Copy every shared-database record from the SQLite file to the PostgreSQL server or back; the source is never changed.

When you move from a SQLite file to a PostgreSQL server, or want a file copy of the server, MediaFlow copies every record for you. The copy reads the source and never changes or removes anything in it. Both buttons are in Settings › Storage, with PostgreSQL server selected as the Store.

If the destination already has records

The copy stops and tells you how many projects and clips are there. Click Replace to replace everything at the destination with the records being copied, or Cancel to leave it alone.

Warning: Replace removes every record at the destination before copying. The source is not changed either way.

Reading the progress list

Each table shows how many rows were copied. Two counts may appear beside it:

A file that has been in use for years usually holds a little of both. The search index is not copied; it is rebuilt at the destination from the copied rows.

When it finishes

Click Switch to It Now to make the copy your store and reconnect, or Close to stay where you are.

Cancelling or failing part-way

Click Cancel at any time. Tables already finished stay at the destination; the table in progress is undone. The destination is then incomplete, so run the copy again and choose Replace. If the two databases are at different versions, update MediaFlow on every Mac and try again.

See also: SQLite File or PostgreSQL Server?, Connecting to a PostgreSQL Server, Shared Database Overview, Migrating Projects to the Database

Working Offline and Syncing Later

Changes you make while the shared database is unreachable are remembered and synced when it reconnects.

You can keep working when the shared database is out of reach, for example when the NAS is off or you are away from your network. Your edits are saved in the project file as usual. MediaFlow remembers which projects changed and syncs them to the database when it reconnects. You do not need to do anything.

What happens on reconnect

The status line reads “Syncing offline changes…” while every project that changed is synced, not only the one that is open.

Projects that wait

A project stays on the waiting list, and is named in the status line, until you open it. This happens when:

The status line

The status line is at the bottom of the Database menu and in Settings › Storage. After a reconnect it takes one of two forms:

Tip: With a SQLite file, only one Mac should use the database at a time. With a PostgreSQL server, several Macs can reconnect and sync at once.

See also: Shared Database Overview, SQLite File or PostgreSQL Server?, Database Connection Issues, Saving Projects

Storage Maintenance

Relinking Missing Media

Point missing clips at their files again, one at a time or by scanning a folder for matching names.

When a file is moved or renamed outside MediaFlow, its clip shows as Missing (a red X in the Where column). Relinking tells MediaFlow where the file is now.

Right-click a missing clip and choose Relink…, then pick the file. Relink… appears only when one missing clip is selected. Whenever the selection includes a missing clip, the same menu offers Relink Missing Media…, which scans a folder for the selected clips.

  1. Choose Workflow → Repair → Relink Missing Media
  2. Select a folder to scan for matching files
  3. MediaFlow matches by filename and uses file size to choose between files with the same name
  4. A progress dialog shows scanning, matching, and checking status
  5. Results report how many clips were relinked, and name any that were found but not relinked

Organized clips are checked, not just matched

When MediaFlow organizes a clip it records a checksum of the file. Clear Card later relies on that checksum to decide that a card can safely be erased. A file with the right name and size is not necessarily the same file, so when you relink a clip that has a recorded checksum, MediaFlow reads the file you chose (or the one it matched) in full and relinks only if its contents are identical.

Reading a large file takes time, especially over a network, so relinking organized clips is slower than it used to be.

The progress window has a Cancel button, for a single clip as well as a folder scan. Cancelling stops the work, including part-way through reading a large file; a clip whose check was stopped is not relinked. Clips that were already matched and checked stay relinked and are saved with the project, and the window reports how many were reconnected before you stopped it. Run the command again to pick up the rest.

Tip: Run Workflow → Repair → Re-check files after relinking to update every Where badge.

See also: Re-check files, Clips Showing as Missing

Storage Forecast

Project when the destination drive will fill up from your recent import rate.

The Storage Forecast tells you when the destination drive will fill up, so you can make room before a shoot. Choose Workflow → Plan & Deliver → Storage Forecast…. MediaFlow looks at the volume that holds the project destination and at how much you imported over the last seven days, then projects the day the drive will be full.

What It Shows

What-If Calculator

Drag the Additional shoot days (1–30) and GB per day (5–200) sliders to see how many days of headroom remain after the next shoot; the result turns red at three days or fewer, or reads “Over capacity!”.

If no destination is set, or its volume is not mounted, the sheet reports “No destination volume detected”. The Storage Warning smart notification opens this sheet when the destination passes 85% full. For storage history across all projects, use Database → Storage Dashboard.

See also: Storage Dashboard, Smart Notifications, Organizing Media to Storage

Reports

Generating Reports

Write a summary of the open project as a PDF, web page or spreadsheet, or as a hand-off file for an editor.

A report lists what is in the open project: totals, a breakdown, and a line for every clip. The project must contain at least one clip.

  1. Choose Workflow → Plan & Deliver → Report
  2. In the Export / Generate Report dialog, choose a format and click Generate
  3. Choose the folder to save into

You do not type a filename. MediaFlow names the file after the project file, as name_report plus the format’s extension. If a file with that name is already there, it adds the date and time to the name rather than replace it.

Formats

What the PDF and HTML Reports Contain

Tip: For more control over what an editor receives, use NLE Template Export instead of the two hand-off formats here.

See also: NLE Template Export, Dailies Report, Day Summary

NLE Template Export

Hand your categories, scenes, ratings and notes to Final Cut Pro, Premiere Pro or DaVinci Resolve as an import file.

The NLE Template Export creates a structured project file that you can import into your editing application. It transfers your MediaFlow organization — categories, cameras, scenes, tags, ratings, and notes — so your clips arrive pre-organized and annotated in your NLE.

How to Export

  1. Open a project with imported media
  2. Choose Workflow → Plan & Deliver → NLE Template Export
  3. Select your target NLE: Final Cut Pro, DaVinci Resolve, or CSV
  4. Set the organization, clip filter and metadata options
  5. Click Preview to see the file MediaFlow would write, if you like
  6. Click Export… and choose where to save

Final Cut Pro (FCPXML)

The FCP export generates an FCPXML v1.11 file that maps your MediaFlow metadata to FCP’s organizational structure:

Metadata mapping: notes become FCP comments, camera names become Reel metadata, star ratings become keywords, clips rated 4 or 5 stars or marked Hero become FCP favorites, the select status (Hero, Maybe or Reject) is added as a keyword, scene/shot/take data become markers at clip start, tags become keywords, and GPS coordinates are embedded as FCP scene/shot metadata with the reverse-geocoded location name as a keyword.

Rejected clips are not marked as rejected in Final Cut Pro. They arrive with the keyword for their select status, so you can filter on it there.

Location-Based Organization

When your clips have GPS coordinates (common with phone and drone footage), MediaFlow reverse-geocodes them into readable place names. You can use Location as an Event or Keyword Collection field to automatically group clips by where they were shot — for example, an event per shooting location like “Malibu Beach” or “Downtown LA”. Clips without GPS data are grouped under “Unknown Location.”

Tip: Combine Location events with Camera keyword collections to see exactly which cameras shot at each location, or use Category events with Location keywords to see where your A-roll vs B-roll was captured.

Tip: A live preview at the bottom of the FCP section shows exactly how your Library → Events → Keywords tree will appear in FCP’s browser, using real data from your project.

Adobe Premiere Pro

Premiere Pro can import FCPXML files natively via File → Import. Select the Final Cut Pro target in MediaFlow, configure your organization, and export the .fcpxml file. Then in Premiere Pro, use File → Import and select the .fcpxml file. Premiere will create bins from Events and preserve keywords, markers, and clip metadata.

Tip: Premiere Pro’s FCPXML import handles Events, keywords, and markers well. This is the recommended workflow for Premiere users — there is no need for a separate Premiere-specific format.

DaVinci Resolve (EDL)

The Resolve export generates an Edit Decision List with bin comments, clip names, timecodes, scene/shot metadata, notes, and ratings. Import the .edl file via File → Import → Timeline in DaVinci Resolve.

Bins for Resolve and CSV

For the DaVinci Resolve and CSV targets, the Organization picker decides how clips are grouped: By Category, By Scene, By Camera, By Shooting Day, By Place, or Flat (No Bins).

CSV (Universal)

The CSV export creates a spreadsheet-compatible file with all clip metadata organized into columns. Use this as a reference alongside manual import, or for custom workflows with other tools.

Clip Filtering

Metadata Options

Choose what travels with each clip: Notes, Scene/Shot, Ratings, Audio Flags and Tags. Turn off anything you do not want in your NLE.

Workflow → Plan & Deliver → Export FCPXML… is a separate, simpler command. It writes only your scene, shot and take data as Final Cut Pro markers.

See also: Generating Reports, Format Conformance Checker

Dailies Report

Generate a structured dailies report organized by shooting day, scene, and camera.

The Dailies Generator creates a report of your footage organized by shooting date, with optional grouping by scene and camera. It highlights circle takes and includes ratings, timecodes, and notes. Output is available in HTML, CSV, or plain text format.

How to Use

  1. Open a project with media clips
  2. Choose Workflow → Plan & Deliver → Generate Dailies
  3. Configure grouping options and content to include
  4. Select the output format (HTML, CSV, or Plain Text)
  5. Click Generate Dailies and choose a save location

Configuration Options

Output Formats

Tip: For the most useful dailies report, make sure clips have scene assignments, camera labels, and ratings before generating.

See also: Smart Selects, NLE Template Export

Day Summary

A one-screen wrap-up of everything imported on a shooting day, ready to paste into a message.

The Day Summary is a wrap-up you can send at the end of a shooting day. Choose Workflow → Plan & Deliver → Day Summary… and pick a date in the header. It covers every clip imported on that date, by import date rather than capture date.

What It Shows

Click the Copy button to place a plain-text summary on the clipboard for a text message, e-mail, or production log. For a printable per-scene breakdown use Generate Dailies instead.

See also: Dailies Report, Audio Levels, Generating Reports

Publishing

Preparing a Video for YouTube

Choose your finished video, transcribe it, and get a title, description, chapters and tags to paste into YouTube.

Prepare for YouTube works on the finished video you exported from your editor, not on the project’s clips. MediaFlow reads the file, transcribes what is said in it, and an SEO agent writes the words that go with it. You edit them, then copy them into YouTube or send the video from the Upload tab.

  1. Choose Workflow → Prepare for YouTube…
  2. Click Choose Video… and pick the exported video. MediaFlow shows its length and format. The file is only read; it is never changed and never sent anywhere
  3. Click Transcribe. A long video takes a few minutes. The line under the button says whether the audio stays on this Mac
  4. Fill in Your brief with what only you know: who the video is for, the tone you want, and anything the description must include, one item per line, such as links, credits or a call to action
  5. Click Write with the SEO Agent. See The SEO Agent for what it does and what it sends. If a title, description or tags are already there, MediaFlow asks before replacing them
  6. Edit anything you like. Click one of the other titles to use it instead. The checklist updates as you type
  7. Click Copy beside the title, the description and the tags, and paste each into YouTube. The chapters are added to the end of the description when you copy it

Your draft is saved in the project’s folder, in Publish/publish-draft.json, a moment after each change and when you close the window. It moves, archives and restores with the project. A project that has not been saved yet has no folder, and the window says the draft cannot be kept until it has one. Choosing a different video clears the transcript, the chapters and the thumbnail’s frame, because they belong to the video they came from.

Tip: You can use the checklist without the agent. Type your own title, description and tags, set the main phrase, and it checks them the same way.

See also: The SEO Agent, The Publishing Checklist, Making a Thumbnail, Uploading to YouTube, Speech Transcription, Privacy: What Leaves This Mac

The SEO Agent

A model writes your title, description, chapters and tags in three passes, and checks its own work against YouTube’s rules before you see it.

SEO means being found: in YouTube’s search, and chosen from the list of results. The agent works only from your video’s transcript and your brief. It is told never to invent facts, names, numbers or links, and never to promise what the video does not deliver.

What It Does

  1. Reads the transcript and works out what the video is, who it is for, and the main phrase: the few words someone would most likely type to find it
  2. Writes a first draft: five titles that take different approaches, a description, chapters at the points where the subject changes, tags, and three suggestions for the words on the thumbnail
  3. Checks the draft against the checklist, is given every fault it found, re-reads the draft as a viewer would, and revises. It always revises once, and again if something that must be fixed remains

The window shows each pass as it happens, and afterwards a line saying what the agent changed on its last revision. A revision that makes the draft worse is not used. Anything still wrong at the end shows in the checklist for you to fix: you have the last word. If the model’s chapters break YouTube’s rules and cannot be repaired, none are added and the Chapters field says why. If your API key is rejected, the spending limit is reached, or the Privacy switch is turned off while it is working, the agent stops and says so.

Which Model

The agent uses the model chosen in Settings › Analysis: the model on this Mac, or Claude, ChatGPT or Gemini with your own API key. A paid provider writes noticeably better than a small model on this Mac, takes about a minute, and costs a few cents for a video. The model on this Mac is free and private but slow: allow ten to twenty minutes for a video, with the window showing which pass it is on. A small model sometimes cannot finish the revision. When that happens you get its first draft, the window says so, and the checklist shows what is left to fix. The daily spending limit in Settings › Analysis applies, and the agent stops before a request that would pass it.

What Is Sent, and to Whom

With the model on this Mac, nothing leaves it. If you have pointed the local model at another computer on your network in Settings › Analysis, the transcript, the video’s length, your brief and the drafts go to that computer and no further; an address on the internet is refused. With a paid provider, the agent sends the transcript of the video you chose, the video’s length, your brief, and then its own drafts for revision, to that provider. It never sends the video, its file name, or anything else in the project.

This is off until you turn it on. In Settings › Privacy, switch on “A model that writes your YouTube title, description and tags”. While it is off and a paid provider is chosen, Write with the SEO Agent tells you where the switch is and sends nothing.

Warning: Read what it writes before you publish it. The agent works from a transcript, and speech recognition mishears names, places and technical words. A wrong name in a title is your name on a mistake.

See also: Preparing a Video for YouTube, The Publishing Checklist, Privacy: What Leaves This Mac, Using a Model to Suggest Categories

The Publishing Checklist

What the checklist checks, which items YouTube enforces and which are advice.

The checklist beside the editor runs on whatever is in the fields, whether you or the agent wrote it. A red item is something YouTube enforces or that breaks a feature. A grey item is advice.

Must Fix

Advice

The limits are YouTube’s. The advice is long-standing common ground about YouTube search, not a promise of how a video will rank.

See also: Preparing a Video for YouTube, The SEO Agent

Making a Thumbnail

Pick a frame from your finished video, put a few words over it, and export a thumbnail that meets YouTube’s specification.

The Thumbnail tab of Prepare for YouTube makes the picture that goes with your title. It works from the finished video you chose; the video is only read. Nothing leaves this Mac.

  1. Choose Workflow → Prepare for YouTube…, choose your finished video if you have not, and click the Thumbnail tab
  2. Drag the Frame slider to the moment you want. The picture follows roughly while you drag and settles on the exact frame when you let go
  3. Or click Suggest Frames. MediaFlow looks through the video, leaving out the first and last twentieth where titles, fades and end cards live, and offers frames with the sharpest first. Click one to use it
  4. Type the words. Press Return for a second line; two lines is the most. If the SEO agent has written for this video, its suggestions appear as buttons under the field
  5. Choose where the words sit, their colour, and whether they have a dark band behind them. Size makes them smaller than the largest that fits
  6. Click Export Thumbnail…. MediaFlow offers the project’s Publish folder

What Is Exported

A JPEG, 1280 by 720 pixels, the 16:9 shape YouTube asks for, and under its 2 MB limit: MediaFlow lowers the JPEG quality a step at a time until the file fits, which for nearly every frame means not at all. A vertical or square video is cropped to its middle, never squashed.

Words That Can Be Read

The frame, the words and their style are saved with your draft, so reopening the window shows the same thumbnail and exporting again gives the same file.

See also: Preparing a Video for YouTube, The SEO Agent

Uploading to YouTube

Send the finished video, its words and its thumbnail to your channel from the Upload tab, with the visibility you choose.

Uploading is off until you turn it on. Turn on Uploading to YouTube in Settings › Privacy, add a Google client of your own (see Setting Up Your Google Client), and sign in. Nothing is sent until you click Upload and confirm.

  1. Choose Workflow → Prepare for YouTube… and click the Upload tab
  2. Click Sign In to YouTube…. Your browser opens at Google; sign in there and pick the channel. MediaFlow never sees your password. It asks for the narrowest permission that can upload, which Google words as “Manage your YouTube videos”. It cannot read your channel or delete videos. It could also replace a thumbnail, watermark or banner; MediaFlow uses it only to send the video and its thumbnail
  3. Choose the visibility: Private, Unlisted or Public. Or turn on Publish at a set time: the video goes up Private and YouTube makes it public at that time, which must be at least 15 minutes away
  4. Answer Made for kids. YouTube requires the answer by law, and MediaFlow does not give it for you: the upload cannot start until you choose
  5. Choose the category. Turn on Send the thumbnail from the Thumbnail tab if you made one; left off, YouTube picks a frame itself
  6. Deal with anything listed in red. An upload does not start while the checklist on the Words tab has something that must be fixed
  7. Click Upload to YouTube…. MediaFlow shows what is going, how large it is and how visible it will be. Click Upload to send it

If Your Uploads Come Out Private

Google keeps every upload Private from a Google Cloud project that has not passed its audit, whatever visibility is asked for. A project you have just made has not. The video is safely on your channel: open it in YouTube Studio and change the visibility there. Google’s audit form is linked from the YouTube Data API page of your project.

A Dropped Connection, or Stopping

The video is sent in pieces. If the connection drops, or YouTube is busy, MediaFlow waits, asks YouTube how much arrived, and carries on from there. It waits longer after each failure and gives up after ten in a row, a little over a quarter of an hour; being off the network altogether is simply waited out. If you click Stop or quit, what was sent is kept: the button reads Continue the Upload… next time, for about a week, unless you sign out. The upload starts again from the beginning if the video file has changed, or if you have changed the title, description, tags or settings, because an unfinished upload carries the words it was started with; MediaFlow tells you so before it begins. Only YouTube letting the upload lapse, a changed video or changed details start it again: an expired sign-in, a full allowance or a dropped connection never do. A publish time is fixed when the upload starts, so for a large video on a slow connection choose a time well ahead.

The Thumbnail

The thumbnail is sent after the video. YouTube accepts custom thumbnails only from a channel verified by phone (youtube.com/verify). If it is refused, the video is still up: MediaFlow says so, and Send the Thumbnail to This Video tries again without uploading the video again. You can also export the thumbnail and add it in YouTube Studio.

What Is Kept

What the Database Records

When an upload finishes, MediaFlow adds the video to the shared database, if you use one. It is kept there, in the published_videos table, as the record of what you have published across all your projects. Nothing about it is sent anywhere else.

These are the words and settings the video went up with, even if you edit the draft afterwards. If the database was not connected when the upload finished, the video is added the next time you open Prepare for YouTube for that project, or upload from it; a later upload does not push it aside. The visibility is what you asked for: MediaFlow’s permission cannot read your channel, so if Google kept a Public video Private, or you changed it in YouTube Studio, the database does not know. Turning on statistics changes that: see How Your Videos Are Doing.

Tip: An upload uses most of a new Google Cloud project’s daily allowance of 10,000 units: 1,600 for the video and 50 for the thumbnail. That is about six videos a day. The allowance resets at midnight Pacific time.

See also: Setting Up Your Google Client, How Your Videos Are Doing, Preparing a Video for YouTube, The Publishing Checklist, Making a Thumbnail, Privacy: What Leaves This Mac

Setting Up Your Google Client

MediaFlow uploads through a Google Cloud project of your own. Making one takes about ten minutes and is free.

Google requires every app that uploads to YouTube to identify itself with a client. MediaFlow uses one that belongs to you, so your uploads count against your own allowance and nobody else stands between you and your channel. You do this once.

  1. In your browser, open console.cloud.google.com and sign in with the Google account that owns your channel
  2. Create a project. Any name will do
  3. Under APIs & Services › Library, find YouTube Data API v3 and click Enable. If you will read statistics, enable YouTube Analytics API too
  4. Under APIs & Services › OAuth consent screen, choose External, give the app a name and your email address, and save. Add your own Google account under Test users
  5. Under APIs & Services › Credentials, click Create Credentials › OAuth client ID, and choose the application type Desktop app
  6. Copy the client ID and the client secret Google shows you
  7. In MediaFlow, open Settings › Analysis. Under YouTube, paste the client ID, paste the secret and click Save

The client ID is kept in MediaFlow’s settings. The secret is kept in the Keychain, never in a file, the saved setup or a log.

What to Expect at Sign-In

Warning: The type must be Desktop app. A Web application client is refused at sign-in, because it does not allow the answer to come back to this Mac.

See also: Uploading to YouTube, Privacy: What Leaves This Mac

How Your Videos Are Doing

The Results tab lists what you have published and, if you allow it, reads each video’s views, watch time and more from YouTube and keeps them over time.

The Results tab of Prepare for YouTube shows the videos MediaFlow uploaded, from this project or from all of them: when each went up, its size and length, the visibility you asked for and when it went live. This comes from your shared database and needs nothing from YouTube. Without a database connected, the tab says so.

Reading Statistics from YouTube

This is off until you turn it on, and it needs more permission than uploading does.

  1. Turn on Reading your videos’ statistics from YouTube in Settings › Privacy
  2. In your Google Cloud project, under APIs & Services › Library, enable YouTube Analytics API as well as YouTube Data API v3
  3. On the Upload tab, sign out if you are signed in, then sign in again. Google now asks for two more permissions, both read-only: View your YouTube account, and View YouTube Analytics reports for your YouTube content. If you untick both at Google you can still upload, and the Results tab tells you statistics were not allowed. Ticking only one is no use, and Google cannot take back one alone, so MediaFlow hands the whole sign-in back and asks you to sign in again
  4. On the Results tab, click Read from YouTube Now

MediaFlow asks Google which channel you signed in to, then sends the YouTube IDs of the videos your database records as uploaded by MediaFlow, and the span of dates from the first upload to today. Nothing else. The two permissions would allow reading your whole channel; MediaFlow asks only about those videos. If your database is shared with someone who publishes to another channel, answers about their videos are set aside, not kept as yours. Neither permission can change or delete anything.

You can turn on statistics without uploading: with only that switch on, sign-in asks for the two read-only permissions alone, and the Upload tab says the sign-in cannot upload.

What Is Read and Kept

Each reading is kept in the published_video_stats table of your database, about one a day for each video (never within 20 hours of the last), so you can see a video at a day, a week and a month. The tab shows the latest numbers and the views gained since the reading before. Reading again sooner updates nothing but the visibility. Statistics are read only when you click the button; nothing is read in the background.

Tip: MediaFlow does not read impressions or click-through rate; look for them in YouTube Studio. The YouTube Studio link beside each video opens it there.

See also: Uploading to YouTube, Setting Up Your Google Client, Privacy: What Leaves This Mac

Project Management

Saving Projects

Save the project file (.vpm), save it under a new name, or go back to the last saved version.

A project is saved as a .vpm file. It holds the list of clips and where their files are, plus your categories, tags, ratings, notes and project settings. It does not contain the media itself.

The project file is the authority. When the shared database is connected, each save also updates the database. If the database cannot be reached, MediaFlow notes that the project changed and syncs it when the connection returns.

See also: Moving a Project, Renaming a Project, Duplicating a Project, Working Offline and Syncing Later

Renaming a Project

Change the open project’s name. Its project file is renamed to match; the project folder and the media keep their names.

  1. Choose File → Rename Project
  2. Enter the new project name in the dialog
  3. Click Rename. The project file is renamed to match, in the folder it is already in. Click Rename, Keep File Name if you want the name changed in MediaFlow only

Renaming changes the project’s name in MediaFlow: in the window, in the recent and browse lists, and in the shared database if it is connected. The project is saved straight away, and any edits still waiting to be saved are written first.

What happens to the file

See also: Saving Projects, Moving a Project

Moving a Project

Copy the whole project folder to a new place, check the copy, then decide whether to delete the original.

  1. Choose File → Move Project To
  2. Select the new parent folder for the project
  3. MediaFlow copies the entire project folder to the new location. If a folder with the project’s name is already there, the move stops before copying anything
  4. All internal paths (clip URLs, thumbnails, etc.) are updated automatically, and the project is saved in its new folder
  5. When you close the progress window, MediaFlow asks whether to delete the original folder

What is checked before the original can go

Every file is read back after it is copied and compared with its original by checksum, and the copy must account for every file in the original folder, including hidden files. Permissions, Finder tags, and dates travel with each file. If any file fails, the partial copy is removed, the original is left exactly as it was, and the project stays where it is. The summary tells you how many files were copied and verified.

The question about deleting the original is answered some time after the copy was made, so MediaFlow checks again at that moment. It deletes the original only if the copy can still be reached, still holds every file of the original, and is where the open project now lives. If the drive holding the copy has been unplugged, or you have opened a different project, the original is kept and MediaFlow says why. On a local drive the original goes to the Trash; on a network volume there is no Trash and it is deleted outright.

If the project cannot be saved in its new folder, MediaFlow puts the project back at its original location and tells you. The copy is left in place for you to inspect or delete.

Cancel on the progress window stops the copy between files. The original project folder is never touched, so nothing is lost, and the partly copied folder is removed.

Tip: Moving copies every file in the project folder, so check that the new location has enough free space first.

See also: Saving Projects, Deleting a Project

Editing on an Editing Drive

Copy the project you are editing to your fastest drive, keep the library copy safe where it is, and bring the project back when the edit is done.

A library lives on large storage, which is rarely the fastest you own. An editing drive is a folder on fast storage, such as an SSD volume on a NAS or an external SSD, for the projects you are editing now. Clips there start sooner, scrub more smoothly and drop fewer frames, in MediaFlowSwift and in your editor.

  1. Open Settings → Storage and choose the Editing drive folder. You do this once
  2. Open the project and choose File → Move to Editing Drive…
  3. MediaFlowSwift measures the project and shows how many files and how much will be copied, where to, and how much room is free there. Click Move to Editing Drive

What Happens

When It Is Refused

Nothing is copied if no editing drive folder has been chosen or it cannot be reached, if the project is already on the editing drive, if a folder with the project’s name is already there, if one folder is inside the other, or if the editing drive does not have room for the project and a little over. Nor if the project folder cannot be reached, or while an import, organize, archive, proxy run or Library Moved is running: it is refused with a message, not queued. Everything is asked again when you click Move to Editing Drive, in case the sheet has been open a while.

Returning to the Library

When the edit is finished, open the project from the editing drive and choose File → Return to Library…. MediaFlowSwift looks at both copies and shows what is new or changed on the editing drive, such as exports, renders and notes. Everything is ticked to begin with; untick anything you do not want in the library. It also says how many files are in both places already, and how many are in the library only, which are left as they are.

Proving the library copy means reading it, so expect roughly the time it would take to copy the project from the library. Stop abandons a file that is being checked at once, and waits for one that is being copied to finish; the project stays on the editing drive and nothing is removed. Once everything is checked and the project is being saved in the library, Stop is no longer offered. If you use a shared database it must be connected.

In the Projects List, and on Another Mac

Warning: While a project is on the editing drive, work in that copy. The library copy is a safety net, not a second place to edit: changes made to it are not brought across. If you open the library copy on this Mac while the project is out, MediaFlowSwift says so.

On a Mac that knows a project is out, Cleanup and Free Up Space never take a file out of its library copy, even where it looks like a spare copy of a clip on the editing drive. The Mac that sent it out knows at once; another Mac knows from the first time it opens the project or its library copy with the shared database connected.

Tip: Copying writes the whole project across. Over a wireless connection that can be slow; a wired connection to the drive is many times faster.

See also: Moving a Project, After Moving Your Library to a New Drive, Processing the Proxy Queue

After Moving Your Library to a New Drive

When you have copied your whole library to a new drive yourself, Library Moved points every project at the new place. Nothing is copied.

Use this when the footage is already where you want it: you copied your projects folder to a new drive or NAS, keeping the folders inside it as they were, and every project still points at the old one. Move Project is for the other case, where MediaFlowSwift does the copying.

  1. Make sure both drives are connected
  2. Choose Workflow → Repair → Library Moved…
  3. Set Was in to the folder your projects used to be in, and Is now in to the folder that holds the same projects now. MediaFlowSwift suggests the folder your recent projects share, and the destination new projects use
  4. Click Find Projects. Nothing is changed yet. Each project file found under the old folder is listed with how many of its clips are at the same place under the new one
  5. Click Check and Point. Projects are done one at a time, and you can stop at any point

What Is Checked

A clip is followed only if a file is at the same place under the new folder and is the same size. If the clip was checksummed when it was organized, the file at the new place is also read in full and compared, because Clear Card later trusts that checksum: same name and same size is not proof. A clip with no recorded checksum is followed on its size. A clip that is missing, a different size, or different inside keeps pointing where it did and is listed.

What Changes

The Old Copy of a Project

Library Moved never changes or removes the project file at the old location, so that file still opens, under the same name. It is an old copy: its clips point at the old location, so they read Not at destination, and work done in it stays in it. When you open one on the Mac that ran Library Moved, MediaFlowSwift says “This is an old copy” and offers to open the current copy instead. It knows from its own note of what Library Moved did. For a library moved before this version, choose Library Moved again with the same two folders and click Find Projects: every project already followed is noted, and nothing is changed. Another Mac has no such note until Library Moved has been opened on it the same way. Separately, if a project file is kept apart from its destination folder and another file for the same project is found in that folder, MediaFlowSwift says “There is another copy”, shows where each is and when each was saved, and does not claim to know which is current. Your answer is a decision about where the project lives, and is recorded at once in this Mac’s projects list and in the shared database. Open the Current Copy (or Open the Other Copy) makes that copy the project’s home, so it is the one that opens next time. Use This Copy and Don’t Ask Again, offered when MediaFlowSwift does not know which copy is current, makes the open copy the home and stops the question for that file. Stay Here only looks: nothing is recorded, this Mac’s projects list points at the other copy, saves made here are not sent to the database (the status line says Not synced), and you are asked again next time.

The same question is asked when the shared database records the project as living in another file that is still there. A project is written to the database only from the file the database says it lives at, unless that file is gone, Library Moved has noted it as the old copy, or you have said otherwise. That is what keeps a stale copy, opened by mistake on any Mac, from overwriting what every Mac sees. When the old drive is retired, the old copies go with it.

Stopping and Running It Again

Stop ends the reading within a moment and leaves the project being checked exactly as it was; projects already finished stay finished. Running Library Moved again skips projects that already point at the new location and reads only what is left: a project whose folder you copied across later, or the clips of a project that could not be followed the first time. It cannot start while an import, organize, archive, move, relink or Clear Card is running. While it runs, organizing, refiling, Clear Card, Free Up Space, archiving and restoring, Move Project, Change Destination, relinking, workflow steps and installing an update are all refused until it has finished. Importing is not: new clips join the open project and are kept.

The progress bar moves as each clip is finished, not while one is being read. The line under it names the clip being read and its size, so a long clip does not look like a stall.

Tip: Reading every checksummed clip takes as long as copying it would. On a wireless connection expect about a minute for every 4 GB.

See also: Moving a Project, Change destination folder, Clear Card

Deleting a Project

Take a project off the project list, or also delete its folder and everything in it.

Choose Projects → Browse Projects, right-click a project and choose Delete Project…. You are offered two things:

Move Folder to Trash does not act at once. MediaFlow first counts what is in the folder and shows a second confirmation with the number of files and their total size. You must tick “I understand this cannot be undone” before the confirm button works.

Warning: The project folder usually holds media files as well as the project file. On a disk in this Mac the folder goes to the Trash, where you can still recover it. A network share has no Trash, so the folder is deleted outright and cannot be recovered.

See also: Moving a Project, Opening an Existing Project

Moving Clips Between Projects

Move selected clips out of the open project and into another project.

  1. Select the clips you want to move
  2. Choose File → Move Assets to Project, or right-click and choose Move to Project…
  3. The project picker shows all available projects
  4. Select the target project and click the Move button, which shows how many clips will move
  5. MediaFlow adds the clips to the target project and removes them from this one

Tip: Both projects are saved automatically after the transfer. If the database is connected, both are synced.

See also: Selecting Clips, Saving Projects

Duplicating a Project

Duplicate asks whether the new project shares this one’s media files or gets verified copies of its own.

Duplicate gives you a second project that starts as a copy of this one: the same clips, categories, tags, ratings, notes, shot list and storyboard. It asks one question first, because the answer decides what deleting a clip will mean.

Share Media

A second project over the same files. It is quick and takes no space, and it suits a second edit of the same shoot. But the files are shared: deleting or moving a clip in either project affects both.

Copy Media Too

Every clip is copied into a folder you choose for the duplicate. Each copy is read back and its SHA-256 compared with the original before the duplicate points at it. It takes as long, and as much space, as the media itself, and you can keep working while it runs.

To duplicate a project

  1. Choose File → Duplicate
  2. Choose Share Media or Copy Media Too…
  3. Choose a name and place for the new project file. MediaFlow suggests the project name followed by “Copy”
  4. For Copy Media Too, choose or create the folder the copies go in

With Share Media the duplicate becomes the open project; open the original again with File → Open Recent. Clips in the proxy queue are not queued in the duplicate.

Tip: To stop two projects sharing, duplicate the one you want to keep working in with Copy Media Too. The new project has files of its own and can be re-filed freely.

See also: Saving Projects, Moving a Project, Deleting a Project, Freeing Up Space, What Happens to Files When You Change a Category

Project Checklist

Track nine milestones of a project, from import through archive, in the older checklist screen.

The Project Checklist shows how far a project has come. Choose Workflow → Plan & Deliver → Project Checklist (legacy)… to open a sheet with nine fixed milestones. Six carry an Auto badge and are ticked from the state of your clips. Three you mark yourself with the Done button beside them; Undo unmarks them. The pipeline strip above the media list now shows the same progress at a glance, which is why the menu item says legacy.

Milestones

Phase and Progress

The header shows the project phase — Setup, then Production once media is imported, Post-Production once it is organized, and Delivered when all nine items are complete — together with an n/9 progress ring (orange below 50%, blue above, green at 100%). Completed items show the date they were completed.

Click Refresh to re-evaluate the automatic items after you make changes. The checklist is saved inside the .vpm project file, and the automatic items are recomputed every time the project loads.

See also: Understanding the Pipeline Strip, Organizing Media to Storage, Archiving a Project to USB, Star Ratings & Selects

Archiving a Project to USB

Copy a finished project folder to a numbered USB drive for long-term storage, with every file checked before the original may go.

Archive to USB frees your working storage by copying a finished project to a drive you can put on a shelf. It copies the whole project folder to a removable drive, checks the copy, and records where it went in the central database. Archive volumes are numbered (USB #0001, USB #0002, …) so a project can always be found again. Only the project folder is copied; media organized to a destination outside the project folder is not included.

Archiving

  1. Plug in the drive and choose Workflow → Archive to USB…; click Scan if it is not listed
  2. A drive that has never been used shows “(not initialized)”. Select it, give it an optional label such as “Interviews 2026”, and click Set Up. MediaFlow writes a hidden marker file to the drive and assigns the next number. Numbers are permanent
  3. Pick a drive. The smallest initialized drive that still fits is marked Recommended; drives that are too small show an orange warning
  4. Click Archive. Progress moves through Preparing, Copying, Flushing, Verifying, Updating Database, and Done
  5. Dismiss the progress dialog to reach the completion screen described below

Every file is read back from the drive after it is written and compared with its original by checksum, so a file damaged on the way — even one that kept its size — fails the archive rather than being recorded. The Verifying step then confirms the number of files and their total size. Because each file is read twice, archiving takes noticeably longer than a plain copy, most of all on a USB hard drive or with a project made of many small files. File contents and dates are archived; Finder tags and similar extras are not, because most archive drives are formatted in a way that cannot hold them. On success the project is marked Archived with the volume number, date, and path, and the Project Checklist’s Archived item completes. In the project browser the row reads “Archived → USB #0007”.

Completion screen

After the progress dialog closes, an Archive Complete screen summarizes the result — “Archived 312 files (48.2 GB) to USB #0007 · verified” — and lists the drive (or every drive, for a split archive) with an Eject button for each one that is still connected. “Keep Original” closes the screen and leaves both copies in place. “Delete Original…” removes the original project folder, wherever it is stored. It scans the folder first and then shows the same confirmation used when you delete staged files or delete a project: the file count, the total size, a warning when the folder is on a network volume (where there is no Trash to recover from), and a checkbox you must tick before the delete button enables. Confirming moves the folder to the Trash, or deletes it outright on a network volume.

Warning: Deleting the original leaves the USB drive as the only copy of the project. Every file on it was compared with its original by checksum, but a single drive can still fail on the shelf; for footage you cannot replace, archive to a second drive as well before you delete. “Delete Original…” is disabled when the database update was queued instead of saved; keep the original until the database has recorded the archive.

Archiving a project again

If the drive already holds an archive of the project, the new archive is written beside it and checked first. Only when every file has passed is the old archive replaced. If the new archive fails or you cancel, the old one is left exactly as it was.

Splitting Across Drives

If the project is larger than any one drive, click Split Across Drives…. MediaFlow plans which folders go on Drive 1, Drive 2, and so on, then asks for each drive in turn. If a run is interrupted, opening the sheet again detects the partial copies and the button reads Resume Archive.

Cancelling

Cancel on the progress window stops an archive between files. Files already written to the drive stay there. A split archive that is stopped part way can be picked up later with Resume Archive.

Archiving needs the central database to record volumes and projects.

See also: Restoring an Archived Project, Managing Archive Volumes, Project Checklist, Shared Database Overview, Freeing Up Space, Moving a Project

Restoring an Archived Project

Bring a project back from its USB archive drive, or drives, with every file checked against the archive.

To bring an archived project back, open the project browser, right-click the archived project, and choose Restore from Archive…. Restoring needs the central database, which records which drive holds each project.

  1. Plug in the archive drive. It does not have to mount under the same name it had when you archived; MediaFlow looks for the project on every connected archive drive
  2. Choose the folder to restore into. The project comes back as a folder inside it, with the name it was archived under. If a folder with that name is already there, the restore stops before copying anything; choose a different folder
  3. For a project split across drives, MediaFlow asks for each drive in turn and merges them into the one folder
  4. When it finishes, the project is no longer marked Archived and its clips point at the restored files

A restore is checked more strictly than an archive. Every file is read back after it is copied and compared with the file on the drive by checksum. Each drive is also checked against the number of files recorded when the project was archived, so a drive that has lost a file since then stops the restore rather than quietly bringing back less than you archived. (Projects archived before this check was added have no recorded count for a single drive; those are checked file by file only.) If anything fails, the partly restored folder is removed, the project stays marked Archived, and nothing on the drive is changed.

If the project lists a clip that was not on any of the drives, the restore still completes and tells you which clips: they are marked Missing, not shown as present. Media the project used from outside its own folder was never copied to the archive, so it is left where it was and shown as In Place if it is still there, or Missing if it is not.

Warning: Do not erase an archive drive just because a restore succeeded. Open the restored project and play a few clips first.

See also: Archiving a Project to USB, Managing Archive Volumes, Shared Database Overview

Managing Archive Volumes

See every numbered archive drive, what is on it, and whether it is connected.

File → Manage Archive Volumes lists every registered drive with its number, label, used space, and whether it is currently connected. Select a volume to edit its label, see capacity and creation date, and view the projects archived on it with their sizes. A drive that carries a marker but is missing from the database is registered automatically the next time it appears in the archive sheet.

Tip: Label each drive on the outside with its USB number so the numbers in the app match the shelf.

See also: Archiving a Project to USB, Restoring an Archived Project

Settings & Preferences

The Settings Window

What each of the eight Settings tabs is for: General, Network, Storage, Cameras, Categories, Analysis, Privacy and Notifications.

Choose MediaFlow → Settings (Cmd+,). The window has eight tabs. This topic says what each one is for; the related topics go into detail.

General

Network

Where you choose the NAS that MediaFlow reconnects to. Nothing is assumed: until you choose one, the tab says “No NAS chosen yet”.

Storage

Cameras

Categories

Analysis

Privacy

Every connection MediaFlow can make to a service outside this Mac, each with its own switch. All are off until you turn them on. Each row says what is sent and to whom. See Privacy: What Leaves This Mac.

Notifications

One switch for each Smart Notification: Uncategorized Clips, Missing Cards, Format Mismatch, Storage Warning, Unrated Clips and Stale Project.

See also: The Settings Window, Tab by Tab, Privacy: What Leaves This Mac, Setting Up MediaFlow, Choosing and Connecting Your NAS, Saved Setup: A Copy of Your Settings, Updating MediaFlow, SQLite File or PostgreSQL Server?, Connecting to a PostgreSQL Server, Adding, Renaming, Retiring and Removing Categories, Using a Model to Suggest Categories, How MediaFlow Verifies Copies, Smart Notifications

Smart Notifications

The banner at the top of the window that points out unfinished work in the open project.

When a project opens or changes, MediaFlow checks it against these conditions and shows the first one that applies as a banner above the media list. Each banner has an action button where one makes sense, and an X button that opens a menu with Dismiss and “Don’t show again for this project”.

Notification Types

Turn individual types off in Settings › Notifications. A “Don’t show again for this project” choice is remembered across launches; a plain Dismiss hides the banner only until MediaFlow next checks the project, so it can come back. A device-connection banner takes precedence while a card or phone is being detected.

See also: The Settings Window, Understanding the Pipeline Strip, Auto-Suggest Categories, Storage Forecast, Format Conformance Checker

Keyboard Shortcuts

Keyboard Shortcuts Reference

Every keyboard shortcut in MediaFlow, grouped by menu, plus the single keys used in Review and the video preview.

Menu shortcuts work anywhere in the main window. The Review keys work while Review is open (Workflow → Review); they are single keys with no modifier. The Video Playback keys work while the video preview has keyboard focus: click the preview first.

File Operations

Cmd+N — New Project

Cmd+Shift+N — Create Project From Folder…

Cmd+O — Open…

Cmd+S — Save

Cmd+Shift+S — Save As…

Cmd+W — Close Project

View

Cmd+Opt+T — Move Media to Top/Bottom

Cmd+Opt+P — Move Preview to Left/Right

Search & Projects

Cmd+Shift+F — Global Search…

Cmd+Shift+P — Browse Projects…

Editing

Cmd+F — Find Clips…

Delete — Remove from Project

Ratings & Selects

Cmd+1 — Rate 1 Star

Cmd+2 — Rate 2 Stars

Cmd+3 — Rate 3 Stars

Cmd+4 — Rate 4 Stars

Cmd+5 — Rate 5 Stars

Cmd+0 — Clear Rating

Cmd+Shift+H — Select › Hero

Cmd+Shift+M — Select › Maybe

Cmd+Shift+K — Select › Reject

Workflow

Cmd+Shift+R — Run Workflow Template…

Cmd+Opt+R — Review

Cmd+Opt+M — Shoot Map…

Cmd+Shift+T — Increment Take (Scene Log tab)

Review

Space — Play or pause

J / K / L — Shuttle reverse, stop, forward (press again to go faster)

← / → — Step one frame back or forward

Home / End — Jump to the start or end of the clip

↑ / ↓ — Previous or next clip

1–5 — Set the star rating

0 — Clear the star rating

F — Toggle Favorite

X — Toggle Reject

C — Toggle circle take

I / O — Mark the in or out point

A — Accept proposed category / camera (in Rapid Review)

R — Mark reject candidate (in Rapid Review)

T — Toggle auto-advance (in Rapid Review)

M — Show or hide the metadata overlay

? — Show or hide the key help

Esc — Close the key help, or leave Review

Video Playback

I — Mark In Point

O — Mark Out Point

Help

Cmd+/ — MediaFlow Help

Settings

Cmd+, — Settings…

Undo and Redo

These come from the standard Edit menu. They undo and redo changes to categories, tags, notes, ratings and selects.

Cmd+Z — Undo

Cmd+Shift+Z — Redo

See also: Reviewing Clips with the Keyboard, Star Ratings & Selects, Undo and Redo, Extracting Thumbnails and Subclips

Troubleshooting

Clips Showing as Missing

A red X in the Where column means MediaFlow cannot find the file; usually a drive or share is not mounted, or the file moved.

Symptom: a clip shows a red X and the word Missing in the Where column. MediaFlow cannot find the file at any path it has recorded for it.

Causes

Fixes

  1. Mount the drive or share. For the NAS you chose in Settings › Network, click Connect now there, or choose Database → Reconnect to NAS. Then choose Workflow → Repair → Re-check files
  2. If the files moved, choose Workflow → Repair → Relink Missing Media and pick the folder they are in now
  3. If the whole destination moved, choose Workflow → Repair → Change destination folder
  4. For one file, right-click the clip, choose Relink… and pick the file

See also: Relinking Missing Media, Change destination folder, Understanding the Where Column, Choosing and Connecting Your NAS

Reporting a Problem

Put together a report of what went wrong, with personal details taken out, to copy or save. Nothing is sent.

Choose Help → Report a Problem…, or click Report a Problem… where it is offered: on an error message, and under the list of files that failed in a copy. Say what happened and what you were doing, and leave an email address if you would like a reply. MediaFlowSwift adds what helps find a fault, and shows you the whole report before anything else happens. You can change any of it.

What Is in a Report

What Is Taken Out

Before you see the report, MediaFlowSwift takes out of everything it adds, including an error message it quotes: your account name and home folder; the names of your drives; every folder and file name in a path, which becomes /…/<file>.mp4, keeping only the kind of file; the names of the projects this Mac knows and of the open project’s clips and cameras; the names and addresses of your computers and servers; email addresses; and map coordinates. Drives, computers, projects and clips are numbered, so the same drive is <drive-1> all the way through and the report can still be followed. From a crash report it takes only the fields listed above: the device identifier and account details Apple puts in those files are never picked up. Passwords, keys and tokens are never in the log or a report; they live only in your Keychain.

It errs on the side of taking out too much. It cannot know a name it has never been told, such as a project on another Mac mentioned in the log, so read the report over; and what you type yourself is left exactly as you typed it. Once you edit the report, the fields above it stop changing it, so nothing you wrote is lost; Start Again from the Fields Above makes it afresh.

Sending It

Copy Report puts the text on the clipboard; Save… writes it to a file; sending it by email or however you like is up to you. There is also a Send button, if Sending problem reports is turned on in Settings › Privacy; it needs the address and key of a report relay entered there, and Test tells you whether the relay is reachable. Whoever supports your copy of MediaFlowSwift gives you both, and can tell you whether the reports they receive are kept private; an email address you give for a reply goes with the report. Send sends the text exactly as it is in the window, with a title, a random identifier for this copy of the app, and the crash signature if there is one, to that relay, which files it as an issue for the people who make MediaFlowSwift. The window then shows the report’s number. If the same crash has been reported before, your report is added to it. Nothing is ever sent on its own, and while the switch is off MediaFlowSwift makes no connection to do with reports.

After a Crash

If MediaFlowSwift quit unexpectedly, or did not quit cleanly (a force-quit, or the Mac losing power), it says so once, the next time it opens, and offers a report. If macOS itself stopped the app, for instance because of how this copy was installed or signed, it says that instead: it is not something you did.

Problems That Are Yours to Fix

A full disk, a drive that is locked, cannot be read or written, or is no longer connected, a network drive that stopped answering, a folder MediaFlowSwift is not allowed to use: these are not faults in the program, and a report about one would tell nobody anything. On an error message, and under the list of files that failed in an import, organize, archive or move, MediaFlowSwift says which it is and what to do about it, and does not offer to report it. Help → Report a Problem… is always there if you disagree.

Some failures could be either. A file that is not where it was expected may be on a drive that is unplugged, or may be a mistake in the program; so may a timeout, or a damaged database file. For these MediaFlowSwift says what to try and offers a report as well.

See also: Database Connection Issues, Clips Showing as Missing

Database Connection Issues

What to check when the shared database will not connect, for a SQLite file and for a PostgreSQL server.

The shared database is optional, and the project file (.vpm) is the authority. When the database is unreachable you can keep working; only the cross-project tools stop. The current state is on the last line of the Database menu and in Settings › Storage.

If You Use a SQLite File

Symptom: the status reads “Connection failed: …”, “NAS offline” or “Waiting for NAS…”. Cause: the file, or the drive or share it is on, cannot be reached.

  1. Open Settings › Storage and read the line under Database. “Database file accessible” means the file can be reached. “Database file not found (will be created on connect)” means the path is reachable but holds no file yet. “No database file chosen yet” means you need to click Choose…
  2. If the file is on a NAS, open Settings › Network. If it says Not connected, click Connect now, or choose Database → Reconnect to NAS
  3. Choose Database → Reconnect Database
  4. If the path is wrong, click Change… and pick the file. Reset to Default points at MediaFlow/mediaflow.db on the chosen NAS; it is dimmed until you choose a NAS in Settings › Network

MediaFlow watches the volume and connects again by itself when it comes back, including after the Mac wakes from sleep.

If You Use a PostgreSQL Server

Open Settings › Storage and click Test Connection. It shows the server’s version, or one of these messages:

If there is no server yet, Set Up a Server… walks you through making one.

It Stopped Connecting After an Update

Symptom: the database connected yesterday, and after an update it does not, with the same settings. The status reads “macOS is keeping MediaFlowSwift off your local network…”. Cause: macOS asks once whether an app may reach devices on your network, and after an update it sometimes stops applying your yes to the new version, even though the switch still shows on. The server and your settings are fine.

  1. Open Settings › Storage and click Open Local Network Settings…, or open System Settings › Privacy & Security › Local Network yourself
  2. Turn MediaFlowswift off, then on again. If it is listed more than once, turn every one on
  3. Go back to MediaFlowSwift. It looks again every few seconds for about ten minutes and connects by itself as soon as macOS lets it through. There is no need to restart it, or to choose Reconnect Database. After ten minutes, choose Database → Reconnect Database

MediaFlowSwift knows this within a few seconds of trying, where it used to wait ten and then guess. It asks macOS why the connection is being held back, looks twice, and still gives the connection itself three seconds to get through before saying so. If macOS will say nothing, you get the ordinary message about a server that did not answer instead, which still mentions the switch. You may also be asked once for leave to read the saved password after an update; choose Always Allow.

The Log

Help → Show Log reveals app.log in the Finder (it is in Logs/MediaFlow in your Library). MediaFlowSwift writes what it does there, and warnings and errors with their reasons in the database’s or the system’s own words, such as why a sync failed. It names projects, clips, cameras and the database server’s address. It never holds passwords or keys, nor the contents of a rejected database row. A new file is started when it passes two megabytes, and the one before is kept as app.previous.log. Nothing is sent anywhere: it is yours to read, or to attach when you report a problem.

Several Macs

Symptom: work done on one Mac is missing from the database after another Mac has used it. Cause: a SQLite file is for one Mac at a time. Each Mac works on its own local copy and writes the file back when it disconnects or quits, so the last Mac to quit wins. Fix: take turns, or switch to a PostgreSQL server, which several Macs can use at once. Your projects are not harmed either way, because the project files are the authority.

What the Status Line Means

See also: Shared Database Overview, Working Offline and Syncing Later, Connecting to a PostgreSQL Server, SQLite File or PostgreSQL Server?, Choosing and Connecting Your NAS, Global Search Finds Nothing

Global Search Finds Nothing

Why Global Search can come back empty on an older database file, and how this version repairs the search index itself.

Symptom: Global Search returns no results, even for a filename you know is in a project.

Cause: SQLite database files made by an early version have a search index that stores nothing, so every search comes back empty. A PostgreSQL server never had this fault.

Fix: nothing to do by hand. The first time this version connects to the file, it replaces the index and fills it again from the clips already in the database. If search is still empty, choose Database → Reconnect Database, or quit and open MediaFlow again.

Other Things to Check

See also: Global Search, Database Connection Issues, Migrating Projects to the Database

NAS ‘Resource Busy’ Errors

Why deleting or moving a project folder on a network share can fail with “resource busy”, and what to try.

Symptom: deleting or moving a project folder on a network share fails with a “resource is busy” error.

Cause: a file in the folder is still open, often because a preview has only just closed. Network shares release files more slowly than a disk in this Mac.

Fixes

See also: Clips Showing as Missing, Deleting a Project

Import Not Detecting Files

What to check when Import shows no files: the file types MediaFlow accepts, the drive, and the iPhone’s Trust prompt.

Symptom: you open Import and the list is empty, or some files are not in it.

Cause: The File Type Is Not One MediaFlow Imports

Import lists only these types, by file extension:

Anything else is left out. That includes TIFF images and camera raw formats other than DNG, such as CR2, NEF and ARW. A folder that holds only those looks empty to Import. Convert them first, for example to DNG or JPG.

Cause: The Source Cannot Be Read

See also: Importing from a Card, Drive or Folder, Importing from iPhone or Camera, The Import Sheet and Completion Card

Understanding the Where Column

What each icon and label in the Where column says about where a clip’s file is right now.

The Where column (once called Location) shows where each clip’s file is. The same seven states appear on the grid badge and in the legend behind the info button above the media list:

The sidebar’s Smart Groups filter the media list to clips that still need attention: Not at destination, Missing, Uncategorized, Unrated, Unreviewed and Reject candidates. Unreviewed holds clips with an import-analysis proposal nobody has confirmed. Reject candidates holds clips import analysis flagged as probable rejects.

Tip: Choose Workflow → Repair → Re-check files to bring every Where badge up to date.

See also: Re-check files, Clips Showing as Missing, Proposals: What Import Analysis Suggests