시작하기

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

        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.

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

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

가져오기

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

빠른 시작

한 번만 설정하고 클립을 프리로드하여 다음을 통해 UI 피드백을 재생하세요: playOnce() 별도 관리 없이 즉시 재생되는 사운드용.

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

예시: 음악 스타일 세션

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

예제: 오디오 세션 해제

다른 플러그인이 오디오를 독점적으로 제어해야 할 때는 재생을 중단하고 다음을 호출하세요. deinitPlugin() 이전 세션을 복원하려면.

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

자주 하는 실수

Now Playing vs 믹싱: showNotification: true iOS에서는 백그라운드 음악을 중단시키는 재생 카테고리로 전환됩니다.
Android 백그라운드: 활성화하려면 backgroundPlayback README에 설명된 필수 포그라운드 서비스를 시작하고 권한을 설정한 후에만 하세요.
Web 리스너: 웹에서는 재생 상태 리스너 이벤트가 발생하지 않으므로, 해당 이벤트에 의존하는 UI는 별도로 처리해야 합니다.

API 개요

`configure`

오디오 플레이어 설정하기

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

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

`preload`

오디오 파일 로드하기

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

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

`playOnce`

자동 정리 기능과 함께 오디오 파일 1회 재생

알림음, UI 피드백 또는 별도의 상태 관리가 필요 없는 짧은 오디오 클립과 같이 단순하고 일회성인 오디오 재생을 위해 설계된 메서드입니다.

주요 기능:

Fire-and-forget: 수동으로 preload, play, stop 또는 unload할 필요 없음
Auto-cleanup: 재생이 완료되면 에셋이 자동으로 unload됨
선택적 파일 삭제: 재생 후 로컬 파일 삭제 가능 (임시 파일에 유용)
assetId 반환: 필요 시 재생 제어 가능 (pause, stop 등)

사용 사례:

알림음
UI 효과음 (버튼 클릭, 알림)
한 번만 재생되는 짧은 오디오 클립
정리가 필요한 임시 오디오 파일

일반 play()와의 비교:

play(): 수동으로 preload, play, unload 단계를 거쳐야 함
playOnce(): 단 한 번의 호출로 모든 과정을 자동 처리

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`

오디오 파일이 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`

오디오 파일 재생

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

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

`pause`

오디오 파일 일시 정지

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

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

`resume`

오디오 파일 이어서 재생

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

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

`loop`

오디오 파일 정지

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

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

`stop`

오디오 파일 정지

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

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

`unload`

오디오 파일 언로드하기

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

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

`setVolume`

오디오 파일 볼륨 설정하기

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

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

`setRate`

오디오 파일 재생 속도 설정하기

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

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

`setCurrentTime`

오디오 파일 현재 재생 시간 설정하기

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

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

`getCurrentTime`

오디오 파일의 현재 재생 시간 가져오기

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

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

`getDuration`

오디오 파일의 길이를 초 단위로 가져오기

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

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

`isPlaying`

오디오 파일 재생 여부 확인하기

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

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

`clearCache`

원격 오디오 파일의 오디오 캐시 삭제하기

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

await NativeAudio.clearCache();

`setDebugMode`

디버그 모드 로깅 설정

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

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

`deinitPlugin`

플러그인을 초기화하고 기존 오디오 세션 설정을 복구합니다. 이 메서드는 재생 중인 모든 오디오를 중단하고 플러그인에 의해 변경된 오디오 세션 설정을 원래대로 되돌립니다. 다른 오디오 플러그인과의 호환성을 보장해야 할 때 사용하세요.

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

await NativeAudio.deinitPlugin();

타입 레퍼런스

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

Source of Truth

이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.

시작하기 다음 단계

사용 중이라면 시작하기 네이티브 미디어 및 인터페이스 동작을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-native-audio 사용하기 @capgo/capacitor-native-audio 사용하기의 네이티브 기능에 대해서는, @capgo/capacitor-live-activities 사용 @capgo/capacitor-live-activities 사용에서의 네이티브 기능, @capgo/capacitor-live-activities @capgo/capacitor-live-activities의 구현 세부 사항, @capgo/capacitor-video-player 사용 @capgo/capacitor-video-player 사용에서의 네이티브 기능 및 @capgo/capacitor-video-player @capgo/capacitor-video-player.의 구현 세부 사항