Package limn.sound

Interface Playback

public interface Playback
A handle to a sound that has started playing on the AudioEngine. It lets the caller stop it, adjust its volume, or query whether it is still sounding. Handles become inert once the underlying voice is recycled for another clip, so operations on a finished playback are harmless no-ops.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Playback
    NONE
    A no-op handle returned when no audio device is available (headless/CI).

  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    canSeek()
     
    boolean
    isPlaying()
     
    default void
    pause()
    Pauses this sound, keeping its position; resume() continues exactly where it left off (the game-pause primitive; stop() loses the position).
    default double
    positionSeconds()
     
    default void
    resume()
    Resumes a paused sound from where it stopped.
    default void
    seek(long micros)
    Moves this sound to micros and discards whatever is already queued on the device: both halves, because either alone is a seek that sounds wrong.
    void
    setGain(float gain)
    Sets this sound's volume in [0..1] (no-op if it already finished).
    default void
    setPan(float pan)
    Sets the stereo pan in [-1..1] (mono clips only; see PlayOptions.pan).
    default void
    setPitch(float pitch)
    Sets the playback-rate multiplier in [0.25..4] (1 = natural speed/pitch).
    default void
    setPosition(float x, float y, float z)
    Moves a positional playback to (x, y, z), for emitters that travel with a game object.
    void
    stop()
    Stops this sound immediately (no-op if it already finished).

  • Field Details

    • NONE

      static final Playback NONE
      A no-op handle returned when no audio device is available (headless/CI).

  • Method Details

    • stop

      void stop()
      Stops this sound immediately (no-op if it already finished).

    • isPlaying

      boolean isPlaying()
      Returns:
      whether this sound is still playing (false while paused)

    • setGain

      void setGain(float gain)
      Sets this sound's volume in [0..1] (no-op if it already finished).

    • pause

      default void pause()
      Pauses this sound, keeping its position; resume() continues exactly where it left off (the game-pause primitive; stop() loses the position). Default no-op for engines without support.

    • resume

      default void resume()
      Resumes a paused sound from where it stopped.

    • setPitch

      default void setPitch(float pitch)
      Sets the playback-rate multiplier in [0.25..4] (1 = natural speed/pitch).

    • setPan

      default void setPan(float pan)
      Sets the stereo pan in [-1..1] (mono clips only; see PlayOptions.pan).

    • setPosition

      default void setPosition(float x, float y, float z)
      Moves a positional playback to (x, y, z), for emitters that travel with a game object. Only affects playbacks started with PlayOptions.at(float, float, float); no-op otherwise.

    • positionSeconds

      default double positionSeconds()
      Returns:
      seconds into the clip/stream, or 0 when finished/unsupported

    • seek

      default void seek(long micros)
      Moves this sound to micros and discards whatever is already queued on the device: both halves, because either alone is a seek that sounds wrong. Repositioning the source without discarding plays the old position for the depth of the queue and then jumps; discarding without repositioning is a gap.

      positionSeconds() reports the target from the moment this returns, before a sample from the new position has been decoded. That is not a convenience: video slaved to this position is re-anchored by the same caller in the same breath, and a position that lagged the request would be read as the track having run away and would cost the video its audio master.

      The sound is silent for a moment. Refilling the device happens on the engine's own thread, so a seek costs one service period plus one decode before anything is heard. A caller scrubbing hears gaps, which is what scrubbing sounds like.

      Default no-op, like every other optional operation here, including on a finished playback and on the handle a machine with no audio device yields. Ask canSeek() first if the difference matters.

      Parameters:
      micros - where to move to, in microseconds from the start; negative is clamped to the start rather than refused, because a transport control computing a position from a pixel will produce one

    • canSeek

      default boolean canSeek()
      Returns:
      whether seek(long) does anything. False for a finished playback, for a streamed source that cannot be repositioned, and when there is no audio device at all