Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changes/add-camera-controls.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
"tauri-plugin-camera-kessdev": "minor"
"tauri-plugin-camera-kessdev-js": "minor"
---

Add fine camera controls: torch (continuous light), tap-to-focus and focus mode,
exposure compensation and mode, and white balance (mode + Kelvin temperature).
Extend `getCapabilities()` with `exposureRange`, `exposureModes` and
`whiteBalanceModes`.
8 changes: 8 additions & 0 deletions .changes/add-camera-lens-selection.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
"tauri-plugin-camera-kessdev": "minor"
"tauri-plugin-camera-kessdev-js": "minor"
---

Add `startPreview({ cameraId })` to open the preview with a specific camera/lens
(id from `getAvailableCameras()`); `cameraId` takes precedence over `camera`
(front/back).
8 changes: 8 additions & 0 deletions .changes/add-capture-config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
"tauri-plugin-camera-kessdev": "minor"
"tauri-plugin-camera-kessdev-js": "minor"
---

Add capture configuration: `capture({ resolution, aspectRatio, format, quality })`
and `startRecording({ quality, fps, bitrate })`. Extend `getCapabilities()` with
`photoResolutions`, `photoAspects`, `videoQualities` and `videoFps`.
157 changes: 149 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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" }
```
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -135,6 +137,7 @@ import {
saveToGallery,
checkPermissions,
requestPermissions,
openAppSettings,
getPreviewStream,
convertFileSrc
} from 'tauri-plugin-camera-kessdev'
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -240,6 +261,31 @@ 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
Expand All @@ -252,7 +298,8 @@ const cameras = await getAvailableCameras()
// 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 }
// exposureRange?, exposureModes?, whiteBalanceModes?, supportsWhiteBalanceTemperature?,
// photoResolutions?, photoAspects?, videoQualities?, videoFps?, photoFormats?, supportsPause }
```

The plugin follows one rule to avoid ambiguity:
Expand Down Expand Up @@ -282,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
Expand All @@ -305,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

Expand Down Expand Up @@ -417,6 +467,12 @@ destination from the generated Xcode project (`src-tauri/gen/apple`).
| `setFlash(mode)` | ✓ | ✗ (throws) |
| `setZoom(factor)` | ✓ | ✗ (throws) |
| `getZoom()` | ✓ | ✗ (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` |
Expand All @@ -428,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' }
```
96 changes: 96 additions & 0 deletions android/src/main/java/CameraMath.kt
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
package app.tauri.camera

import kotlin.math.ln
import kotlin.math.pow

/**
* Pure helpers for camera control logic. Kept free of Android framework
* dependencies so they can be unit-tested with plain JUnit.
Expand Down Expand Up @@ -71,6 +74,99 @@ internal object CameraMath {
fun toEquivalentFocalLength(focalMm: Float, sensorWidthMm: Float): Float? =
if (focalMm > 0f && sensorWidthMm > 0f) focalMm * 36f / sensorWidthMm else null

/**
* Resolves a requested camera id against the available ids. Returns null when no
* id was requested, the id when present, or throws when it is not available.
*/
fun resolveCameraId(availableIds: List<String>, requested: String?): String? {
if (requested == null) return null
if (requested in availableIds) return requested
throw IllegalArgumentException("No camera available for cameraId: $requested")
}

/** CameraMetadata CONTROL_AWB_MODE_* values. */
const val AWB_MODE_OFF = 0
const val AWB_MODE_AUTO = 1

/** CameraMetadata COLOR_CORRECTION_MODE_TRANSFORM_MATRIX. */
const val COLOR_CORRECTION_MODE_TRANSFORM_MATRIX = 1

/** Maps the plugin focus mode to a CameraMetadata CONTROL_AF_MODE_* value. */
fun afModeFromFocusMode(mode: String?): Int = when (mode) {
"auto" -> AF_MODE_AUTO
"continuous" -> AF_MODE_CONTINUOUS_PICTURE
else -> AF_MODE_OFF
}

/** Maps the plugin white balance mode to a CameraMetadata CONTROL_AWB_MODE_* value. */
fun awbModeFromString(mode: String?): Int = when (mode) {
"auto" -> AWB_MODE_AUTO
else -> AWB_MODE_OFF
}

/** Converts an EV value to the Camera2 AE compensation index, clamped to the range. */
fun evToCompensationIndex(ev: Double, step: Double, minIndex: Int, maxIndex: Int): Int {
if (step <= 0.0) return 0
return Math.round(ev / step).toInt().coerceIn(minIndex, maxIndex)
}

/**
* Approximate Rggb channel gains (red, greenEven, greenOdd, blue) for a color
* temperature in Kelvin, normalized so the green gain is 1. Best-effort.
*/
fun awbGainsFromKelvin(kelvin: Int): FloatArray {
val t = kelvin.coerceIn(1000, 40000) / 100.0
val r: Double
val g: Double
if (t <= 66.0) {
r = 255.0
g = 99.4708025861 * ln(t) - 161.1195681661
} else {
r = 329.698727446 * (t - 60.0).pow(-0.1332047592)
g = 288.1221695283 * (t - 60.0).pow(-0.0755148492)
}
val b: Double = when {
t >= 66.0 -> 255.0
t <= 19.0 -> 0.0
else -> 138.5177312231 * ln(t - 10.0) - 305.0447927307
}
val rr = r.coerceIn(1.0, 255.0)
val gg = g.coerceIn(1.0, 255.0)
val bb = b.coerceIn(1.0, 255.0)
return floatArrayOf((rr / gg).toFloat(), 1f, 1f, (bb / gg).toFloat())
}

/** Whether manual AWB gains are supported (`CONTROL_AWB_MODE_OFF` available). */
fun supportsManualAwb(availableModes: IntArray?): Boolean =
availableModes != null && availableModes.contains(AWB_MODE_OFF)

/** Parses an aspect ratio like "4:3" into a (width, height) pair, or null. */
fun parseAspectRatio(value: String?): Pair<Int, Int>? {
val parts = value?.split(":") ?: return null
if (parts.size != 2) return null
val w = parts[0].trim().toIntOrNull() ?: return null
val h = parts[1].trim().toIntOrNull() ?: return null
return if (w > 0 && h > 0) Pair(w, h) else null
}

/** Normalizes a video quality name; unknown values default to "hd". */
fun videoQualityName(value: String?): String = when (value) {
"sd", "hd", "fhd", "uhd" -> value
else -> "hd"
}

/** Greatest common divisor, used to reduce an aspect ratio. */
fun gcd(a: Int, b: Int): Int {
var x = kotlin.math.abs(a)
var y = kotlin.math.abs(b)
while (y != 0) {
val t = y
y = x % y
x = t
}
return if (x == 0) 1 else x
}

private val VIDEO_EXTENSIONS = setOf("mp4", "mov", "m4v", "webm", "3gp", "mkv")

/** Infers the media kind ("image" | "video") from the path, honoring an override. */
Expand Down
Loading
Loading