시작하기
이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
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-audiobunx cap sync가져오기
“Import” 섹션import { NativeAudio } from '@capgo/capacitor-native-audio';빠른 시작
“빠른 시작” 섹션한 번 설정하고 클립을 미리 로드한 뒤 UI 피드백을 재생하세요 playOnce() 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 });예시: 음악 스타일 세션
“예시: 음악 스타일 세션” 섹션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: trueiOS에서는 백그라운드 음악을 중단시키는 재생 카테고리로 전환됩니다. - Android 백그라운드: 활성화하려면
backgroundPlaybackREADME에 설명된 필수 포그라운드 서비스를 시작하고 권한을 설정한 후에만 하세요. - Web 리스너:
playbackStateWeb에서 플러그인 전송 메서드가 재생 상태(재생, 일시정지, 재개, 반복, 완료 포함)를 변경할 때 발생됩니다.
API 개요
“API 개요” 섹션configure
“configure” 섹션오디오 플레이어 설정
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.configure({ focus: false, background: false, ignoreSilent: false, showNotification: false, backgroundPlayback: false,});preload
“preload” 섹션오디오 파일 로드
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.preload({ assetPath: 'path/to/file', assetId: 'asset-id-123',});playOnce
“playOnce” 섹션오디오 파일을 자동 정리와 함께 한 번 재생
알림음, UI 피드백 또는 수동 상태 관리가 필요 없는 짧은 오디오 클립처럼 단순한 단발성 오디오 재생을 위해 설계된 메서드입니다.
주요 기능:
- Fire-and-forget: 수동으로 preload, play, stop 또는 unload할 필요가 없음
- 자동 정리: 재생이 완료되면 에셋이 자동으로 unload됨
- 파일 삭제 옵션: 재생 후 로컬 파일 삭제 가능 (임시 파일 관리에 유용)
- assetId 반환: 필요 시 재생 제어 가능 (pause, stop 등)
사용 사례:
- 알림음
- UI 효과음 (버튼 클릭, 알림)
- 한 번만 재생되는 짧은 오디오 클립
- 정리해야 하는 임시 오디오 파일
일반적인 play()와의 비교:
play(): 수동으로 preload, play, unload 단계가 필요합니다playOnce(): 단일 호출로 모든 것을 자동으로 처리합니다
import { NativeAudio } from '@capgo/capacitor-native-audio';
// Simple one-shot playbackawait NativeAudio.playOnce({ assetPath: 'audio/notification.mp3' });
// Play and delete the file after completionawait NativeAudio.playOnce({ assetPath: 'file:///path/to/temp/audio.mp3', isUrl: true, deleteAfterPlay: true});
// Get the assetId to control playbackconst { assetId } = await NativeAudio.playOnce({ assetPath: 'audio/long-track.mp3', autoPlay: true});// Later, you can stop it manually if neededawait NativeAudio.stop({ assetId });isPreloaded
“isPreloaded” 섹션오디오 파일이 미리 로드되었는지 확인
import { NativeAudio } from '@capgo/capacitor-native-audio';
const result = await NativeAudio.isPreloaded({ assetPath: 'path/to/file', assetId: 'asset-id-123',});console.log(result);play
“play” 섹션오디오 파일 재생
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.play({ assetId: 'asset-id-123' });pause
“pause” 섹션오디오 파일 일시 정지
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.pause({ assetId: 'asset-id-123' });resume
“resume” 섹션오디오 파일 이어서 재생
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.resume({ assetId: 'asset-id-123' });loop
“loop” 섹션오디오 파일 정지
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.loop({ assetId: 'asset-id-123' });stop
“stop” 섹션오디오 파일 정지
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.stop({ assetId: 'asset-id-123' });unload
“unload” 섹션오디오 파일 언로드
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.unload({ assetId: 'asset-id-123' });setVolume
“setVolume” 섹션오디오 파일 볼륨 설정
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.setVolume({ assetId: 'asset-id-123', volume: 0.5,});setRate
“setRate” 섹션오디오 파일 재생 속도 설정
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.setRate({ assetId: 'asset-id-123', rate: 1,});setCurrentTime
“setCurrentTime” 섹션오디오 파일의 현재 재생 위치 설정
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.setCurrentTime({ assetId: 'asset-id-123', time: 10,});getCurrentTime
“getCurrentTime” 섹션오디오 파일의 현재 재생 시간 가져오기
import { NativeAudio } from '@capgo/capacitor-native-audio';
const result = await NativeAudio.getCurrentTime({ assetId: 'asset-id-123' });console.log(result);getDuration
“getDuration” 섹션오디오 파일의 재생 시간(초) 가져오기
import { NativeAudio } from '@capgo/capacitor-native-audio';
const result = await NativeAudio.getDuration({ assetId: 'asset-id-123' });console.log(result);isPlaying
“isPlaying” 섹션오디오 파일 재생 여부 확인
import { NativeAudio } from '@capgo/capacitor-native-audio';
const result = await NativeAudio.isPlaying({ assetId: 'asset-id-123' });console.log(result);clearCache
“clearCache” 섹션원격 오디오 파일의 오디오 캐시 지우기
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.clearCache();setDebugMode
“setDebugMode” 섹션디버그 모드 로깅 설정
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.setDebugMode({ enabled: true });deinitPlugin
“deinitPlugin” 섹션플러그인 초기화를 해제하고 원래 오디오 세션 설정을 복원합니다 이 메서드는 재생 중인 모든 오디오를 중지하고 플러그인이 적용한 오디오 세션 변경 사항을 모두 되돌립니다 다른 오디오 플러그인과의 호환성을 보장해야 할 때 사용하세요
import { NativeAudio } from '@capgo/capacitor-native-audio';
await NativeAudio.deinitPlugin();타입 레퍼런스
“타입 참조” 섹션ConfigureOptions
“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
“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
“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
“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
“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
“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
“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
“Assets” 섹션export interface Assets { /** * Asset Id, unique identifier of the file */ assetId: string;}AssetStopOptions
“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
“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
“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
“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
“Source Of Truth” 섹션이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.
시작하기 다음 단계
“Getting Started에서 계속하기” 섹션사용 중이라면 시작하기 네이티브 미디어 및 인터페이스 동작을 계획하려면, 이를 다음 항목과 연결하세요: @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.의 구현 세부 사항