내용으로 건너뛰기

시작하기

터미널 창
bun add @capgo/camera-preview
bunx cap sync
import { CameraPreview } from '@capgo/camera-preview';

카메라 미리보기 시작합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.start({} as CameraPreviewOptions);

stop

정지

카메라 미리보기 중지합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.stop();

capture

촬영

카메라에서 사진을 캡처합니다.

만약 storeToFile 시작할 때 true 미리보기로 설정된 경우, 반환된 value 디바이스의 절대 파일 경로 대신 base64 문자열이 아닌

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.capture({} as CameraPreviewPictureOptions);

captureSample

captureSample

카메라 프리뷰 스트림에서 단일 프레임을 캡처합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.captureSample({} as CameraSampleOptions);

getSupportedFlashModes

getSupportedFlashModes

활성 카메라에서 지원하는 플래시 모드 가져오기

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getSupportedFlashModes();

setAspectRatio

setAspectRatio

카메라 프리뷰의 비율을 설정합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.setAspectRatio({} as { aspectRatio: '4:3' | '16:9'; x?: number; y?: number });

getAspectRatio

getAspectRatio

현재 카메라 프리뷰의 비율을 가져옵니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getAspectRatio();

카메라 프리뷰-overlay의 격자 모드 설정

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.setGridMode({} as { gridMode: GridMode });

카메라 프리뷰-overlay의 현재 격자 모드 가져오기

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getGridMode();

시스템 대화 프롬프트 없이 카메라 (및 선택적으로 마이크) 권한 상태를 확인합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.checkPermissions();

카메라 (선택적으로 마이크) 권한을 요청합니다. 권한이 이미 허용되거나 거부된 경우, 현재 상태가 반환됩니다. 권한이 거부된 경우, true 인 경우 플랫폼에 따라 사용자에게 앱 설정으로 안내하는 알림이 표시됩니다. showSettingsAlert Section titled “setGridMode”_copy_to_clipboard_button

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.requestPermissions();

활성 카메라의 수평 시야각을 가져옵니다. 주의: 일부 기기에서는 추정치일 수 있습니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getHorizontalFov();

모든 카메라의 지원하는 사진 크기를 가져옵니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getSupportedPictureSizes();

활성 카메라의闪光 모드를 설정합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.setFlashMode({} as { flashMode: CameraPreviewFlashMode | string });

앞과 뒤의 카메라를 전환합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.flip();

__CAPGO_KEEP_2__

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.setOpacity({} as CameraOpacityOptions);

stopRecordVideo

__CAPGO_KEEP_3__

__CAPGO_KEEP_4__

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.stopRecordVideo();

startRecordVideo

__CAPGO_KEEP_5__

__CAPGO_KEEP_0__

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.startRecordVideo({} as CameraPreviewOptions);

__CAPGO_KEEP_7__

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.isRunning();

getAvailableDevices

getAvailableDevices 섹션

모든 사용 가능한 카메라 장치를 가져옵니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getAvailableDevices();

현재 줌 상태를 가져옵니다. (최소/최대 및 현재 렌즈 정보 포함)

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getZoom();

getZoomButtonValues

getZoomButtonValues 섹션

빠른 Switching을 위한 줌 버튼 값을 반환합니다.

  • iOS/Android: 초광각이 사용 가능하면 0.5; 광각이 사용 가능하면 1과 2; 망원경이 사용 가능하면 3
  • Web: 지원되지 않음
import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getZoomButtonValues();

setZoom

줌 설정

카메라의 줌 레벨을 설정합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.setZoom({} as { level: number; ramp?: boolean; autoFocus?: boolean });

현재 플래시 모드를 가져옵니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getFlashMode();

사용 중인 카메라를 지정된 디바이스로 전환합니다. deviceId.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.setDeviceId({} as { deviceId: string });

현재 바인드된 카메라 디바이스의 아이디를 가져옵니다. 안드로이드에서 물리 렌즈 요청이 논리 카메라로 전환되는 경우 이 메소드는 바인드된 논리 카메라 아이디를 반환합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getDeviceId();

getPreviewSize

getPreviewSize 섹션

현재 미리보기 크기와 위치를 가져옵니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getPreviewSize();

setPreviewSize

setPreviewSize 섹션

미리보기 크기와 위치를 설정합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.setPreviewSize({} as { x?: number; y?: number; width: number; height: number });

미리보기에서 특정 위치에 카메라 초점을 설정합니다.

주의: 플러그인은 native tap-to-focus 제스처 핸들러를 첨부하지 않습니다. HTML/JS (예: overlaying UI)에 탭을 처리한 후 normalized 좌표를 여기에 전달하세요.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.setFocus({} as { x: number; y: number });

장치의 절대 경로에 있는 파일을 삭제합니다. 임시로 생성된 이미지와 같은 임시 파일을 빠르게 삭제하려면 이 메서드를 사용하세요. storeToFile. 웹에서는 지원되지 않으며 오류를 발생시킵니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.deleteFile({} as { path: string });

디바이스의 안전 영역 인셋을 가져옵니다. 디바이스의 방향에 따라 notch/camera cutout 인셋과 현재 방향을 반환합니다. 포트레이트 모드: 상단 인셋 (상단 notch)을 반환합니다. 랜스케이프 모드: 왼쪽 인셋 (쪽으로 이동한 notch)을 반환합니다. 모든 현대 전화기에 있는 cutout 영역 (notch, punch hole, etc.)을 특정합니다.

Android: dp (논리적 픽셀)에서 반환됩니다. iOS: 물리 픽셀에서 반환되며 상태바를 제외한 notch/cutout 크기만을 포함합니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getSafeAreaInsets();

디바이스의 현재 방향을 크로스 플랫폼 형식으로 가져옵니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getOrientation();

활성 카메라에서 지원하는 노출 모드를 반환합니다. 모드에는 ‘locked’, ‘auto’, ‘continuous’, ‘custom’가 포함될 수 있습니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getExposureModes();

getExposureMode

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getExposureMode();

setExposureMode

__CAPGO_KEEP_3__

__CAPGO_KEEP_4__

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.setExposureMode({} as { mode: ExposureMode });

getExposureCompensationRange

__CAPGO_KEEP_6__

__CAPGO_KEEP_7__

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getExposureCompensationRange();

getExposureCompensation

__CAPGO_KEEP_9__

__CAPGO_KEEP_10__

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.getExposureCompensation();

setExposureCompensation

노출 보상 설정

노출 보상 (EV 편차)를 설정합니다. 값은 범위에 따라 클램핑됩니다.

import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.setExposureCompensation({} as { value: number });

타입 참조

타입 참조

CameraPreviewOptions

카메라 프리뷰 옵션

카메라 프리뷰를 시작하기 위한 구성 옵션을 정의합니다.

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

사진 촬영 옵션

사진을 찍기 위한 옵션을 정의합니다.

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';
}

__CAPGO_KEEP_0__을 이미지에서 추출한 EXIF 데이터를 나타냅니다.

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

CameraSampleOptions

__CAPGO_KEEP_0__ 섹션

__CAPGO_KEEP_0__를 사용하여 카메라 프리뷰에서 샘플 프레임을 캡처하는 옵션을 정의합니다.

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

CameraPreviewFlashMode

__CAPGO_KEEP_0__ 섹션

__CAPGO_KEEP_0__를 사용하여 카메라의_FLASH 모드를 정의합니다.

export type CameraPreviewFlashMode = 'off' | 'on' | 'auto' | 'torch';
export type GridMode = 'none' | '3x3' | '4x4';
export interface PermissionRequestOptions {
disableAudio?: boolean;
showSettingsAlert?: boolean;
title?: string;
message?: string;
openSettingsButtonTitle?: string;
cancelButtonTitle?: string;
}

CameraPermissionStatus

카메라 접근 허용 상태
export interface CameraPermissionStatus {
camera: PermissionState;
microphone?: PermissionState;
}

SupportedPictureSizes

카메라 지원 사진 크기

특정 방향으로 향하는 카메라에 대한 사진 크기 지원을 나타냅니다.

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

카메라 프리뷰 불투명도 설정을 위한 옵션을 정의합니다.

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

CameraDevice

카메라 장치

장치 내의 물리적 카메라 (예: 전면 카메라)를 나타냅니다.

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;
}

현재 활성 렌즈의 세부 정보를 나타냅니다.

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;
}

플러그인의 src/definitions.ts공개 API이 업스트림에서 변경될 때 다시 동기화 하십시오.