Package pi.resources.sound

Class AudioEngine

java.lang.Object
pi.resources.sound.AudioEngine
public final class AudioEngine extends Object
Die AudioEngine-Klasse bietet Methoden an, um Klänge (Sound) und Musik (Music) im Spiel wiederzugeben.

Jede Audio-Datei kann sowohl als Musik als auch als Klang abgespielt. Der Hauptunterschied zwischen Musik und Klang ist: Die playMusic()-Methoden ermöglichen eine feinere Steuerung der Wiedergabe durch zwei Parameter:

  1. Parameter restart: Ob die aktuelle Musikwiedergabe von neuem gestartet werden kann.
  2. Parameter stop: Ob die neu gestartet Musikwiedergabe eine laufende Musikwiedergabe stoppen soll.

Die AudioEngine kann standardmäßig .wav, .mp3 und .ogg Dateien abspielen. Wenn andere Dateierweiterungen benötigt werden, muss eine eigene SPI-Implementierung geschrieben und dem Projekt hinzugefügt werden.

Author:
Steffen Wilke, Matthias Wilke

  • Field Details

  • Method Details

    • getInstance

      @API public static AudioEngine getInstance()
      Liefert die Singleton-Instanz der AudioEngine.
      Returns:
      Die Singleton-Instanz.

    • playSound

      @API public SoundPlayback playSound(String filePath)
      Spielt den Klang einmalig ab, der durch einen Dateipfad als Zeichenkette angegeben wird.
      Parameters:
      filePath - Der Pfad zur Audiodatei als Zeichenkette.
      Returns:
      Die gestartete Klangwiedergabe.

    • playSound

      @API public SoundPlayback playSound(String filePath, boolean loop)
      Spielt den Klang ab, der durch einen Dateipfad als Zeichenkette angegeben wird.
      Parameters:
      filePath - Der Pfad zur Audiodatei als Zeichenkette.
      loop - Gibt an, ob der Klang in einer Schleife abgespielt werden soll.
      Returns:
      Die gestartete Klangwiedergabe.

    • playSound

      @API public SoundPlayback playSound(Sound sound, boolean loop)
      Spielt den Klang ab, der als Sound-Objekt angegeben wird.
      Parameters:
      sound - Der abzuspielende Klang.
      loop - Gibt an, ob der Klang in einer Schleife abgespielt werden soll.
      Returns:
      Die gestartete Klangwiedergabe oder null, falls kein Klang übergeben wurde.

    • sound

      @API public Sound sound(String filePath)
      Liefert den Sound zur angegebenen Datei.
      Parameters:
      filePath - Der Pfad zur Audiodatei als Zeichenkette.
      Returns:
      Der geladene Klang.

    • createSoundPlayback

      @API public @NonNull SoundPlayback createSoundPlayback(Sound sound, boolean loop)
      Erzeugt ein SoundPlayback-Objekt, das vor dem Start konfiguriert werden kann.

      Im Gegensatz zu den playSound-Methoden muss das von dieser Methode zurückgegebene SoundPlayback-Objekt manuell mit Playback.start() gestartet werden. Die benötigten Ressourcen werden jedoch sofort beim Aufruf dieser Methode reserviert und bleiben belegt, bis die Wiedergabe abgebrochen oder beendet wird.

      Parameters:
      sound - Der abzuspielende Klang.
      loop - Gibt an, ob der Klang in einer Schleife abgespielt werden soll.
      Returns:
      Ein konfigurierbares SoundPlayback-Objekt, das manuell gestartet werden muss.

    • createSoundPlayback

      @API public SoundPlayback createSoundPlayback(String filePath, boolean loop)
      Erzeugt ein SoundPlayback-Objekt zur angegebenen Datei.
      Parameters:
      filePath - Der Pfad zur Audiodatei als Zeichenkette.
      loop - Gibt an, ob der Klang in einer Schleife abgespielt werden soll.
      Returns:
      Ein konfigurierbares SoundPlayback-Objekt.

    • allSounds

      @API @Getter public Collection<SoundPlayback> allSounds()
      Liefert eine Liste mit allen Klangwiedergaben.
      Returns:
      Eine Liste mit allen Klangwiedergaben.
      Since:
      0.47.0

    • addSound

      @API public void addSound(SoundPlayback playback)
      Fügt eine Klangwiedergabe zur internen Verwaltung hinzu.
      Parameters:
      playback - Die zu verwaltende Klangwiedergabe.

    • playMusic

      @API public MusicPlayback playMusic(String music)
      Spielt die als Zeichenkette angegebene Audio-Datei in einer Endlosschleife ab.playbacks.size()

      Wird diese Audio-Datei bereits abgespielt, so wird diese Wiedergabe nicht unterbrochen. Der Aufruf dieser Methode ist dann ohne Wirkung.

      Parameters:
      music - Die als Zeichenkette angegebene Audio-Datei, die abgespielt werden soll.
      Returns:
      Ermöglicht die Steuerung der Musikwiedergabe.

    • playMusic

      @API public MusicPlayback playMusic(Sound sound)
      Setzt die aktuell abgespielte Spur auf einen LoopedMusic mit dem angegebenen Musik-Sound.

      Hat keine Wirkung, wenn die angegebene Spur bereits läuft.

      Parameters:
      sound - Der Klang, der abgespielt werden soll.
      Returns:
      Ermöglicht die Steuerung der Musikwiedergabe.

    • playMusic

      @API public MusicPlayback playMusic(Music music)
      Setzt die aktuell abgespielte Audiospur auf die angegebene Audiospur. Hat keine Wirkung, wenn die angegebene Spur bereits läuft.
      Parameters:
      music - Die Audiospur, die gespielt werden soll.
      Returns:
      Ermöglicht die Steuerung der Musikwiedergabe.

    • playMusic

      @API public MusicPlayback playMusic(Music music, boolean restart)
      Setzt die aktuell abgespielte Audiospur auf die angegebene Audiospur.
      Parameters:
      music - Die Audiospur, die gespielt werden soll.
      restart - Ob die laufende Musikwiedergabe der eigenen Musik (bestimmt mit Object.equals(Object)) neu gestartet werden soll.
      Returns:
      Ermöglicht die Steuerung der Musikwiedergabe.

    • playMusic

      @API public MusicPlayback playMusic(String music, boolean restart, boolean stop)
      Setzt die aktuell abgespielte Audiospur auf einen LoopedMusic mit dem angegebenen Musik-Sound. Hat keine Wirkung, wenn die angegebene Spur bereits läuft.
      Parameters:
      music - Die als Zeichenkette angegebene Audio-Datei, die abgespielt werden soll
      restart - Ob die laufende Musikwiedergabe der eigenen Musik (bestimmt mit Object.equals(Object)) neu gestartet werden soll.
      stop - Ob die laufende Musikwiedergabe gestoppt werden soll.
      Returns:
      Ermöglicht die Steuerung der Musikwiedergabe.

    • playMusic

      @API public MusicPlayback playMusic(Sound sound, boolean restart, boolean stop)
      Setzt die aktuell abgespielte Spur auf einen LoopedMusic mit dem angegebenen Musik-Sound. Hat keine Wirkung, wenn die angegebene Spur bereits läuft.
      Parameters:
      sound - Der Klang, der abgespielt werden soll.
      restart - Ob die laufende Musikwiedergabe der eigenen Musik (bestimmt mit Object.equals(Object)) neu gestartet werden soll.
      stop - Ob die laufende Musikwiedergabe gestoppt werden soll.
      Returns:
      Ermöglicht die Steuerung der Musikwiedergabe.

    • playMusic

      @API public MusicPlayback playMusic(Music music, boolean restart, boolean stop)
      Spielt die angegebene Audiospur ab.
      Parameters:
      music - Die Audiospur, die gespielt werden soll.
      restart - Ob die laufende Musikwiedergabe der eigenen Musik (bestimmt mit Object.equals(Object)) neu gestartet werden soll.
      stop - Ob die laufende Musikwiedergabe gestoppt werden soll.
      Returns:
      Ermöglicht die Steuerung der Musikwiedergabe.

    • music

      @API @Getter public @Nullable MusicPlayback music()
      Liefert die aktuell relevante „Hauptmusik“. In der Regel ist das die letzte Wiedergabe, die mit playMusic gestartet wurde. Wenn die Musik gestoppt wurde, ist der Rückgabewert null.
      Returns:
      Die Hauptmusik oder null.

    • playMusic

      @API public @NonNull MusicPlayback playMusic(Music music, Consumer<? super MusicPlayback> config, boolean restart, boolean stop)
      Spielt die angegebene Audiospur ab und erlaubt optional eine Konfiguration vor dem Start.
      Parameters:
      music - Die Audiospur, die gespielt werden soll.
      config - Funktion zur Konfiguration der Wiedergabe vor dem Start; kann null sein.
      restart - Ob die laufende Musikwiedergabe der eigenen Musik (bestimmt mit Object.equals(Object)) neu gestartet werden soll.
      stop - Ob die laufende Musikwiedergabe gestoppt werden soll.
      Returns:
      Ermöglicht die Steuerung der Musikwiedergabe.

    • playIntroMusic

      @API public MusicPlayback playIntroMusic(String intro, String loop)
      Spielt zwei als Zeichenkette angegeben Audiodateien ab: die Erste nur einmalig und die darauf Folgende in einer Endlosschleife.
      Parameters:
      intro - Die Eingangsmusik als Zeichenkette angegeben.
      loop - Die zu wiederholende Musik als Zeichenkette.
      Returns:
      Ermöglicht die Steuerung der Musikwiedergabe.

    • allMusic

      @API @Getter public Collection<MusicPlayback> allMusic()
      Liefert eine Liste mit allen Musikwiedergaben.
      Returns:
      Eine Liste mit allen Musikwiedergaben.

    • stopMusic

      @API public void stopMusic()
      Stoppt die Wiedergabe der aktuellen Hintergrundmusik.