Erste Schritte

Installieren

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

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

Nutze anschließend 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 bevorziehst, 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

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

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 für Android (API 24+), iOS und Web verfügbar.

Beispiel: Live-Pegelanzeige

Polling getCurrentAmplitude() per Timer (ca. 60 bis 100 ms), während der Status RECORDINGist. Die Werte sind normalisiert 0 zu 1, aber das zugrunde liegende Signal variiert je nach Plattform (Peak auf Android, Average Power auf iOS, RMS im Web). Nutze ggf. einen kleinen Skalierungsfaktor pro Plattform für visuelle Konsistenz.

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 Fehlerquellen

• Rückgabestruktur: Web vs. Native: Android und iOS geben zurück uri von stopRecording. Web gibt zurück blob (und kann weglassen uri).
• Leise Wiedergabe auf iOS nach der Aufnahme: setzen resetToPlaybackOnStop: true in startRecording wenn Nutzer den Clip in derselben Session abspielen.
• Aufnahme im Hintergrund: das Plugin aktiviert den Hintergrund-Audio-Modus nicht von selbst. Füge unter iOS den Audio-Background-Mode hinzu, wenn du während des Sperrbildschirms aufnehmen willst.
• Vermeide zu viele Amplitude-Updates: jeder getCurrentAmplitude Aufruf überquert die Bridge. Nutze ein UI-Intervall statt einer engen Schleife.

API Übersicht

startRecording

Audioaufnahme über das Mikrofon des Geräts starten.

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

await CapacitorAudioRecorder.startRecording();

pauseRecording

Pausiert die laufende Aufnahme. Nur verfügbar für Android (API 24+), iOS und Web.

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

await CapacitorAudioRecorder.pauseRecording();

resumeRecording

Setzt eine zuvor pausierte Aufnahme fort.

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

await CapacitorAudioRecorder.resumeRecording();

stopRecording

Stoppt die aktuelle Aufnahme und speichert das Audio.

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

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

cancelRecording

Bricht die aktuelle Aufnahme ab und verwirft das Audio.

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

await CapacitorAudioRecorder.cancelRecording();

getRecordingStatus

Ruft den aktuellen Aufnahme-Status ab.

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

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

getCurrentAmplitude

Ruft die aktuelle Eingabeamplitude (Mikrofonpegel) als normalisierte Zahl in der [0, 1] Bereich ab.

Dient der Steuerung von Live-Visualisierungen wie VU-Metern oder Waveforms während der Aufnahme. Gibt 0 zurück, wenn keine Aufnahme aktiv ist. Gedacht für Polling in UI-Rate — ein Intervall von 60–100 ms ist ein guter Startpunkt für eine Waveform. Vermeide Aufrufe in einer engen Schleife; jeder Aufruf überquert 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 Zugriff auf das Mikrofon zurück.

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

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

requestPermissions

Berechtigung für den Mikrofonzugriff anfordern.

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

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

Typ-Referenz

StartRecordingOptions

Akzeptierte Optionen für .

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

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

GetRecordingStatusResult

Rückgabewert von .

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

GetCurrentAmplitudeResult

Das von . zurückgegebene Ergebnis.

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

Event, das bei einem Fehler während der Aufnahme ausgelöst wird.

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

RecordingStoppedEvent

Wird ausgelöst, wenn eine Aufnahme abgeschlossen ist.

export type RecordingStoppedEvent = StopRecordingResult;

AudioSessionCategoryOption

Verfügbare Audio-Session-Kategorieoptionen unter 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 unter 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-Berechtigungszustände.

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

Source of Truth

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

Weiter mit Getting Started

Wenn Sie ... verwenden Erste Schritte um natives Medien- und Interface-Verhalten zu planen, verbinde es mit Verwendung von @capgo/capacitor-audio-recorder für die native Funktion in Verwendung 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 das Implementierungsdetail in @capgo/capacitor-live-activities, @capgo/capacitor-video-player verwenden für die native Funktionalität bei der Nutzung von @capgo/capacitor-video-player, und @capgo/capacitor-video-player für das Implementierungsdetail in @capgo/capacitor-video-player.