start shared camera
Requests camera permission and starts or keeps a named MediaStream such as `pose` or `qr`.
Complete block reference (41 blocks)
TurboWarp capability extension
TurboWarp Camera Source owns `navigator.mediaDevices.getUserMedia()` and shares live frame sources by role name, so TM can use a horizontal camera while jsQR or image recognition uses a downward camera.
Requests camera permission and starts or keeps a named MediaStream such as `pose` or `qr`.
Places Chrome's `<usermedia>` element on the stage and shares the stream it returns, without calling getUserMedia. For a .sb3 opened in the editor, where no host above the project can place the element.
Controls the opt-in GPU-backed stage preview. Repeated show calls keep one block-owned lease per camera.
Updates the browser camera list so projects can bind role names to device IDs.
Reports whether a named stream is active. The device-ID reporter identifies the selected physical camera when available.
Reports the latest failure code and message for each named camera, and clears them after a successful start.
Reports the delivered width, height, and track frame rate. Unavailable values and stopped cameras report zero.
Unsandboxed extensions can read `Scratch.vm.runtime.ext_kubohiroyacamerasource`.
const poseLease = await cameraSource.acquireCamera({
owner: 'tm',
cameraId: 'pose',
deviceId: poseDeviceId
});
const qrLease = await cameraSource.acquireCamera({
owner: 'jsqr',
cameraId: 'qr',
deviceId: qrDeviceId
});
const previewLease = await cameraSource.acquireCamera({
owner: 'camera-preview',
cameraId: 'pose',
preview: true,
mirrored: true
});
const frame = qrLease.getFrameSource();
// frame.element is an HTMLVideoElement.
await qrLease.release();
await previewLease.release();
await poseLease.release();
Each named stream remains active until its last lease is released. Consumers that use the same `cameraId` share one physical camera; different IDs can run separate cameras.
preview: true enables the dedicated GPU-backed stage preview for that lease. It sends the shared video element to texImage2D(video) without drawImage(), getImageData(), or CPU pixel scanning. Mirroring changes only the drawable scale, leaving frame.element unmodified for WebGPU, WebCodecs, and vision consumers.
The path avoids explicit CPU readback but does not guarantee browser-internal zero-copy. The browser may still perform color conversion or GPU transfer.
Block-owned previews are cleaned up when the named camera stops, the project stops or reloads, or the runtime is disposed.
Camera access requires user permission and a secure browser context such as HTTPS or localhost. Camera Source does not upload frames or store images.
All 41 blocks are documented below, including compatibility blocks and blocks available through optional features. Select a block to read its behavior, arguments, default values, and menu choices. Each block has a permanent link.
start shared camera [CAMERA_ID] with device ID [DEVICE_ID]Starts or keeps a named shared MediaDevices camera stream.
Block type: COMMAND. Opcode: startSharedCamera. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default | |
DEVICE_ID | STRING | |
start shared camera [CAMERA_ID] requested by this pageStarts the camera the page's query parameters name: `cameraDeviceId` exactly, and `cameraWidth`, `cameraHeight` and `cameraFrameRate` as ideal values. Without them it behaves like `start shared camera` with no device. An app with several USB cameras opens another app on the same origin, such as the lens calibration app, for one of them this way.
Block type: COMMAND. Opcode: startRequestedSharedCamera. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
start shared camera [CAMERA_ID] from the browser's camera buttonPlaces the browser's own camera button on the stage and waits for the operator to answer it, then shares the stream it returns under this camera id without calling getUserMedia. For a .sb3 opened in the editor, where no host above the project can place the element. When the camera id already runs a stream -- a packaged work whose host adopted one -- this joins that stream instead of asking again. A refusal leaves the work running: the camera does not start, `shared camera error code` reads `usermedia-cancelled`, and `start shared camera` is still available. Browsers without the element report `usermedia-unsupported`.
Block type: COMMAND. Opcode: startSharedCameraFromCameraButton. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
hide the camera button for shared camera [CAMERA_ID]Removes a camera button still waiting for an answer. The script waiting on it continues, with `usermedia-cancelled` as the camera's error code. The stop sign and loading another project remove it too.
Block type: COMMAND. Opcode: hideCameraButton. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
browser's camera button available?Whether this browser has the camera button element (`<usermedia>`, Chrome 151 and later). Check it before offering the button, and fall back to `start shared camera` where it is false.
Block type: BOOLEAN. Opcode: cameraButtonAvailable. Permanent link
This block has no arguments.
stop shared camera [CAMERA_ID]Stops a named shared camera stream and releases its tracks.
Block type: COMMAND. Opcode: stopSharedCamera. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
shared camera [CAMERA_ID] is running?Reports whether a named shared camera stream is active.
Block type: BOOLEAN. Opcode: isCameraRunning. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
shared camera [CAMERA_ID] error codeReturns the latest camera failure code, or an empty string after a successful start.
Block type: REPORTER. Opcode: cameraErrorCode. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
shared camera [CAMERA_ID] errorReturns the latest camera failure message, or an empty string after a successful start.
Block type: REPORTER. Opcode: cameraError. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
shared camera [CAMERA_ID] device IDReturns the active device ID for a named shared camera when available.
Block type: REPORTER. Opcode: cameraDeviceIdReporter. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
show shared camera [CAMERA_ID] preview flipped [PREVIEW_FLIP]Draws the named camera on the stage, turned over as asked. The flip is how the preview is drawn and never changes the frames a consumer is handed.
Block type: COMMAND. Opcode: showCameraPreview. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default | |
PREVIEW_FLIP | STRING | horizontal |
|
PREVIEW_FLIPをnone・horizontal・vertical・bothから選択します。映像の反転設定だけを編集し、カメラ取得やプレビューの実行は行いません。既存rawは無変更時に原文保持します。CAMERA_IDは対象外です。 GUIのDialogs/FixedInputsは起動時既定OFFです。有効にして再読込すると利用できます。
hide shared camera [CAMERA_ID] previewHides the block-owned preview without stopping leases owned by other consumers.
Block type: COMMAND. Opcode: hideCameraPreview. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
shared camera [CAMERA_ID] frame widthReturns the active video frame width in pixels, or zero while the camera is not running.
Block type: REPORTER. Opcode: cameraFrameWidth. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
shared camera [CAMERA_ID] frame heightReturns the active video frame height in pixels, or zero while the camera is not running.
Block type: REPORTER. Opcode: cameraFrameHeight. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
shared camera [CAMERA_ID] frame rateReturns the active video track frame rate, or zero when it is unavailable.
Block type: REPORTER. Opcode: cameraFrameRate. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
refresh camera devicesRefreshes the browser camera device list.
Block type: COMMAND. Opcode: refreshCameraDevices. Permanent link
This block has no arguments.
camera device countReturns the number of known camera devices after refresh.
Block type: REPORTER. Opcode: cameraDeviceCount. Permanent link
This block has no arguments.
camera device ID at [INDEX]Returns the one-based camera device ID at the requested index.
Block type: REPORTER. Opcode: cameraDeviceIdAt. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
INDEX | STRING | 1 |
camera device label at [INDEX]Returns the one-based camera device label at the requested index when the browser exposes it.
Block type: REPORTER. Opcode: cameraDeviceLabelAt. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
INDEX | STRING | 1 |
register camera profile [PROFILE_JSON]Validates a calibration and stores it against the camera it names. Accepts a ROS camera_info YAML file carrying the turbowarp_camera_source mapping, as the calibration app writes it, as well as twcs/camera-intrinsics version 1 JSON and the legacy twrmc/camera-calibration JSON. Nothing is stored unless the whole document passes, and the profile in force for that camera is replaced.
Block type: COMMAND. Opcode: registerCameraProfile. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
PROFILE_JSON | STRING | {} |
register camera profile [PROFILE_JSON] as [CAMERA_ID]Registers a profile under the named camera ID, replacing the ID the document carries before it is validated. Use it when a profile was solved under another name, such as `default` in a calibration app. Sets or clears the camera profile error like the plain register block.
Block type: COMMAND. Opcode: registerCameraProfileAs. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
PROFILE_JSON | STRING | {} | |
CAMERA_ID | STRING | default |
forget camera profile for [CAMERA_ID]Removes the stored calibration profile for one camera.
Block type: COMMAND. Opcode: forgetCameraProfile. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
camera [CAMERA_ID] is calibrated?Reports whether a calibration profile is stored for the camera. An uncalibrated camera is an ordinary state and not an error.
Block type: BOOLEAN. Opcode: cameraProfileRegistered. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
camera profile JSON for [CAMERA_ID]Returns the stored profile as twcs/camera-intrinsics JSON, or an empty string when the camera has none. For a file to hand to another machine or tool, use camera profile YAML.
Block type: REPORTER. Opcode: cameraProfileJson. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
camera profile YAML for [CAMERA_ID]Returns the stored profile as a ROS camera_info YAML document, or an empty string when the camera has none. This is the form to write to a file or show as a QR code: ROS and OpenCV-based tools read the standard part as it is, and the turbowarp_camera_source mapping carries the calibration time and camera settings compatibility needs.
Block type: REPORTER. Opcode: cameraProfileYaml. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
camera profile errorReturns the code of the last rejected profile document, or an empty string when the last one was accepted.
Block type: REPORTER. Opcode: cameraProfileError. Permanent link
This block has no arguments.
camera profile error detailReturns why the last profile document was rejected, naming the member at fault.
Block type: REPORTER. Opcode: cameraProfileErrorDetail. Permanent link
This block has no arguments.
camera profile compatibility for [CAMERA_ID]Returns compatible, incompatible, undetermined, or an empty string when the camera has no profile. Undetermined is a distinct answer from compatible and never resolves upward into it.
Block type: REPORTER. Opcode: cameraProfileCompatibility. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
camera profile compatibility detail for [CAMERA_ID]Returns the findings that decided the verdict, so an operator sees the one thing that has to change.
Block type: REPORTER. Opcode: cameraProfileCompatibilityDetail. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
camera profile adaptation for [CAMERA_ID]Returns exact, scaled, or unavailable. A frame size that differs by a pure scale can be projected with scaled intrinsics; a crop or an aspect change cannot, because the principal point cannot be placed.
Block type: REPORTER. Opcode: cameraProfileAdaptation. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
camera intrinsics JSON for [CAMERA_ID]Returns the intrinsics to project the current frames with, already adapted to the frame size, or an empty string when they cannot be established. Consumers use this rather than scaling a profile themselves, because only this extension can tell a scale from a crop.
Block type: REPORTER. Opcode: cameraProfileIntrinsicsJson. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
camera conditions JSON for [CAMERA_ID]Returns what the track reports about itself: frame size, resize mode, zoom, focus and frame rate. Read only; this extension never changes a shared camera configuration.
Block type: REPORTER. Opcode: cameraConditionsJson. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
camera conditions generation for [CAMERA_ID]Returns a number that increases whenever something affecting the geometry changes. A consumer holding a derived result compares this instead of re-checking every condition.
Block type: REPORTER. Opcode: cameraConditionsGeneration. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
save camera profile for [CAMERA_ID] to browser storageSaves the profile registered for the camera to this origin's browser storage (IndexedDB) and tells other windows on the same origin. Waits until the write commits. The result becomes `saved`, `no-profile` or `unavailable`.
Block type: COMMAND. Opcode: saveCameraProfile. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
restore stored camera profile for [CAMERA_ID]Registers the newest saved profile that is `compatible` with the camera as configured now, under this camera ID. Fails closed: an `undetermined` or `incompatible` profile is never registered and the current registration is left untouched. The result becomes `restored`, `none`, `incompatible`, `undetermined` or `unavailable`.
Block type: COMMAND. Opcode: restoreStoredCameraProfile. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
restore stored camera profile calibrated on the device of [CAMERA_ID]Like `restore stored camera profile`, but considers only profiles calibrated on the device this camera is running on now, so two cameras of the same model never receive each other's calibration. Device IDs are scoped to the origin and browser profile, as browser storage is. A camera that is not running gives `undetermined`; `none` says how many saved profiles belong to other devices.
Block type: COMMAND. Opcode: restoreStoredCameraProfileForDevice. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
bind camera profile for [CAMERA_ID] to its current deviceRecords the device this camera is running on in its registered profile, for a profile the operator has assigned to this camera, such as one loaded from a file. Only a profile `compatible` with the camera as it is now is bound; otherwise nothing changes. Save the profile afterwards to keep the binding.
Block type: COMMAND. Opcode: bindCameraProfileToDevice. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
camera profile for [CAMERA_ID] belongs to its current device?Whether the registered profile was calibrated on, or bound to, the device this camera is running on now.
Block type: BOOLEAN. Opcode: cameraProfileOnDevice. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
stored camera profile result for [CAMERA_ID]Returns the outcome of the last save or restore for the camera ID, or an empty string before either has run.
Block type: REPORTER. Opcode: storedCameraProfileResult. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
stored camera profile detail for [CAMERA_ID]Explains the last save or restore: which profile was saved or restored, or why no saved profile fits the camera.
Block type: REPORTER. Opcode: storedCameraProfileDetail. Permanent link
| Argument | Type | Default value | Menu choices |
|---|---|---|---|
CAMERA_ID | STRING | default |
stored camera profiles generationA counter that increments whenever a profile is saved in this window or another window on the same origin. It is not reset by loading a project.
Block type: REPORTER. Opcode: storedCameraProfilesGeneration. Permanent link
This block has no arguments.
カメラのレンズと共有先への接続線で、映像共有を表します。 拡張一覧とブロックのアイコンに同じ図案を使用します。