tauri-plugin-camera-kessdev 0.1.1-beta.4 → 0.2.0-beta.1

package/README.md

@@ -2,7 +2,8 @@
 
 A [Tauri v2](https://v2.tauri.app) plugin that provides a **unified JavaScript API** for
 camera access across Android, iOS and desktop. It supports live preview, photo capture,
-video recording (with audio), camera controls (front/back, flash, zoom), saving to the
+video recording (with audio), camera controls (front/back, flash, zoom), camera
+introspection (list the available cameras and query their capabilities), saving to the
 photo gallery, and camera permission management.
 
 | Platform | Supported |
@@ -25,7 +26,7 @@ Add the Rust crate to `src-tauri/Cargo.toml`:
 
 ```toml
 [dependencies]
-tauri-plugin-camera-kessdev = "0.1.0"
+tauri-plugin-camera-kessdev = "0.2.0-beta.0"   # beta
 # or from a git/path source:
 # tauri-plugin-camera-kessdev = { path = "../tauri-plugin-camera" }
 ```
@@ -61,15 +62,16 @@ Add the default permission set to `src-tauri/capabilities/default.json`:
 {
   "permissions": [
     "core:default",
-    "camera:default"
+    "camera-kessdev:default"
   ]
 }
 ```
 
 To allow only specific commands, use the granular permissions instead of
-`camera:default` (e.g. `camera:allow-capture`, `camera:allow-start-recording`,
-`camera:allow-check-permissions`, …). The full list is generated under
-`permissions/autogenerated/commands/` as `allow-<command>` / `deny-<command>`.
+`camera-kessdev:default` (e.g. `camera-kessdev:allow-capture`,
+`camera-kessdev:allow-start-recording`, `camera-kessdev:allow-check-permissions`, …).
+The full list is generated under `permissions/autogenerated/commands/` as
+`allow-<command>` / `deny-<command>`.
 
 ### Android
 
@@ -128,13 +130,14 @@ import {
   stopRecording,
   flipCamera,
   setFlash,
-  isFlashAvailable,
   setZoom,
   getZoom,
-  getZoomRange,
+  getAvailableCameras,
+  getCapabilities,
   saveToGallery,
   checkPermissions,
   requestPermissions,
+  openAppSettings,
   getPreviewStream,
   convertFileSrc
 } from 'tauri-plugin-camera-kessdev'
@@ -146,6 +149,10 @@ import {
 // windowed: true keeps the webview transparent so your UI renders over the camera.
 await startPreview({ camera: 'back', windowed: true })
 
+// Or pick a specific lens by id (from getAvailableCameras()); cameraId takes precedence.
+const cameras = await getAvailableCameras()
+await startPreview({ cameraId: cameras[0].id })
+
 // Desktop: attach the stream to a <video> element.
 const stream = await getPreviewStream()
 if (stream) videoEl.srcObject = stream
@@ -164,6 +171,17 @@ const photo = await capture({ flash: 'auto' })
 imageEl.src = convertFileSrc(photo.path)
 ```
 
+Configurable (mobile and desktop):
+
+```ts
+await capture({
+  resolution: { width: 1920, height: 1080 }, // nearest supported size (best-effort)
+  aspectRatio: '16:9',                        // '4:3' | '16:9' | '1:1' | ...
+  format: 'jpeg',                             // 'jpeg' | 'png' | 'heif' (mobile jpeg; desktop jpeg/png)
+  quality: 0.9                                // 0..1 for lossy formats
+})
+```
+
 ### Video recording (with audio)
 
 ```ts
@@ -175,6 +193,9 @@ const video = await stopRecording()
 // Optionally request a base64 JPEG thumbnail of the recording:
 const withThumbnail = await stopRecording({ thumbnail: true })
 // withThumbnail.thumbnail: string | undefined
+
+// Configure quality/fps/bitrate (mobile and desktop):
+await startRecording({ quality: 'fhd', fps: 30, bitrate: 2_000_000 }) // quality: 'sd' | 'hd' | 'fhd' | 'uhd'
 ```
 
 ### Video thumbnail
@@ -233,14 +254,64 @@ await flipCamera()
 await setFlash('on') // 'on' | 'off' | 'auto'
 await setZoom(2.0)
 
-// Query the active camera (mobile). Desktop has no zoom/flash control:
-const zoom = await getZoom()                       // number
-const range = await getZoomRange()                 // { min, max, current }
-const hasFlash = await isFlashAvailable()          // boolean (false on desktop)
+// Live state (mobile):
+const zoom = await getZoom() // number
+```
+
+On desktop `getZoom()` rejects with a descriptive error (consistent with
+`setZoom`).
+
+### Fine controls
+
+Torch, tap-to-focus, exposure and white balance (mobile; desktop throws):
+
+```ts
+await setTorch(true)                 // continuous light (independent from capture flash)
+await setFocusPoint(0.5, 0.5)        // normalized 0..1, top-left origin
+await setFocusMode('continuous')     // 'auto' | 'continuous' | 'locked'
+await setExposureCompensation(1.5)   // EV, clamped to getCapabilities().exposureRange
+await setExposureMode('locked')      // 'auto' | 'locked'
+await setWhiteBalance({ mode: 'locked', temperatureK: 5000 })  // Kelvin; 'auto' | 'locked'
+```
+
+Details:
+
+- **Torch** is independent from the capture flash (`setFlash`); query `hasTorch`.
+- **Focus** uses normalized coordinates (0..1, top-left origin); query `supportsFocus` / `focusModes`.
+- **Exposure**: `ev` is clamped to `exposureRange`; `exposureModes` is `['auto', 'locked']`.
+- **White balance** is uniform across platforms: `mode: 'auto' | 'locked'`. In `locked`, `temperatureK` (Kelvin) is applied where the hardware supports it (`supportsWhiteBalanceTemperature`); when unsupported, the plugin locks the current gains (or rejects) instead of inventing a temperature. `auto` uses the platform's continuous AWB.
+
+On desktop all of these controls reject with a descriptive error. Query the
+supported values with `getCapabilities()` first: `hasTorch`,
+`supportsFocus`/`focusModes`, `exposureRange`/`exposureModes`,
+`whiteBalanceModes`/`supportsWhiteBalanceTemperature`.
+
+### Camera introspection
+
+Use `getAvailableCameras()` to list the cameras (physical/logical lenses) and
+`getCapabilities()` to know what a camera *can* do, before trying:
+
+```ts
+const cameras = await getAvailableCameras()
+// [{ id: '0', facing: 'back', lens: 'wide' }, { id: '1', facing: 'front' }, ...]
+
+// No argument: the active camera, or the default (back) camera without a preview.
+const caps = await getCapabilities(cameras[0].id)
+// { cameraId, hasFlash, hasTorch, zoomRange?, supportsFocus, focusModes?,
+//   exposureRange?, exposureModes?, whiteBalanceModes?, supportsWhiteBalanceTemperature?,
+//   photoResolutions?, photoAspects?, videoQualities?, videoFps?, photoFormats?, supportsPause }
 ```
 
-On desktop `getZoom()` and `getZoomRange()` reject with a descriptive error
-(consistent with `setZoom`), while `isFlashAvailable()` resolves to `false`.
+The plugin follows one rule to avoid ambiguity:
+
+- **What the hardware can do** -> `getCapabilities()` (declarative).
+- **What a value is right now** -> a dedicated live getter (e.g. `getZoom()`).
+
+Both work without an active preview on mobile. On desktop `getAvailableCameras()`
+works cold (labels may stay empty until camera permission has been granted once),
+while the hardware capabilities `zoomRange`, `hasTorch` and `focusModes` are
+omitted until a preview/recording stream is active; `hasFlash` is always `false`
+and `supportsPause` is `true`.
 
 ### Gallery
 
@@ -258,6 +329,9 @@ webm, 3gp, mkv are treated as video); pass `{ type }` to force it.
 ```ts
 const state = await checkPermissions()   // 'granted' | 'denied' | 'prompt'
 await requestPermissions()
+
+// Mobile: open the OS settings screen (e.g. after a permanent denial).
+await openAppSettings()
 ```
 
 ## Image return pattern
@@ -281,7 +355,7 @@ hardware, emulator or device is required.
 | Rust    | `src/models.rs` (inline tests)             | `cargo test`   | plugin root         | Rust + Cargo                      |
 | JS      | `guest-js/index.test.ts`                   | `npm test`     | plugin root         | Node.js 18+ + npm                 |
 | Android | `android/src/test/java/CameraPluginTest.kt`| `gradle test`  | `android/` (or generated app) | JDK 17+, Android SDK, Gradle |
-| iOS     | `ios/Tests/PluginTests/PluginTests.swift`  | `swift test`   | `ios/`              | macOS + Xcode                     |
+| iOS     | `ios/Tests/PluginTests/PluginTests.swift`  | `xcodebuild test` | iOS Simulator (generated app) | macOS + Xcode                     |
 
 ### Prerequisites
 
@@ -391,10 +465,16 @@ destination from the generated Xcode project (`src-tauri/gen/apple`).
 | `capture(options?)` | ✓ `ImageCapture` / `AVCapturePhotoOutput` | ✓ canvas |
 | `flipCamera()` | ✓ | ✗ (throws) |
 | `setFlash(mode)` | ✓ | ✗ (throws) |
-| `isFlashAvailable()` | ✓ | `false` |
 | `setZoom(factor)` | ✓ | ✗ (throws) |
 | `getZoom()` | ✓ | ✗ (throws) |
-| `getZoomRange()` | ✓ | ✗ (throws) |
+| `setTorch(on)` | ✓ | ✗ (throws) |
+| `setFocusPoint(x, y)` | ✓ | ✗ (throws) |
+| `setFocusMode(mode)` | ✓ | ✗ (throws) |
+| `setExposureCompensation(ev)` | ✓ | ✗ (throws) |
+| `setExposureMode(mode)` | ✓ | ✗ (throws) |
+| `setWhiteBalance(options)` | ✓ | ✗ (throws) |
+| `getAvailableCameras()` | ✓ | ✓ |
+| `getCapabilities(cameraId?)` | ✓ | ✓ (partial) |
 | `startRecording(options?)` | ✓ `VideoCapture` / `AVCaptureMovieFileOutput` | ✓ `MediaRecorder` |
 | `stopRecording(options?)` | ✓ | ✓ |
 | `RecordingProgress` telemetry (`onProgress` channel) | ✓ | ✓ |
@@ -404,3 +484,88 @@ destination from the generated Xcode project (`src-tauri/gen/apple`).
 | `requestPermissions()` | ✓ | ✓ |
 | `openAppSettings()` | ✓ | ✗ (throws) |
 | `getPreviewStream()` | `null` | `MediaStream` |
+
+## Types
+
+```ts
+type CameraDirection = 'front' | 'back'
+type FlashMode = 'on' | 'off' | 'auto'
+type CameraFacing = 'front' | 'back' | 'external'
+type CameraLens = 'wide' | 'ultraWide' | 'telephoto' | (string & {})
+type FocusMode = 'auto' | 'continuous' | 'locked'
+type ExposureMode = 'auto' | 'locked'
+type WhiteBalanceMode = 'auto' | 'locked'
+type PhotoFormat = 'jpeg' | 'png' | 'heif'
+type VideoQuality = 'sd' | 'hd' | 'fhd' | 'uhd'
+type PermissionState = 'granted' | 'denied' | 'prompt'  // re-exported from @tauri-apps/api/core
+
+interface StartPreviewOptions { camera?: CameraDirection; cameraId?: string; windowed?: boolean }
+interface CaptureOptions {
+  flash?: FlashMode
+  resolution?: Resolution
+  aspectRatio?: string
+  format?: PhotoFormat
+  quality?: number
+}
+interface Resolution { width: number; height: number }
+interface ExposureRange { minEv: number; maxEv: number }
+interface WhiteBalanceOptions { mode: WhiteBalanceMode; temperatureK?: number }
+
+interface Photo {
+  path?: string          // mobile: absolute path to the captured file
+  dataUrl?: string       // desktop: base64 data URL
+  blob?: Blob            // desktop
+  width: number
+  height: number
+  orientation: number    // EXIF orientation
+  format: string
+  thumbnail?: string     // base64 JPEG thumbnail (mobile; desktop reuses dataUrl)
+}
+
+interface Video {
+  path?: string          // mobile
+  duration: number
+  blob?: Blob            // desktop
+  url?: string           // desktop object URL
+  thumbnail?: string     // base64 JPEG when requested via stopRecording({ thumbnail: true })
+}
+
+interface ZoomRange { min: number; max: number }
+
+interface CameraInfo {
+  id: string             // native, session-stable identifier
+  facing?: CameraFacing
+  lens?: CameraLens
+  label?: string
+}
+
+interface CameraCapabilities {
+  cameraId?: string
+  hasFlash: boolean
+  hasTorch: boolean
+  zoomRange?: ZoomRange
+  supportsFocus: boolean
+  focusModes?: string[]
+  exposureRange?: ExposureRange
+  exposureModes?: ExposureMode[]
+  whiteBalanceModes?: WhiteBalanceMode[]
+  supportsWhiteBalanceTemperature?: boolean
+  photoResolutions?: Resolution[]
+  photoAspects?: string[]
+  videoQualities?: VideoQuality[]
+  videoFps?: number[]
+  photoFormats?: string[]
+  supportsPause: boolean
+}
+
+interface RecordingProgress { duration: number; bytesRecorded?: number; bitrate?: number }
+
+interface StartRecordingOptions {
+  onProgress?: Channel<RecordingProgress>
+  quality?: VideoQuality
+  fps?: number
+  bitrate?: number
+}
+interface StopRecordingOptions { thumbnail?: boolean }
+interface SaveToGalleryOptions { type?: 'image' | 'video' }
+```

package/dist-js/index.cjs

@@ -48,12 +48,14 @@ function stopProgressTimer() {
 async function ensureDesktopStream(options) {
     if (activeStream)
         return activeStream;
-    const constraints = {
-        video: {
-            facingMode: options?.camera === 'front' ? 'user' : 'environment'
-        },
-        audio: false
-    };
+    const videoConstraints = {};
+    if (options?.cameraId) {
+        videoConstraints.deviceId = { exact: options.cameraId };
+    }
+    else {
+        videoConstraints.facingMode = options?.camera === 'front' ? 'user' : 'environment';
+    }
+    const constraints = { video: videoConstraints, audio: false };
     const stream = await navigator.mediaDevices.getUserMedia(constraints);
     activeStream = stream;
     const video = document.createElement('video');
@@ -78,12 +80,55 @@ function teardownDesktopStream() {
     activeStream = null;
     activeVideo = null;
 }
-function captureDesktopFrame() {
+/** Parses an aspect ratio like '4:3' into a number (4/3), or null. */
+function parseAspectRatio(value) {
+    const [w, h] = value.split(':').map((n) => Number(n));
+    if (!w || !h)
+        return null;
+    return w / h;
+}
+/** Target capture height (px) for a video quality preset (desktop best-effort). */
+function qualityHeight(quality) {
+    switch (quality) {
+        case 'sd':
+            return 480;
+        case 'hd':
+            return 720;
+        case 'fhd':
+            return 1080;
+        case 'uhd':
+            return 2160;
+    }
+}
+/** MIME type for a photo format on desktop, or null when unsupported. */
+function desktopPhotoMime(format) {
+    switch (format) {
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'png':
+            return 'image/png';
+        default:
+            return null;
+    }
+}
+function captureDesktopFrame(options) {
     if (!activeVideo) {
         throw new Error('Camera preview is not active. Call startPreview() first.');
     }
-    const width = activeVideo.videoWidth;
-    const height = activeVideo.videoHeight;
+    const format = options?.format ?? 'jpeg';
+    const mime = desktopPhotoMime(format);
+    if (!mime) {
+        throw new Error(`${format} is not supported on desktop.`);
+    }
+    const sourceWidth = activeVideo.videoWidth;
+    const sourceHeight = activeVideo.videoHeight;
+    let width = options?.resolution?.width ?? sourceWidth;
+    let height = options?.resolution?.height ?? sourceHeight;
+    if (!options?.resolution && options?.aspectRatio) {
+        const ratio = parseAspectRatio(options.aspectRatio);
+        if (ratio)
+            height = Math.round(width / ratio);
+    }
     const canvas = document.createElement('canvas');
     canvas.width = width;
     canvas.height = height;
@@ -92,13 +137,13 @@ function captureDesktopFrame() {
         throw new Error('Failed to create canvas context for capture.');
     }
     ctx.drawImage(activeVideo, 0, 0, width, height);
-    const dataUrl = canvas.toDataURL('image/jpeg');
+    const dataUrl = canvas.toDataURL(mime, options?.quality);
     return {
         dataUrl,
         width,
         height,
         orientation: 1,
-        format: 'jpeg',
+        format,
         thumbnail: dataUrl
     };
 }
@@ -152,7 +197,7 @@ async function capture(options) {
     if (isMobile()) {
         return await core.invoke('plugin:camera-kessdev|capture', { ...options });
     }
-    return captureDesktopFrame();
+    return captureDesktopFrame(options);
 }
 // ---------------------------------------------------------------------------
 // Camera controls
@@ -188,23 +233,140 @@ async function getZoom() {
     }
     throw new Error('getZoom is not supported on desktop.');
 }
-/** Gets the supported zoom range of the active camera (mobile). */
-async function getZoomRange() {
+// ---------------------------------------------------------------------------
+// Introspection (available cameras + declarative capabilities)
+// ---------------------------------------------------------------------------
+/** Best-effort facing detection from a device label (desktop). */
+function facingFromLabel(label) {
+    const value = label.toLowerCase();
+    if (value.includes('front') || value.includes('user'))
+        return 'front';
+    if (value.includes('back') || value.includes('rear') || value.includes('environment'))
+        return 'back';
+    return undefined;
+}
+/** Enumerates video input devices on desktop via `enumerateDevices()`. */
+async function enumerateDesktopCameras() {
+    const devices = await navigator.mediaDevices.enumerateDevices();
+    return devices
+        .filter((device) => device.kind === 'videoinput')
+        .map((device) => {
+        const info = { id: device.deviceId };
+        const facing = facingFromLabel(device.label);
+        if (facing)
+            info.facing = facing;
+        if (device.label)
+            info.label = device.label;
+        return info;
+    });
+}
+/**
+ * Declarative capabilities on desktop. Hardware fields (`zoomRange`, `hasTorch`,
+ * `focusModes`) are only known while a preview/recording stream is active; they
+ * are omitted otherwise.
+ */
+function desktopCapabilities(cameraId) {
+    const caps = {
+        hasFlash: false,
+        hasTorch: false,
+        supportsFocus: false,
+        supportsPause: true,
+        photoFormats: ['jpeg', 'png', 'webp']
+    };
+    if (cameraId)
+        caps.cameraId = cameraId;
+    const track = activeStream?.getVideoTracks?.()[0];
+    const trackCaps = track?.getCapabilities?.();
+    if (trackCaps) {
+        if (trackCaps.zoom) {
+            caps.zoomRange = { min: trackCaps.zoom.min, max: trackCaps.zoom.max };
+        }
+        if (typeof trackCaps.torch === 'boolean') {
+            caps.hasTorch = trackCaps.torch;
+        }
+        if (trackCaps.focusMode && trackCaps.focusMode.length > 0) {
+            caps.supportsFocus = true;
+            caps.focusModes = trackCaps.focusMode;
+        }
+    }
+    return caps;
+}
+/**
+ * Lists the cameras (physical or logical lenses) available on the device.
+ *
+ * Works without an active preview on every platform. On desktop the labels may
+ * be empty until camera permission has been granted at least once.
+ */
+async function getAvailableCameras() {
     if (isMobile()) {
-        return await core.invoke('plugin:camera-kessdev|get_zoom_range');
+        return await core.invoke('plugin:camera-kessdev|get_available_cameras');
     }
-    throw new Error('getZoomRange is not supported on desktop.');
+    return enumerateDesktopCameras();
 }
 /**
- * Returns whether the active camera has a flash unit.
+ * Returns the declarative capabilities of a camera.
  *
- * On desktop this always resolves to `false` (no flash control).
+ * Without `cameraId` it describes the active camera, or the default (back)
+ * camera when no preview is active. On mobile it works without an active
+ * preview; on desktop hardware fields are omitted until a stream is active.
+ * Live values are exposed by dedicated getters (e.g. {@link getZoom}).
  */
-async function isFlashAvailable() {
+async function getCapabilities(cameraId) {
     if (isMobile()) {
-        return await core.invoke('plugin:camera-kessdev|is_flash_available');
+        return await core.invoke('plugin:camera-kessdev|get_capabilities', { cameraId });
+    }
+    return desktopCapabilities(cameraId);
+}
+// ---------------------------------------------------------------------------
+// Fine controls (torch, focus, exposure, white balance)
+// ---------------------------------------------------------------------------
+/** Turns the torch (continuous light) on or off (mobile). */
+async function setTorch(on) {
+    if (isMobile()) {
+        await core.invoke('plugin:camera-kessdev|set_torch', { on });
+        return;
+    }
+    throw new Error('setTorch is not supported on desktop.');
+}
+/** Sets the focus point in normalized coordinates (0..1, top-left origin) (mobile). */
+async function setFocusPoint(x, y) {
+    if (isMobile()) {
+        await core.invoke('plugin:camera-kessdev|set_focus_point', { x, y });
+        return;
+    }
+    throw new Error('setFocusPoint is not supported on desktop.');
+}
+/** Sets the focus mode (mobile). */
+async function setFocusMode(mode) {
+    if (isMobile()) {
+        await core.invoke('plugin:camera-kessdev|set_focus_mode', { mode });
+        return;
+    }
+    throw new Error('setFocusMode is not supported on desktop.');
+}
+/** Sets the exposure compensation in EV (mobile). */
+async function setExposureCompensation(ev) {
+    if (isMobile()) {
+        await core.invoke('plugin:camera-kessdev|set_exposure_compensation', { ev });
+        return;
+    }
+    throw new Error('setExposureCompensation is not supported on desktop.');
+}
+/** Sets the exposure mode (mobile). */
+async function setExposureMode(mode) {
+    if (isMobile()) {
+        await core.invoke('plugin:camera-kessdev|set_exposure_mode', { mode });
+        return;
+    }
+    throw new Error('setExposureMode is not supported on desktop.');
+}
+/** Sets the white balance mode (with an optional Kelvin temperature when `locked`) (mobile). */
+async function setWhiteBalance(options) {
+    if (isMobile()) {
+        await core.invoke('plugin:camera-kessdev|set_white_balance', { ...options });
+        return;
     }
-    return false;
+    throw new Error('setWhiteBalance is not supported on desktop.');
 }
 // ---------------------------------------------------------------------------
 // Video recording
@@ -220,7 +382,12 @@ async function startRecording(options) {
         activeStream = null;
         activeVideo = null;
     }
-    const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
+    const videoConstraints = {};
+    if (options?.quality)
+        videoConstraints.height = { ideal: qualityHeight(options.quality) };
+    if (options?.fps)
+        videoConstraints.frameRate = { ideal: options.fps };
+    const stream = await navigator.mediaDevices.getUserMedia({ video: videoConstraints, audio: true });
     activeStream = stream;
     const video = document.createElement('video');
     video.muted = true;
@@ -230,7 +397,10 @@ async function startRecording(options) {
     activeVideo = video;
     recordedChunks = [];
     recordedBytes = 0;
-    mediaRecorder = new MediaRecorder(stream);
+    const recorderOptions = {};
+    if (options?.bitrate)
+        recorderOptions.videoBitsPerSecond = options.bitrate;
+    mediaRecorder = new MediaRecorder(stream, recorderOptions);
     mediaRecorder.ondataavailable = (event) => {
         if (event.data.size > 0) {
             recordedChunks.push(event.data);
@@ -363,14 +533,20 @@ Object.defineProperty(exports, "convertFileSrc", {
 exports.capture = capture;
 exports.checkPermissions = checkPermissions;
 exports.flipCamera = flipCamera;
+exports.getAvailableCameras = getAvailableCameras;
+exports.getCapabilities = getCapabilities;
 exports.getPreviewStream = getPreviewStream;
 exports.getZoom = getZoom;
-exports.getZoomRange = getZoomRange;
-exports.isFlashAvailable = isFlashAvailable;
 exports.openAppSettings = openAppSettings;
 exports.requestPermissions = requestPermissions;
 exports.saveToGallery = saveToGallery;
+exports.setExposureCompensation = setExposureCompensation;
+exports.setExposureMode = setExposureMode;
 exports.setFlash = setFlash;
+exports.setFocusMode = setFocusMode;
+exports.setFocusPoint = setFocusPoint;
+exports.setTorch = setTorch;
+exports.setWhiteBalance = setWhiteBalance;
 exports.setZoom = setZoom;
 exports.startPreview = startPreview;
 exports.startRecording = startRecording;

package/dist-js/index.d.ts

@@ -6,10 +6,27 @@ export type CameraDirection = 'front' | 'back';
 export type FlashMode = 'on' | 'off' | 'auto';
 export interface StartPreviewOptions {
     camera?: CameraDirection;
+    /** Specific camera/lens id from `getAvailableCameras()`. Takes precedence over `camera`. */
+    cameraId?: string;
     windowed?: boolean;
 }
+export type PhotoFormat = 'jpeg' | 'png' | 'heif';
+export type VideoQuality = 'sd' | 'hd' | 'fhd' | 'uhd';
+/** A width/height pair in pixels. */
+export interface Resolution {
+    width: number;
+    height: number;
+}
 export interface CaptureOptions {
     flash?: FlashMode;
+    /** Target resolution (best-effort: the nearest supported is used). */
+    resolution?: Resolution;
+    /** Target aspect ratio (e.g. '4:3', '16:9', '1:1'). */
+    aspectRatio?: string;
+    /** Image format. Mobile supports `jpeg`; desktop `jpeg`/`png`. */
+    format?: PhotoFormat;
+    /** Compression quality (0..1) for lossy formats. */
+    quality?: number;
 }
 export interface Photo {
     /** Absolute path to the captured image (mobile). */
@@ -37,11 +54,72 @@ export interface Video {
     /** Optional base64-encoded thumbnail, when requested via `stopRecording`. */
     thumbnail?: string;
 }
-/** Supported zoom range of the active camera. */
+/** Supported zoom range of a camera (declarative, without the live value). */
 export interface ZoomRange {
     min: number;
     max: number;
-    current: number;
+}
+/** Orientation of a camera. */
+export type CameraFacing = 'front' | 'back' | 'external';
+/**
+ * Best-effort hint of which lens a camera maps to. Platforms that cannot
+ * determine it (notably desktop) omit the field.
+ */
+export type CameraLens = 'wide' | 'ultraWide' | 'telephoto' | (string & {});
+/** Camera focus mode. */
+export type FocusMode = 'auto' | 'continuous' | 'locked';
+/** Camera exposure mode. */
+export type ExposureMode = 'auto' | 'locked';
+/** White balance mode. */
+export type WhiteBalanceMode = 'auto' | 'locked';
+/** Supported exposure compensation range (EV). */
+export interface ExposureRange {
+    minEv: number;
+    maxEv: number;
+}
+/** Options for `setWhiteBalance`. */
+export interface WhiteBalanceOptions {
+    mode: WhiteBalanceMode;
+    /** Color temperature in Kelvin; only meaningful when `mode` is `locked`. */
+    temperatureK?: number;
+}
+/** A camera (physical or logical lens) available on the device. */
+export interface CameraInfo {
+    /** Native, session-stable identifier (usable to reference this camera). */
+    id: string;
+    /** Orientation, when the platform can determine it. */
+    facing?: CameraFacing;
+    /** Best-effort lens hint, when the platform can determine it. */
+    lens?: CameraLens;
+    /** Human-readable label, when available. */
+    label?: string;
+}
+/**
+ * Declarative capabilities of a camera: what the hardware/platform *can* do.
+ *
+ * Optional fields are omitted when the platform cannot determine them. Live
+ * values (e.g. the current zoom factor) are exposed by dedicated getters such
+ * as {@link getZoom}, never here.
+ */
+export interface CameraCapabilities {
+    /** Identifier of the camera these capabilities describe, when known. */
+    cameraId?: string;
+    hasFlash: boolean;
+    hasTorch: boolean;
+    zoomRange?: ZoomRange;
+    supportsFocus: boolean;
+    focusModes?: string[];
+    exposureRange?: ExposureRange;
+    exposureModes?: ExposureMode[];
+    whiteBalanceModes?: WhiteBalanceMode[];
+    /** Whether an arbitrary color temperature (Kelvin) can be applied. */
+    supportsWhiteBalanceTemperature?: boolean;
+    photoResolutions?: Resolution[];
+    photoAspects?: string[];
+    videoQualities?: VideoQuality[];
+    videoFps?: number[];
+    photoFormats?: string[];
+    supportsPause: boolean;
 }
 /**
  * Live telemetry emitted while a video recording is in progress.
@@ -61,6 +139,12 @@ export interface RecordingProgress {
 export interface StartRecordingOptions {
     /** Receives live recording telemetry while the recording is active. */
     onProgress?: Channel<RecordingProgress>;
+    /** Video quality preset. */
+    quality?: VideoQuality;
+    /** Target frame rate. */
+    fps?: number;
+    /** Target bitrate in bits per second. */
+    bitrate?: number;
 }
 export interface StopRecordingOptions {
     /** When true, the result includes a base64-encoded `thumbnail`. */
@@ -103,14 +187,34 @@ export declare function setFlash(mode: FlashMode): Promise<void>;
 export declare function setZoom(factor: number): Promise<void>;
 /** Gets the current camera zoom factor (mobile). */
 export declare function getZoom(): Promise<number>;
-/** Gets the supported zoom range of the active camera (mobile). */
-export declare function getZoomRange(): Promise<ZoomRange>;
 /**
- * Returns whether the active camera has a flash unit.
+ * Lists the cameras (physical or logical lenses) available on the device.
+ *
+ * Works without an active preview on every platform. On desktop the labels may
+ * be empty until camera permission has been granted at least once.
+ */
+export declare function getAvailableCameras(): Promise<CameraInfo[]>;
+/**
+ * Returns the declarative capabilities of a camera.
  *
- * On desktop this always resolves to `false` (no flash control).
+ * Without `cameraId` it describes the active camera, or the default (back)
+ * camera when no preview is active. On mobile it works without an active
+ * preview; on desktop hardware fields are omitted until a stream is active.
+ * Live values are exposed by dedicated getters (e.g. {@link getZoom}).
  */
-export declare function isFlashAvailable(): Promise<boolean>;
+export declare function getCapabilities(cameraId?: string): Promise<CameraCapabilities>;
+/** Turns the torch (continuous light) on or off (mobile). */
+export declare function setTorch(on: boolean): Promise<void>;
+/** Sets the focus point in normalized coordinates (0..1, top-left origin) (mobile). */
+export declare function setFocusPoint(x: number, y: number): Promise<void>;
+/** Sets the focus mode (mobile). */
+export declare function setFocusMode(mode: FocusMode): Promise<void>;
+/** Sets the exposure compensation in EV (mobile). */
+export declare function setExposureCompensation(ev: number): Promise<void>;
+/** Sets the exposure mode (mobile). */
+export declare function setExposureMode(mode: ExposureMode): Promise<void>;
+/** Sets the white balance mode (with an optional Kelvin temperature when `locked`) (mobile). */
+export declare function setWhiteBalance(options: WhiteBalanceOptions): Promise<void>;
 /** Starts video recording (with audio). */
 export declare function startRecording(options?: StartRecordingOptions): Promise<void>;
 /** Stops video recording and returns the recorded media. */

package/dist-js/index.js

@@ -47,12 +47,14 @@ function stopProgressTimer() {
 async function ensureDesktopStream(options) {
     if (activeStream)
         return activeStream;
-    const constraints = {
-        video: {
-            facingMode: options?.camera === 'front' ? 'user' : 'environment'
-        },
-        audio: false
-    };
+    const videoConstraints = {};
+    if (options?.cameraId) {
+        videoConstraints.deviceId = { exact: options.cameraId };
+    }
+    else {
+        videoConstraints.facingMode = options?.camera === 'front' ? 'user' : 'environment';
+    }
+    const constraints = { video: videoConstraints, audio: false };
     const stream = await navigator.mediaDevices.getUserMedia(constraints);
     activeStream = stream;
     const video = document.createElement('video');
@@ -77,12 +79,55 @@ function teardownDesktopStream() {
     activeStream = null;
     activeVideo = null;
 }
-function captureDesktopFrame() {
+/** Parses an aspect ratio like '4:3' into a number (4/3), or null. */
+function parseAspectRatio(value) {
+    const [w, h] = value.split(':').map((n) => Number(n));
+    if (!w || !h)
+        return null;
+    return w / h;
+}
+/** Target capture height (px) for a video quality preset (desktop best-effort). */
+function qualityHeight(quality) {
+    switch (quality) {
+        case 'sd':
+            return 480;
+        case 'hd':
+            return 720;
+        case 'fhd':
+            return 1080;
+        case 'uhd':
+            return 2160;
+    }
+}
+/** MIME type for a photo format on desktop, or null when unsupported. */
+function desktopPhotoMime(format) {
+    switch (format) {
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'png':
+            return 'image/png';
+        default:
+            return null;
+    }
+}
+function captureDesktopFrame(options) {
     if (!activeVideo) {
         throw new Error('Camera preview is not active. Call startPreview() first.');
     }
-    const width = activeVideo.videoWidth;
-    const height = activeVideo.videoHeight;
+    const format = options?.format ?? 'jpeg';
+    const mime = desktopPhotoMime(format);
+    if (!mime) {
+        throw new Error(`${format} is not supported on desktop.`);
+    }
+    const sourceWidth = activeVideo.videoWidth;
+    const sourceHeight = activeVideo.videoHeight;
+    let width = options?.resolution?.width ?? sourceWidth;
+    let height = options?.resolution?.height ?? sourceHeight;
+    if (!options?.resolution && options?.aspectRatio) {
+        const ratio = parseAspectRatio(options.aspectRatio);
+        if (ratio)
+            height = Math.round(width / ratio);
+    }
     const canvas = document.createElement('canvas');
     canvas.width = width;
     canvas.height = height;
@@ -91,13 +136,13 @@ function captureDesktopFrame() {
         throw new Error('Failed to create canvas context for capture.');
     }
     ctx.drawImage(activeVideo, 0, 0, width, height);
-    const dataUrl = canvas.toDataURL('image/jpeg');
+    const dataUrl = canvas.toDataURL(mime, options?.quality);
     return {
         dataUrl,
         width,
         height,
         orientation: 1,
-        format: 'jpeg',
+        format,
         thumbnail: dataUrl
     };
 }
@@ -151,7 +196,7 @@ async function capture(options) {
     if (isMobile()) {
         return await invoke('plugin:camera-kessdev|capture', { ...options });
     }
-    return captureDesktopFrame();
+    return captureDesktopFrame(options);
 }
 // ---------------------------------------------------------------------------
 // Camera controls
@@ -187,23 +232,140 @@ async function getZoom() {
     }
     throw new Error('getZoom is not supported on desktop.');
 }
-/** Gets the supported zoom range of the active camera (mobile). */
-async function getZoomRange() {
+// ---------------------------------------------------------------------------
+// Introspection (available cameras + declarative capabilities)
+// ---------------------------------------------------------------------------
+/** Best-effort facing detection from a device label (desktop). */
+function facingFromLabel(label) {
+    const value = label.toLowerCase();
+    if (value.includes('front') || value.includes('user'))
+        return 'front';
+    if (value.includes('back') || value.includes('rear') || value.includes('environment'))
+        return 'back';
+    return undefined;
+}
+/** Enumerates video input devices on desktop via `enumerateDevices()`. */
+async function enumerateDesktopCameras() {
+    const devices = await navigator.mediaDevices.enumerateDevices();
+    return devices
+        .filter((device) => device.kind === 'videoinput')
+        .map((device) => {
+        const info = { id: device.deviceId };
+        const facing = facingFromLabel(device.label);
+        if (facing)
+            info.facing = facing;
+        if (device.label)
+            info.label = device.label;
+        return info;
+    });
+}
+/**
+ * Declarative capabilities on desktop. Hardware fields (`zoomRange`, `hasTorch`,
+ * `focusModes`) are only known while a preview/recording stream is active; they
+ * are omitted otherwise.
+ */
+function desktopCapabilities(cameraId) {
+    const caps = {
+        hasFlash: false,
+        hasTorch: false,
+        supportsFocus: false,
+        supportsPause: true,
+        photoFormats: ['jpeg', 'png', 'webp']
+    };
+    if (cameraId)
+        caps.cameraId = cameraId;
+    const track = activeStream?.getVideoTracks?.()[0];
+    const trackCaps = track?.getCapabilities?.();
+    if (trackCaps) {
+        if (trackCaps.zoom) {
+            caps.zoomRange = { min: trackCaps.zoom.min, max: trackCaps.zoom.max };
+        }
+        if (typeof trackCaps.torch === 'boolean') {
+            caps.hasTorch = trackCaps.torch;
+        }
+        if (trackCaps.focusMode && trackCaps.focusMode.length > 0) {
+            caps.supportsFocus = true;
+            caps.focusModes = trackCaps.focusMode;
+        }
+    }
+    return caps;
+}
+/**
+ * Lists the cameras (physical or logical lenses) available on the device.
+ *
+ * Works without an active preview on every platform. On desktop the labels may
+ * be empty until camera permission has been granted at least once.
+ */
+async function getAvailableCameras() {
     if (isMobile()) {
-        return await invoke('plugin:camera-kessdev|get_zoom_range');
+        return await invoke('plugin:camera-kessdev|get_available_cameras');
     }
-    throw new Error('getZoomRange is not supported on desktop.');
+    return enumerateDesktopCameras();
 }
 /**
- * Returns whether the active camera has a flash unit.
+ * Returns the declarative capabilities of a camera.
  *
- * On desktop this always resolves to `false` (no flash control).
+ * Without `cameraId` it describes the active camera, or the default (back)
+ * camera when no preview is active. On mobile it works without an active
+ * preview; on desktop hardware fields are omitted until a stream is active.
+ * Live values are exposed by dedicated getters (e.g. {@link getZoom}).
  */
-async function isFlashAvailable() {
+async function getCapabilities(cameraId) {
     if (isMobile()) {
-        return await invoke('plugin:camera-kessdev|is_flash_available');
+        return await invoke('plugin:camera-kessdev|get_capabilities', { cameraId });
+    }
+    return desktopCapabilities(cameraId);
+}
+// ---------------------------------------------------------------------------
+// Fine controls (torch, focus, exposure, white balance)
+// ---------------------------------------------------------------------------
+/** Turns the torch (continuous light) on or off (mobile). */
+async function setTorch(on) {
+    if (isMobile()) {
+        await invoke('plugin:camera-kessdev|set_torch', { on });
+        return;
+    }
+    throw new Error('setTorch is not supported on desktop.');
+}
+/** Sets the focus point in normalized coordinates (0..1, top-left origin) (mobile). */
+async function setFocusPoint(x, y) {
+    if (isMobile()) {
+        await invoke('plugin:camera-kessdev|set_focus_point', { x, y });
+        return;
+    }
+    throw new Error('setFocusPoint is not supported on desktop.');
+}
+/** Sets the focus mode (mobile). */
+async function setFocusMode(mode) {
+    if (isMobile()) {
+        await invoke('plugin:camera-kessdev|set_focus_mode', { mode });
+        return;
+    }
+    throw new Error('setFocusMode is not supported on desktop.');
+}
+/** Sets the exposure compensation in EV (mobile). */
+async function setExposureCompensation(ev) {
+    if (isMobile()) {
+        await invoke('plugin:camera-kessdev|set_exposure_compensation', { ev });
+        return;
+    }
+    throw new Error('setExposureCompensation is not supported on desktop.');
+}
+/** Sets the exposure mode (mobile). */
+async function setExposureMode(mode) {
+    if (isMobile()) {
+        await invoke('plugin:camera-kessdev|set_exposure_mode', { mode });
+        return;
+    }
+    throw new Error('setExposureMode is not supported on desktop.');
+}
+/** Sets the white balance mode (with an optional Kelvin temperature when `locked`) (mobile). */
+async function setWhiteBalance(options) {
+    if (isMobile()) {
+        await invoke('plugin:camera-kessdev|set_white_balance', { ...options });
+        return;
     }
-    return false;
+    throw new Error('setWhiteBalance is not supported on desktop.');
 }
 // ---------------------------------------------------------------------------
 // Video recording
@@ -219,7 +381,12 @@ async function startRecording(options) {
         activeStream = null;
         activeVideo = null;
     }
-    const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
+    const videoConstraints = {};
+    if (options?.quality)
+        videoConstraints.height = { ideal: qualityHeight(options.quality) };
+    if (options?.fps)
+        videoConstraints.frameRate = { ideal: options.fps };
+    const stream = await navigator.mediaDevices.getUserMedia({ video: videoConstraints, audio: true });
     activeStream = stream;
     const video = document.createElement('video');
     video.muted = true;
@@ -229,7 +396,10 @@ async function startRecording(options) {
     activeVideo = video;
     recordedChunks = [];
     recordedBytes = 0;
-    mediaRecorder = new MediaRecorder(stream);
+    const recorderOptions = {};
+    if (options?.bitrate)
+        recorderOptions.videoBitsPerSecond = options.bitrate;
+    mediaRecorder = new MediaRecorder(stream, recorderOptions);
     mediaRecorder.ondataavailable = (event) => {
         if (event.data.size > 0) {
             recordedChunks.push(event.data);
@@ -355,4 +525,4 @@ async function openAppSettings() {
     throw new Error('openAppSettings is not supported on desktop.');
 }
 
-export { capture, checkPermissions, flipCamera, getPreviewStream, getZoom, getZoomRange, isFlashAvailable, openAppSettings, requestPermissions, saveToGallery, setFlash, setZoom, startPreview, startRecording, stopPreview, stopRecording };
+export { capture, checkPermissions, flipCamera, getAvailableCameras, getCapabilities, getPreviewStream, getZoom, openAppSettings, requestPermissions, saveToGallery, setExposureCompensation, setExposureMode, setFlash, setFocusMode, setFocusPoint, setTorch, setWhiteBalance, setZoom, startPreview, startRecording, stopPreview, stopRecording };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tauri-plugin-camera-kessdev",
-  "version": "0.1.1-beta.4",
+  "version": "0.2.0-beta.1",
   "author": "kess",
   "description": "Camera plugin for Tauri v2: photo capture, video recording and preview on Android, iOS and desktop.",
   "license": "MIT",