Erste Schritte

1. Installieren Sie das Paket

   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. Synchronisieren Sie mit nativen Projekten

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Fügen Sie Audiodateien hinzu Platzieren Sie Ihre Audiodateien in den entsprechenden Plattformordnern:

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

Verwendung

Importieren Sie das Plugin und laden Sie Audiodateien vor, bevor Sie sie abspielen:

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

// Audiodateien vorladen
const preloadAudio = async () => {
  // Einfaches Vorladen für kurze Sounds
  await NativeAudio.preload({
    assetId: 'click',
    assetPath: 'sounds/click.mp3',
    audioChannelNum: 1,
    isUrl: false
  });

  // Komplexes Vorladen für Musik/längere Audiodateien
  await NativeAudio.preloadComplex({
    assetId: 'background-music',
    assetPath: 'sounds/background.mp3',
    audioChannelNum: 1,
    volume: 0.5,
    delay: 0,
    isUrl: false
  });
};

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

// Mit Optionen abspielen
const playMusic = async () => {
  await NativeAudio.play({
    assetId: 'background-music',
    time: 0 // Von Anfang an starten
  });
};

// Audio in Schleife abspielen
const loopMusic = async () => {
  await NativeAudio.loop({
    assetId: 'background-music'
  });
};

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

// Entladen wenn fertig
const cleanup = async () => {
  await NativeAudio.unload({
    assetId: 'click'
  });
  await NativeAudio.unload({
    assetId: 'background-music'
  });
};

API-Referenz

preload(options)

Lädt eine Audiodatei für einfache Wiedergabe vor (am besten für kurze Sounds).

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)

Lädt Audio mit erweiterten Optionen vor (am besten für Musik/Hintergrundaudio).

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

Spielt eine vorgeladene Audiodatei ab.

interface PlayOptions {
  assetId: string;
  time?: number; // Startzeit in Sekunden
}

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

loop(options)

Spielt eine vorgeladene Audiodatei in Schleife ab.

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

stop(options)

Stoppt die Wiedergabe einer Audiodatei.

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

pause(options)

Pausiert die Audio-Wiedergabe.

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

resume(options)

Setzt pausiertes Audio fort.

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

setVolume(options)

Setzt die Lautstärke für ein Audio-Asset.

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

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

getDuration(options)

Ermittelt die Dauer einer Audiodatei in Sekunden.

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

getCurrentTime(options)

Ermittelt die aktuelle Wiedergabezeit in Sekunden.

const { currentTime } = await NativeAudio.getCurrentTime({
  assetId: 'background-music'
});
console.log(`Aktuelle Zeit: ${currentTime} Sekunden`);

isPlaying(options)

Überprüft, ob Audio gerade abgespielt wird.

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

unload(options)

Entlädt eine Audiodatei aus dem Speicher.

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

Erweiterte Verwendung

Sound Manager-Klasse

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

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

  async init() {
    // Alle Sounds vorladen
    await this.preloadSound('click', 'sounds/click.mp3');
    await this.preloadSound('success', 'sounds/success.mp3');
    await this.preloadSound('error', 'sounds/error.mp3');

    // Musik vorladen
    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(`Fehler beim Vorladen von ${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(`Fehler beim Vorladen von ${id}:`, error);
    }
  }

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

    try {
      await NativeAudio.play({ assetId: id });
    } catch (error) {
      console.error(`Fehler beim Abspielen von ${id}:`, error);
    }
  }

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

    try {
      await NativeAudio.loop({ assetId: id });
    } catch (error) {
      console.error(`Fehler beim Abspielen von Musik ${id}:`, error);
    }
  }

  async stopMusic(id: string) {
    try {
      await NativeAudio.stop({ assetId: id });
    } catch (error) {
      console.error(`Fehler beim Stoppen von ${id}:`, error);
    }
  }

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

    // Alle geladenen Sounds aktualisieren
    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();
  }
}

Laden von URLs

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

Ein-/Ausblenden-Effekte

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

Best Practices

1. Während der App-Initialisierung vorladen

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

2. Fehler elegant behandeln

   try {
     await NativeAudio.play({ assetId: 'sound' });
   } catch (error) {
     console.log('Audio-Wiedergabe fehlgeschlagen, wird ohne Ton fortgesetzt');
   }

3. Nicht verwendetes Audio entladen

   // Sounds entladen beim Verlassen eines Bildschirms
   ionViewWillLeave() {
     this.unloadScreenSounds();
   }

4. Geeignete Vorlade-Methoden verwenden

   • preload() für kurze Soundeffekte (< 5 Sekunden)
   • preloadComplex() für Musik und längere Audiodateien

Plattform-Hinweise

iOS

• Unterstützt AAC, MP3, WAV und andere Core Audio-Formate
• Verwendet AVAudioPlayer für komplexes Audio
• Verwendet System Sound Services für einfaches Audio
• Unterstützt Hintergrundaudio mit entsprechender Konfiguration

Android

• Unterstützt MP3, OGG, WAV-Formate
• Verwendet SoundPool für einfaches Audio
• Verwendet MediaPlayer für komplexes Audio
• Benötigt möglicherweise WAKE_LOCK-Berechtigung für Hintergrundwiedergabe

Dateiplatzierung

iOS

Platzieren Sie Dateien in ios/App/App/sounds/ oder erstellen Sie eine Ordnerreferenz in Xcode.

Android

Platzieren Sie Dateien in android/app/src/main/res/raw/. Hinweis: Dateinamen müssen in Kleinbuchstaben und ohne Sonderzeichen sein.

Häufige Probleme

1. Audio wird nicht abgespielt

   • Stellen Sie sicher, dass Dateien in den richtigen Verzeichnissen sind
   • Überprüfen Sie die Kompatibilität des Dateiformats
   • Stellen Sie sicher, dass assetId genau übereinstimmt

2. Verzögerung bei der Wiedergabe

   • Verwenden Sie preload() für Soundeffekte
   • Vorladen, bevor Sie abspielen müssen

3. Speicherprobleme

   • Audiodateien entladen, wenn sie nicht benötigt werden
   • Nicht zu viele große Dateien vorladen

4. Hintergrundwiedergabe

   • Hintergrundaudio-Fähigkeit auf iOS konfigurieren
   • Audio-Fokus auf Android behandeln