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-native-audio`
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/native-audio/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.

Instal

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-plugins

Lalu gunakan prompt berikut:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-native-audio` 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-native-audio
bunx cap sync

Impor

import { NativeAudio } from '@capgo/capacitor-native-audio';

Mulai cepat

Konfigurasi sekali, preload klip, dan mainkan feedback UI dengan playOnce() untuk sound fire and forget.

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.configure({ focus: true, showNotification: false });
await NativeAudio.playOnce({ assetPath: 'public/sounds/tap.mp3', volume: 0.8 });

Contoh: sesi bergaya musik

await NativeAudio.preload({
  assetId: 'episode-1',
  assetPath: 'https://cdn.example.com/episode.m3u8',
  isUrl: true,
});
await NativeAudio.play({ assetId: 'episode-1' });
await NativeAudio.addListener('currentTime', ({ assetId, time }) => updateScrubber(assetId, time));

Contoh: lepaskan audio session

Saat plugin lain butuh kontrol audio eksklusif, hentikan playback dan panggil deinitPlugin() untuk memulihkan session sebelumnya.

await NativeAudio.stop({ assetId: 'episode-1' });
await NativeAudio.deinitPlugin();

Kesalahan umum

Now Playing vs mixing: showNotification: true di iOS beralih ke kategori playback yang menginterupsi musik latar.
Latar Belakang Android: aktifkan backgroundPlayback hanya setelah Anda menjalankan foreground service dan mengatur izin yang diperlukan dari README.
Web listener: event playback state tidak dikirim di web; pastikan UI yang bergantung padanya aman.

Ringkasan API

`configure`

Konfigurasi audio player

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.configure({
  focus: false,
  background: false,
  ignoreSilent: false,
  showNotification: false,
  backgroundPlayback: false,
});

`preload`

Muat file audio

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.preload({
  assetPath: 'path/to/file',
  assetId: 'asset-id-123',
});

`playOnce`

Putar file audio sekali dengan pembersihan otomatis

Metode yang dirancang untuk pemutaran audio sekali jalan yang simpel, seperti suara notifikasi, feedback UI, atau klip audio pendek lainnya yang tidak memerlukan manajemen state manual.

Fitur Utama:

Fire-and-forget: Tidak perlu preload, play, stop, atau unload secara manual
Auto-cleanup: Asset otomatis di-unload setelah pemutaran selesai
Opsi penghapusan file: Bisa menghapus file lokal setelah pemutaran (berguna untuk file temp)
Mengembalikan assetId: Tetap bisa kontrol playback jika diperlukan (pause, stop, dll.)

Kasus Penggunaan:

Suara notifikasi
Efek suara UI (klik tombol, alert)
Klip audio pendek yang diputar sekali
File audio sementara yang perlu dihapus

Perbandingan dengan play() biasa:

play(): Perlu langkah preload, play, dan unload manual
playOnce(): Menangani semuanya otomatis dengan satu panggilan

import { NativeAudio } from '@capgo/capacitor-native-audio';

// Simple one-shot playback
await NativeAudio.playOnce({ assetPath: 'audio/notification.mp3' });

// Play and delete the file after completion
await NativeAudio.playOnce({
  assetPath: 'file:///path/to/temp/audio.mp3',
  isUrl: true,
  deleteAfterPlay: true
});

// Get the assetId to control playback
const { assetId } = await NativeAudio.playOnce({
  assetPath: 'audio/long-track.mp3',
  autoPlay: true
});
// Later, you can stop it manually if needed
await NativeAudio.stop({ assetId });

`isPreloaded`

Cek apakah file audio sudah di-preload

import { NativeAudio } from '@capgo/capacitor-native-audio';

const result = await NativeAudio.isPreloaded({
  assetPath: 'path/to/file',
  assetId: 'asset-id-123',
});
console.log(result);

`play`

Putar file audio

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.play({ assetId: 'asset-id-123' });

`pause`

Jeda file audio

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.pause({ assetId: 'asset-id-123' });

`resume`

Lanjutkan file audio

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.resume({ assetId: 'asset-id-123' });

`loop`

Hentikan file audio

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.loop({ assetId: 'asset-id-123' });

`stop`

Hentikan file audio

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.stop({ assetId: 'asset-id-123' });

`unload`

Unload file audio

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.unload({ assetId: 'asset-id-123' });

`setVolume`

Atur volume file audio

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.setVolume({
  assetId: 'asset-id-123',
  volume: 0.5,
});

`setRate`

Set the rate of an audio file

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.setRate({
  assetId: 'asset-id-123',
  rate: 1,
});

`setCurrentTime`

Atur current time file audio

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.setCurrentTime({
  assetId: 'asset-id-123',
  time: 10,
});

`getCurrentTime`

Dapatkan waktu saat ini dari file audio

import { NativeAudio } from '@capgo/capacitor-native-audio';

const result = await NativeAudio.getCurrentTime({ assetId: 'asset-id-123' });
console.log(result);

`getDuration`

Dapatkan durasi file audio dalam satuan detik

import { NativeAudio } from '@capgo/capacitor-native-audio';

const result = await NativeAudio.getDuration({ assetId: 'asset-id-123' });
console.log(result);

`isPlaying`

Cek apakah file audio sedang diputar

import { NativeAudio } from '@capgo/capacitor-native-audio';

const result = await NativeAudio.isPlaying({ assetId: 'asset-id-123' });
console.log(result);

`clearCache`

Hapus cache audio untuk file audio remote

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.clearCache();

`setDebugMode`

Atur logging debug mode

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.setDebugMode({ enabled: true });

`deinitPlugin`

Deinisialisasi plugin dan kembalikan pengaturan audio session asli Metode ini menghentikan semua audio yang sedang diputar dan mengembalikan perubahan audio session yang dilakukan oleh plugin Gunakan ini saat Anda perlu memastikan kompatibilitas dengan plugin audio lainnya

import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.deinitPlugin();

Referensi Tipe

`ConfigureOptions`

export interface ConfigureOptions {
  /**
   * focus the audio with Audio Focus
   */
  focus?: boolean;
  /**
   * Play the audio in the background
   */
  background?: boolean;
  /**
   * Ignore silent mode, works only on iOS setting this will nuke other audio apps
   */
  ignoreSilent?: boolean;
  /**
   * Show audio playback in the notification center (iOS and Android)
   * When enabled, displays audio metadata (title, artist, album, artwork) in the system notification
   * and Control Center (iOS) or lock screen.
   *
   * **Important iOS Behavior:**
   * Enabling this option changes the audio session category to `.playback` with `.default` mode,
   * which means your app's audio will **interrupt** other apps' audio (like background music from
   * Spotify, Apple Music, etc.) instead of mixing with it. This is required for the Now Playing
   * info to appear in Control Center and on the lock screen.
   *
   * **Trade-offs:**
   * - `showNotification: true` → Shows Now Playing controls, but interrupts other audio
   * - `showNotification: false` → Audio mixes with other apps, but no Now Playing controls
   *
   * Use this when your app is the primary audio source (music players, podcast apps, etc.).
   * Disable this for secondary audio like sound effects or notification sounds where mixing
   * with background music is preferred.
   *
   * @see https://github.com/Cap-go/capacitor-native-audio/issues/202
   */
  showNotification?: boolean;
  /**
   * Enable background audio playback (Android only)
   *
   * When enabled, audio will continue playing when the app is backgrounded or the screen is locked.
   * The plugin will skip the automatic pause/resume logic that normally occurs when the app
   * enters the background or returns to the foreground.
   *
   * **Important Android Requirements:**
   * To use background playback on Android, your app must:
   * 1. Declare the required permissions in `AndroidManifest.xml`:
   *    - `<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />`
   *    - `<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />`
   *    - `<uses-permission android:name="android.permission.WAKE_LOCK" />`
   * 2. Start a Foreground Service with a media-style notification before backgrounding
   *    (the plugin does not automatically create or manage the foreground service)
   * 3. Use `showNotification: true` to display playback controls in the notification
   *
   * **Usage Example:**
   * ```typescript
   * await NativeAudio.configure({
   *   backgroundPlayback: true,
   *   showNotification: true
   * });
   * // Start your foreground service here
   * // Then preload and play audio as normal
   * ```
   *
   * @default false
   * @platform Android
   * @since 8.2.0
   */
  backgroundPlayback?: boolean;
}

`PreloadOptions`

export interface PreloadOptions {
  /**
   * Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://)
   * Supported formats:
   * - MP3, WAV (all platforms)
   * - M3U8/HLS streams (iOS and Android)
   */
  assetPath: string;
  /**
   * Asset Id, unique identifier of the file
   */
  assetId: string;
  /**
   * Volume of the audio, between 0.1 and 1.0
   */
  volume?: number;
  /**
   * Audio channel number, default is 1
   */
  audioChannelNum?: number;
  /**
   * Is the audio file a URL, pass true if assetPath is a `file://` url
   * or a streaming URL (m3u8)
   */
  isUrl?: boolean;
  /**
   * Metadata to display in the notification center when audio is playing.
   * Only used when `showNotification: true` is set in `configure()`.
   *
   * See {@link ConfigureOptions.showNotification} for important details about
   * how this affects audio mixing behavior on iOS.
   *
   * @see NotificationMetadata
   */
  notificationMetadata?: NotificationMetadata;
  /**
   * Custom HTTP headers to include when fetching remote audio files.
   * Only used when isUrl is true and assetPath is a remote URL (http/https).
   * Example: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }
   *
   * @since 7.10.0
   */
  headers?: Record<string, string>;
}

`PlayOnceOptions`

export interface PlayOnceOptions {
  /**
   * Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://)
   * Supported formats:
   * - MP3, WAV (all platforms)
   * - M3U8/HLS streams (iOS and Android)
   */
  assetPath: string;
  /**
   * Volume of the audio, between 0.1 and 1.0
   * @default 1.0
   */
  volume?: number;
  /**
   * Is the audio file a URL, pass true if assetPath is a `file://` url
   * or a streaming URL (m3u8)
   * @default false
   */
  isUrl?: boolean;
  /**
   * Automatically start playback after loading
   * @default true
   */
  autoPlay?: boolean;
  /**
   * Delete the audio file from disk after playback completes
   * Only works for local files (file:// URLs), ignored for remote URLs
   * @default false
   * @since 7.11.0
   */
  deleteAfterPlay?: boolean;
  /**
   * Metadata to display in the notification center when audio is playing.
   * Only used when `showNotification: true` is set in `configure()`.
   *
   * See {@link ConfigureOptions.showNotification} for important details about
   * how this affects audio mixing behavior on iOS.
   *
   * @see NotificationMetadata
   * @since 7.10.0
   */
  notificationMetadata?: NotificationMetadata;
  /**
   * Custom HTTP headers to include when fetching remote audio files.
   * Only used when isUrl is true and assetPath is a remote URL (http/https).
   * Example: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }
   *
   * @since 7.10.0
   */
  headers?: Record<string, string>;
}

`PlayOnceResult`

export interface PlayOnceResult {
  /**
   * The internally generated asset ID for this playback
   * Can be used to control playback (pause, stop, etc.) before completion
   */
  assetId: string;
}

`AssetPlayOptions`

export interface AssetPlayOptions {
  /**
   * Asset Id, unique identifier of the file
   */
  assetId: string;
  /**
   * Time to start playing the audio, in seconds
   */
  time?: number;
  /**
   * Delay to start playing the audio, in seconds
   */
  delay?: number;

  /**
   * Volume of the audio, between 0.1 and 1.0
   */
  volume?: number;

  /**
   * Whether to fade in the audio
   */
  fadeIn?: boolean;

  /**
   * Whether to fade out the audio
   */
  fadeOut?: boolean;

  /**
   * Fade in duration in seconds.
   * Only used if fadeIn is true.
   * Default is 1s.
   */
  fadeInDuration?: number;

  /**
   * Fade out duration in seconds.
   * Only used if fadeOut is true.
   * Default is 1s.
   */
  fadeOutDuration?: number;

  /**
   * Time in seconds from the start of the audio to start fading out.
   * Only used if fadeOut is true.
   * Default is fadeOutDuration before end of audio.
   */
  fadeOutStartTime?: number;
}

`AssetPauseOptions`

export interface AssetPauseOptions {
  /**
   * Asset Id, unique identifier of the file
   */
  assetId: string;

  /**
   * Whether to fade out the audio before pausing
   */
  fadeOut?: boolean;

  /**
   * Fade out duration in seconds.
   * Default is 1s.
   */
  fadeOutDuration?: number;
}

`AssetResumeOptions`

export interface AssetResumeOptions {
  /**
   * Asset Id, unique identifier of the file
   */
  assetId: string;

  /**
   * Whether to fade in the audio during resume
   */
  fadeIn?: boolean;

  /**
   * Fade in duration in seconds.
   * Default is 1s.
   */
  fadeInDuration?: number;
}

`Assets`

export interface Assets {
  /**
   * Asset Id, unique identifier of the file
   */
  assetId: string;
}

`AssetStopOptions`

export interface AssetStopOptions {
  /**
   * Asset Id, unique identifier of the file
   */
  assetId: string;

  /**
   * Whether to fade out the audio before stopping
   */
  fadeOut?: boolean;

  /**
   * Fade out duration in seconds.
   * Default is 1s.
   */
  fadeOutDuration?: number;
}

`AssetVolume`

export interface AssetVolume {
  /**
   * Asset Id, unique identifier of the file
   */
  assetId: string;
  /**
   * Volume of the audio, between 0.1 and 1.0
   */
  volume: number;
  /**
   * Time over which to fade to the target volume, in seconds. Default is 0s (immediate).
   */
  duration?: number;
}

`AssetRate`

export interface AssetRate {
  /**
   * Asset Id, unique identifier of the file
   */
  assetId: string;
  /**
   * Rate of the audio, between 0.1 and 1.0
   */
  rate: number;
}

`AssetSetTime`

export interface AssetSetTime {
  /**
   * Asset Id, unique identifier of the file
   */
  assetId: string;
  /**
   * Time to set the audio, in seconds
   */
  time: number;
}

Sumber Kebenaran

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

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan perilaku media dan antarmuka native, hubungkan dengan Menggunakan @capgo/capacitor-native-audio untuk kapabilitas native di Using @capgo/capacitor-native-audio, 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.