Prise en main
Copiez un prompt de configuration incluant les étapes d'installation et le guide markdown complet pour ce 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.
Installer
Section intitulée « Installation »Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-pluginsUtilisez ensuite le prompt suivant :
Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-audio-recorder` plugin in my project.Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :
bun add @capgo/capacitor-audio-recorderbunx cap syncImporter
Section intitulée « Import »import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';Démarrage rapide
Section intitulée « Démarrage rapide »Demandez l'accès au micro, enregistrez, puis arrêtez et lisez l'URI du fichier natif (ou 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);Enregistrement résistant aux crashs (format: 'aac')
Section intitulée « Enregistrement résistant aux crashs (format : 'aac') »Nécessite une @capgo/capacitor-audio-recorder 8.4.0 ou plus récent depuis capacitor-audio-recorder PR #35. Fusionnez et publiez cette modification du plugin avant de vous fier à ce API en production.
Quand l'utiliser
Section intitulée « Quand l’utiliser »Utiliser format: 'aac' pour les audio irremplaçables : interviews, notes de conformité, mémos médicaux ou juridiques, et tout clip où perdre le fichier entier est pire que de perdre la fin après une fin anormale.
Conservez la valeur par défaut format: 'm4a' quand vous maîtrisez le cycle de vie (clips courts, toujours au premier plan, une prise perdue en cas de crash est acceptable) ou quand les outils en aval attendent .m4a et jamais .aac.
Comment ça marche
Section intitulée « Fonctionnement »format | Conteneur | Après une fin anormale (crash, kill, batterie à plat) |
|---|---|---|
'm4a' (par défaut) | MPEG-4 AAC dans .m4a | Souvent illisible jusqu'à moov est écrit à stop() |
'aac' | ADTS AAC en .aac | Lisible jusqu'à la dernière frame complète |
Encoding settings are the same AAC bit rate and sample rate you already pass to startRecording. Le web ignore format et continue d'utiliser le navigateur MediaRecorder.
await CapacitorAudioRecorder.startRecording({ format: 'aac', sampleRate: 44100, bitRate: 128000,});Compromis
Section intitulée « Compromis »- Lecture et partage:
.aac(ADTS) est largement pris en charge sur mobile, mais certains pipelines desktop attendent.m4a. Convertissez dans votre backend si les reviewers exigent du MPEG-4. - Taille du fichier et seek: ADTS n’a pas d’index comme MPEG-4. Le seek et les métadonnées de durée peuvent être moins précis tant que le fichier n’est pas entièrement finalisé.
- Interruptions iOS: Les appels téléphoniques et les transferts de session audio peuvent laisser plusieurs fichiers de segments. À l’arrêt, le plugin fusionne les segments ADTS sans réencodage lorsque c’est possible.
Notes de plateforme pour stopRecording
Section intitulée « Notes de plateforme pour stopRecording »Android
- Quand
MediaRecorder.stop()lève,stopRecordingrejette mais le fichier reste sur le disque. Lireerror.data.urieterror.data.duration(millisecondes) à partir du rejet de Capacitor pour conserver le clip partiel. - Les noms de fichiers sont
recording-yyyyMMdd-HHmmss-<uuid>.m4aou.aac, correspondant àformat. L'UUID empêche deux enregistrements démarrés dans la même seconde de s'écraser mutuellement. Les versions antérieures utilisaientrecording-yyyyMMdd-HHmmss.m4a(sans UUID, toujours.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
- Interrompu
'aac'Les enregistrements interrompus sont fusionnés en un seul.aaclorsque la fusion réussit. - Si la fusion échoue (par exemple disque plein),
stopRecordingpeut résoudre parmergeFailed: true, un fallbackuri, etsegments: string[]en listant chaque segment dans l’ordre. Pour'aac', ne concaténez pas aveuglément les fichiers bruts : un segment peut se terminer par une trame ADTS incomplète, et une concaténation naïve peut casser la lecture de ce qui suit. Copiez uniquement les trames complètes de chaque segment (la logique de fusion du plugin le fait), ou envoyez chaque segment séparément et assemblez-les côté serveur. Pour'm4a', les segments ne peuvent pas être fusionnés par concaténation ; remuxez-les ou assemblez-les côté serveur. - Lorsque la finalisation échoue sans segment de repli utilisable,
stopRecordingrejette but segment files remain on disk.
const result = await CapacitorAudioRecorder.stopRecording();if (result.mergeFailed && result.segments?.length) { console.warn('Join failed, segments on disk', result.segments, result.uri);}startRecording rejette désormais lorsque AVAudioRecorder.record() renvoie false (par exemple si le micro est utilisé ailleurs) au lieu de renvoyer une prise vide.
Exemple : mémo vocal avec pause
Section intitulée « Exemple : mémo vocal avec pause »await CapacitorAudioRecorder.startRecording();// user taps pause during a long noteawait CapacitorAudioRecorder.pauseRecording();await CapacitorAudioRecorder.resumeRecording();const clip = await CapacitorAudioRecorder.stopRecording();pauseRecording est disponible sur Android (API 24+), iOS et Web.
Exemple : vumètre en direct
Section intitulée « Exemple : indicateur de niveau en direct »Interroger getCurrentAmplitude() via un timer (environ 60 à 100 ms) pendant que le statut est RECORDING. Les valeurs sont normalisées 0 vers 1, mais le signal sous-jacent diffère selon la plateforme (peak sur Android, puissance moyenne sur iOS, RMS sur Web). Appliquez un léger facteur d'échelle propre à chaque plateforme si vous voulez un rendu visuel identique.
const tick = async () => { const { status } = await CapacitorAudioRecorder.getRecordingStatus(); if (status !== 'RECORDING') return; const { value } = await CapacitorAudioRecorder.getCurrentAmplitude(); updateMeterUi(value);};Exemple : abandonner une prise
Section intitulée « Exemple : abandonner une prise »await CapacitorAudioRecorder.startRecording();await CapacitorAudioRecorder.cancelRecording(); // no file persistedErreurs courantes
Section intitulée « Erreurs courantes »- Forme de retour Web vs natif: Android et iOS renvoient
uridepuisstopRecording. Le Web renvoieblob(et peut omettreuri). - Sécurité anti-crash par rapport au format par défaut : uniquement
format: 'aac'sur Android et iOS garde l’audio lisible après un arrêt forcé. Le format par défaut.m4anécessite un arrêt proprestopRecordingpour rester lisible. - Échec de l’arrêt sur Android : gérez les
stopRecordingrejets et lisezerror.datapoururietdurationau lieu de supposer que le fichier a été supprimé. - Noms de fichiers Android: ne pas parser l'ancien
recording-yyyyMMdd-HHmmss.m4amotif. Les fichiers actuels incluent un UUID et peuvent se terminer par.aaclorsque vous optez pourformat: 'aac'. - Échecs de fusion iOS: lorsque
mergeFailedvaut true, utilisezsegmentsou le fallbackurià partir du résultat résolu. - Lecture en sourdine sur iOS après l'enregistrement: définissez
resetToPlaybackOnStop: truedansstartRecordingsi les utilisateurs lisent l'extrait dans la même session. - Capture en arrière-plan: le plugin n'active pas l'audio en arrière-plan par lui-même. Sur iOS, ajoutez le mode Audio background lorsque vous avez besoin d'enregistrer l'appareil lorsqu'il est verrouillé.
- Ne spammez pas amplitude: chaque
getCurrentAmplitudeappel traverse le bridge. Utilisez un intervalle UI plutôt qu'une boucle serrée.
Aperçu de API
Section intitulée « Aperçu API »startRecording
Section intitulée « startRecording »Démarrez l'enregistrement audio via le micro de l'appareil.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.startRecording();pauseRecording
Section intitulée « pauseRecording »Mettez en pause l'enregistrement en cours. Disponible uniquement sur Android (API 24+), iOS et Web.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.pauseRecording();resumeRecording
Section intitulée « resumeRecording »Reprenez un enregistrement précédemment mis en pause.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.resumeRecording();stopRecording
Section intitulée « stopRecording »Arrêtez l'enregistrement en cours et conservez l'audio enregistré.
Sur Android, si l’enregistreur ne peut pas s’arrêter proprement, l’appel est rejeté et le fichier d’enregistrement est conservé sur le disque. Le rejet data.uri y fait référence et data.duration indique le temps écoulé.
Sur iOS, lorsque les segments d'une interruption 'aac' l’enregistrement ne peut pas être joint, mais un segment de secours existe, l’appel se résout avec mergeFailed et segments. Si la finalisation échoue sans segment de secours, l’appel est rejeté et les fichiers de segments restent sur le disque.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.stopRecording();console.log(result);cancelRecording
Section intitulée « cancelRecording »Annulez l'enregistrement en cours et supprimez l'audio capturé.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.cancelRecording();getRecordingStatus
Section intitulée « getRecordingStatus »Récupérez le statut de l'enregistrement en cours.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.getRecordingStatus();console.log(result);getCurrentAmplitude
Section intitulée « getCurrentAmplitude »Récupère l’amplitude d’entrée actuelle (niveau du microphone) sous forme d’un nombre normalisé dans l’intervalle [0, 1] plage.
Conçu pour piloter des visualisations en direct, comme des VU-mètres ou des formes d’onde, pendant l’enregistrement. Renvoie 0 lorsqu'aucun enregistrement n'est actif. Conçu pour un polling à la fréquence de l'UI. Un intervalle de 60 à 100 ms est un bon point de départ pour une forme d'onde. Évitez de l'appeler dans une boucle serrée ; chaque appel traverse le pont JS/natif.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.getCurrentAmplitude();console.log(result);checkPermissions
Section intitulée « checkPermissions »Renvoie l'état actuel des permissions pour l'accès au microphone.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.checkPermissions();console.log(result);requestPermissions
Section intitulée « requestPermissions »Demande la permission d'accéder au microphone.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.requestPermissions();console.log(result);Référence de type
Section intitulée « Référence de type »StartRecordingOptions
Section intitulée « StartRecordingOptions »Options acceptées par .
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
Section intitulée « RecordingFormat »export type RecordingFormat = 'm4a' | 'aac';StopRecordingResult
Section intitulée « StopRecordingResult »Résultat renvoyé par.
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
Section intitulée « GetRecordingStatusResult »Résultat renvoyé par.
export interface GetRecordingStatusResult { /** * The current recording status. * * @since 1.0.0 */ status: RecordingStatus;}GetCurrentAmplitudeResult
Section intitulée « GetCurrentAmplitudeResult »Résultat renvoyé par.
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
Section intitulée « PermissionStatus »Informations sur les autorisations renvoyées par et .
export interface PermissionStatus { /** * The permission state for audio recording. * * @since 1.0.0 */ recordAudio: PermissionState;}RecordingErrorEvent
Section intitulée « RecordingErrorEvent »Événement émis lorsqu'une erreur se produit pendant l'enregistrement.
export interface RecordingErrorEvent { /** * The error message. * * @since 1.0.0 */ message: string;}RecordingStoppedEvent
Section intitulée « RecordingStoppedEvent »Événement émis lorsqu'un enregistrement se termine.
export type RecordingStoppedEvent = StopRecordingResult;AudioSessionCategoryOption
Section intitulée « AudioSessionCategoryOption »Options de catégorie de session audio disponibles sur 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
Section intitulée « AudioSessionMode »Modes de session audio disponibles sur iOS.
export enum AudioSessionMode { Default = 'DEFAULT', GameChat = 'GAME_CHAT', Measurement = 'MEASUREMENT', SpokenAudio = 'SPOKEN_AUDIO', VideoChat = 'VIDEO_CHAT', VideoRecording = 'VIDEO_RECORDING', VoiceChat = 'VOICE_CHAT',}RecordingStatus
Section intitulée « RecordingStatus »Le statut de l'enregistrement.
export enum RecordingStatus { Inactive = 'INACTIVE', Recording = 'RECORDING', Paused = 'PAUSED',}PermissionState
Section intitulée « PermissionState »États de permission des plateformes supportés par Capacitor.
export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';Source de vérité
Section intitulée « Source de vérité »Cette page est générée à partir de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.
Continuer depuis Getting Started
Section intitulée « Continuer après Prise en main »Si vous utilisez Prise en main pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utiliser @capgo/capacitor-audio-recorder pour la capacité native dans « Utiliser @capgo/capacitor-audio-recorder », Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Utiliser @capgo/capacitor-video-player pour la capacité native dans Utiliser @capgo/capacitor-video-player, et @capgo/capacitor-video-player pour le détail d'implémentation dans @capgo/capacitor-video-player.