`capture`

capture 在用户明确授权后创建摄像头或麦克风流。宿主代持真实设备、系统权限和采集缓冲，guest 只得到类型化句柄及有界媒体数据。

基本示例

// 必须直接发生在可信的用户操作处理器中。
async function startCamera() {
  const camera = await host.capture.requestCamera({
    facing: 'user',
    maxWidth: 1280,
    maxHeight: 720,
  });
  if (!camera) return; // 用户取消

  const target = new Uint8Array(1280 * 720 * 4);
  const frame = await host.capture.frame(camera, target, 'rgba8');
  consumeFrame(target.subarray(0, frame.written), frame);
}

适用场景

扫码、头像拍摄、视频特效的单帧或连续摄像头输入。
录音、音量分析、语音处理的麦克风 PCM 输入。
需要随权限撤销立即终止的数据流。

屏幕捕获、系统音频、后台监听、设备枚举和长期设备标识不在 v0.1。

能力声明

{
  "capabilities": [
    "host:capture.requestCamera",
    "host:capture.frame",
    "host:capture.requestMic",
    "host:capture.readAudio",
    "host:capture.stop"
  ]
}

摄像头和麦克风逐方法声明；申请一种设备不会获得另一种。

Reference

方法

capture.requestCamera()：经可信 UI 申请摄像头句柄；取消返回 null。
capture.requestMic()：经可信 UI 申请麦克风句柄；取消返回 null。
capture.frame()：读取最新可用视频帧。
capture.readAudio()：读取有界 PCM 采样。
capture.stop()：停止设备并使句柄失效。

事件

capture.ended：权限撤销、设备断开、应用停止或采集错误。

约束对象

v0.1 只接受宿主白名单字段：摄像头朝向、最大宽高、最大帧率；麦克风最大声道数和偏好采样率。它们是偏好或上限，不是浏览器原始 constraints 透传。

宿主返回实际格式：

VideoFrameResult { written, required?, width, height, stride, format, sequence }
AudioReadResult  { written, required?, sampleRate, channels, frames, sequence }

麦克风工作流示例

const mic = await host.capture.requestMic({
  preferredSampleRate: 48_000,
  maxChannels: 1,
});
if (!mic) return;

const bytes = new Uint8Array(16 * 1024);
for (;;) {
  const result = await host.capture.readAudio(mic, bytes);
  if (result.frames > 0) analyzePcm(bytes.subarray(0, result.written), result);
}

生产代码应由数据可读事件或异步等待驱动，不能忙循环读取。

原生 WASM 示例

CaptureHandle camera = host_capture_request_camera(camera_constraints());
if (!camera.valid) return; // 用户取消

uint8_t *buffer = frame_pool_acquire(MAX_FRAME_BYTES);
VideoFrameResult r = host_capture_frame(
  camera,
  byte_sink(buffer, MAX_FRAME_BYTES),
  RGBA8
);
process_frame(buffer, r.written, r.width, r.height, r.stride);

生命周期与授权

句柄为 Handle<camera-stream, read, external-resource, session> 或 Handle<microphone-stream, read, external-resource, session>。
request* 必须继承可信用户操作，并由宿主显示设备类型和应用身份。
用户取消返回 null；策略拒绝或系统错误返回 HostError。
权限撤销、设备断开、应用隐藏策略或 stop 使句柄立即失效。
stop 幂等，不能在关闭后继续交付缓冲数据。

安全与预算

信任档位：yellow；数据来自独立治理的外部资源。
宿主不返回设备名、序列号或稳定 deviceId。
预算覆盖活跃流数、分辨率、帧率、采样率、声道数、单次输出和时间窗字节。
视频格式和音频格式必须封闭枚举；元数据不能夹带浏览器设备对象。
采集状态必须在可信壳层持续可见，并提供停止入口。

错误与测试

特有错误包括 activation-required、denied、device-unavailable、sink-too-small、stale-handle 和 limit-exceeded。一致性测试至少覆盖用户取消、权限撤销、设备热拔插、部分缓冲、格式协商、后台策略、重复停止和跨类型句柄误用。