Vai al contenuto

Per iniziare

GitHub

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

Finestra del terminale
bun add @capgo/capacitor-audio-recorder
bunx cap sync
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

Richiedi l'accesso al microfono, registra, poi ferma la registrazione e leggi l'URI del file 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);

Richiede @capgo/capacitor-audio-recorder 8.4.0 o versione successiva da capacitor-audio-recorder PR #35. Integra e rilascia la modifica del plugin prima di affidarti a questo API in produzione.

Usa format: 'aac' per audio insostituibile: interviste, note di conformità, memo medici o legali e qualsiasi clip in cui perdere l'intero file è peggio che perdere la coda dopo una terminazione anomala.

Mantieni il valore predefinito format: 'm4a' quando controlli il lifecycle (clip brevi, sempre in foreground, puoi tollerare la perdita di una take in caso di crash) o quando gli strumenti a valle si aspettano .m4a e mai .aac.

formatContainerDopo una terminazione anomala (crash, kill, batteria scarica)
'm4a' (predefinito)MPEG-4 AAC in .m4aSpesso non leggibile finché moov non viene scritto in stop()
'aac'ADTS AAC in .aacLeggibile fino all'ultimo frame completo

Le impostazioni di encoding sono le stesse: bit rate AAC e sample rate che già passi a startRecording. Web ignora format e continua a usare il browser MediaRecorder.

await CapacitorAudioRecorder.startRecording({
format: 'aac',
sampleRate: 44100,
bitRate: 128000,
});
  • Riproduzione e condivisione: .aac (ADTS) è ampiamente supportato su mobile, ma alcune pipeline desktop si aspettano .m4a. Converti nel backend se i revisori richiedono MPEG-4.
  • Dimensione file e seeking: ADTS non ha un indice come MPEG-4. I metadati di seeking e durata possono essere meno precisi finché il file non è completamente finalizzato.
  • Interruzioni su iOS: Le chiamate e il passaggio delle sessioni audio possono lasciare più file di segmenti. Al termine, il plugin unisce i segmenti ADTS senza ricodifica quando possibile.

Android

  • Quando MediaRecorder.stop() throws, stopRecording rifiuta ma il file resta su disco. Leggi error.data.uri e error.data.duration (millisecondi) dal rifiuto di Capacitor per mantenere il clip parziale.
  • I nomi dei file sono recording-yyyyMMdd-HHmmss-<uuid>.m4a oppure .aac, corrispondente a format. L'UUID impedisce che due registrazioni avviate nello stesso secondo si sovrascrivano. Le versioni precedenti usavano recording-yyyyMMdd-HHmmss.m4a (senza UUID, sempre .m4a).
import type { StopRecordingResult } from '@capgo/capacitor-audio-recorder';
try {
const clip = await CapacitorAudioRecorder.stopRecording();
await upload(clip.uri!, clip.duration);
} catch (error: unknown) {
const data = (error as { data?: Pick<StopRecordingResult, 'uri' | 'duration'> }).data;
if (data?.uri) {
await upload(data.uri, data.duration);
} else {
throw error;
}
}

iOS

  • Interrotte 'aac' le registrazioni vengono unite in un unico .aac quando l'unione riesce.
  • Se l'unione fallisce (ad esempio disco pieno), stopRecording può resolve con mergeFailed: true, un fallback uri, e segments: string[] che elenca ogni segmento in ordine. Per 'aac', non concatenare i file grezzi alla cieca: un segmento può terminare con un frame ADTS incompleto e una concatenazione ingenua può rompere la riproduzione dei segmenti successivi. Copia solo i frame completi da ciascun segmento (la logica di join del plugin lo fa) oppure carica ogni segmento separatamente e uniscili lato server. Per 'm4a', i segmenti non possono essere uniti per concatenazione; rimuxali o uniscili lato server.
  • Quando la finalizzazione fallisce e non c'è un segmento di fallback utilizzabile, stopRecording rifiuta ma i file dei segmenti restano su disco.
const result = await CapacitorAudioRecorder.stopRecording();
if (result.mergeFailed && result.segments?.length) {
console.warn('Join failed, segments on disk', result.segments, result.uri);
}

startRecording ora rifiuta quando AVAudioRecorder.record() restituisce false (ad esempio se il microfono è in uso altrove) invece di restituire una registrazione vuota.

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

pauseRecording è disponibile su Android (API 24+), iOS e Web.

Poll getCurrentAmplitude() su un timer (circa 60-100 ms) mentre lo status è RECORDING. I valori sono normalizzati 0 a 1, ma il segnale sottostante cambia in base alla piattaforma (picco su Android, potenza media su iOS, RMS su Web). Applica un piccolo fattore di scala per piattaforma se ti serve una resa visiva coerente.

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

Esempio: scartare una registrazione

Sezione intitolata “Esempio: scartare una take”
await CapacitorAudioRecorder.startRecording();
await CapacitorAudioRecorder.cancelRecording(); // no file persisted
  • Struttura del valore restituito Web vs nativo: Android e iOS restituiscono uri da stopRecording. Web restituisce blob (e può omettere uri).
  • Sicurezza crash rispetto al formato predefinito: solo format: 'aac' su Android e iOS mantiene l'audio riproducibile dopo un arresto forzato. Il formato predefinito .m4a richiede un stopRecording pulito per restare leggibile.
  • Stop non riuscito su Android: gestisci stopRecording rifiuti e lettura error.data per uri e duration invece di dare per scontato che il file sia stato eliminato.
  • Nomi file Android: non analizzare il vecchio recording-yyyyMMdd-HHmmss.m4a pattern. I file attuali includono un UUID e possono terminare con .aac quando si opta per format: 'aac'.
  • Fallimenti di merge su iOS: quando mergeFailed è true, usa segments o il fallback uri dal risultato risolto.
  • Riproduzione silenziosa su iOS dopo la registrazione: imposta resetToPlaybackOnStop: true nella startRecording se gli utenti riproducono il clip nella stessa sessione.
  • Cattura in background: il plugin non abilita l'audio in background di per sé. Su iOS, aggiungi la modalità background Audio quando serve la registrazione a dispositivo bloccato.
  • Non spammare l'ampiezza: ogni getCurrentAmplitude call attraversa il bridge. Usa un intervallo UI, non un loop stretto.

Avvia la registrazione audio tramite il microfono del dispositivo.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.startRecording();

Mette in pausa la registrazione in corso. Disponibile solo su Android (API 24+), iOS e Web.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.pauseRecording();

Riprendi una registrazione precedentemente in pausa.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.resumeRecording();

Interrompe la registrazione attuale e salva l'audio registrato.

Su Android, se il recorder non riesce a fermarsi correttamente, la chiamata viene rifiutata e il file di registrazione viene mantenuto su disco. Il rejection data.uri punta ad esso e data.duration riporta il tempo trascorso.

Su iOS, quando i segmenti di un'interruzione 'aac' la registrazione non può essere unita, ma esiste un segmento di fallback: la chiamata si risolve con mergeFailed e segments. Se la finalizzazione fallisce senza un segmento di fallback, la chiamata viene rifiutata e i file dei segmenti restano su disco.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.stopRecording();
console.log(result);

Annulla la registrazione attuale e scarta l'audio catturato.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.cancelRecording();

Recupera lo stato attuale della registrazione.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.getRecordingStatus();
console.log(result);

Recupera l'ampiezza dell'input attuale (livello del microfono) come numero normalizzato nell'intervallo [0, 1] specificato.

Ideale per gestire visualizzazioni live come VU meter o waveform durante la registrazione. Restituisce 0 quando nessuna registrazione è attiva. Progettato per il polling a frequenza UI. Un intervallo di 60-100 ms è un buon punto di partenza per una forma d'onda. Evita di chiamarlo in un loop stretto; ogni chiamata attraversa il bridge JS/nativo.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.getCurrentAmplitude();
console.log(result);

Restituisce lo stato attuale dei permessi per l'accesso al microfono.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.checkPermissions();
console.log(result);

Richiedi il permesso per accedere al microfono.

import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.requestPermissions();
console.log(result);

Opzioni accettate da .

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;
/**
* When `true`, reset the iOS `AVAudioSession` category to `.playback` when recording stops or is canceled.
*
* @since 8.2.10
*/
resetToPlaybackOnStop?: boolean;
/**
* The container the recording is written in. Only available on Android and iOS.
*
* @default 'm4a'
* @since 8.4.0
*/
format?: RecordingFormat;
}
export type RecordingFormat = 'm4a' | 'aac';

Risultato restituito da .

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;
/**
* `true` when the segments of an interrupted recording could not be joined. Only available on iOS.
*
* @since 8.4.0
*/
mergeFailed?: boolean;
/**
* Segment URIs in recording order when `mergeFailed` is `true`. Only available on iOS.
*
* @since 8.4.0
*/
segments?: string[];
}

Risultato restituito da .

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

Risultato restituito da .

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

Informazioni sui permessi restituite da e .

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

Evento emesso quando si verifica un errore durante la registrazione.

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

Evento emesso quando una registrazione viene completata.

export type RecordingStoppedEvent = StopRecordingResult;

Opzioni di categoria della sessione audio disponibili su 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',
}

Modalità di sessione audio disponibili su iOS.

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

Stato della registrazione.

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

Stati dei permessi della piattaforma supportati da Capacitor.

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

Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.

Se stai usando Per iniziare per pianificare il comportamento dei media nativi e dell'interfaccia, collegalo a Utilizzo di @capgo/capacitor-audio-recorder per la funzionalità nativa in Using @capgo/capacitor-audio-recorder, Uso di @capgo/capacitor-live-activities per la funzionalità nativa nella pagina Uso di @capgo/capacitor-live-activities, @capgo/capacitor-live-activities per il dettaglio implementativo in @capgo/capacitor-live-activities, Uso di @capgo/capacitor-video-player per la funzionalità nativa nella pagina Uso di @capgo/capacitor-video-player, e @capgo/capacitor-video-player per il dettaglio implementativo in @capgo/capacitor-video-player.