[camera_web] Re: Support for camera stream on web - #7950

Description

Adds image streaming to camera_web, so CameraController.startImageStream works on web. CameraPlugin.supportsImageStreaming() now returns true, and onStreamedFrameAvailable returns a stream of RGBA CameraImageData frames.

How frames are captured

There are two capture paths, chosen per camera when it is created:

Both paths emit a single-plane RGBA image (bytesPerPixel: 4, bytesPerRow set to the stride the browser reports). format is ImageFormatGroup.unknown with raw: 'rgba8888', because the platform interface has no RGBA group yet (see TODO, flutter/flutter#151193).

Frame ownership

Every emitted frame has its own buffer. The copyTo destination is allocated per frame, and JSUint8Array.toDart returns a view of it, not a second copy. This matches the native implementations: a consumer can keep a CameraImage past the callback, for example across an await or when sending it to an isolate, and later frames won't change its bytes.

An earlier revision reused one buffer across frames. I benchmarked both approaches before switching (Chrome 155 with the fake camera; 640×480 to 1080p at 30, 60 and 90 fps; 3 runs per case):

• Throughput: identical up to 60 fps. At 1080p90, buffer reuse was +1.3%, but the fake source itself tops out at about 85 fps there.
• CPU and GC: buffer reuse used about 45–50% less renderer CPU and avoided the GC caused by per-frame allocation. GC pauses with per-frame buffers were at most 4.7 ms, there were no long tasks, and memory did not grow over time.
• Correctness: with buffer reuse, 100% of frames held for 50 ms or longer had been overwritten by later frames (70/70). With per-frame buffers, 0/70 were.

A buffer pool would need an explicit release API on the platform interface, so I've left it as a possible follow-up.

Lifecycle and errors

• The frame stream is a broadcast stream. Capture starts when the first listener subscribes and stops when the last one cancels. Camera.dispose() now closes the stream.
• A VideoFrame is always closed after it is copied, including on errors. The reader lock is released when the loop ends.
• Frames that can't be copied are skipped, and the stream keeps going (unableToCloneFrame, missingPlaneLayout). The stream closes without an error if the track reader closes (videoTrackReaderClosed).
• Any other error is emitted on the stream before it closes. In onStreamedFrameAvailable, a CameraWebException is reported as a camera error event and rethrown as a PlatformException.
• New CameraErrorCodes: noVideoTrack, videoTrackReaderClosed, videoTrackReaderNotInitialized, cameraFrameDimensionsZero, unableToCloneFrame, missingPlaneLayout.

Refactors in CameraService

• The DOMException → CameraWebException mapping now lives in _domExceptionToCameraWebException, shared by getMediaStreamForOptions and the new frame-stream methods. DOMExceptions are now detected with isA<DOMException>() instead of on DOMException, so the check behaves the same under dart2wasm.
• New methods so the stream loop can be mocked in tests: hasMediaStreamTrackProcessor, hasPropertyOffScreenCanvas, takeFrame, getMediaStreamVideoTrack, getMediaStreamTrackReader, readVideoTrack, copyVideoFrameToBufferAndGetStride, getCameraImageData.

Known limitations / follow-ups

• No frame-rate option yet. The fallback path targets 60 fps, and the MediaStreamTrackProcessor path delivers whatever the track produces. CameraImageStreamOptions has no fps field (TODO, [camera] Add framesPerSecond parameter to CameraImageStreamOptions flutter#176148).
• No RGBA format group in ImageFormatGroup ([camera_android_camerax] Support RGBA_8888 image format group  flutter#151193).
• Crop-and-scale resolutions aren't scaled on the MediaStreamTrackProcessor path. When Chrome crops and scales the track to fit the requested resolution (e.g. ResolutionPreset.low = 320×240 on a 1080p camera), the VideoFrame's visibleRect is the crop (1440×1080), and only displayWidth/displayHeight are 320×240. Frames are copied at visibleRect size, so they can be larger than previewSize. Scaling to the display size could be a follow-up.

Fixes flutter/flutter#92460

Testing

• New integration tests, all passing in Chrome (flutter drive -d chrome for each file in example/integration_test/):
  • camera_web_stream_test.dart: supportsImageStreaming, onStreamedFrameAvailable, and the PlatformException mapping.
  • camera_test.dart, in the cameraFrameStream group:
    • emitting frames;
    • closing with an error when reading a frame or building CameraImageData fails;
    • closing quietly when the reader closes;
    • closing on dispose;
    • continuing after unableToCloneFrame;
    • the fallback path's frame-rate target and RGBA byte length;
    • fallback errors.
  • camera_service_test.dart: each new CameraService method, including its error cases.
  • camera_error_code_test.dart: the new error codes.
• Manually tested with startImageStream in Chrome using a fake camera (--use-file-for-fake-video-capture) at 640×480 to 1080p and 30–90 fps. That covered frame dimensions, stride and byte length, stopping and restarting the stream, background tabs, and dispose.

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under[^1].
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under[^1].
• All existing and new tests are passing.