Commencer

1. Installer le package

   npm

   npm i @capgo/native-audio

   pnpm

   pnpm add @capgo/native-audio

   yarn

   yarn add @capgo/native-audio

   bun

   bun add @capgo/native-audio

2. Synchroniser avec les projets natifs

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Ajouter des fichiers audio Placez vos fichiers audio dans les dossiers de plateforme appropriés :

   • iOS : ios/App/App/sounds/
   • Android : android/app/src/main/res/raw/

Utilisation

Importez le plugin et préchargez les fichiers audio avant de les lire :

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

// Précharger les fichiers audio
const preloadAudio = async () => {
  // Préchargement simple pour les sons courts
  await NativeAudio.preload({
    assetId: 'click',
    assetPath: 'sounds/click.mp3',
    audioChannelNum: 1,
    isUrl: false
  });

  // Préchargement complexe pour la musique/audio plus long
  await NativeAudio.preloadComplex({
    assetId: 'background-music',
    assetPath: 'sounds/background.mp3',
    audioChannelNum: 1,
    volume: 0.5,
    delay: 0,
    isUrl: false
  });
};

// Lire l'audio
const playSound = async () => {
  await NativeAudio.play({
    assetId: 'click'
  });
};

// Lire avec des options
const playMusic = async () => {
  await NativeAudio.play({
    assetId: 'background-music',
    time: 0 // Commencer depuis le début
  });
};

// Boucler l'audio
const loopMusic = async () => {
  await NativeAudio.loop({
    assetId: 'background-music'
  });
};

// Arrêter l'audio
const stopMusic = async () => {
  await NativeAudio.stop({
    assetId: 'background-music'
  });
};

// Décharger quand terminé
const cleanup = async () => {
  await NativeAudio.unload({
    assetId: 'click'
  });
  await NativeAudio.unload({
    assetId: 'background-music'
  });
};

Référence API

preload(options)

Précharge un fichier audio pour une lecture simple (idéal pour les sons courts).

interface PreloadOptions {
  assetId: string;
  assetPath: string;
  audioChannelNum?: number;
  isUrl?: boolean;
}

await NativeAudio.preload({
  assetId: 'sound-effect',
  assetPath: 'sounds/effect.mp3',
  audioChannelNum: 1,
  isUrl: false
});

preloadComplex(options)

Précharge l’audio avec des options avancées (idéal pour la musique/audio de fond).

interface PreloadComplexOptions {
  assetId: string;
  assetPath: string;
  volume?: number; // 0.0 à 1.0
  audioChannelNum?: number;
  delay?: number;
  isUrl?: boolean;
  fadeDuration?: number;
}

await NativeAudio.preloadComplex({
  assetId: 'theme-song',
  assetPath: 'sounds/theme.mp3',
  volume: 0.7,
  audioChannelNum: 2,
  isUrl: false
});

play(options)

Lit un fichier audio préchargé.

interface PlayOptions {
  assetId: string;
  time?: number; // Temps de départ en secondes
}

await NativeAudio.play({
  assetId: 'sound-effect',
  time: 0
});

loop(options)

Boucle un fichier audio préchargé en continu.

await NativeAudio.loop({
  assetId: 'background-music'
});

stop(options)

Arrête la lecture d’un fichier audio.

await NativeAudio.stop({
  assetId: 'background-music'
});

pause(options)

Met en pause la lecture audio.

await NativeAudio.pause({
  assetId: 'background-music'
});

resume(options)

Reprend l’audio en pause.

await NativeAudio.resume({
  assetId: 'background-music'
});

setVolume(options)

Définit le volume pour un actif audio.

interface SetVolumeOptions {
  assetId: string;
  volume: number; // 0.0 à 1.0
}

await NativeAudio.setVolume({
  assetId: 'background-music',
  volume: 0.3
});

getDuration(options)

Obtient la durée d’un fichier audio en secondes.

const { duration } = await NativeAudio.getDuration({
  assetId: 'background-music'
});
console.log(`Durée : ${duration} secondes`);

getCurrentTime(options)

Obtient le temps de lecture actuel en secondes.

const { currentTime } = await NativeAudio.getCurrentTime({
  assetId: 'background-music'
});
console.log(`Temps actuel : ${currentTime} secondes`);

isPlaying(options)

Vérifie si l’audio est en cours de lecture.

const { isPlaying } = await NativeAudio.isPlaying({
  assetId: 'background-music'
});
console.log(`En cours de lecture : ${isPlaying}`);

unload(options)

Décharge un fichier audio de la mémoire.

await NativeAudio.unload({
  assetId: 'sound-effect'
});

Utilisation avancée

Classe gestionnaire de son

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

export class SoundManager {
  private sounds: Map<string, boolean> = new Map();
  private volume = 1.0;

  async init() {
    // Précharger tous les sons
    await this.preloadSound('click', 'sounds/click.mp3');
    await this.preloadSound('success', 'sounds/success.mp3');
    await this.preloadSound('error', 'sounds/error.mp3');

    // Précharger la musique
    await this.preloadMusic('background', 'sounds/background.mp3', 0.5);
  }

  private async preloadSound(id: string, path: string) {
    try {
      await NativeAudio.preload({
        assetId: id,
        assetPath: path,
        audioChannelNum: 1,
        isUrl: false
      });
      this.sounds.set(id, true);
    } catch (error) {
      console.error(`Échec du préchargement de ${id} :`, error);
    }
  }

  private async preloadMusic(id: string, path: string, volume: number) {
    try {
      await NativeAudio.preloadComplex({
        assetId: id,
        assetPath: path,
        volume,
        audioChannelNum: 2,
        isUrl: false
      });
      this.sounds.set(id, true);
    } catch (error) {
      console.error(`Échec du préchargement de ${id} :`, error);
    }
  }

  async playSound(id: string) {
    if (!this.sounds.has(id)) {
      console.warn(`Son ${id} non préchargé`);
      return;
    }

    try {
      await NativeAudio.play({ assetId: id });
    } catch (error) {
      console.error(`Échec de la lecture de ${id} :`, error);
    }
  }

  async playMusic(id: string) {
    if (!this.sounds.has(id)) return;

    try {
      await NativeAudio.loop({ assetId: id });
    } catch (error) {
      console.error(`Échec de la lecture de la musique ${id} :`, error);
    }
  }

  async stopMusic(id: string) {
    try {
      await NativeAudio.stop({ assetId: id });
    } catch (error) {
      console.error(`Échec de l'arrêt de ${id} :`, error);
    }
  }

  async setMasterVolume(volume: number) {
    this.volume = Math.max(0, Math.min(1, volume));

    // Mettre à jour tous les sons chargés
    for (const [id] of this.sounds) {
      await NativeAudio.setVolume({
        assetId: id,
        volume: this.volume
      });
    }
  }

  async cleanup() {
    for (const [id] of this.sounds) {
      await NativeAudio.unload({ assetId: id });
    }
    this.sounds.clear();
  }
}

Chargement depuis des URL

// Charger l'audio depuis une URL
await NativeAudio.preloadComplex({
  assetId: 'remote-audio',
  assetPath: 'https://example.com/audio.mp3',
  isUrl: true,
  volume: 0.8
});

Effets de fondu enchaîné

const fadeIn = async (assetId: string, duration: number) => {
  const steps = 20;
  const stepDuration = duration / steps;

  await NativeAudio.setVolume({ assetId, volume: 0 });
  await NativeAudio.play({ assetId });

  for (let i = 1; i <= steps; i++) {
    await new Promise(resolve => setTimeout(resolve, stepDuration));
    await NativeAudio.setVolume({
      assetId,
      volume: i / steps
    });
  }
};

const fadeOut = async (assetId: string, duration: number) => {
  const steps = 20;
  const stepDuration = duration / steps;

  for (let i = steps; i >= 0; i--) {
    await NativeAudio.setVolume({
      assetId,
      volume: i / steps
    });
    await new Promise(resolve => setTimeout(resolve, stepDuration));
  }

  await NativeAudio.stop({ assetId });
};

Bonnes pratiques

1. Précharger pendant l’initialisation de l’application

   import { App } from '@capacitor/app';
   
   App.addListener('appStateChange', async ({ isActive }) => {
     if (isActive) {
       await soundManager.init();
     }
   });

2. Gérer les erreurs avec élégance

   try {
     await NativeAudio.play({ assetId: 'sound' });
   } catch (error) {
     console.log('La lecture audio a échoué, continuation silencieuse');
   }

3. Décharger l’audio inutilisé

   // Décharger les sons lors de la sortie d'un écran
   ionViewWillLeave() {
     this.unloadScreenSounds();
   }

4. Utiliser les méthodes de préchargement appropriées

   • preload() pour les effets sonores courts (< 5 secondes)
   • preloadComplex() pour la musique et l’audio plus long

Notes sur les plateformes

iOS

• Prend en charge AAC, MP3, WAV et autres formats Core Audio
• Utilise AVAudioPlayer pour l’audio complexe
• Utilise System Sound Services pour l’audio simple
• Prend en charge l’audio en arrière-plan avec la configuration appropriée

Android

• Prend en charge les formats MP3, OGG, WAV
• Utilise SoundPool pour l’audio simple
• Utilise MediaPlayer pour l’audio complexe
• Peut nécessiter la permission WAKE_LOCK pour la lecture en arrière-plan

Placement des fichiers

iOS

Placez les fichiers dans ios/App/App/sounds/ ou créez une référence de dossier dans Xcode.

Android

Placez les fichiers dans android/app/src/main/res/raw/. Remarque : Les noms de fichiers doivent être en minuscules sans caractères spéciaux.

Problèmes courants

1. L’audio ne se lit pas

   • Assurez-vous que les fichiers sont dans les bons répertoires
   • Vérifiez la compatibilité du format de fichier
   • Vérifiez que l’assetId correspond exactement

2. Délai dans la lecture

   • Utilisez preload() pour les effets sonores
   • Préchargez avant d’avoir besoin de lire

3. Problèmes de mémoire

   • Déchargez les fichiers audio lorsqu’ils ne sont plus nécessaires
   • Ne préchargez pas trop de gros fichiers

4. Lecture en arrière-plan

   • Configurez la capacité audio en arrière-plan sur iOS
   • Gérez le focus audio sur Android