Skip to content
Capgo - Capacitor 앱의 실시간 업데이트 Capgo

시작하기

GitHub

설치

설치
터미널 창
bun add @capgo/camera-preview
bunx cap sync

Import

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

API 개요

API 개요

start

시작

카메라 프리뷰를 시작합니다.

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 문자열이 아닌 것입니다. getBase64FromFilePath를 사용하여 파일 경로에서 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();

setGridMode

setGridMode

카메라 프리뷰 오버레이의 격자 모드 설정

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


await CameraPreview.setGridMode({} as { gridMode: GridMode });

getGridMode

getGridMode

카메라 프리뷰 오버레이의 현재 격자 모드 가져오기

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


await CameraPreview.getGridMode();

checkPermissions

권한 확인

클립보드 복사

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


await CameraPreview.checkPermissions();

requestPermissions

클립보드 복사

권한이 거부된 경우 사용자에게 앱 설정으로 안내하는 플랫폼별 알림이 표시됩니다. showSettingsAlert 클립보드 복사

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


await CameraPreview.requestPermissions();

getHorizontalFov

__CAPGO_KEEP_1__

__CAPGO_KEEP_2__

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


await CameraPreview.getHorizontalFov();

getSupportedPictureSizes

__CAPGO_KEEP_3__

__CAPGO_KEEP_4__

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


await CameraPreview.getSupportedPictureSizes();

setFlashMode

__CAPGO_KEEP_5__

__CAPGO_KEEP_6__

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


await CameraPreview.setFlashMode({} as { flashMode: CameraPreviewFlashMode | string });

flip

__CAPGO_KEEP_7__

__CAPGO_KEEP_8__

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


await CameraPreview.flip();

setOpacity

__CAPGO_KEEP_1__

__CAPGO_KEEP_2__

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


await CameraPreview.setOpacity({} as CameraOpacityOptions);

stopRecordVideo

__CAPGO_KEEP_1__

__CAPGO_KEEP_3__

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


await CameraPreview.stopRecordVideo();

startRecordVideo

__CAPGO_KEEP_1__

__CAPGO_KEEP_4__

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


await CameraPreview.startRecordVideo({} as CameraPreviewOptions);

isRunning

__CAPGO_KEEP_1__

__CAPGO_KEEP_5__

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


await CameraPreview.isRunning();

getAvailableDevices

getAvailableDevices

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

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


await CameraPreview.getAvailableDevices();

getZoom

getZoom

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

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

getFlashMode

플래시 모드 가져오기

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

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


await CameraPreview.getFlashMode();

setDeviceId

디바이스 ID 설정

지정된 디바이스 ID를 가진 카메라를 활성화합니다. deviceId.

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


await CameraPreview.setDeviceId({} as { deviceId: string });

getDeviceId

디바이스 ID 가져오기

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

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

setFocus

setFocus 섹션 제목

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

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

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


await CameraPreview.setFocus({} as { x: number; y: number });

deleteFile

deleteFile 섹션 제목

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

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


await CameraPreview.deleteFile({} as { path: string });

getSafeAreaInsets

‘getSafeAreaInsets’라는 제목의 섹션

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

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

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


await CameraPreview.getSafeAreaInsets();

getOrientation

‘getOrientation’라는 제목의 섹션

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

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


await CameraPreview.getOrientation();

getExposureModes

‘getExposureModes’라는 제목의 섹션

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

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


await CameraPreview.getExposureModes();

getExposureMode

getExposureMode 섹션 제목

현재 노출 모드를 반환합니다.

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


await CameraPreview.getExposureMode();

setExposureMode

setExposureMode 섹션 제목

노출 모드를 설정합니다.

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


await CameraPreview.setExposureMode({} as { mode: ExposureMode });

getExposureCompensationRange

getExposureCompensationRange 섹션 제목

노출 보상 범위 (EV 편차)를 반환합니다.

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


await CameraPreview.getExposureCompensationRange();

getExposureCompensation

getExposureCompensation 섹션 제목

현재 노출 보상 (EV 편차)를 반환합니다.

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


await CameraPreview.getExposureCompensation();

setExposureCompensation

Section titled “노출 보상”

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

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


await CameraPreview.setExposureCompensation({} as { value: number });

타입 참조

Section titled “타입 참조”

CameraPreviewOptions

Section titled “카메라 미리보기 옵션”

카메라 미리보기 시작을 위한 구성 옵션을 정의합니다.

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

Section titled “사진 촬영 옵션”

사진 촬영을 위한 옵션을 정의합니다.

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

Section titled “EXIF 데이터”

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

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

CameraSampleOptions

카메라 샘플 옵션 섹션 제목 ‘CameraSampleOptions’

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

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

CameraPreviewFlashMode

카메라 프리뷰 플래시 모드 섹션 제목 ‘CameraPreviewFlashMode’

카메라의 사용 가능한 플래시 모드입니다. ‘torch’는 연속적인 빛 모드입니다.

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

GridMode

그리드 모드 섹션 제목 ‘GridMode’
export type GridMode = 'none' | '3x3' | '4x4';

PermissionRequestOptions

권한 요청 옵션 섹션 제목 ‘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

지원하는 사진 크기

특정 방향을 향한 카메라에 대한 사진 크기입니다.

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

CameraOpacityOptions

카메라预览 불투명도 옵션

카메라 프리뷰 불투명도 설정 옵션입니다.

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

LensInfo

렌즈 정보

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

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를 재생성합니다. upstream의 공공 API이 변경될 때 다시 동기화하십시오.

Getting Started에서 계속하기

'Getting Started에서 계속하기'라는 제목의 섹션

native media 및 인터페이스 동작을 계획하고 있는 경우 Getting Started 를 사용하여 연결하십시오. @capgo/camera-preview를 사용하여 capgo의 원생 기능을 사용하는 방법 capgo의 capacitor-라이브-활동을 사용하는 방법 for the native capability in Using @capgo/capacitor-live-activities, capgo의 capacitor-라이브-활동 capgo의 capacitor-라이브-활동 구현 세부 사항 capgo의 capacitor-비디오-플레이어를 사용하는 방법 for the native capability in Using @capgo/capacitor-video-player, and capgo의 capacitor-비디오-플레이어 capgo의 capacitor-비디오-플레이어 구현 세부 사항