Skip to content

Commit 4ea5aa8

Browse files
1313Copilot
andcommitted
fix(docs): drop non-existent com.apple.security.screen-capture entitlement (#144)
The README told users to add com.apple.security.screen-capture to their Entitlements.plist alongside com.apple.security.app-sandbox. That entitlement key does not exist — Apple's entitlement reference has never defined a screen-capture entitlement. ScreenCaptureKit is gated by the user's TCC grant in System Settings, requested via NSScreenCaptureUsageDescription in Info.plist; no code-signing entitlement is required on signed or sandboxed apps. Rewrite the Requirements section to: - document the required Info.plist key (with example string), - call out explicitly that no com.apple.security.screen-capture entitlement exists, - keep the sandbox entitlement note for apps that opt into the App Sandbox. Update the Troubleshooting row 'App crashes after notarization' to point at the actual cause (missing NSScreenCaptureUsageDescription) instead of recommending the fake entitlement. The Tauri example's Entitlements.plist already documents this correctly (see examples/22_tauri_app/src-tauri/Entitlements.plist); this commit brings the top-level README in line. Fixes #144 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent dc68e89 commit 4ea5aa8

1 file changed

Lines changed: 16 additions & 4 deletions

File tree

README.md

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -355,12 +355,24 @@ Screen capture **always requires user permission**. To grant it:
355355
2. Enable your binary (during development this is usually your terminal or IDE)
356356
3. Restart the app
357357

358-
For distribution, add `NSScreenCaptureUsageDescription` to `Info.plist` and the
359-
appropriate entitlements:
358+
For distribution, add a purpose string to `Info.plist` — the user-facing
359+
TCC prompt requires it and the app will be terminated without one:
360+
361+
```xml
362+
<key>NSScreenCaptureUsageDescription</key>
363+
<string>Capture your screen so the app can …</string>
364+
```
365+
366+
ScreenCaptureKit itself does **not** require a code-signing entitlement
367+
on either signed or sandboxed apps — capture is gated by the user's TCC
368+
grant in **System Settings → Privacy & Security → Screen & System
369+
Audio Recording**, not by an `Entitlements.plist` key. (There is no
370+
`com.apple.security.screen-capture` entitlement; that key does not
371+
exist in Apple's entitlement reference.) If your app is sandboxed you
372+
still need the sandbox entitlement itself:
360373

361374
```xml
362375
<key>com.apple.security.app-sandbox</key> <true/>
363-
<key>com.apple.security.screen-capture</key> <true/>
364376
```
365377

366378
## Performance
@@ -422,7 +434,7 @@ numbers at various resolutions, and tuning guidance.
422434
| Black / empty frames | Captured window minimized; pixel format mismatch; filter doesn't include the right display/window |
423435
| No audio samples | Did you set `.with_captures_audio(true)` **and** add a handler for `SCStreamOutputType::Audio`? |
424436
| Build fails with Swift bridge errors | `xcode-select --install`; then `cargo clean && cargo build` |
425-
| App crashes after notarization | Add the `screen-capture` entitlement (see [Requirements](#requirements--permissions)) |
437+
| App crashes after notarization | Missing `NSScreenCaptureUsageDescription` in `Info.plist` — the system terminates apps that trigger the Screen Recording TCC prompt without one (see [Requirements](#requirements--permissions)) |
426438
| `match` on `PixelFormat` / `SCStreamErrorCode` no longer compiles | Both are `#[non_exhaustive]` in 2.0 — add a wildcard `_ => …` arm |
427439

428440
## Migration

0 commit comments

Comments
 (0)