Commencer

1. Installez 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. Synchronisation 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 appropriés de la plateforme :

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

Utilisation

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

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

// Preload audio files
const preloadAudio = async () => {
  // Simple preload for short sounds
  await NativeAudio.preload({
    assetId: 'click',
    assetPath: 'sounds/click.mp3',
    audioChannelNum: 1,
    isUrl: false
  });

  // Complex preload for music/longer audio
  await NativeAudio.preloadComplex({
    assetId: 'background-music',
    assetPath: 'sounds/background.mp3',
    audioChannelNum: 1,
    volume: 0.5,
    delay: 0,
    isUrl: false
  });
};

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

// Play with options
const playMusic = async () => {
  await NativeAudio.play({
    assetId: 'background-music',
    time: 0 // Start from beginning
  });
};

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

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

// Unload when done
const cleanup = async () => {
  await NativeAudio.unload({
    assetId: 'click'
  });
  await NativeAudio.unload({
    assetId: 'background-music'
  });
};

API Référence

préchargement (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/l’audio de fond).

interface PreloadComplexOptions {
  assetId: string;
  assetPath: string;
  volume?: number; // 0.0 to 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
});

jouer(options)

Lit un fichier audio préchargé.

interface PlayOptions {
  assetId: string;
  time?: number; // Start time in seconds
}

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

boucle(options)

Met en boucle un fichier audio préchargé en continu.

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

arrêter(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'
});

CV(options)

Reprend l’audio en pause.

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

setVolume(options)

Définit le volume d’un élément audio.

interface SetVolumeOptions {
  assetId: string;
  volume: number; // 0.0 to 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(`Duration: ${duration} seconds`);

getCurrentTime (options)

Obtient la durée de lecture actuelle en secondes.

const { currentTime } = await NativeAudio.getCurrentTime({
  assetId: 'background-music'
});
console.log(`Current time: ${currentTime} seconds`);

est en train de jouer (options)

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

const { isPlaying } = await NativeAudio.isPlaying({
  assetId: 'background-music'
});
console.log(`Is playing: ${isPlaying}`);

décharger (options)

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

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

Utilisation avancée

Classe de 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() {
    // Preload all sounds
    await this.preloadSound('click', 'sounds/click.mp3');
    await this.preloadSound('success', 'sounds/success.mp3');
    await this.preloadSound('error', 'sounds/error.mp3');

    // Preload music
    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(`Failed to preload ${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(`Failed to preload ${id}:`, error);
    }
  }

  async playSound(id: string) {
    if (!this.sounds.has(id)) {
      console.warn(`Sound ${id} not preloaded`);
      return;
    }

    try {
      await NativeAudio.play({ assetId: id });
    } catch (error) {
      console.error(`Failed to play ${id}:`, error);
    }
  }

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

    try {
      await NativeAudio.loop({ assetId: id });
    } catch (error) {
      console.error(`Failed to play music ${id}:`, error);
    }
  }

  async stopMusic(id: string) {
    try {
      await NativeAudio.stop({ assetId: id });
    } catch (error) {
      console.error(`Failed to stop ${id}:`, error);
    }
  }

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

    // Update all loaded sounds
    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 à partir d’URL

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

Effets de fondu entrant/sortant

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

## meilleures pratiques

1. Préchargement lors de 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('Audio playback failed, continuing silently');
   }

3. Décharger l’audio inutilisé

   // Unload sounds when leaving a screen
   ionViewWillLeave() {
     this.unloadScreenSounds();
   }

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

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

## Remarques sur la plate-forme

iOS

• Prend en charge AAC, MP3, WAV et autres formats Core Audio
• Utilise AVAudioPlayer pour l’audio complexe
• Utilise System Sound Services pour un son simple
• Prend en charge l’audio de fond avec une configuration appropriée

Android

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

Placement de 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 et sans caractères spéciaux.

Problèmes courants

1. Le son ne joue pas

   • Assurez-vous que les fichiers sont dans les bons répertoires
   • Vérifier la compatibilité des formats de fichiers
   • Vérifier que l’assetId correspond exactement

2. Retard de lecture

   • Utilisez preload() pour les effets sonores
   • Préchargez avant de devoir jouer

3. Problèmes de mémoire

   • Déchargez les fichiers audio lorsque vous n’en avez pas besoin
   • Ne préchargez pas trop de fichiers volumineux

4. Lecture en arrière-plan

   • Configurer la capacité audio de fond sur iOS
   • Gérer le focus audio sur Android