The symptom is always the same. Capture worked yesterday. Nobody changed anything. The source is listed, the app is running, and the frame is black — or the app is showing you a permission prompt that you swear you already answered.

This is macOS’s Screen Recording privilege, and it fails in ways that look like the application is broken. Understanding what it keys on turns a twenty-minute panic into a thirty-second fix.

What macOS is actually tracking

Since Catalina, reading the contents of the screen requires explicit user consent. That consent lives in a database called TCC — Transparency, Consent and Control — under System Settings → Privacy & Security → Screen & System Audio Recording.

The critical detail: the grant is not attached to the app’s name, or to its location on disk. It is attached to the app’s code signature and bundle identifier. macOS is recording “the thing signed by this identity, with this bundle ID, is allowed to read the screen.”

That is why the permission survives moving an app between folders, and why it evaporates in situations that feel like they should be harmless:

  • You rebuilt the app locally. A development build signed ad-hoc gets a different signature every build. Every build is a new stranger.
  • You replaced the app with a different signing identity. A build signed with a personal certificate is not the notarised release, even at the same version.
  • The app updated and the signature changed. A normal Sparkle or App Store update usually keeps the grant, because the identity is stable. A change of certificate does not.
  • There are two copies on disk. One in /Applications, one in ~/Downloads, and you granted the download. macOS is not confused; you are running the other one.
  • The Mac was restored from a migration or a fresh image. TCC grants do not always survive Migration Assistant, and rarely survive an MDM re-enrolment.

The fifteen-second diagnosis

Open System Settings → Privacy & Security → Screen & System Audio Recording and look for the app.

Three states, three different problems:

  1. Not in the list at all. The app has never successfully requested the permission on this machine, or the entry was removed. Quit the app, launch it, trigger a capture, and answer the prompt.
  2. In the list, toggle off. Someone said no, or a reset cleared it. Turn it on. Then quit and relaunch the app — this is the step people skip, and it is why the fix appears not to work.
  3. In the list, toggle on, still black. This is the interesting one. Either you are running a different copy of the app than the one that holds the grant, or the entry is stale — the toggle refers to a signature that no longer matches the binary on disk.

For that third case, check which binary is actually running:

ps -Ao pid,command | grep -i spectrabridge | grep -v grep

If the path is not the one you expect, that is your answer. Move the copy you want to /Applications, delete the others, and grant it there.

Resetting the grant properly

When an entry is stale, toggling it does nothing useful — you need to remove it and let the app ask again. macOS ships a tool for this:

# reset Screen Recording for a single app
tccutil reset ScreenCapture com.bitstreammedia.SpectraBridge

# reset it for every app on the machine — a blunt instrument
tccutil reset ScreenCapture

After a reset, quit the app fully, launch it, and trigger a capture so it prompts. The prompt will not appear until the app actually attempts to read the screen.

Two caveats worth knowing before you run this at 5pm:

  • The bundle-specific form fails silently on some macOS versions if the identifier is not exactly right. Copy it, don’t type it.
  • The global form resets every app — including Zoom, your conferencing client, and anything else the venue relies on. On a house machine, don’t.

Why the prompt sometimes never arrives

Occasionally the app requests the permission and no dialog appears. Two common causes:

The dialog is behind something. Full-screen apps and multiple displays are very good at hiding a system modal on a display nobody is looking at. Check every screen, and press ⌘Tab away from full-screen apps.

The machine is managed. MDM can pre-approve or pre-deny screen recording via a PPPC profile, and a deny is silent — no prompt, no entry the user can change. If the Mac belongs to a venue, a university or a corporate client, this is a very likely explanation and the fix is a conversation with their IT team, not with the Mac. Check for it:

profiles show -type enrollment

Making it survive show day

The permission itself is stable once granted correctly. What destabilises it is churn around it. A short set of habits removes nearly all of the risk:

  • One copy of the app, in /Applications. Delete every other copy, including the disk image and the download. This single rule prevents the most common failure.
  • Grant the permission at build time, not at load-in. Bring up the rig, capture something, answer every prompt, then shut down and travel. Prompts you have already answered do not appear in front of a client.
  • Do not update the OS or the app between rehearsal and show. Obvious, universally ignored. If an update is required, do it before the last full run, not after.
  • Check the whole permission set, not just this one. A capture app may also need Accessibility, and an app that publishes audio needs microphone or system audio access. Verify all of them in one pass.
  • Note it in the show file. Whoever inherits the rig will hit this. One line — “SpectraBridge needs Screen Recording; if the wall is black, check there first” — saves them the diagnosis.

A note on what capture apps can and cannot see

Even with permission granted, a capture app is bounded by what macOS will hand it. Content protected by DRM will render black in a captured stream by design — a paid streaming service in a browser window is not going to appear on your wall, and no permission fixes that. Some applications also mark windows as excluded from capture. If one specific window is black while everything else works, that is the likely cause, and the workaround is a different source, not a different setting.

If capture is working and the problem is which window ends up on the wall, that is a different article — getting one window into Resolume covers the routes. And for a broader sweep of the things that break a Mac rig on show day, there is the pre-show checklist.

Originally published on the SpectraRig blog.