Getting Started

설치

npm install @capgo/capacitor-native-audio
npx cap sync

수입

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

API 개요

configure

음악 재생기를 설정합니다.

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

await NativeAudio.configure({} as ConfigureOptions);

preload

음성 파일을 불러오기

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

await NativeAudio.preload({} as PreloadOptions);

playOnce

자동으로 정리되는 한 번만 재생하는 음성 파일

알림 소리, UI 피드백, 또는 다른 짧은 음성 클립이 필요할 때 수동 상태 관리가 필요하지 않아도 되는 단순한 음성 재생을 위한 메소드

주요 기능:

• Fire-and-forget: 수동으로 미리 로드, 재생, 중지, 또는 언로드할 필요가 없습니다
• Auto-cleanup: 재생이 완료되면 자원은 자동으로 언로드됩니다
• Optional file deletion: 재생 후 로컬 파일을 삭제할 수 있습니다 (임시 파일에 유용합니다)
• __CAPGO_KEEP_0__ ID: __CAPGO_KEEP_0__을 여전히 제어할 수 있습니다 (일시 정지, 중단 등)

사용 사례:

• 알림 소리
• UI 소리 효과 (버튼 클릭, 알림)
• 한 번만 재생하는 짧은 오디오 클립
• 임시 오디오 파일이 자동으로 삭제되어야 함

정규 play()와의 비교:

• play(): 수동으로 미리 로드, 재생, 언로드 단계가 필요합니다
• 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

음악 파일이 미리 로드되어 있는지 확인하세요

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

await NativeAudio.isPreloaded({} as PreloadOptions);

play

음악 파일을 재생하세요

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

await NativeAudio.play({} as AssetPlayOptions);

pause

음악 파일을 정지하세요

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

await NativeAudio.pause({} as AssetPauseOptions);

resume

음악 파일을 재개하세요

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

await NativeAudio.resume({} as AssetResumeOptions);

loop

__CAPGO_KEEP_0__를 중지합니다.

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

await NativeAudio.loop({} as Assets);

stop

__CAPGO_KEEP_0__를 중지합니다.

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

await NativeAudio.stop({} as AssetStopOptions);

unload

__CAPGO_KEEP_0__를 해제합니다.

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

await NativeAudio.unload({} as Assets);

setVolume

__CAPGO_KEEP_0__의 볼륨을 설정합니다.

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

await NativeAudio.setVolume({} as AssetVolume);

setRate

__CAPGO_KEEP_0__의 오디오 파일 속도 설정

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

await NativeAudio.setRate({} as AssetRate);

setCurrentTime

__CAPGO_KEEP_0__의 오디오 파일 현재 시간 설정

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

await NativeAudio.setCurrentTime({} as AssetSetTime);

getCurrentTime

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

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

await NativeAudio.getCurrentTime({} as Assets);

getDuration

__CAPGO_KEEP_0__의 오디오 파일 길이 가져오기 (초 단위)

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

await NativeAudio.getDuration({} as Assets);

isPlaying

음악 파일이 재생 중인지 확인합니다.

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

await NativeAudio.isPlaying({} as Assets);

clearCache

remote 음악 파일의 캐시를 삭제합니다.

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

await NativeAudio.clearCache();

setDebugMode

디버그 모드 로깅을 설정합니다.

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

await NativeAudio.setDebugMode({} as { enabled: boolean });

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

실질적 진원지

플러그인에서 생성된 이 페이지는 src/definitions.tsAPI이 업스트림에서 변경될 때 다시 싱크를 실행하세요.

Getting Started

Capgo를 사용하여 Getting Started native 미디어 및 인터페이스 동작을 계획하려면 Capgo를 @capgo/capacitor-native-audio와 연결하세요. Capgo를 @capgo/capacitor-native-audio와 연결하세요. Using @capgo/capacitor-live-activities native 기능을 위해 @capgo/capacitor-live-activities를 사용합니다. @capgo/capacitor-live-activities @capgo/capacitor-live-activities의 구현 세부 사항을 위해 사용합니다. Using @capgo/capacitor-video-player native 기능을 위해 Using @capgo/capacitor-video-player를 사용합니다. @capgo/capacitor-video-player @capgo/capacitor-video-player의 구현 세부 사항을 위해 사용합니다.