Panduan Memulai
Salin prompt setup yang berisi langkah install dan panduan markdown lengkap untuk plugin ini.
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.
Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-pluginsLalu 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:
bun add @capgo/capacitor-audio-recorderbunx cap syncimport { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';Mulai cepat
Bagian berjudul “Mulai cepat”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);Perekaman tahan crash (format: 'aac')
Bagian berjudul “Perekaman tahan crash (format: 'aac')”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.
Kapan harus menggunakannya
Bagian berjudul “Kapan harus menggunakannya”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.
Cara kerjanya
Bagian berjudul “Cara kerjanya”format | Kontainer | Setelah akhir yang tidak normal (crash, kill, baterai habis) |
|---|---|---|
'm4a' (default) | MPEG-4 AAC di .m4a | Sering tidak terbaca sampai moov ditulis di stop() |
'aac' | ADTS AAC in .aac | Readable 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,});Tradeoffs
Bagian berjudul “Tradeoffs”- 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.
Catatan platform untuk stopRecording
Bagian berjudul “Catatan platform untuk stopRecording”Android
- Saat
MediaRecorder.stop()throws,stopRecordingmenolak tetapi file tetap ada di disk. Bacaerror.data.uridanerror.data.duration(milidetik) dari penolakan Capacitor untuk mempertahankan klip parsial. - Nama file adalah
recording-yyyyMMdd-HHmmss-<uuid>.m4aatau.aac, sesuai denganformat. UUID mencegah dua rekaman yang dimulai pada detik yang sama saling menimpa. Versi sebelumnya menggunakanrecording-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.aacketika penggabungan berhasil. - Jika penggabungan gagal (misalnya disk penuh),
stopRecordingbisa menyelesaikan denganmergeFailed: true, fallbackuri, dansegments: 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,
stopRecordingmenolak 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.
Contoh: voice memo dengan pause
Bagian berjudul “Contoh: memo suara dengan jeda”await CapacitorAudioRecorder.startRecording();// user taps pause during a long noteawait CapacitorAudioRecorder.pauseRecording();await CapacitorAudioRecorder.resumeRecording();const clip = await CapacitorAudioRecorder.stopRecording();pauseRecording tersedia di Android (API 24+), iOS, dan Web.
Contoh: level meter live
Bagian berjudul “Contoh: meter level real-time”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);};Contoh: membuang take
Bagian berjudul “Contoh: membuang rekaman”await CapacitorAudioRecorder.startRecording();await CapacitorAudioRecorder.cancelRecording(); // no file persistedKesalahan umum
Bagian berjudul “Kesalahan umum”- Perbedaan format return Web vs native: Android dan iOS mengembalikan
uridaristopRecording. Web mengembalikanblob(dan mungkin tidak menyertakanuri). - Keamanan crash vs format default: hanya
format: 'aac'di Android dan iOS menjaga audio tetap dapat diputar setelah hard stop. Default.m4amembutuhkanstopRecordingyang bersih agar tetap terbaca. - Gagal stop di Android: tangani
stopRecordingrejection dan bacaerror.datauntukuridandurationalih-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.aacketika Anda memilihformat: 'aac'. - Gagal merge iOS: ketika
mergeFailedadalah true, gunakansegmentsatau fallbackuridari hasil yang dipecahkan. - Playback pelan di iOS setelah merekam: atur
resetToPlaybackOnStop: truedistartRecordingjika 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
getCurrentAmplitudepanggilan melewati bridge. Gunakan interval UI, bukan tight loop.
Ringkasan API
Bagian berjudul “Ikhtisar API”startRecording
Bagian berjudul “startRecording”Mulai merekam audio menggunakan mikrofon perangkat.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.startRecording();pauseRecording
Bagian berjudul “pauseRecording”Jeda rekaman yang sedang berjalan. Hanya tersedia di Android (API 24+), iOS, dan Web.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.pauseRecording();resumeRecording
Bagian berjudul “resumeRecording”Lanjutkan kembali rekaman yang sebelumnya dijeda.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.resumeRecording();stopRecording
Bagian berjudul “stopRecording”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);cancelRecording
Bagian berjudul “cancelRecording”Batalkan rekaman saat ini dan buang audio yang sudah terekam.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
await CapacitorAudioRecorder.cancelRecording();getRecordingStatus
Bagian berjudul “getRecordingStatus”Ambil status rekaman saat ini.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.getRecordingStatus();console.log(result);getCurrentAmplitude
Bagian berjudul “getCurrentAmplitude”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);checkPermissions
Bagian berjudul “checkPermissions”Kembalikan status izin saat ini untuk mengakses mikrofon.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.checkPermissions();console.log(result);requestPermissions
Bagian berjudul “requestPermissions”Minta izin untuk mengakses mikrofon.
import { CapacitorAudioRecorder } from '@capgo/capacitor-audio-recorder';
const result = await CapacitorAudioRecorder.requestPermissions();console.log(result);Referensi Tipe
Bagian berjudul “Referensi Tipe”StartRecordingOptions
Bagian berjudul “StartRecordingOptions”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;}RecordingFormat
Bagian berjudul “RecordingFormat”export type RecordingFormat = 'm4a' | 'aac';StopRecordingResult
Bagian berjudul “StopRecordingResult”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[];}GetRecordingStatusResult
Bagian berjudul “GetRecordingStatusResult”Hasil yang dikembalikan oleh .
export interface GetRecordingStatusResult { /** * The current recording status. * * @since 1.0.0 */ status: RecordingStatus;}GetCurrentAmplitudeResult
Bagian berjudul “GetCurrentAmplitudeResult”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;}PermissionStatus
Bagian berjudul “PermissionStatus”Informasi izin yang dikembalikan oleh dan .
export interface PermissionStatus { /** * The permission state for audio recording. * * @since 1.0.0 */ recordAudio: PermissionState;}RecordingErrorEvent
Bagian berjudul “RecordingErrorEvent”Event yang dipicu saat terjadi error selama perekaman.
export interface RecordingErrorEvent { /** * The error message. * * @since 1.0.0 */ message: string;}RecordingStoppedEvent
Bagian berjudul “RecordingStoppedEvent”Event yang dipancarkan saat rekaman selesai.
export type RecordingStoppedEvent = StopRecordingResult;AudioSessionCategoryOption
Bagian berjudul “AudioSessionCategoryOption”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',}AudioSessionMode
Bagian berjudul “AudioSessionMode”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',}RecordingStatus
Bagian berjudul “RecordingStatus”Status rekaman.
export enum RecordingStatus { Inactive = 'INACTIVE', Recording = 'RECORDING', Paused = 'PAUSED',}PermissionState
Bagian berjudul “PermissionState”Status izin platform yang didukung oleh Capacitor.
export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';Sumber Kebenaran
Bagian berjudul “Sumber Kebenaran”Halaman ini dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.
Lanjutkan dari Getting Started
Bagian berjudul “Lanjutkan dari Getting Started”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.