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 los siguientes comandos y sigue las instrucciones específicas para cada plataforma a continuación:

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, detén la grabación y lee la URI del archivo nativo (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

Poll getCurrentAmplitude() con un timer (aprox. 60 a 100 ms) mientras el status es RECORDING. Los valores están normalizados 0 a 1, pero la señal base varía según la plataforma (peak en Android, average power en iOS, RMS en Web). Aplica un pequeño scale por plataforma si buscas 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: Retorno en Android e iOS uri de stopRecording. Retorno en Web blob (y podría omitir uri).
• Reproducción silenciosa en iOS tras grabar: establece resetToPlaybackOnStop: true en startRecording si los usuarios reproducen el clip en la misma sesión.
• Captura en segundo plano: el plugin no habilita el audio en segundo plano por sí solo. En iOS, añade el Audio background mode si necesitas grabar con la pantalla bloqueada.
• No satures con la amplitud: cada getCurrentAmplitude llamada cruza el bridge. Usa un intervalo de UI, no un bucle infinito.

Resumen de API

startRecording

Empieza a grabar audio usando 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

Detén 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 el audio capturado.

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

await CapacitorAudioRecorder.cancelRecording();

getRecordingStatus

Obtén 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 waveforms durante la grabación. Devuelve 0 cuando no hay ninguna grabación activa. Diseñado para polling a tasa de UI: un intervalo de 60–100 ms es un buen punto de partida para una waveform. Evita llamarlo en un bucle cerrado; cada llamada cruza el bridge JS/native.

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

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

checkPermissions

Devuelve el estado actual de los permisos para acceder 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 al finalizar una grabación.

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 src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en el upstream.

Continúa desde Primeros pasos

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