Skip to content

Commit 7148a2b

Browse files
1313Copilot
andcommitted
docs(readme): expand entitlement section with full TCC matrix (#144)
Yury asked which entitlement is the correct one. Spelling out the answer in the README to prevent the next person from copy-pasting the fake `com.apple.security.screen-capture` key from older snippets: - Replace the prose paragraph + bare sandbox example with a 3-row table covering every relevant app type (signed, sandboxed, sandboxed-with-system-audio) and exactly what each one needs. - Add a callout block that names the two real screen-capture entitlements (`com.apple.developer.screen-capture.include-passthrough`, `com.apple.developer.protected-content`) and links to Apple's security-entitlements reference, so readers can verify themselves. - Note that those two are Enterprise / visionOS managed entitlements, so they don't apply to ScreenCaptureKit on macOS. Follow-up to 5ba4811 (which dropped the fake entitlement from the distribution snippet but didn't yet enumerate what is actually required). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent a2e9a00 commit 7148a2b

1 file changed

Lines changed: 18 additions & 10 deletions

File tree

README.md

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -363,17 +363,25 @@ TCC prompt requires it and the app will be terminated without one:
363363
<string>Capture your screen so the app can …</string>
364364
```
365365

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:
366+
`ScreenCaptureKit` is **purely TCC-gated**: there is no code-signing
367+
entitlement that grants screen capture access. Capture is allowed solely
368+
when the user enables your binary under **System Settings → Privacy &
369+
Security → Screen & System Audio Recording**.
373370

374-
```xml
375-
<key>com.apple.security.app-sandbox</key> <true/>
376-
```
371+
| App type | What you need |
372+
|---|---|
373+
| Any signed macOS app (sandboxed or not) | `NSScreenCaptureUsageDescription` in `Info.plist` + user TCC grant |
374+
| Sandboxed app | Additionally `com.apple.security.app-sandbox = true` in `Entitlements.plist` — this only turns the sandbox on; it does not grant capture |
375+
| Sandboxed app capturing system audio (macOS 13+) | Optionally `com.apple.security.device.audio-input = true` |
376+
377+
> **There is no `com.apple.security.screen-capture` entitlement.** That key
378+
> isn't part of Apple's [security-entitlements reference](https://developer.apple.com/documentation/bundleresources/security-entitlements);
379+
> the only `com.apple.security.device.*` keys are `camera`, `microphone`,
380+
> `audio-input`, `usb`, and `bluetooth`. The two real screen-capture
381+
> entitlements ([`com.apple.developer.screen-capture.include-passthrough`](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.screen-capture.include-passthrough)
382+
> and [`com.apple.developer.protected-content`](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.protected-content))
383+
> are Enterprise / visionOS managed entitlements and don't apply to
384+
> `ScreenCaptureKit` on macOS.
377385
378386
## Performance
379387

0 commit comments

Comments
 (0)