Aller au contenu

Prise en main

GitHub

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 :

Fenêtre de terminal
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez 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 :

Fenêtre de terminal
bun add @capgo/capacitor-audio-recorder
bunx cap sync
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';

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.

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.

formatConteneurAprès une fin anormale (crash, kill, batterie à plat)
'm4a' (par défaut)MPEG-4 AAC dans .m4aSouvent illisible jusqu'à moov est écrit à stop()
'aac'ADTS AAC en .aacLisible 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,
});
  • 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.

Android

  • Quand MediaRecorder.stop() lève, stopRecording rejette mais le fichier reste sur le disque. Lire error.data.uri et error.data.duration (millisecondes) à partir du rejet de Capacitor pour conserver le clip partiel.
  • Les noms de fichiers sont recording-yyyyMMdd-HHmmss-<uuid>.m4a ou .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 utilisaient recording-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 .aac lorsque la fusion réussit.
  • Si la fusion échoue (par exemple disque plein), stopRecording peut résoudre par mergeFailed: true, un fallback uri, et segments: 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, stopRecording rejette 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.

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

pauseRecording est disponible sur Android (API 24+), iOS et Web.

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);
};
await CapacitorAudioRecorder.startRecording();
await CapacitorAudioRecorder.cancelRecording(); // no file persisted
  • Forme de retour Web vs natif: Android et iOS renvoient uri depuis stopRecording. Le Web renvoie blob (et peut omettre uri).
  • 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 .m4a nécessite un arrêt propre stopRecording pour rester lisible.
  • Échec de l’arrêt sur Android : gérez les stopRecording rejets et lisez error.data pour uri et duration au lieu de supposer que le fichier a été supprimé.
  • Noms de fichiers Android: ne pas parser l'ancien recording-yyyyMMdd-HHmmss.m4a motif. Les fichiers actuels incluent un UUID et peuvent se terminer par .aac lorsque vous optez pour format: 'aac'.
  • Échecs de fusion iOS: lorsque mergeFailed vaut true, utilisez segments ou le fallback uri à partir du résultat résolu.
  • Lecture en sourdine sur iOS après l'enregistrement: définissez resetToPlaybackOnStop: true dans startRecording si 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 getCurrentAmplitude appel traverse le bridge. Utilisez un intervalle UI plutôt qu'une boucle serrée.

Démarrez l'enregistrement audio via le micro de l'appareil.

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

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();

Reprenez un enregistrement précédemment mis en pause.

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

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

Annulez l'enregistrement en cours et supprimez l'audio capturé.

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

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

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

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

Demande la permission d'accéder au microphone.

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

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;
}
export type RecordingFormat = 'm4a' | 'aac';

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

Résultat renvoyé par.

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

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

Informations sur les autorisations renvoyées par et .

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

Événement émis lorsqu'une erreur se produit pendant l'enregistrement.

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

Événement émis lorsqu'un enregistrement se termine.

export type RecordingStoppedEvent = StopRecordingResult;

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',
}

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',
}

Le statut de l'enregistrement.

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

États de permission des plateformes supportés par Capacitor.

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

Cette page est générée à partir de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

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.