You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit afb6179
Browse filesBrowse the repository at this point in the historyBrowse files
Preview is rotated 90° left on all tested macOS cameras. Still photos from Continuity/iPhone cameras are also rotated incorrectly.
6
+
7
+
## Root Cause
8
+
9
+
Two interacting issues in the current code:
10
+
11
+
1.**`DeviceOrientationProvider.swift`** hardcodes macOS device orientation to `.landscapeLeft` (macOS has no gyroscope).
12
+
2.**`DefaultCamera.videoOrientation(forDeviceOrientation:)`** maps `.landscapeLeft` → `AVCaptureVideoOrientation.landscapeRight`. This swap is correct on iOS (compensating for physical device rotation) but wrong on macOS where cameras are fixed-position.
13
+
14
+
The result: every macOS capture connection gets `videoOrientation = .landscapeRight`, which instructs AVFoundation to rotate all delivered pixel buffers by 90°.
15
+
16
+
Additionally, **`SavePhotoDelegate.normalizedPhotoDataForMacOS()`** applies a blanket -90° CGContext rotation to any photo where `height > width`. This is a compensation hack that works for some cameras but fails for Continuity/iPhone cameras and will conflict with any connection-level fix.
17
+
18
+
## Fix: Use `videoRotationAngle` on macOS (Option B)
19
+
20
+
### What changes
21
+
22
+
On macOS, use `AVCaptureConnection.videoRotationAngle` (available macOS 14.0+) instead of the deprecated `videoOrientation` enum. Set the angle to `0` for the natural sensor orientation (correct for fixed-position macOS cameras).
23
+
24
+
For macOS < 14.0 (deployment target is 10.15), fall back to `videoOrientation = .portrait` which is the identity orientation.
25
+
26
+
Remove `normalizedPhotoDataForMacOS()` since the connection-level fix makes it unnecessary — photos will be captured with correct orientation from the source.
27
+
28
+
### Files changed
29
+
30
+
| File | Change |
31
+
|------|--------|
32
+
|`DefaultCamera.swift`| macOS branch in `updateOrientation(_:forCaptureOutput:)` using `videoRotationAngle`|
33
+
|`CaptureConnection.swift`| Add `videoRotationAngle` and `isVideoRotationAngleSupported(_:)` to the protocol |
34
+
|`SavePhotoDelegate.swift`| Remove `normalizedPhotoDataForMacOS()` and its call site |
35
+
|`MockCaptureConnection.swift`| Add mock implementations for new protocol members |
36
+
37
+
### What does NOT change
38
+
39
+
| Aspect | Status |
40
+
|--------|--------|
41
+
| iOS behavior | Completely unchanged — all macOS code is behind `#if os(macOS)`|
42
+
| Public Dart API | No change — `lockCaptureOrientation()`, `unlockCaptureOrientation()`, `DeviceOrientation` enum all stay the same |
43
+
| Pigeon interface | No change — `PlatformDeviceOrientation` enum and host API unchanged |
44
+
| iOS native tests | Unchanged — orientation tests use `MockCaptureConnection` which is iOS-only |
45
+
46
+
## Performance Analysis: `videoRotationAngle` vs `videoOrientation`
47
+
48
+
Both `videoRotationAngle` and `videoOrientation` are properties on `AVCaptureConnection`. They control how AVFoundation's internal pipeline delivers frames. The rotation happens inside the hardware-accelerated capture pipeline before the pixel buffer reaches the app.
**There is no performance difference.** Both APIs configure the same underlying hardware rotation in the capture pipeline. Apple introduced `videoRotationAngle` as a clearer replacement for `videoOrientation`, not as a different mechanism. The pixel buffer delivered to `copyPixelBuffer()` is already rotated by the hardware in both cases — there is no additional CPU-side image manipulation.
59
+
60
+
The `camera_macos` third-party package has been shipping with `videoRotationAngle` and shows no performance issues in its frame delivery path.
61
+
62
+
## Public API Impact
63
+
64
+
### Will this break users?
65
+
66
+
**No.** The changes are entirely inside the native AVFoundation layer and do not affect:
67
+
68
+
- The public `CameraController` API (`lockCaptureOrientation()`, `unlockCaptureOrientation()`)
69
+
- The `DeviceOrientation` enum values
70
+
- The `CameraValue` properties (`lockedCaptureOrientation`, `deviceOrientation`)
71
+
- The `CameraPreview` widget
72
+
- The Pigeon-generated platform channel interface
73
+
74
+
On macOS, `lockCaptureOrientation()` will continue to work. When a user locks to a specific orientation, the fix maps that orientation to the correct `videoRotationAngle` value for macOS.
75
+
76
+
On iOS, nothing changes at all — all new code is behind `#if os(macOS)` or `#available(macOS 14.0, *)` guards.
77
+
78
+
### Edge case: macOS < 14.0
79
+
80
+
The deployment target is macOS 10.15. For macOS versions older than 14.0:
81
+
82
+
-`videoRotationAngle` is unavailable
83
+
- The fallback uses `videoOrientation = .portrait` (identity orientation)
84
+
- This is correct for fixed-position macOS cameras and is better than the current `.landscapeRight` behavior
85
+
86
+
In practice, Flutter's macOS support and the macOS devices in active use make macOS < 14.0 a diminishing edge case, but it remains handled.
- rapid camera switching no longer reproduces the earlier disposed-controller crash
22
22
- unsupported tap-to-focus/exposure no longer throws on the iPhone camera
23
23
24
-
## Current Testing Matrix
24
+
## Orientation Fix Applied
25
25
26
-
| Camera | Current displayed name | Still image | Live preview/video | Notes |
27
-
| --- | --- | --- | --- | --- |
28
-
| 1 | HD Pro Webcam C920 | OK | Rotated 90 degrees left | Device itself appears landscape-capable in native apps |
29
-
| 2 | FaceTime HD Camera | OK | Rotated 90 degrees left | Internal Mac camera |
30
-
| 3 | kPhone Camera | Rotated 90 degrees right | Rotated 90 degrees left | Continuity/iPhone camera still differs from internal cameras |
26
+
Root cause: `DeviceOrientationProvider` hardcoded `.landscapeLeft` on macOS, which the iOS-designed
27
+
orientation mapper translated to `AVCaptureVideoOrientation.landscapeRight`, introducing an unwanted
28
+
90° rotation on fixed-position macOS cameras.
31
29
32
-
Interpretation:
30
+
Fix: on macOS 14+, use `AVCaptureConnection.videoRotationAngle = 0` (identity) instead of the
31
+
deprecated `videoOrientation` enum. For macOS < 14.0, fall back to `.portrait` (identity).
32
+
Also removed the `normalizedPhotoDataForMacOS()` workaround from `SavePhotoDelegate` that was
33
+
applying a blanket -90° CGContext rotation to photos.
33
34
34
-
- still-photo orientation is correct for the two non-Continuity cameras tested most recently
35
-
- preview orientation is still wrong on all tested cameras
36
-
- the Continuity/iPhone camera still has incorrect still-photo orientation as well
35
+
See [camera_avfoundation_macos_orientation_analysis.md](camera_avfoundation_macos_orientation_analysis.md) for the full analysis.
37
36
38
-
## Open Issues
37
+
## Current Testing Matrix (needs manual re-verification)
39
38
40
-
### Orientation
39
+
| Camera | Current displayed name | Still image | Live preview/video | Notes |
40
+
| --- | --- | --- | --- | --- |
41
+
| 1 | HD Pro Webcam C920 | Needs recheck | Needs recheck | Was rotated 90° left before fix |
42
+
| 2 | FaceTime HD Camera | Needs recheck | Needs recheck | Was rotated 90° left before fix |
43
+
| 3 | kPhone Camera | Needs recheck | Needs recheck | Was rotated 90° in both directions before fix |
41
44
42
-
- preview remains rotated 90 degrees left on all tested cameras
43
-
- Continuity/iPhone still photos remain rotated 90 degrees right
44
-
- image rotation mismatch also causes the preview to appear stretched even though the underlying width/height values are correct
45
+
## Open Issues
45
46
46
47
### Audio
47
48
48
49
- after repeated camera switching in earlier manual testing, loud white noise played from the MacBook speakers for roughly 20 seconds
49
-
- as a mitigation, audio is currently disabled by default on macOS in the example
50
-
- explicit macOS audio testing is still needed before enabling it again
50
+
- as a mitigation, audio is currently disabled by default on macOS in the example (`enableAudio = !Platform.isMacOS`)
51
+
- macOS has no `AVAudioSession` — unlike iOS, there is no session category to configure; audio capture is set up directly via `AVCaptureAudioDataOutput` on the `audioCaptureSession`
52
+
- the white noise likely came from a feedback loop between mic input and speaker output, since macOS does not have the `AVAudioSession.setCategory(.playAndRecord, options: .defaultToSpeaker)` separation that iOS uses
53
+
- this is a known platform difference; fixing it properly would require either routing audio output explicitly or keeping audio disabled until a recording starts
54
+
-**Impact**: low — audio defaults to off, users can toggle it on via the example UI when they want to test recording with audio
51
55
52
56
### Example video thumbnail crash
53
57
54
-
Manual testing surfaced an example-side error while rendering the thumbnail video player:
55
-
56
-
-`Bad state: No active player with ID 1.`
57
-
58
-
This appears to be a `video_player` lifecycle issue in the example app rather than a core camera capture failure. The example has been hardened to clear old video controllers earlier, but this should still be rechecked manually.
58
+
-`Bad state: No active player with ID 1.` error from `video_player_avfoundation`
59
+
- occurs when the `VideoPlayerController` tries to interact with a player that has already been disposed
60
+
-the example code disposes the old controller during `_startVideoPlayer()` after initializing the new one, but there is a race: the listener callback may fire after disposal
61
+
-**Impact**: example-only, does not affect the plugin — the thumbnail just fails to display
62
+
-**Possible fix**: guard the listener callback with a `mounted` and controller identity check before accessing the video controller
59
63
60
64
### macOS startup warning
61
65
62
-
The startup log still includes:
63
-
64
66
-`objc[...]: class 'NSKVONotifying_AVCapturePhotoOutput' not linked into application`
65
-
66
-
It does not currently appear to block preview or still capture, so it remains a secondary issue.
67
+
- appears on startup in the console log
68
+
- does not block preview or still capture
69
+
- likely a KVO observation side-effect from AVFoundation's internal implementation
70
+
-**Impact**: cosmetic log noise only
67
71
68
72
## Example-Only Debugging Notes
69
73
@@ -73,7 +77,8 @@ It does not currently appear to block preview or still capture, so it remains a
73
77
74
78
## Next Manual Checks
75
79
76
-
1. Recheck preview orientation on all three cameras after the latest preview/layout changes.
77
-
2. Recheck still-photo orientation on the Continuity/iPhone camera.
78
-
3. Confirm that the `VideoPlayer` thumbnail crash no longer occurs.
79
-
4. If audio is re-enabled for testing, explicitly test for speaker noise during camera switching.
80
+
1. Recheck preview orientation on all three cameras after the `videoRotationAngle` fix.
81
+
2. Recheck still-photo orientation on all cameras, especially the Continuity/iPhone camera.
82
+
3. Confirm that still photos are written to disk (check the path shown in the snack bar).
83
+
4. Confirm that the `VideoPlayer` thumbnail crash no longer occurs, or reproduces consistently.
84
+
5. If audio is re-enabled for testing, explicitly test for speaker noise during camera switching.
Copy file name to clipboardExpand all lines: packages/camera/camera_avfoundation/darwin/camera_avfoundation/Sources/camera_avfoundation/CaptureConnection.swift
Copy file name to clipboardExpand all lines: packages/camera/camera_avfoundation/darwin/camera_avfoundation/Sources/camera_avfoundation/DefaultCamera.swift
+44-5Lines changed: 44 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -885,13 +885,52 @@ final class DefaultCamera: NSObject, Camera {
Copy file name to clipboardExpand all lines: packages/camera/camera_avfoundation/darwin/camera_avfoundation/Sources/camera_avfoundation/SavePhotoDelegate.swift
0 commit comments