시작하기

설치

AI 지원 설정으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그다음 아래 prompt를 사용하세요:

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

Manual Setup을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/capacitor-audio-recorder
bunx cap sync

가져오기

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

빠른 시작

마이크 권한을 요청하고, 녹음한 뒤, 중지하여 네이티브 파일 URI(또는 웹 URI)를 읽어옵니다. Blob).

import { Capacitor } from '@capacitor/core';
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

const mic = await CapacitorAudioRecorder.requestPermissions();
if (mic.recordAudio !== 'granted') {
  throw new Error('Microphone permission required');
}

await CapacitorAudioRecorder.startRecording({
  sampleRate: 44100,
  bitRate: 128000,
  resetToPlaybackOnStop: true, // iOS only: restore playback-friendly audio session after stop
});

const { uri, blob, duration } = await CapacitorAudioRecorder.stopRecording();
const clipRef = Capacitor.getPlatform() === 'web' ? blob : uri;
console.log('Saved clip', clipRef, duration);

예제: 일시 정지 기능이 포함된 음성 메모

await CapacitorAudioRecorder.startRecording();
// user taps pause during a long note
await CapacitorAudioRecorder.pauseRecording();
await CapacitorAudioRecorder.resumeRecording();
const clip = await CapacitorAudioRecorder.stopRecording();

pauseRecording 은 Android (API 24+), iOS 및 Web에서 사용할 수 있습니다.

예제: 실시간 레벨 미터

Poll getCurrentAmplitude() 상태가 다음과 같을 때 타이머를 사용하여(약 60~100ms) 폴링(Poll)을 수행합니다. RECORDING값은 정규화되어 있지만, 0 로 1플랫폼마다 기본 신호가 다릅니다(Android는 peak, iOS는 average power, Web은 RMS). 시각적 일관성이 필요하다면 플랫폼별로 약간의 스케일을 조정하세요.

const tick = async () => {
  const { status } = await CapacitorAudioRecorder.getRecordingStatus();
  if (status !== 'RECORDING') return;
  const { value } = await CapacitorAudioRecorder.getCurrentAmplitude();
  updateMeterUi(value);
};

예시: 녹음 취소하기

await CapacitorAudioRecorder.startRecording();
await CapacitorAudioRecorder.cancelRecording(); // no file persisted

자주 하는 실수

• Web과 Native의 반환 형태 차이: Android 및 iOS 반환값 uri 웹 레이어 릴리스를 stopRecording. Web 반환값 blob (및 다음 항목이 생략될 수 있음 uri).
• iOS 녹음 후 무음 재생: 설정 resetToPlaybackOnStop: true 에서 startRecording 사용자가 동일한 세션 내에서 클립을 재생하는 경우.
• 백그라운드 캡처: 이 플러그인이 자동으로 백그라운드 오디오를 활성화하지는 않습니다. iOS에서 화면 잠금 상태로 녹음이 필요하다면 Audio background mode를 추가하세요.
• Amplitude 호출 남발 금지: 각 getCurrentAmplitude 호출은 브릿지를 통과합니다. Tight loop 대신 UI interval을 사용하세요.

API 개요

startRecording

기기 마이크를 사용해 오디오 녹음을 시작합니다.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

await CapacitorAudioRecorder.startRecording();

pauseRecording

진행 중인 녹음을 일시 중지합니다. Android (API 24+), iOS, Web에서만 사용할 수 있습니다.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

await CapacitorAudioRecorder.pauseRecording();

resumeRecording

일시 중지된 녹음을 다시 시작합니다.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

await CapacitorAudioRecorder.resumeRecording();

stopRecording

현재 녹음을 중지하고 녹음된 오디오를 저장합니다.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

const result = await CapacitorAudioRecorder.stopRecording();
console.log(result);

cancelRecording

현재 녹음을 취소하고 캡처된 오디오를 모두 삭제합니다.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

await CapacitorAudioRecorder.cancelRecording();

getRecordingStatus

현재 녹음 상태를 조회합니다.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

const result = await CapacitorAudioRecorder.getRecordingStatus();
console.log(result);

getCurrentAmplitude

현재 입력 진폭(마이크 레벨)을 정규화된 숫자로 가져옵니다. [0, 1] 범위.

녹음 중 VU 미터나 웨이브폼 같은 실시간 시각화를 구현할 때 사용합니다. 반환값은 0 녹음 중이 아닐 때 발생합니다. UI 갱신 속도에 맞춘 폴링용으로 설계되었습니다. 웨이브폼의 경우 60–100 ms 간격이 적당합니다. 루프 내에서 너무 빈번하게 호출하지 마세요. 호출할 때마다 JS/native 브릿지를 거치게 됩니다.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

const result = await CapacitorAudioRecorder.getCurrentAmplitude();
console.log(result);

checkPermissions

마이크 접근 권한의 현재 상태를 반환합니다.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

const result = await CapacitorAudioRecorder.checkPermissions();
console.log(result);

requestPermissions

마이크 접근 권한을 요청합니다.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

const result = await CapacitorAudioRecorder.requestPermissions();
console.log(result);

타입 참조

StartRecordingOptions

.

export interface StartRecordingOptions {
  /**
   * The audio session category options for recording. Only available on iOS.
   *
   * @since 1.0.0
   */
  audioSessionCategoryOptions?: AudioSessionCategoryOption[];

  /**
   * The audio session mode for recording. Only available on iOS.
   *
   * @since 1.0.0
   */
  audioSessionMode?: AudioSessionMode;

  /**
   * The audio bit rate in bytes per second.
   * Only available on Android and iOS.
   *
   * @since 1.0.0
   */
  bitRate?: number;

  /**
   * The audio sample rate in Hz.
   * Only available on Android and iOS.
   *
   * @since 1.0.0
   */
  sampleRate?: number;
}

StopRecordingResult

.

export interface StopRecordingResult {
  /**
   * The recorded audio as a Blob. Only available on Web.
   *
   * @since 1.0.0
   */
  blob?: Blob;

  /**
   * The duration of the recording in milliseconds.
   *
   * @since 1.0.0
   */
  duration?: number;

  /**
   * The URI pointing to the recorded file. Only available on Android and iOS.
   *
   * @since 1.0.0
   */
  uri?: string;
}

GetRecordingStatusResult

.에서 반환된 결과

export interface GetRecordingStatusResult {
  /**
   * The current recording status.
   *
   * @since 1.0.0
   */
  status: RecordingStatus;
}

GetCurrentAmplitudeResult

.에서 반환된 결과

export interface GetCurrentAmplitudeResult {
  /**
   * The current input amplitude normalized to the `[0, 1]` range, where `0`
   * represents silence and `1` represents the maximum level the platform can
   * report. The value is `0` when no recording is active.
   *
   * Note: the source signal differs between platforms — Android reports the
   * peak sample amplitude since the last call, iOS reports the average power
   * in dB converted to linear, and Web reports the RMS of the latest frame.
   * Consumers that need cross-platform parity may want to apply a
   * per-platform scaling curve.
   *
   * @since 8.1.0
   */
  value: number;
}

PermissionStatus

및 에서 반환된 권한 정보

export interface PermissionStatus {
  /**
   * The permission state for audio recording.
   *
   * @since 1.0.0
   */
  recordAudio: PermissionState;
}

RecordingErrorEvent

녹음 중 오류가 발생할 때 발생하는 이벤트

export interface RecordingErrorEvent {
  /**
   * The error message.
   *
   * @since 1.0.0
   */
  message: string;
}

RecordingStoppedEvent

녹음이 완료되면 발생하는 이벤트입니다.

export type RecordingStoppedEvent = StopRecordingResult;

AudioSessionCategoryOption

iOS에서 사용 가능한 오디오 세션 카테고리 옵션입니다.

export enum AudioSessionCategoryOption {
  AllowAirPlay = 'ALLOW_AIR_PLAY',
  AllowBluetooth = 'ALLOW_BLUETOOTH',
  AllowBluetoothA2DP = 'ALLOW_BLUETOOTH_A2DP',
  DefaultToSpeaker = 'DEFAULT_TO_SPEAKER',
  DuckOthers = 'DUCK_OTHERS',
  InterruptSpokenAudioAndMixWithOthers = 'INTERRUPT_SPOKEN_AUDIO_AND_MIX_WITH_OTHERS',
  MixWithOthers = 'MIX_WITH_OTHERS',
  OverrideMutedMicrophoneInterruption = 'OVERRIDE_MUTED_MICROPHONE_INTERRUPTION',
}

AudioSessionMode

iOS에서 사용 가능한 오디오 세션 모드입니다.

export enum AudioSessionMode {
  Default = 'DEFAULT',
  GameChat = 'GAME_CHAT',
  Measurement = 'MEASUREMENT',
  SpokenAudio = 'SPOKEN_AUDIO',
  VideoChat = 'VIDEO_CHAT',
  VideoRecording = 'VIDEO_RECORDING',
  VoiceChat = 'VOICE_CHAT',
}

RecordingStatus

녹음 상태입니다.

export enum RecordingStatus {
  Inactive = 'INACTIVE',
  Recording = 'RECORDING',
  Paused = 'PAUSED',
}

PermissionState

Capacitor에서 지원하는 플랫폼 권한 상태입니다.

export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';

기준 소스

이 페이지는 플러그인의 src/definitions.ts에서 생성되었습니다. public API가 업스트림에서 변경되면 동기화를 다시 실행하세요.

Getting Started에서 계속하기

사용 중인 경우 시작하기 네이티브 미디어 및 인터페이스 동작을 설계하려면, 이를 다음 항목과 연결하세요 @capgo/capacitor-audio-recorder 사용하기 @capgo/capacitor-audio-recorder를 사용하여 Native Build 기능을 구현하려면, @capgo/capacitor-live-activities 사용하기 @capgo/capacitor-live-activities 사용하기의 네이티브 기능을 위해서는, @capgo/capacitor-live-activities @capgo/capacitor-live-activities의 구현 세부 사항에 대해서는, @capgo/capacitor-video-player 사용하기 @capgo/capacitor-video-player 사용하기의 네이티브 기능에 대해서는, 그리고 @capgo/capacitor-video-player @capgo/capacitor-video-player.의 구현 세부 사항에 대해서는