Langsung ke konten

Panduan Memulai

GitHub

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

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

Minta akses mikrofon, rekam, lalu hentikan dan baca URI file native (atau 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);

Membutuhkan @capgo/capacitor-audio-recorder 8.4.0 atau lebih baru dari capacitor-audio-recorder PR #35. Merge dan rilis perubahan plugin tersebut sebelum mengandalkan API ini di produksi.

Gunakan format: 'aac' untuk audio yang tak tergantikan: wawancara, catatan kepatuhan, memo medis atau hukum, dan klip apa pun di mana kehilangan seluruh file lebih buruk daripada kehilangan bagian akhir setelah pengakhiran abnormal.

Pertahankan default format: 'm4a' ketika Anda mengontrol lifecycle (klip pendek, selalu di foreground, Anda bisa mentolerir kehilangan rekaman saat crash) atau ketika tool downstream mengharapkan .m4a dan tidak pernah .aac.

formatKontainerSetelah akhir yang tidak normal (crash, kill, baterai habis)
'm4a' (default)MPEG-4 AAC di .m4aSering tidak terbaca sampai moov ditulis di stop()
'aac'ADTS AAC in .aacReadable hingga frame lengkap terakhir

Pengaturan encoding sama dengan bit rate dan sample rate AAC yang sudah Anda lewati ke startRecording. Web mengabaikan format dan tetap menggunakan browser MediaRecorder.

await CapacitorAudioRecorder.startRecording({
format: 'aac',
sampleRate: 44100,
bitRate: 128000,
});
  • Playback dan sharing: .aac (ADTS) didukung luas di mobile, tetapi beberapa pipeline desktop mengharapkan .m4a. Konversi di backend Anda jika reviewer membutuhkan MPEG-4.
  • Ukuran file dan seeking: ADTS tidak memiliki indeks seperti MPEG-4. Metadata seeking dan durasi bisa kurang akurat sampai file sepenuhnya difinalisasi.
  • Interruptions di iOS: Panggilan telepon dan handoff sesi audio bisa meninggalkan beberapa file segmen. Saat stop, plugin menggabungkan segmen ADTS tanpa re-encoding jika memungkinkan.

Android

  • Saat MediaRecorder.stop() throws, stopRecording menolak tetapi file tetap ada di disk. Baca error.data.uri dan error.data.duration (milidetik) dari penolakan Capacitor untuk mempertahankan klip parsial.
  • Nama file adalah recording-yyyyMMdd-HHmmss-<uuid>.m4a atau .aac, sesuai dengan format. UUID mencegah dua rekaman yang dimulai pada detik yang sama saling menimpa. Versi sebelumnya menggunakan recording-yyyyMMdd-HHmmss.m4a (tanpa UUID, selalu .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

  • Terganggu 'aac' rekaman digabungkan menjadi satu .aac ketika penggabungan berhasil.
  • Jika penggabungan gagal (misalnya disk penuh), stopRecording bisa menyelesaikan dengan mergeFailed: true, fallback uri, dan segments: string[] mencantumkan setiap segmen secara berurutan. Untuk 'aac', jangan langsung menggabungkan file mentah: segmen bisa berakhir dengan frame ADTS yang tidak lengkap, dan penggabungan naif bisa merusak pemutaran bagian berikutnya. Salin hanya frame lengkap dari setiap segmen (logika join plugin melakukan ini), atau unggah setiap segmen secara terpisah dan gabungkan di sisi server. Untuk 'm4a', segmen tidak bisa digabungkan dengan concatenation; remux atau gabungkan di sisi server.
  • Saat finalisasi gagal tanpa segmen fallback yang dapat digunakan, stopRecording menolak tetapi file segmen tetap ada di disk.
const result = await CapacitorAudioRecorder.stopRecording();
if (result.mergeFailed && result.segments?.length) {
console.warn('Join failed, segments on disk', result.segments, result.uri);
}

startRecording sekarang menolak ketika AVAudioRecorder.record() mengembalikan false (misalnya mic sedang digunakan di tempat lain) alih-alih mengembalikan rekaman kosong.

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

pauseRecording tersedia di Android (API 24+), iOS, dan Web.

Poll getCurrentAmplitude() dengan timer (sekitar 60 hingga 100 ms) selama status RECORDING. Nilai dinormalisasi 0 ke 1, tetapi sinyal dasarnya berbeda di setiap platform (peak di Android, average power di iOS, RMS di Web). Terapkan skala kecil per platform jika Anda membutuhkan kesetaraan visual.

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
  • Perbedaan format return Web vs native: Android dan iOS mengembalikan uri dari stopRecording. Web mengembalikan blob (dan mungkin tidak menyertakan uri).
  • Keamanan crash vs format default: hanya format: 'aac' di Android dan iOS menjaga audio tetap dapat diputar setelah hard stop. Default .m4a membutuhkan stopRecording yang bersih agar tetap terbaca.
  • Gagal stop di Android: tangani stopRecording rejection dan baca error.data untuk uri dan duration alih-alih mengasumsikan file sudah dihapus.
  • Nama file Android: jangan parse pola lama recording-yyyyMMdd-HHmmss.m4a . File saat ini berisi UUID dan mungkin diakhiri dengan .aac ketika Anda memilih format: 'aac'.
  • Gagal merge iOS: ketika mergeFailed adalah true, gunakan segments atau fallback uri dari hasil yang dipecahkan.
  • Playback pelan di iOS setelah merekam: atur resetToPlaybackOnStop: true di startRecording jika pengguna memutar ulang klip dalam sesi yang sama.
  • Perekaman background: plugin ini tidak mengaktifkan audio background dengan sendirinya. Di iOS, tambahkan Audio background mode saat Anda perlu merekam ketika layar terkunci.
  • Jangan spam amplitude: setiap getCurrentAmplitude panggilan melewati bridge. Gunakan interval UI, bukan tight loop.

Mulai merekam audio menggunakan mikrofon perangkat.

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

Jeda rekaman yang sedang berjalan. Hanya tersedia di Android (API 24+), iOS, dan Web.

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

Lanjutkan kembali rekaman yang sebelumnya dijeda.

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

Hentikan rekaman saat ini dan simpan audio yang direkam.

Di Android, jika perekam tidak dapat berhenti dengan bersih, panggilan ditolak dan file rekaman tetap tersimpan di disk. Penolakan tersebut data.uri menunjuk ke file tersebut dan data.duration melaporkan waktu yang telah berlalu.

On iOS, when the segments of an interrupted 'aac' rekaman yang terputus tidak dapat digabungkan tetapi segmen fallback tersedia, panggilan akan resolve dengan mergeFailed dan segments. Jika finalisasi gagal tanpa segmen fallback, panggilan ditolak dan file segmen tetap tersimpan di disk.

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

Batalkan rekaman saat ini dan buang audio yang sudah terekam.

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

Ambil status rekaman saat ini.

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

Ambil amplitudo input saat ini (level mikrofon) sebagai angka ternormalisasi dalam [0, 1] rentang.

Ditujukan untuk visualisasi live seperti VU meter atau waveform saat merekam. Mengembalikan 0 saat tidak ada rekaman aktif. Dirancang untuk polling tingkat UI. Interval 60 hingga 100 ms adalah titik awal yang bagus untuk waveform. Hindari memanggilnya dalam loop ketat; setiap panggilan melewati bridge JS/native.

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

Kembalikan status izin saat ini untuk mengakses mikrofon.

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

Minta izin untuk mengakses mikrofon.

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

Opsi yang diterima oleh .

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

Hasil yang dikembalikan oleh .

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

Hasil yang dikembalikan oleh .

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

Hasil yang dikembalikan oleh .

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

Informasi izin yang dikembalikan oleh dan .

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

Event yang dipicu saat terjadi error selama perekaman.

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

Event yang dipancarkan saat rekaman selesai.

export type RecordingStoppedEvent = StopRecordingResult;

Opsi kategori audio session yang tersedia di 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',
}

Mode audio session yang tersedia di iOS.

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

Status rekaman.

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

Status izin platform yang didukung oleh Capacitor.

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

Halaman ini dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.

Jika Anda menggunakan Panduan Memulai untuk merencanakan perilaku media dan antarmuka native, hubungkan dengan Menggunakan @capgo/capacitor-audio-recorder untuk kapabilitas native di Menggunakan @capgo/capacitor-audio-recorder, Menggunakan @capgo/capacitor-live-activities untuk kemampuan native di Menggunakan @capgo/capacitor-live-activities, @capgo/capacitor-live-activities untuk detail implementasi di @capgo/capacitor-live-activities, Menggunakan @capgo/capacitor-video-player untuk kemampuan native di Menggunakan @capgo/capacitor-video-player, dan @capgo/capacitor-video-player untuk detail implementasi di @capgo/capacitor-video-player.