Per iniziare
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-audio-recorder`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/audio-recorder/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.
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:
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-pluginsPoi 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:
bun add @capgo/capacitor-audio-recorderbunx cap syncImporta
Sezione intitolata “Import”import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';Avvio rapido
Sezione intitolata “Quick start”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);Registrazione crash-safe (format: 'aac')
Sezione intitolata “Registrazione crash-safe (formato: 'aac')”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.
Quando usarlo
Sezione intitolata “Quando usarlo”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.
Come funziona
Sezione intitolata “Come funziona”format | Container | Dopo una terminazione anomala (crash, kill, batteria scarica) |
|---|---|---|
'm4a' (predefinito) | MPEG-4 AAC in .m4a | Spesso non leggibile finché moov non viene scritto in stop() |
'aac' | ADTS AAC in .aac | Leggibile 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,});Compromessi
Sezione intitolata “Compromessi”- 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.
Note sulla piattaforma per stopRecording
Sezione intitolata “Note sulla piattaforma per stopRecording”Android
- Quando
MediaRecorder.stop()throws,stopRecordingrifiuta ma il file resta su disco. Leggierror.data.urieerror.data.duration(millisecondi) dal rifiuto di Capacitor per mantenere il clip parziale. - I nomi dei file sono
recording-yyyyMMdd-HHmmss-<uuid>.m4aoppure.aac, corrispondente aformat. L'UUID impedisce che due registrazioni avviate nello stesso secondo si sovrascrivano. Le versioni precedenti usavanorecording-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.aacquando l'unione riesce. - Se l'unione fallisce (ad esempio disco pieno),
stopRecordingpuò resolve conmergeFailed: true, un fallbackuri, esegments: 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,
stopRecordingrifiuta 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.
Esempio: nota vocale con pausa
Sezione intitolata “Esempio: memo vocale con pausa”await CapacitorAudioRecorder.startRecording();// user taps pause during a long noteawait CapacitorAudioRecorder.pauseRecording();await CapacitorAudioRecorder.resumeRecording();const clip = await CapacitorAudioRecorder.stopRecording();pauseRecording è disponibile su Android (API 24+), iOS e Web.
Esempio: indicatore di livello live
Sezione intitolata “Esempio: misuratore di livello live”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 persistedErrori comuni
Sezione intitolata “Errori comuni”- Struttura del valore restituito Web vs nativo: Android e iOS restituiscono
uridastopRecording. Web restituisceblob(e può omettereuri). - Sicurezza crash rispetto al formato predefinito: solo
format: 'aac'su Android e iOS mantiene l'audio riproducibile dopo un arresto forzato. Il formato predefinito.m4arichiede unstopRecordingpulito per restare leggibile. - Stop non riuscito su Android: gestisci
stopRecordingrifiuti e letturaerror.dataperuriedurationinvece di dare per scontato che il file sia stato eliminato. - Nomi file Android: non analizzare il vecchio
recording-yyyyMMdd-HHmmss.m4apattern. I file attuali includono un UUID e possono terminare con.aacquando si opta performat: 'aac'. - Fallimenti di merge su iOS: quando
mergeFailedè true, usasegmentso il fallbackuridal risultato risolto. - Riproduzione silenziosa su iOS dopo la registrazione: imposta
resetToPlaybackOnStop: truenellastartRecordingse 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
getCurrentAmplitudecall attraversa il bridge. Usa un intervallo UI, non un loop stretto.
Panoramica API
Sezione intitolata “Panoramica API”startRecording
Sezione intitolata “startRecording”Avvia la registrazione audio tramite il microfono del dispositivo.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.startRecording();pauseRecording
Sezione intitolata “pauseRecording”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();resumeRecording
Sezione intitolata “resumeRecording”Riprendi una registrazione precedentemente in pausa.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.resumeRecording();stopRecording
Sezione intitolata “stopRecording”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);cancelRecording
Sezione intitolata “cancelRecording”Annulla la registrazione attuale e scarta l'audio catturato.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.cancelRecording();getRecordingStatus
Sezione intitolata “getRecordingStatus”Recupera lo stato attuale della registrazione.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.getRecordingStatus();console.log(result);getCurrentAmplitude
Sezione intitolata “getCurrentAmplitude”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);checkPermissions
Sezione intitolata “checkPermissions”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);requestPermissions
Sezione intitolata “requestPermissions”Richiedi il permesso per accedere al microfono.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.requestPermissions();console.log(result);Riferimento ai tipi
Sezione: “Type Reference”StartRecordingOptions
Sezione intitolata “StartRecordingOptions”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;}RecordingFormat
Sezione intitolata “RecordingFormat”export type RecordingFormat = 'm4a' | 'aac';StopRecordingResult
Sezione intitolata “StopRecordingResult”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[];}GetRecordingStatusResult
Sezione intitolata “GetRecordingStatusResult”Risultato restituito da .
export interface GetRecordingStatusResult { /** * The current recording status. * * @since 1.0.0 */ status: RecordingStatus;}GetCurrentAmplitudeResult
Sezione intitolata “GetCurrentAmplitudeResult”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;}PermissionStatus
Sezione intitolata “PermissionStatus”Informazioni sui permessi restituite da e .
export interface PermissionStatus { /** * The permission state for audio recording. * * @since 1.0.0 */ recordAudio: PermissionState;}RecordingErrorEvent
Sezione intitolata “RecordingErrorEvent”Evento emesso quando si verifica un errore durante la registrazione.
export interface RecordingErrorEvent { /** * The error message. * * @since 1.0.0 */ message: string;}RecordingStoppedEvent
Sezione intitolata “RecordingStoppedEvent”Evento emesso quando una registrazione viene completata.
export type RecordingStoppedEvent = StopRecordingResult;AudioSessionCategoryOption
Sezione intitolata “AudioSessionCategoryOption”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',}AudioSessionMode
Sezione intitolata “AudioSessionMode”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',}RecordingStatus
Sezione intitolata “RecordingStatus”Stato della registrazione.
export enum RecordingStatus { Inactive = 'INACTIVE', Recording = 'RECORDING', Paused = 'PAUSED',}PermissionState
Sezione intitolata “PermissionState”Stati dei permessi della piattaforma supportati da Capacitor.
export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';Fonte di verità
Sezione intitolata “Fonte di verità”Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.
Continua da Getting Started
Sezione intitolata “Continua da Getting Started”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.