Package limn.sound

Interface AudioDecoder

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface AudioDecoder
Decodes encoded audio bytes into an AudioClip. Exactly one is installed at a time (the backend's at startup, or a fake in a test), and which formats work is that implementation's to document; anything it does not recognise throws rather than returning silence.

Both methods run on the caller's thread and are allowed to be slow. An implementation may read a whole file, allocate for the whole of it and decode; none of that has to be deferred, split or made cancellable here. That freedom is deliberate and is paid for one level up: the Sounds facade owns the asynchronous forms, so the only thing an implementation must not do is assume which thread it is on; in particular it must not touch widgets, and it must not assume the UI thread is available to it.

  • Method Summary

    Modifier and Type
    Method
    Description
    AudioClip
    decode(byte[] fileBytes)
    Decodes a whole clip, on the calling thread.
    default AudioStreamSource
    openStream(Path file)
    Opens file for incremental decoding, the streamed-music path (see AudioStreamSource).

  • Method Details

    • decode

      AudioClip decode(byte[] fileBytes)
      Decodes a whole clip, on the calling thread. Cost scales with the decoded length, not the file length: a four-minute track is tens of megabytes of PCM and hundreds of milliseconds of work, which is why streaming exists.
      Parameters:
      fileBytes - the full encoded file
      Returns:
      the decoded PCM clip
      Throws:
      RuntimeException - if the bytes are not a supported format

    • openStream

      default AudioStreamSource openStream(Path file)
      Opens file for incremental decoding, the streamed-music path (see AudioStreamSource). Which formats stream is a smaller set than which decode, and is the implementation's to document. Default: unsupported.

      On the calling thread, and open is not required to be cheap: sniffing the format needs a read, and a container that has to be seekable in memory may be read whole and a first frame decoded to learn the channel count and sample rate before this returns. What streaming saves is the decoded audio, not the encoded file.

      Throws:
      RuntimeException - if the format cannot be streamed (decode fully with decode(byte[]) instead)