@octane-xplat/camera 0.0.0-nightly.g2e22171

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# `@octane-xplat/camera`
+
+```sh
+pnpm add @octane-xplat/camera
+```
+
+Live camera preview for Octane xplat apps: `getUserMedia` video on web,
+`AVCaptureSession` on iOS, CameraX on Android,
+`AVCaptureSession` + `AVCaptureVideoPreviewLayer` on macOS (AppKit), and
+`MediaCapture` + `CaptureElement` on the Windows (WinUI 3) target.
+
+```tsx
+import { CameraView } from '@octane-xplat/camera'
+
+export function Preview() {
+	return (
+		<CameraView
+			facing="back"
+			active
+			onReady={() => console.log('Preview running')}
+			onError={(error) => console.log(error.message)}
+		/>
+	)
+}
+```
+
+This is the preview surface only — for one-shot still capture and library
+picking use [`@octane-xplat/media`](../media/README.md). Permissions are
+requested when the session starts; `onError` is how a denial shows up.
+`ref` hands you the platform surface (`HTMLVideoElement` on web) for
+controls the shared props don't cover, and the `ios`/`android`/`web`/
+`windows` escape props apply after the shared props. On macOS the leaf is a
+compiled Swift `XplatCameraHost` that owns the capture session; the app bundle
+needs `NSCameraUsageDescription` (and `NSMicrophoneUsageDescription` for
+audio) declared through `xplat.targets.macos.package.infoPlist`.
+
+```tsx
+// Preview.web.tsx — browser properties belong in this platform file.
+import { CameraView } from '@octane-xplat/camera'
+
+export function Preview() {
+	return (
+		<CameraView
+			web={{ playsInline: true }}
+			ref={(handle) => console.log(handle.native)}
+			onError={(error) => console.log(error.message)}
+		/>
+	)
+}
+```
+
+## Tap-to-focus
+
+`CameraView` reports where the user tapped as a normalized point —
+`{x: 0, y: 0}` is the top-left corner of the preview, `{x: 1, y: 1}` the
+bottom-right. Hand the point to a session's `focusAtPoint` to meter one
+autofocus and auto-exposure pass there:
+
+```tsx
+import { CameraView, createCameraSession } from '@octane-xplat/camera'
+
+const session = createCameraSession()
+
+export function FocusablePreview() {
+	return <CameraView session={session} onTap={(point) => session.focusAtPoint(point)} />
+}
+```
+
+`onTap` is a pure notification — it never takes over the gesture, so
+double-tap and pan recognizers layered over the preview keep working.
+`focusAtPoint` needs a session (it drives the camera the preview
+attaches) and quietly does nothing on cameras that cannot meter at a
+point — front cameras are often fixed-focus. Check
+`capabilities().focusPointOfInterest` and `exposurePointOfInterest`
+before showing focus UI. Metering lands on iOS, Android, and macOS; the
+tap event fires on iOS, Android, and web.
+
+## Movie recording
+
+`createCameraSession` creates a shared camera owner: the same session can
+drive a `CameraView` preview and one movie-recording attempt at a time.
+Pass the session to `CameraView` instead of `facing`; the preview attaches
+the camera the session owns. Recording requires an attached, ready preview.
+
+```tsx
+import { CameraView, createCameraSession } from '@octane-xplat/camera'
+
+const session = createCameraSession({ camera: 'default' })
+
+export function Recorder() {
+	return <CameraView session={session} />
+}
+```
+
+A take settles after the movie is finalized, metadata is verified, and local
+storage is committed. Native output lives in app-private files — including the
+packaged Linux WebKitGTK host, which writes under the app's data directory;
+Web uses persistent origin storage. Reopen it with `session.openOutput(output)`.
+
+```ts
+const take = session.startRecording({ maximumDurationMs: 30_000 })
+// … later, on a stop press or a maximum-duration limit:
+const outcome = await take.stop()
+if (outcome.kind === 'clip') {
+	const clip = outcome.clip
+	console.log(clip.durationMs, clip.width, clip.height, clip.output)
+}
+```
+
+One preview and one recording per session; a second `startRecording` throws
+`CameraCaptureError` with `kind: 'busy'`. Check `session.capabilities()` for
+`supported`/`available` before presenting capture UI, and `session.snapshot()`
+or `session.subscribe` for state. iOS, Android, Web, macOS, the Windows WinUI
+target, and the packaged Linux WebKitGTK host have recording adapters; Web
+requires persistent origin storage.
+macOS writes app-private MOV files through `AVCaptureMovieFileOutput` and
+reports finalized track metadata; on macOS 14+ the four cardinal orientations
+are lockable. Inside a qualified `xplat` WKWebView host the Web backend stores
+output in the app's private storage root instead of IndexedDB. Windows records
+through `MediaCapture` into app-private MP4 files and is pending real-host
+qualification. On Linux the GJS/WebKitGTK host owns media permissions and
+writes MP4 clips under the app's data directory.
+See [Record and reopen a camera movie](../../docs/app/movie-capture.md) for
+explicit permission actions, audio, local output, and qualification limits.
+
+```ts
+console.log(await session.permissions())
+// Call from an app button:
+await session.requestPermission('camera')
+console.log(await session.capabilities())
+```
+
+Guide: [Building screens](../../docs/app/primitives.md) (leaf components);
+component index: [`docs/app/components.md`](../../docs/app/components.md).
+Exercised by [`CameraDemo`](../demos/src/CameraDemo.tsrx).

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@octane-xplat/camera",
+  "version": "0.0.0-nightly.g2e22171",
+  "description": "Live camera preview for Octane xplat — web getUserMedia + native capture (AVCapture / CameraX)",
+  "keywords": [
+    "android",
+    "camera",
+    "camera-preview",
+    "cross-platform",
+    "ios",
+    "nativescript",
+    "octane",
+    "photo",
+    "video-capture",
+    "web",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/camera",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
+    "directory": "packages/camera"
+  },
+  "files": [
+    "types",
+    "src",
+    "platforms",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "linux": "./src/index.web.ts",
+      "web": "./src/index.web.ts",
+      "native": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@octane-xplat/platform": "0.0.0-nightly.g2e22171",
+    "mediabunny": "1.61.3"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.5",
+    "@nativescript/core": "9.1.3",
+    "@octane-xplat/macos-renderer": "0.0.0-nightly.g2e22171",
+    "@octanejs/vite-plugin": "0.1.61",
+    "octane": "0.11.0",
+    "tsrx-typegen": "0.3.0",
+    "typescript": "5.9.3",
+    "vite": "8.3.0",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "octane": ">=0.6.3 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    },
+    "octane": {
+      "optional": true
+    }
+  },
+  "nativescript": {
+    "platforms": {
+      "ios": "7.0.0",
+      "android": "7.0.0"
+    }
+  },
+  "xplat": {
+    "macos": {
+      "swiftHeaderImports": [
+        "AppKit/AppKit.h"
+      ],
+      "frameworks": [
+        "AVFoundation",
+        "CoreMedia",
+        "AppKit"
+      ]
+    }
+  },
+  "scripts": {
+    "typegen": "tsc -p tsconfig.types.json",
+    "test:packed": "node tests/packed-consumer.mjs",
+    "pack:check": "tsrx-typegen --pack-check",
+    "test": "vitest run && node --test tests/*.test.mjs",
+    "test:macos-photo": "node tests/photo-native.macos.mjs",
+    "test:macos-photo-hardware": "node tests/photo-hardware.macos.mjs",
+    "test:web": "node tests/browser-conformance.web.mjs",
+    "test:webkitgtk": "node tests/webkitgtk-conformance.linux.mjs"
+  }
+}

package/platforms/android/AndroidManifest.xml

@@ -0,0 +1,6 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+	<uses-feature android:name="android.hardware.camera.any" android:required="false" />
+	<uses-feature android:name="android.hardware.microphone" android:required="false" />
+	<uses-permission android:name="android.permission.CAMERA" />
+	<uses-permission android:name="android.permission.RECORD_AUDIO" />
+</manifest>

package/platforms/android/include.gradle

@@ -0,0 +1,14 @@
+allprojects {
+	repositories {
+		google()
+		mavenCentral()
+	}
+}
+
+dependencies {
+	def cameraXVersion = '1.5.3'
+	implementation "androidx.camera:camera-camera2:${cameraXVersion}"
+	implementation "androidx.camera:camera-lifecycle:${cameraXVersion}"
+	implementation "androidx.camera:camera-view:${cameraXVersion}"
+	implementation "androidx.camera:camera-video:${cameraXVersion}"
+}

package/platforms/android/java/com/octanexplat/camera/CameraPreviewView.java

@@ -0,0 +1,84 @@
+package com.octanexplat.camera;
+
+import android.content.Context;
+import android.view.ViewGroup;
+import android.widget.FrameLayout;
+
+import androidx.camera.core.MeteringPoint;
+import androidx.camera.core.Preview;
+import androidx.camera.view.PreviewView;
+import androidx.lifecycle.Lifecycle;
+import androidx.lifecycle.LifecycleOwner;
+import androidx.lifecycle.LifecycleRegistry;
+
+public final class CameraPreviewView extends FrameLayout implements LifecycleOwner {
+	private final LifecycleRegistry lifecycle;
+	private final PreviewView previewView;
+	private boolean cameraActive = true;
+	private boolean attached;
+
+	public CameraPreviewView(Context context) {
+		super(context);
+		lifecycle = new LifecycleRegistry(this);
+		lifecycle.handleLifecycleEvent(Lifecycle.Event.ON_CREATE);
+		previewView = new PreviewView(context);
+		previewView.setScaleType(PreviewView.ScaleType.FILL_CENTER);
+		addView(
+			previewView,
+			new FrameLayout.LayoutParams(
+				ViewGroup.LayoutParams.MATCH_PARENT,
+				ViewGroup.LayoutParams.MATCH_PARENT
+			)
+		);
+	}
+
+	@Override
+	public Lifecycle getLifecycle() {
+		return lifecycle;
+	}
+
+	public void setCameraActive(boolean active) {
+		cameraActive = active;
+		updateLifecycle();
+	}
+
+	public Preview.SurfaceProvider getSurfaceProvider() {
+		return previewView.getSurfaceProvider();
+	}
+
+	/** Converts a normalized view-space point (0-1, top-left origin) into a
+	 *  CameraX metering point. The PreviewView factory accounts for scale
+	 *  type, rotation, and front-camera mirroring. */
+	public MeteringPoint meteringPoint(float x, float y) {
+		return previewView.getMeteringPointFactory().createPoint(
+			x * previewView.getWidth(), y * previewView.getHeight());
+	}
+
+	public androidx.lifecycle.LiveData<PreviewView.StreamState> getStreamState() {
+		return previewView.getPreviewStreamState();
+	}
+
+	@Override
+	protected void onAttachedToWindow() {
+		super.onAttachedToWindow();
+		attached = true;
+		updateLifecycle();
+	}
+
+	@Override
+	protected void onDetachedFromWindow() {
+		attached = false;
+		updateLifecycle();
+		super.onDetachedFromWindow();
+	}
+
+	private void updateLifecycle() {
+		boolean shouldStart = cameraActive && attached;
+		boolean isStarted = lifecycle.getCurrentState().isAtLeast(Lifecycle.State.STARTED);
+		if (shouldStart && !isStarted) {
+			lifecycle.handleLifecycleEvent(Lifecycle.Event.ON_START);
+		} else if (!shouldStart && isStarted) {
+			lifecycle.handleLifecycleEvent(Lifecycle.Event.ON_STOP);
+		}
+	}
+}