Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

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

Importer

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

Démarrage rapide

Configurez une seule fois, préchargez un clip et jouez un retour UI avec playOnce() pour les sons de type « 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 });

Exemple : session de style musical

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

Exemple : libérer la session audio

Lorsqu'un autre plugin nécessite le contrôl’exclusif de l'audio, arrêtez la lecture et appelez deinitPlugin() pour restaurer la session précédente.

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

Erreurs courantes

• Now Playing vs mixage: showNotification: true sur iOS bascule vers une catégorie de lecture qui interrompt la musique de fond.
• Arrière-plan Android: activer backgroundPlayback uniquement après avoir lancé le service de premier plan requis et les permissions du README.
• Écouteurs web: les événements d'écoute de l'état de lecture ne sont pas émis sur le web ; protégez l'UI qui en dépend.

Aperçu de API

configure

Configurer le lecteur audio

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

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

preload

Charger un fichier audio

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

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

playOnce

Lire un fichier audio une seule fois avec nettoyage automatique

Méthode conçue pour une lecture audio simple et ponctuelle, comme des sons de notification, des retours UI ou d'autres clips audio courts ne nécessitant pas de gestion manuelle d'état.

Fonctionnalités clés :

• Fire-and-forget: Pas besoin de précharger, lire, arrêter ou décharger manuellement
• Auto-cleanup: L'asset est automatiquement déchargé une fois la lecture terminée
• Suppression de fichier optionnelle: Peut supprimer les fichiers locaux après la lecture (utile pour les fichiers temporaires)
• Retourne l'assetId: Peut toujours contrôler la lecture si nécessaire (pause, stop, etc.)

Cas d'usage :

• Sons de notification
• Effets sonores d'interface (clics, alertes)
• Clips audio courts joués une seule fois
• Fichiers audio temporaires à nettoyer

Comparaison avec play() classique :

• play(): Nécessite le préchargement, la lecture et le déchargement manuels
• playOnce(): Gère tout automatiquement avec un seul appel

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

Vérifier si un fichier audio est préchargé

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

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

play

Lire un fichier audio

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

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

pause

Mettre en pause un fichier audio

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

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

resume

Reprendre un fichier audio

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

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

loop

Arrêter un fichier audio

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

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

stop

Arrêter un fichier audio

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

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

unload

Décharger un fichier audio

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

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

setVolume

Régler le volume d'un fichier audio

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

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

setRate

Régler la vitesse de lecture d'un fichier audio

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

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

setCurrentTime

Définir la position de lecture d'un fichier audio

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

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

getCurrentTime

Obtenir l'heure actuelle d'un fichier audio

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

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

getDuration

Obtenir la durée d'un fichier audio en secondes

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

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

isPlaying

Check if an audio file is playing

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

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

clearCache

Vider le cache audio des fichiers audio distants

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

await NativeAudio.clearCache();

setDebugMode

Activer les logs en mode debug

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

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

deinitPlugin

Désinitialiser le plugin et restaurer les paramètres d'origine de la session audio Cette méthode arrête toute lecture audio en cours et annule toutes les modifications apportées à la session audio par le plugin Utilisez cette méthode pour garantir la compatibilité avec d'autres plugins audio

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

await NativeAudio.deinitPlugin();

Référence de type

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 de vérité

Cette page est générée à partir de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utiliser @capgo/capacitor-native-audio pour la fonctionnalité native dans « Utiliser @capgo/capacitor-native-audio », Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Utiliser @capgo/capacitor-video-player pour la capacité native dans Utiliser @capgo/capacitor-video-player, et @capgo/capacitor-video-player pour le détail d'implémentation dans @capgo/capacitor-video-player.