Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-audio-recorder
bunx cap sync

Importieren

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

Quickstart

Mikrofonzugriff anfordern, aufnehmen, dann stoppen und die native Datei-URI (oder Web-URI) lesen 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);

Crash-sichere Aufnahme (format: 'aac')

Erfordert @capgo/capacitor-audio-recorder 8.4.0 oder neuer von capacitor-audio-recorder PR #35. Mergen und veröffentlichen Sie diese Plugin-Änderung, bevor Sie dieses API in der Produktion einsetzen.

Wann einsetzen

Nutzt format: 'aac' für unersetzliche Audioinhalte: Interviews, Compliance-Notizen, medizinische oder rechtliche Memos und alle Clips, bei denen der Verlust der gesamten Datei schlimmer ist als der Verlust des Endes nach einem abnormalen Abschluss.

Standard beibehalten format: 'm4a' wenn du den Lifecycle kontrollierst (kurze Clips, immer im Vordergrund, Verlust eines Takes bei Crash ist akzeptabel) oder wenn nachgelagerte Tools das erwarten .m4a und niemals .aac.

So funktioniert es

format	Container	Nach einem abnormalen Ende (Crash, Kill, leerer Akku)
'm4a' (Standard)	MPEG-4 AAC in .m4a	Oft nicht lesbar bis moov geschrieben wird bei stop()
'aac'	ADTS AAC in .aac	Lesbar bis zum letzten vollständigen Frame

Die Encoding-Einstellungen sind derselbe AAC-Bitrate und Abtastrate, die du bereits an startRecordingübergibst. Web ignoriert format und nutzt weiterhin den Browser MediaRecorder.

await CapacitorAudioRecorder.startRecording({
  format: 'aac',
  sampleRate: 44100,
  bitRate: 128000,
});

Tradeoffs

• Wiedergabe und Teilen: .aac (ADTS) wird auf Mobilgeräten weitgehend unterstützt, aber einige Desktop-Pipelines erwarten .m4a. Konvertiere in deinem Backend, falls Reviewer MPEG-4 verlangen.
• Dateigröße und Seeking: ADTS hat keinen Index wie MPEG-4. Seeking und Dauer-Metadaten können ungenauer sein, bis die Datei vollständig finalisiert ist.
• iOS-Unterbrechungen: Telefonate und Audio-Session-Übergaben können mehrere Segmentdateien hinterlassen. Beim Stoppen fügt das Plugin ADTS-Segmente zusammen, ohne sie neu zu kodieren, wenn möglich.

Plattform-Hinweise für stopRecording

Android

• Wenn MediaRecorder.stop() wirft, stopRecording lehnt ab aber die Datei bleibt auf der Festplatte. Lies error.data.uri und error.data.duration (Millisekunden) nach der Capacitor-Ablehnung, um den Teilclip zu behalten.
• Dateinamen sind recording-yyyyMMdd-HHmmss-<uuid>.m4a oder .aac, passend zu format. Die UUID verhindert, dass zwei in derselben Sekunde gestartete Aufzeichnungen einander überschreiben. Ältere Versionen verwendeten recording-yyyyMMdd-HHmmss.m4a (keine UUID, immer .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

• Unterbrochene 'aac' Aufzeichnungen werden zu einer einzigen .aac zusammengeführt, wenn der Vorgang erfolgreich ist.
• Wenn das Zusammenführen fehlschlägt (z. B. bei vollem Speicher), stopRecording kannst auflösen mit mergeFailed: true, ein Fallback uri, und segments: string[] jede Sequenz nacheinander auflistet. Für 'aac', die rohen Dateien nicht einfach blind zusammenfügen: Ein Segment kann mit einem unvollständigen ADTS-Frame enden, und ein naives Zusammenfügen kann die Wiedergabe der folgenden Daten beschädigen. Kopiere nur vollständige Frames aus jedem Segment (die Join-Logik des Plugins erledigt das) oder lade jedes Segment separat hoch und füge sie serverseitig zusammen. Für 'm4a', können Segmente nicht durch Zusammenfügen verbunden werden; remuxe sie oder füge sie serverseitig zusammen.
• When finalization fails with no usable fallback segment, stopRecording lehnt ab 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 jetzt eine Ablehnung zurückgibt, wenn AVAudioRecorder.record() gibt zurück false (z. B. das Mikrofon wird woanders verwendet), anstatt einen leeren Take zurückzugeben.

Beispiel: Sprachmemo mit Pause

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

pauseRecording ist auf Android (API 24+), iOS und Web verfügbar.

Beispiel: Live-Pegelanzeige

Abfragen getCurrentAmplitude() per Timer (ca. 60 bis 100 ms), während der Status ist RECORDING. Die Werte sind normalisiert 0 zu 1, aber das zugrunde liegende Signal unterscheidet sich je nach Plattform (Peak auf Android, Average Power auf iOS, RMS im Web). Nutze bei Bedarf einen kleinen plattformspezifischen Skalierungsfaktor, wenn du visuelle Konsistenz brauchst.

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

Beispiel: Aufnahme verwerfen

await CapacitorAudioRecorder.startRecording();
await CapacitorAudioRecorder.cancelRecording(); // no file persisted

Häufige Stolperfallen

• Web vs. native Rückgabeform: Android und iOS geben zurück uri von stopRecording. Web gibt zurück blob (und lässt ggf. weg uri).
• Crash-Sicherheit vs. Standardformat: nur format: 'aac' auf Android und iOS hält die Audioaufnahme auch nach einem harten Stopp abspielbar. Standard .m4a benötigt einen sauberen stopRecording um lesbar zu bleiben.
• Fehlgeschlagener Stopp auf Android: behandeln stopRecording Rejections und Lese error.data für uri und duration statt davon auszugehen, dass die Datei gelöscht wurde.
• Android-Dateinamen: nicht den alten recording-yyyyMMdd-HHmmss.m4a Muster nicht parsen. Aktuelle Dateien enthalten eine UUID und enden ggf. mit .aac , wenn du dich für format: 'aac'.
• iOS-Merge-Fehler: Wenn mergeFailed true ist, verwende segments oder den Fallback uri aus dem aufgelösten Ergebnis.
• Leise Wiedergabe auf iOS nach der Aufnahme: setzen resetToPlaybackOnStop: true in einem startRecording wenn Nutzer den Clip in derselben Session abspielen.
• Aufnahme im Hintergrund: Das Plugin aktiviert Hintergrund-Audio nicht von selbst. Füge unter iOS den Audio-Hintergrundmodus hinzu, wenn du bei gesperrtem Gerät aufnehmen willst.
• Amplitude nicht spammen: Jeder getCurrentAmplitude Aufruf geht über die Bridge. Nutze ein UI-Intervall, keine enge Schleife.

API Übersicht

startRecording

Aufnahme mit dem Gerätemikrofon starten.

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

await CapacitorAudioRecorder.startRecording();

pauseRecording

Die laufende Aufnahme pausieren. Nur auf Android (API 24+), iOS und Web verfügbar.

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

await CapacitorAudioRecorder.pauseRecording();

resumeRecording

Eine zuvor pausierte Aufnahme fortsetzen.

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

await CapacitorAudioRecorder.resumeRecording();

stopRecording

Die aktuelle Aufnahme stoppen und das aufgenommene Audio speichern.

Auf Android wird der Aufruf abgelehnt und die Aufnahme-Datei auf der Festplatte behalten, wenn der Recorder nicht sauber gestoppt werden kann. Die Ablehnung data.uri verweist darauf und data.duration meldet die verstrichene Zeit.

Auf iOS, wenn die Segmente einer unterbrochenen 'aac' Aufnahme nicht zusammengeführt werden können, aber ein Fallback-Segment existiert, wird der Aufruf aufgelöst mit mergeFailed und segments. Wenn die Finalisierung ohne Fallback-Segment fehlschlägt, wird der Aufruf abgelehnt und die Segmentdateien verbleiben auf der Festplatte.

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

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

cancelRecording

Die aktuelle Aufnahme abbrechen und bereits aufgenommenes Audio verwerfen.

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

await CapacitorAudioRecorder.cancelRecording();

getRecordingStatus

Den aktuellen Aufnahmestatus abrufen.

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

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

getCurrentAmplitude

Ruft die aktuelle Eingangsamplitude (Mikrofonpegel) als normalisierte Zahl im Bereich ab [0, 1] Bereich.

Gedacht für Live-Visualisierungen wie VU-Meter oder Waveforms während der Aufnahme. Gibt 0 wenn keine Aufnahme aktiv ist. Gedacht für Polling im UI-Takt. Ein Intervall von 60 bis 100 ms ist ein guter Ausgangspunkt für eine Waveform. Rufe es nicht in einer engen Schleife auf; jeder Aufruf geht über die JS/Native-Bridge.

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

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

checkPermissions

Gibt den aktuellen Berechtigungsstatus für den Mikrofonzugriff zurück.

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

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

requestPermissions

Fordert die Berechtigung für den Mikrofonzugriff an.

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

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

Typreferenz

StartRecordingOptions

Von . akzeptierte Optionen

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

export type RecordingFormat = 'm4a' | 'aac';

StopRecordingResult

Rückgabewert von .

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

Rückgabewert von .

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

GetCurrentAmplitudeResult

Rückgabewert von .

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

Permission information returned by and .

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

RecordingErrorEvent

Ereignis, das ausgelöst wird, wenn während der Aufnahme ein Fehler auftritt.

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

RecordingStoppedEvent

Event emitted when a recording completes.

export type RecordingStoppedEvent = StopRecordingResult;

AudioSessionCategoryOption

Verfügbare Audio-Session-Kategorie-Optionen auf 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

Verfügbare Audio-Session-Modi auf iOS.

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

RecordingStatus

Der Aufnahme-Status.

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

PermissionState

Von Capacitor unterstützte Plattform-Berechtigungsstatus.

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

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte , um natives Media- und Interface-Verhalten zu planen, verbinde es mit @capgo/capacitor-audio-recorder verwenden für die native Funktionalität bei der Nutzung von @capgo/capacitor-audio-recorder, @capgo/capacitor-live-activities verwenden für die native Funktion in „@capgo/capacitor-live-activities verwenden“, @capgo/capacitor-live-activities für die Implementierungsdetails in @capgo/capacitor-live-activities, Verwendung von @capgo/capacitor-video-player für die native Funktion in „@capgo/capacitor-video-player verwenden“, und @capgo/capacitor-video-player für das Implementierungsdetail in @capgo/capacitor-video-player.