はじめに

インストール

AIアシストによるセットアップを使用してプラグインをインストールできます。以下のコマンドを使用して、お使いのAIツールに Capgo のスキルを追加してください：

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

次に、以下のプロンプトを使用します：

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

手動でのセットアップを希望する場合は、以下のコマンドを実行してプラグインをインストールし、各プラットフォーム固有の指示に従ってください：

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

インポート

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

クイックスタート

マイクの使用権限をリクエストし、録音を開始、停止した後、ネイティブのファイルURI（またはWeb）を取得します 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で利用可能です。

例：ライブレベルメーター

ポーリングを getCurrentAmplitude() ステータスが〜の間、タイマー（約60〜100ms）で実行します。 RECORDING値は正規化されていますが、 0 へ 1プラットフォームによって基底となる信号が異なります（Androidはピーク、iOSは平均電力、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とネイティブの戻り値の形式: AndroidおよびiOSの戻り値 uri と stopRecording. Webの戻り値 blob (および省略される可能性がある uri).
• 録音後のiOSでの無音再生: 設定 resetToPlaybackOnStop: true 内の startRecording ユーザーが同じセッション内でクリップを再生する場合。
• バックグラウンドでのキャプチャ: このプラグイン自体ではバックグラウンドオーディオを有効にしません。iOSで画面ロック中に録音を行う必要がある場合は、Audio background modeを追加してください。
• 振幅（amplitude）の過剰な取得は避けてください: 各 getCurrentAmplitude コールがブリッジを越えます。タイトなループではなく、UIのインターバルを使用してください。

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〜100ms間隔での実行が推奨されます。ループ内で頻繁に呼び出すことは避けてください。呼び出しのたびに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

Capacitor および Capgo から返される権限情報。

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から生成されています。upstreamの公開 API が変更された場合は、再度syncを実行してください。

Getting Startedの続きはこちら

以下を使用している場合： はじめに ネイティブのメディアやインターフェースの挙動を計画し、以下と連携させるには、 @capgo/capacitor-audio-recorder を使用して 「@capgo/capacitor-audio-recorder を使用して」におけるネイティブ機能について、 @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. の実装詳細については