// 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.IOException;

/** Interface for streaming to a remote player. Extends {@link Device.Player} so that it can be
  * plugged-in in place of any player.
  */
public interface AudioStream extends Device.Player {
    /** AudioStream factory interface. */
    interface Factory extends Device.Player.Factory {
        AudioStream open(PcmFormat format) throws IOException;
    }

    /** Callback by which the recipient can tell the writer how much of its received data it has
      * finished playing. The writer can use this information to refrain from flooding the recipient
      * with data while making sure it has enough left to play without underflow. Typically not used
      * if the recipient is a file or something else that does not place a limit on output speed.
      */
    void playedMillis(long time);

    /** Returns the output bitrate or other quality measure, or null (the default) for lossless. */
    default String quality() { return null; }

    /** Checks if the stream recipient still appears to be actively processing audio data from the
      * stream, which may continue after the stream is closed.
      */
    boolean streaming();
}