tauri-plugin-camera-kessdev 0.1.1-beta.3 → 0.2.0-beta.0

package/README.md

@@ -129,6 +129,9 @@ import {
   flipCamera,
   setFlash,
   setZoom,
+  getZoom,
+  getAvailableCameras,
+  getCapabilities,
   saveToGallery,
   checkPermissions,
   requestPermissions,
@@ -168,8 +171,23 @@ await startRecording()
 // ... user records ...
 const video = await stopRecording()
 // video: { path, duration } (mobile) | { duration, blob, url } (desktop)
+
+// Optionally request a base64 JPEG thumbnail of the recording:
+const withThumbnail = await stopRecording({ thumbnail: true })
+// withThumbnail.thumbnail: string | undefined
 ```
 
+### Video thumbnail
+
+Pass `{ thumbnail: true }` to `stopRecording()` to include a base64-encoded JPEG
+poster frame in the `Video` result. It is opt-in because it costs a frame decode
+and encode. When it cannot be generated the field is omitted (the recording still
+succeeds).
+
+- **Android**: extracted with `MediaMetadataRetriever` on the recording executor.
+- **iOS**: extracted with `AVAssetImageGenerator` at ~0.1 s (avoids a black first frame).
+- **Desktop**: captured from the live preview stream at stop time.
+
 ### Recording progress (telemetry)
 
 Pass an `onProgress` channel to `startRecording()` to receive live telemetry while
@@ -214,14 +232,51 @@ ends. Telemetry is never emitted after `stopRecording()` resolves.
 await flipCamera()
 await setFlash('on') // 'on' | 'off' | 'auto'
 await setZoom(2.0)
+
+// Live state (mobile):
+const zoom = await getZoom() // number
+```
+
+On desktop `getZoom()` rejects with a descriptive error (consistent with
+`setZoom`).
+
+### 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?,
+//   photoFormats?, supportsPause }
 ```
 
+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
 
 ```ts
-await saveToGallery(photo.path) // mobile only
+await saveToGallery(photo.path)                 // image
+await saveToGallery(video.path)                 // video
+await saveToGallery(media.path, { type: 'video' }) // forced type override
 ```
 
+Mobile only. The media type is inferred from the file extension (mp4, mov, m4v,
+webm, 3gp, mkv are treated as video); pass `{ type }` to force it.
+
 ### Permissions
 
 ```ts
@@ -361,10 +416,14 @@ destination from the generated Xcode project (`src-tauri/gen/apple`).
 | `flipCamera()` | ✓ | ✗ (throws) |
 | `setFlash(mode)` | ✓ | ✗ (throws) |
 | `setZoom(factor)` | ✓ | ✗ (throws) |
+| `getZoom()` | ✓ | ✗ (throws) |
+| `getAvailableCameras()` | ✓ | ✓ |
+| `getCapabilities(cameraId?)` | ✓ | ✓ (partial) |
 | `startRecording(options?)` | ✓ `VideoCapture` / `AVCaptureMovieFileOutput` | ✓ `MediaRecorder` |
-| `stopRecording()` | ✓ | ✓ |
+| `stopRecording(options?)` | ✓ | ✓ |
 | `RecordingProgress` telemetry (`onProgress` channel) | ✓ | ✓ |
-| `saveToGallery(path)` | ✓ | ✗ (throws) |
+| `Video.thumbnail` (`stopRecording({ thumbnail: true })`) | ✓ | ✓ |
+| `saveToGallery(path, options?)` | ✓ image & video | ✗ (throws) |
 | `checkPermissions()` | ✓ | ✓ |
 | `requestPermissions()` | ✓ | ✓ |
 | `openAppSettings()` | ✓ | ✗ (throws) |

package/dist-js/index.cjs

@@ -181,6 +181,97 @@ async function setZoom(factor) {
     }
     throw new Error('setZoom is not supported on desktop.');
 }
+/** Gets the current camera zoom factor (mobile). */
+async function getZoom() {
+    if (isMobile()) {
+        return await core.invoke('plugin:camera-kessdev|get_zoom');
+    }
+    throw new Error('getZoom is not supported on desktop.');
+}
+// ---------------------------------------------------------------------------
+// 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_available_cameras');
+    }
+    return enumerateDesktopCameras();
+}
+/**
+ * Returns the declarative capabilities of a camera.
+ *
+ * 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 getCapabilities(cameraId) {
+    if (isMobile()) {
+        return await core.invoke('plugin:camera-kessdev|get_capabilities', { cameraId });
+    }
+    return desktopCapabilities(cameraId);
+}
 // ---------------------------------------------------------------------------
 // Video recording
 // ---------------------------------------------------------------------------
@@ -228,14 +319,15 @@ async function startRecording(options) {
     }
 }
 /** Stops video recording and returns the recorded media. */
-async function stopRecording() {
+async function stopRecording(options) {
     if (isMobile()) {
-        return await core.invoke('plugin:camera-kessdev|stop_recording');
+        return await core.invoke('plugin:camera-kessdev|stop_recording', { ...options });
     }
     if (!mediaRecorder) {
         throw new Error('Recording is not active. Call startRecording() first.');
     }
     const duration = (performance.now() - recordingStartedAt) / 1000;
+    const thumbnail = options?.thumbnail ? captureDesktopThumbnail() : undefined;
     stopProgressTimer();
     return await new Promise((resolve, reject) => {
         mediaRecorder.onstop = () => {
@@ -245,23 +337,48 @@ async function stopRecording() {
             recordedChunks = [];
             recordedBytes = 0;
             mediaRecorder = null;
-            resolve({ duration, blob, url });
+            const result = { duration, blob, url };
+            if (thumbnail)
+                result.thumbnail = thumbnail;
+            resolve(result);
         };
         mediaRecorder.onerror = () => reject(new Error('Video recording failed.'));
         mediaRecorder.stop();
     });
 }
+/** Captures the current desktop preview frame as a base64 JPEG thumbnail. */
+function captureDesktopThumbnail() {
+    if (!activeVideo || !activeVideo.videoWidth || !activeVideo.videoHeight) {
+        return undefined;
+    }
+    try {
+        const canvas = document.createElement('canvas');
+        canvas.width = activeVideo.videoWidth;
+        canvas.height = activeVideo.videoHeight;
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return undefined;
+        ctx.drawImage(activeVideo, 0, 0, canvas.width, canvas.height);
+        return canvas.toDataURL('image/jpeg');
+    }
+    catch {
+        return undefined;
+    }
+}
 // ---------------------------------------------------------------------------
 // Gallery
 // ---------------------------------------------------------------------------
 /**
- * Saves a captured image to the device photo gallery (mobile).
+ * Saves a captured photo or video to the device gallery (mobile).
+ *
+ * The media type is inferred from the file extension; pass `options.type` to
+ * force it. On desktop this is not supported.
  *
- * @param path Absolute path to the image file.
+ * @param path Absolute path to the media file.
  */
-async function saveToGallery(path) {
+async function saveToGallery(path, options) {
     if (isMobile()) {
-        await core.invoke('plugin:camera-kessdev|save_to_gallery', { path });
+        await core.invoke('plugin:camera-kessdev|save_to_gallery', { path, ...options });
         return;
     }
     throw new Error('saveToGallery is not supported on desktop.');
@@ -312,7 +429,10 @@ 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.openAppSettings = openAppSettings;
 exports.requestPermissions = requestPermissions;
 exports.saveToGallery = saveToGallery;

package/dist-js/index.d.ts

@@ -34,6 +34,49 @@ export interface Video {
     blob?: Blob;
     /** Object URL for the recorded video (desktop). */
     url?: string;
+    /** Optional base64-encoded thumbnail, when requested via `stopRecording`. */
+    thumbnail?: string;
+}
+/** Supported zoom range of a camera (declarative, without the live value). */
+export interface ZoomRange {
+    min: number;
+    max: 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 & {});
+/** 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[];
+    photoFormats?: string[];
+    supportsPause: boolean;
 }
 /**
  * Live telemetry emitted while a video recording is in progress.
@@ -54,6 +97,14 @@ export interface StartRecordingOptions {
     /** Receives live recording telemetry while the recording is active. */
     onProgress?: Channel<RecordingProgress>;
 }
+export interface StopRecordingOptions {
+    /** When true, the result includes a base64-encoded `thumbnail`. */
+    thumbnail?: boolean;
+}
+export interface SaveToGalleryOptions {
+    /** Force the media type instead of inferring it from the file. */
+    type?: 'image' | 'video';
+}
 /**
  * Starts the camera preview.
  *
@@ -85,16 +136,37 @@ export declare function flipCamera(): Promise<void>;
 export declare function setFlash(mode: FlashMode): Promise<void>;
 /** Sets the camera zoom factor (mobile). */
 export declare function setZoom(factor: number): Promise<void>;
+/** Gets the current camera zoom factor (mobile). */
+export declare function getZoom(): Promise<number>;
+/**
+ * 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.
+ *
+ * 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 getCapabilities(cameraId?: string): Promise<CameraCapabilities>;
 /** Starts video recording (with audio). */
 export declare function startRecording(options?: StartRecordingOptions): Promise<void>;
 /** Stops video recording and returns the recorded media. */
-export declare function stopRecording(): Promise<Video>;
+export declare function stopRecording(options?: StopRecordingOptions): Promise<Video>;
 /**
- * Saves a captured image to the device photo gallery (mobile).
+ * Saves a captured photo or video to the device gallery (mobile).
+ *
+ * The media type is inferred from the file extension; pass `options.type` to
+ * force it. On desktop this is not supported.
  *
- * @param path Absolute path to the image file.
+ * @param path Absolute path to the media file.
  */
-export declare function saveToGallery(path: string): Promise<void>;
+export declare function saveToGallery(path: string, options?: SaveToGalleryOptions): Promise<void>;
 /** Gets the current camera permission state. */
 export declare function checkPermissions(): Promise<PermissionState>;
 /** Requests camera permission. */

package/dist-js/index.js

@@ -180,6 +180,97 @@ async function setZoom(factor) {
     }
     throw new Error('setZoom is not supported on desktop.');
 }
+/** Gets the current camera zoom factor (mobile). */
+async function getZoom() {
+    if (isMobile()) {
+        return await invoke('plugin:camera-kessdev|get_zoom');
+    }
+    throw new Error('getZoom is not supported on desktop.');
+}
+// ---------------------------------------------------------------------------
+// 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_available_cameras');
+    }
+    return enumerateDesktopCameras();
+}
+/**
+ * Returns the declarative capabilities of a camera.
+ *
+ * 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 getCapabilities(cameraId) {
+    if (isMobile()) {
+        return await invoke('plugin:camera-kessdev|get_capabilities', { cameraId });
+    }
+    return desktopCapabilities(cameraId);
+}
 // ---------------------------------------------------------------------------
 // Video recording
 // ---------------------------------------------------------------------------
@@ -227,14 +318,15 @@ async function startRecording(options) {
     }
 }
 /** Stops video recording and returns the recorded media. */
-async function stopRecording() {
+async function stopRecording(options) {
     if (isMobile()) {
-        return await invoke('plugin:camera-kessdev|stop_recording');
+        return await invoke('plugin:camera-kessdev|stop_recording', { ...options });
     }
     if (!mediaRecorder) {
         throw new Error('Recording is not active. Call startRecording() first.');
     }
     const duration = (performance.now() - recordingStartedAt) / 1000;
+    const thumbnail = options?.thumbnail ? captureDesktopThumbnail() : undefined;
     stopProgressTimer();
     return await new Promise((resolve, reject) => {
         mediaRecorder.onstop = () => {
@@ -244,23 +336,48 @@ async function stopRecording() {
             recordedChunks = [];
             recordedBytes = 0;
             mediaRecorder = null;
-            resolve({ duration, blob, url });
+            const result = { duration, blob, url };
+            if (thumbnail)
+                result.thumbnail = thumbnail;
+            resolve(result);
         };
         mediaRecorder.onerror = () => reject(new Error('Video recording failed.'));
         mediaRecorder.stop();
     });
 }
+/** Captures the current desktop preview frame as a base64 JPEG thumbnail. */
+function captureDesktopThumbnail() {
+    if (!activeVideo || !activeVideo.videoWidth || !activeVideo.videoHeight) {
+        return undefined;
+    }
+    try {
+        const canvas = document.createElement('canvas');
+        canvas.width = activeVideo.videoWidth;
+        canvas.height = activeVideo.videoHeight;
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return undefined;
+        ctx.drawImage(activeVideo, 0, 0, canvas.width, canvas.height);
+        return canvas.toDataURL('image/jpeg');
+    }
+    catch {
+        return undefined;
+    }
+}
 // ---------------------------------------------------------------------------
 // Gallery
 // ---------------------------------------------------------------------------
 /**
- * Saves a captured image to the device photo gallery (mobile).
+ * Saves a captured photo or video to the device gallery (mobile).
+ *
+ * The media type is inferred from the file extension; pass `options.type` to
+ * force it. On desktop this is not supported.
  *
- * @param path Absolute path to the image file.
+ * @param path Absolute path to the media file.
  */
-async function saveToGallery(path) {
+async function saveToGallery(path, options) {
     if (isMobile()) {
-        await invoke('plugin:camera-kessdev|save_to_gallery', { path });
+        await invoke('plugin:camera-kessdev|save_to_gallery', { path, ...options });
         return;
     }
     throw new Error('saveToGallery is not supported on desktop.');
@@ -304,4 +421,4 @@ async function openAppSettings() {
     throw new Error('openAppSettings is not supported on desktop.');
 }
 
-export { capture, checkPermissions, flipCamera, getPreviewStream, openAppSettings, requestPermissions, saveToGallery, setFlash, setZoom, startPreview, startRecording, stopPreview, stopRecording };
+export { capture, checkPermissions, flipCamera, getAvailableCameras, getCapabilities, getPreviewStream, getZoom, openAppSettings, requestPermissions, saveToGallery, setFlash, setZoom, startPreview, startRecording, stopPreview, stopRecording };

package/package.json

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