// Copyright 2014-2025 Jesper Larsson
//
// This file is part of Klipspringer, <https://klipspringer.avadeaux.net/>
//
// Klipspringer is free software: you can redistribute it and/or modify it under the terms of the
// GNU General Public License as published by the Free Software Foundation, either version 3 of the
// License, or (at your option) any later version.
//
// Klipspringer is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
// even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License along with Klipspringer. If
// not, see <https://www.gnu.org/licenses/>.

package net.avadeaux.klipspringer.codec;

import java.io.Closeable;
import java.io.IOException;
import java.nio.ByteBuffer;
import javax.sound.sampled.*;

/** Interface for streamed audio decoding. Each decoder has a {@link Target}, which receives decoded
  * metadata and PCM audio.
  */
public interface AudioDecoder extends Closeable {
    /** Interface for the destination of an audio decoder. */
    interface Target extends PcmWriter {
        /** Makes the writer ready to recieve data in the given format, and gives the intended full
          * length of the input if available, otherwise supplying {@link
          * AudioSystem#NOT_SPECIFIED}. This method is to be called once per target.
          */
        void metadata(PcmFormat format, long totalFrames) throws IOException;
    }

    /** Interface that can be implemented by decoder in order to receive pictures embedded in the
      * decoded file metadata.
      */
    interface PictureTarget {
        /** Handles picture data. Optional parameters may be null or empty strings.
          *
          * @param mimeType     MIME type string, for instance "image/jpeg", or "-->" if data is a URL
          * @param picType      optional picture type string, for instance "Cover (front)"
          * @param description  optional picture description string
          * @param data         picture data
          */
        void picture(String mimeType, String picType, String description, ByteBuffer data) throws IOException;
    }

    /** True if {@link #decodeAll} can be called more than once, each time resetting the underlying
      * input.
      */
    boolean reusable();

    /** Decodes metadata and sends it to the target, without writing any blocks. Must be called at
      * most once, and never after {@link #decodeAll(long) decodeAll}. If this is not called,
      * metadata gets sent to the target by {@link #decodeAll(long) decodeAll}.
      */
    void decodeMetadata() throws IOException;

    /** Sends audio data to the target, one block at the time, starting from the given sample frame
      * (zero to start at the beginning). If {@link #decodeMetadata()} has not been called, metadata
      * is sent to the target before the first block. Returns when the input is exhausted (in which
      * case it returns true) or the target aborts decoding by returning false from write (in which
      * case this method returns false). In either case, if this decoder is {@link #reusable()},
      * {@link #decodeAll(long) decodeAll} may be called again to once more decode part of the same
      * file. */
    boolean decodeAll(long fromFrame) throws IOException;

    /** Returns a string to indicate compression quality, or empty string for lossless formats (the
      * default). The string may contain a numeric value for the quality or simply indicate that it
      * is (lossily) compressed.
      */
    default String quality() { return ""; }

    /** See {@link Closeable#close()}. */
    void close() throws IOException;
}

Version: v4.3.2.2 (2026-05-16T17:03:34+02:00)
Raw file
Source code overview
Klipspringer home