Empezando

1. Instalar el paquete

   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. Sincronización con proyectos nativos

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Agregar archivos de audio Coloque sus archivos de audio en las carpetas de la plataforma apropiadas:

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

Uso

Importe el complemento y precargue los archivos de audio antes de reproducirlos:

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 Referencia

precarga (opciones)

Precarga un archivo de audio para una reproducción sencilla (mejor para sonidos cortos).

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

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

precargaComplejo(opciones)

Precarga audio con opciones avanzadas (mejor para música/audio de fondo).

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

jugar(opciones)

Reproduce un archivo de audio precargado.

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

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

bucle (opciones)

Realiza un bucle continuo de un archivo de audio precargado.

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

detener(opciones)

Deja de reproducir un archivo de audio.

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

pausa (opciones)

Pausa la reproducción de audio.

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

currículum (opciones)

Reanuda el audio en pausa.

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

establecerVolumen(opciones)

Establece el volumen de un recurso de audio.

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

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

obtenerDuración(opciones)

Obtiene la duración de un archivo de audio en segundos.

const { duration } = await NativeAudio.getDuration({
  assetId: 'background-music'
});
console.log(`Duration: ${duration} seconds`);

getCurrentTime(opciones)

Obtiene el tiempo de reproducción actual en segundos.

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

está reproduciendo (opciones)

Comprueba si el audio se está reproduciendo actualmente.

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

descargar (opciones)

Descarga un archivo de audio de la memoria.

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

Uso avanzado

Clase de administrador de sonido

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

Cargando desde URL

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

Efectos de aparición y desaparición gradual

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

Mejores prácticas

1. Precarga durante la inicialización de la aplicación

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

2. Maneja los errores con elegancia

   try {
     await NativeAudio.play({ assetId: 'sound' });
   } catch (error) {
     console.log('Audio playback failed, continuing silently');
   }

3. Descargar audio no utilizado

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

4. Utilice métodos de precarga adecuados

   • preload() para efectos de sonido cortos (< 5 segundos)
   • preloadComplex() para música y audio más largo

Notas de plataforma

iOS

• Admite AAC, MP3, WAV y otros formatos Core Audio
• Utiliza AVAudioPlayer para audio complejo
• Utiliza System Sound Services para audio simple
• Admite audio de fondo con la configuración adecuada

Android

• Soporta formatos MP3, OGG, WAV
• Utiliza SoundPool para audio simple
• Utiliza MediaPlayer para audio complejo
• Puede requerir permiso WAKE_LOCK para reproducción en segundo plano

Colocación de archivos

iOS

Coloque archivos en ios/App/App/sounds/ o cree una referencia de carpeta en Xcode.

Android

Coloque archivos en android/app/src/main/res/raw/. Nota: Los nombres de los archivos deben estar en minúsculas y sin caracteres especiales.

Problemas comunes

1. El audio no se reproduce

   • Asegúrese de que los archivos estén en los directorios correctos.
   • Verificar la compatibilidad del formato de archivo
   • Verificar que el identificador de activo coincida exactamente

2. Retraso en la reproducción

   • Utilice preload() para efectos de sonido
   • Precarga antes de que necesites jugar

3. Problemas de memoria

   • Descargar archivos de audio cuando no sea necesario
   • No precargues demasiados archivos grandes

4. Reproducción en segundo plano

   • Configurar la capacidad de audio de fondo en iOS
   • Manejar el enfoque de audio en Android