Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Lalu gunakan prompt berikut:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/camera-preview` plugin in my project.

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

bun add @capgo/camera-preview
bunx cap sync

Impor

import { CameraPreview } from '@capgo/camera-preview';

Mulai cepat

Jalankan preview kamera belakang di balik UI Anda, ambil foto, lalu hentikan untuk melepas kamera.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.start({
  position: 'rear',
  parent: 'cameraPreview',
  toBack: true,
});

const { value } = await CameraPreview.capture({ quality: 90 });
console.log('Photo base64', value);

await CameraPreview.stop();

Pasang elemen full-screen dengan id="cameraPreview" di HTML Anda, dan buat background route atau app menjadi transparan agar native preview di balik WebView terlihat (misalnya ion-content { --background: transparent; } pada rute Ionic).

Contoh: overlay barcode

await CameraPreview.start({ position: 'rear', toBack: true });

await CameraPreview.startBarcodeScanner({
  formats: ['qr_code', 'code_128'],
  detectionInterval: 400,
});

let handled = false;
const barcodeListener = await CameraPreview.addListener('barcodeScanned', async (event) => {
  if (handled) return;
  const code = event.barcodes[0]?.value;
  if (!code) return;
  handled = true;
  await CameraPreview.stopBarcodeScanner();
  await handleScan(code);
});

// When leaving the screen:
await barcodeListener.remove();

Contoh: flip kamera dan flash

await CameraPreview.flip();
await CameraPreview.setFlashMode({ flashMode: 'torch' });

Kesalahan umum

• Izin: minta izin kamera (dan mikrofon jika merekam video) sebelum start.
• Lifecycle: panggil stop() saat meninggalkan rute atau layar berikutnya bisa gagal membuka kamera.
• Web: cek API yang didukung di README plugin sebelum mengandalkan preview di browser mobile.

Ringkasan API

start

Memulai camera preview.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.start({ parent: 'parent' });
console.log(result);

stop

Menghentikan camera preview.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.stop();

capture

Mengambil foto dari kamera.

Jika storeToFile diatur ke true saat memulai preview, hasil yang dikembalikan value akan berupa path file absolut di perangkat, bukan string base64. Gunakan getBase64FromFilePath untuk mendapatkan string base64 dari path file tersebut.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.capture({ height: 1920 });
console.log(result);

captureSample

Mengambil satu frame dari stream camera preview.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.captureSample({
  quality: 85,
  mirrorFrontCamera: false,
});
console.log(result);

getSupportedFlashModes

Mendapatkan mode flash yang didukung oleh kamera aktif.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getSupportedFlashModes();
console.log(result);

setAspectRatio

Mengatur aspect ratio camera preview.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setAspectRatio({} as { aspectRatio: '4:3' | '16:9'; x?: number; y?: number });

getAspectRatio

Mendapatkan aspect ratio camera preview saat ini.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getAspectRatio();
console.log(result);

setGridMode

Mengatur mode grid pada overlay camera preview.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setGridMode({ gridMode: 'none' });

getGridMode

Mendapatkan mode grid overlay camera preview saat ini.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getGridMode();
console.log(result);

checkPermissions

Mengecek status izin kamera (dan mikrofon, opsional) saat ini tanpa memunculkan dialog sistem.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.checkPermissions();
// The result holds sensitive values: use it without logging it.

requestPermissions

Meminta izin kamera (dan mikrofon, opsional). Jika izin sudah diberikan atau ditolak, status saat ini dikembalikan tanpa prompt. Jika showSettingsAlert bernilai true dan izin ditolak, alert khusus platform akan ditampilkan untuk mengarahkan pengguna ke pengaturan aplikasi.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.requestPermissions();
// The result holds sensitive values: use it without logging it.

getHorizontalFov

Mendapatkan field of view horizontal untuk kamera yang aktif. Catatan: Nilainya bisa hanya perkiraan di beberapa perangkat.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getHorizontalFov();
console.log(result);

getSupportedPictureSizes

Mendapatkan ukuran foto yang didukung untuk semua kamera.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getSupportedPictureSizes();
console.log(result);

setFlashMode

Mengatur mode flash untuk kamera yang aktif.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setFlashMode({ flashMode: 'off' });

flip

Beralih antara kamera depan dan belakang.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.flip();

setOpacity

Mengatur opasitas preview kamera.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setOpacity({ opacity: 1.0 });

stopRecordVideo

Menghentikan rekaman video yang sedang berjalan.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.stopRecordVideo();
console.log(result);

startRecordVideo

Memulai rekaman video.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.startRecordVideo({ parent: 'parent' });

isRunning

Memeriksa apakah preview kamera sedang berjalan.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.isRunning();
console.log(result);

getAvailableDevices

Mengambil semua perangkat kamera yang tersedia.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getAvailableDevices();
console.log(result);

getZoom

Mendapatkan status zoom saat ini, termasuk min/max dan info lensa saat ini.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getZoom();
console.log(result);

getZoomButtonValues

Mengembalikan nilai tombol zoom untuk perpindahan cepat.

• iOS/Android: menyertakan 0.5 jika ultra-wide tersedia; 1 dan 2 jika wide tersedia; 3 jika telephoto tersedia
• Web: tidak didukung

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getZoomButtonValues();
console.log(result);

setZoom

Mengatur level zoom kamera.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setZoom({ level: 1 });

getFlashMode

Mendapatkan mode flash saat ini.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getFlashMode();
console.log(result);

setDeviceId

Mengalihkan kamera aktif ke kamera dengan spesifikasi tertentu deviceId.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setDeviceId({ deviceId: 'device-id-123' });

getDeviceId

Mendapatkan ID perangkat kamera yang sedang terikat. Di Android, jika permintaan lensa fisik fallback ke kamera logis, ini mengembalikan ID kamera logis yang terikat.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getDeviceId();
console.log(result);

getPreviewSize

Mendapatkan ukuran dan posisi preview saat ini.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getPreviewSize();
console.log(result);

setPreviewSize

Mengatur ukuran dan posisi preview.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.setPreviewSize({
  width: 1080,
  height: 1920,
});
console.log(result);

setFocus

Mengatur fokus kamera ke titik tertentu pada preview.

Catatan: Plugin ini tidak menyertakan handler gesture tap-to-focus native. Tangani tap di HTML/JS Anda (misalnya, pada UI overlay), lalu kirimkan koordinat yang sudah dinormalisasi ke sini.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setFocus({
  x: 1,
  y: 1,
});

deleteFile

Menghapus file pada path absolut tertentu di perangkat. Gunakan ini untuk membersihkan gambar sementara yang dibuat dengan storeToFile. Di web, fitur ini tidak didukung dan akan memunculkan error.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.deleteFile({ path: 'path/to/file' });
console.log(result);

getSafeAreaInsets

Mendapatkan safe area insets untuk perangkat. Mengembalikan inset notch/cutout kamera sesuai orientasi dan orientasi saat ini. Dalam mode portrait: mengembalikan top inset (notch di atas). Dalam mode landscape: mengembalikan left inset (notch di samping). Ini secara khusus menargetkan area cutout (notch, punch hole, dll.) yang ada di semua ponsel modern.

Android: Nilai dikembalikan dalam dp (logical pixels). iOS: Nilai dikembalikan dalam physical pixels, tidak termasuk status bar (hanya ukuran notch/cutout murni).

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getSafeAreaInsets();
console.log(result);

getOrientation

Mendapatkan orientasi perangkat saat ini dalam format cross-platform.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getOrientation();
console.log(result);

getExposureModes

Mengembalikan mode exposure yang didukung oleh kamera yang aktif. Mode dapat berupa: ‘locked’, ‘auto’, ‘continuous’, ‘custom’.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getExposureModes();
console.log(result);

getExposureMode

Mengembalikan mode exposure saat ini.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getExposureMode();
console.log(result);

setExposureMode

Mengatur mode exposure.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setExposureMode({ mode: 'AUTO' });

getExposureCompensationRange

Mengembalikan rentang kompensasi eksposur (EV bias) yang didukung.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getExposureCompensationRange();
console.log(result);

getExposureCompensation

Mengembalikan kompensasi eksposur (EV bias) saat ini.

import { CameraPreview } from '@capgo/camera-preview';

const result = await CameraPreview.getExposureCompensation();
console.log(result);

setExposureCompensation

Mengatur kompensasi eksposur (EV bias). Nilai akan dibatasi sesuai rentang.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setExposureCompensation({ value: 1 });

Referensi Tipe

CameraPreviewOptions

Menentukan opsi konfigurasi untuk memulai camera preview.

export interface CameraPreviewOptions {
  /**
   * The parent element to attach the video preview to.
   * @platform web
   */
  parent?: string;
  /**
   * A CSS class name to add to the preview element.
   * @platform web
   */
  className?: string;
  /**
   * The width of the preview in pixels. Defaults to the screen width.
   * @platform android, ios, web
   */
  width?: number;
  /**
   * The height of the preview in pixels. Defaults to the screen height.
   * @platform android, ios, web
   */
  height?: number;
  /**
   * The horizontal origin of the preview, in pixels.
   * @platform android, ios
   */
  x?: number;
  /**
   * The vertical origin of the preview, in pixels.
   * @platform android, ios
   */
  y?: number;
  /**
   * The aspect ratio of the camera preview, '4:3' or '16:9' or 'fill'.
   * Cannot be set if width or height is provided, otherwise the call will be rejected.
   * Use setPreviewSize to adjust size after starting.
   *
   * @since 2.0.0
   */
  aspectRatio?: '4:3' | '16:9';
  /**
   * Controls how the camera preview fills the available space.
   * - 'contain': Fits the entire preview within the space, may show letterboxing (default).
   * - 'cover': Fills the entire space, may crop edges of the preview.
   * @default "contain"
   * @platform android, ios, web
   */
  aspectMode?: 'cover' | 'contain';
  /**
   * The grid overlay to display on the camera preview.
   * @default "none"
   * @since 2.1.0
   */
  gridMode?: GridMode;
  /**
   * Adjusts the y-position to account for safe areas (e.g., notches).
   * @platform ios
   * @default false
   */
  includeSafeAreaInsets?: boolean;
  /**
   * If true, places the preview behind the webview.
   * @platform android
   * @default true
   */
  toBack?: boolean;
  /**
   * Bottom padding for the preview, in pixels.
   * @platform android, ios
   */
  paddingBottom?: number;
  /**
   * Whether to rotate the preview when the device orientation changes.
   * @platform ios
   * @default true
   */
  rotateWhenOrientationChanged?: boolean;
  /**
   * The camera to use.
   * @default "rear"
   */
  position?: CameraPosition | string;
  /**
   * If true, saves the captured image to a file and returns the file path.
   * If false, returns a base64 encoded string.
   * @default false
   */
  storeToFile?: boolean;
  /**
   * If true, prevents the plugin from rotating the image based on EXIF data.
   * @platform android
   * @default false
   */
  disableExifHeaderStripping?: boolean;
  /**
   * If true, disables the audio stream, preventing audio permission requests.
   * @default true
   */
  disableAudio?: boolean;
  /**
   * If true, locks the device orientation while the camera is active.
   * @platform android
   * @default false
   */
  lockAndroidOrientation?: boolean;
  /**
   * If true, allows the camera preview's opacity to be changed.
   * @platform android, web
   * @default false
   */
  enableOpacity?: boolean;

  /**
   * If true, disables the visual focus indicator when tapping to focus.
   * @platform android, ios
   * @default false
   */
  disableFocusIndicator?: boolean;
  /**
   * The `deviceId` of the camera to use. If provided, `position` is ignored.
   * @platform ios
   */
  deviceId?: string;
  /**
   * On Android, attempts to bind a physical camera directly when `deviceId` refers to a physical lens.
   * Disabled by default because OEM support is inconsistent; when false, Android keeps the current logical-camera fallback behavior.
   * @default false
   * @platform android
   */
  enablePhysicalDeviceSelection?: boolean;
  /**
   * The initial zoom level when starting the camera preview.
   * If the requested zoom level is not available, the native plugin will reject.
   * @default 1.0
   * @platform android, ios
   * @since 2.2.0
   */
  initialZoomLevel?: number;
  /**
   * The vertical positioning of the camera preview.
   * @default "center"
   * @platform android, ios, web
   * @since 2.3.0
   */
  positioning?: CameraPositioning;
  /**
   * If true, enables video capture capabilities when the camera starts.
   * @default false
   * @platform android
   * @since 7.11.0
   */
  enableVideoMode?: boolean;
  /**
   * If true, forces the camera to start/restart even if it's already running or busy.
   * This will kill the current camera session and start a new one, ignoring all state checks.
   * @default false
   * @platform android, ios, web
   */
  force?: boolean;
  /**
   * Sets the quality of video for recording.
   * Options: 'low', 'medium', 'high'
   * @note On Android requires 'enableVideoMode' to be true
   * @note Will affect the entire preview stream for iOS
   * @platform ios, android
   * @default "high"
   */
  videoQuality?: 'low' | 'medium' | 'high';
}

CameraPreviewPictureOptions

Menentukan opsi untuk mengambil foto.

export interface CameraPreviewPictureOptions {
  /**
   * The maximum height of the picture in pixels. The image will be resized to fit within this height while maintaining aspect ratio.
   * If not specified the captured image will match the preview's visible area.
   */
  height?: number;
  /**
   * The maximum width of the picture in pixels. The image will be resized to fit within this width while maintaining aspect ratio.
   * If not specified the captured image will match the preview's visible area.
   */
  width?: number;
  /**
   * The quality of the captured image, from 0 to 100.
   * Does not apply to `.png` format.
   * @default 85
   */
  quality?: number;
  /**
   * The format of the captured image.
   * @default "jpeg"
   */
  format?: PictureFormat;
  /**
   * If true, the captured image will be saved to the user's gallery.
   * @default false
   * @since 7.5.0
   */
  saveToGallery?: boolean;
  /**
   * If true, the plugin will attempt to add GPS location data to the image's EXIF metadata.
   * This may prompt the user for location permissions.
   * @default false
   * @since 7.6.0
   */
  withExifLocation?: boolean;
  /**
   * If true, the plugin will embed a timestamp in the top-right corner of the image.
   * @default false
   * @since 7.17.0
   */
  embedTimestamp?: boolean;
  /**
   * If true, the plugin will embed the current location in the top-right corner of the image.
   * Requires `withExifLocation` to be enabled.
   * @default false
   * @since 7.18.0
   */
  embedLocation?: boolean;
  /**
   * Sets the priority for photo quality vs. capture speed.
   * - "speed": Prioritizes faster capture times, may reduce image quality.
   * - "balanced": Aims for a balance between quality and speed.
   * - "quality": Prioritizes image quality, may reduce capture speed.
   * See https://developer.apple.com/documentation/avfoundation/avcapturephotosettings/photoqualityprioritization for details.
   *
   * @since 7.21.0
   * @platform ios
   * @default "speed"
   */
  photoQualityPrioritization?: 'speed' | 'balanced' | 'quality';
}

ExifData

Merepresentasikan data EXIF yang diekstrak dari gambar.

export interface ExifData {
  [key: string]: any;
}

CameraSampleOptions

Menentukan opsi untuk mengambil sample frame dari camera preview.

export interface CameraSampleOptions {
  /**
   * The quality of the captured sample, from 0 to 100.
   * @default 85
   */
  quality?: number;
}

CameraPreviewFlashMode

Mode flash yang tersedia untuk kamera. ‘torch’ adalah mode lampu terus-menerus.

export type CameraPreviewFlashMode = 'off' | 'on' | 'auto' | 'torch';

GridMode

export type GridMode = 'none' | '3x3' | '4x4';

PermissionRequestOptions

export interface PermissionRequestOptions {
  disableAudio?: boolean;
  showSettingsAlert?: boolean;
  title?: string;
  message?: string;
  openSettingsButtonTitle?: string;
  cancelButtonTitle?: string;
}

CameraPermissionStatus

export interface CameraPermissionStatus {
  camera: PermissionState;
  microphone?: PermissionState;
}

SupportedPictureSizes

Merepresentasikan ukuran foto yang didukung untuk kamera yang menghadap arah tertentu.

export interface SupportedPictureSizes {
  /** The camera direction ("front" or "rear"). */
  facing: string;
  /** A list of supported picture sizes for this camera. */
  supportedPictureSizes: PictureSize[];
}

CameraOpacityOptions

Menentukan opsi untuk mengatur opacity preview kamera.

export interface CameraOpacityOptions {
  /**
   * The opacity percentage, from 0.0 (fully transparent) to 1.0 (fully opaque).
   * @default 1.0
   */
  opacity?: number;
}

CameraDevice

Mewakili kamera fisik pada perangkat (misalnya, kamera depan).

export interface CameraDevice {
  /** A unique identifier for the camera device. */
  deviceId: string;
  /** A human-readable name for the camera device. */
  label: string;
  /** The physical position of the camera on the device. */
  position: CameraPosition;
  /** A list of all available lenses for this camera device. */
  lenses: CameraLens[];
  /** The overall minimum zoom factor available across all lenses on this device. */
  minZoom: number;
  /** The overall maximum zoom factor available across all lenses on this device. */
  maxZoom: number;
  /** Identifies whether the device is a logical camera (composed of multiple physical lenses). */
  isLogical: boolean;
}

LensInfo

Merepresentasikan informasi detail dari lensa yang sedang aktif.

export interface LensInfo {
  /** The focal length of the active lens in millimeters. */
  focalLength: number;
  /** The device type of the active lens. */
  deviceType: DeviceType;
  /** The base zoom ratio of the active lens (e.g., 0.5x, 1.0x). */
  baseZoomRatio: number;
  /** The current digital zoom factor applied on top of the base zoom. */
  digitalZoom: number;
}

Sumber Kebenaran

Halaman ini dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan perilaku media dan antarmuka native, hubungkan dengan Menggunakan @capgo/camera-preview untuk kapabilitas native saat menggunakan @capgo/camera-preview, Menggunakan @capgo/capacitor-live-activities untuk kemampuan native di Menggunakan @capgo/capacitor-live-activities, @capgo/capacitor-live-activities untuk detail implementasi di @capgo/capacitor-live-activities, Menggunakan @capgo/capacitor-video-player untuk kemampuan native di Menggunakan @capgo/capacitor-video-player, dan @capgo/capacitor-video-player untuk detail implementasi di @capgo/capacitor-video-player.