Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

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

Importar

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

Inicio rápido

Solicita el micrófono, graba, luego detén y lee la URI nativa del archivo (o 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);

Ejemplo: nota de voz con pausa

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

pauseRecording está disponible en Android (API 24+), iOS y Web.

Ejemplo: medidor de nivel en vivo

Haz polling getCurrentAmplitude() con un timer (aprox. 60 a 100 ms) mientras el estado es RECORDING. Los valores están normalizados 0 a 1, pero la señal subyacente varía según la plataforma (pico en Android, potencia media en iOS, RMS en Web). Aplica un pequeño ajuste de escala por plataforma si necesitas paridad visual.

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

Ejemplo: descartar una toma

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

Errores comunes

• Formato de retorno: Web vs nativo: Android e iOS devuelven uri de los stopRecording. Web devuelve blob (y puede omitir uri).
• Reproducción silenciosa en iOS tras la grabación: establece resetToPlaybackOnStop: true en startRecording si los usuarios reproducen el clip dentro de la misma sesión.
• Captura en segundo plano: el plugin no habilita la audio en segundo plano por sí solo. En iOS, añade el modo de fondo Audio cuando necesites grabar con el dispositivo bloqueado.
• No spamees la amplitud: cada getCurrentAmplitude llamada cruza el bridge. Usa un intervalo de UI, no un bucle cerrado.

Resumen de API

startRecording

Inicia la grabación de audio con el micrófono del dispositivo.

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

await CapacitorAudioRecorder.startRecording();

pauseRecording

Pausa la grabación en curso. Solo disponible en Android (API 24+), iOS y Web.

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

await CapacitorAudioRecorder.pauseRecording();

resumeRecording

Reanuda una grabación pausada anteriormente.

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

await CapacitorAudioRecorder.resumeRecording();

stopRecording

Detiene la grabación actual y guarda el audio grabado.

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

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

cancelRecording

Cancela la grabación actual y descarta cualquier audio capturado.

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

await CapacitorAudioRecorder.cancelRecording();

getRecordingStatus

Obtiene el estado actual de la grabación.

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

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

getCurrentAmplitude

Obtén la amplitud de entrada actual (nivel del micrófono) como un número normalizado en el [0, 1] rango.

Ideal para alimentar visualizaciones en vivo como VU meters o formas de onda durante la grabación. Devuelve 0 cuando no hay ninguna grabación activa. Pensado para hacer polling a la frecuencia de la UI: un intervalo de 60–100 ms es un buen punto de partida para una forma de onda. Evita llamarlo en un bucle ajustado; cada llamada cruza el bridge JS/nativo.

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

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

checkPermissions

Devuelve el estado actual del permiso de acceso al micrófono.

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

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

requestPermissions

Solicita permiso para acceder al micrófono.

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

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

Referencia de tipos

StartRecordingOptions

Opciones aceptadas por .

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

Resultado devuelto por .

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

Resultado devuelto por .

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

GetCurrentAmplitudeResult

Resultado devuelto por .

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

Información de permisos devuelta por y .

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

RecordingErrorEvent

Evento emitido cuando ocurre un error durante la grabación.

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

RecordingStoppedEvent

Evento emitido cuando una grabación se completa.

export type RecordingStoppedEvent = StopRecordingResult;

AudioSessionCategoryOption

Opciones de categoría de sesión de audio disponibles en 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

Modos de sesión de audio disponibles en iOS.

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

RecordingStatus

El estado de la grabación.

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

PermissionState

Estados de permisos de plataforma compatibles con Capacitor.

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

Fuente de verdad

Esta página se genera a partir del plugin src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en upstream.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar el comportamiento de los medios nativos y la interfaz, conéctalo con Uso de @capgo/capacitor-audio-recorder para la funcionalidad nativa en Uso de @capgo/capacitor-audio-recorder, Uso de @capgo/capacitor-live-activities para la capacidad nativa en Uso de @capgo/capacitor-live-activities, @capgo/capacitor-live-activities para los detalles de implementación en @capgo/capacitor-live-activities, Uso de @capgo/capacitor-video-player para la capacidad nativa en Uso de @capgo/capacitor-video-player, y @capgo/capacitor-video-player para el detalle de implementación en @capgo/capacitor-video-player.