ICodec.java

package paulscode.sound;

import java.net.URL;
import javax.sound.sampled.AudioFormat;

/**
 * The ICodec interface provides a common interface for SoundSystem to use
 * for accessing external codec libraries.
 *<br><br>
 *<b><i>    SoundSystem License:</b></i><br><b><br>
 *    You are free to use this library for any purpose, commercial or otherwise.
 *    You may modify this library or source code, and distribute it any way you
 *    like, provided the following conditions are met:
 *<br>
 *    1) You may not falsely claim to be the author of this library or any
 *    unmodified portion of it.
 *<br>
 *    2) You may not copyright this library or a modified version of it and then
 *    sue me for copyright infringement.
 *<br>
 *    3) If you modify the source code, you must clearly document the changes
 *    made before redistributing the modified source code, so other users know
 *    it is not the original code.
 *<br>
 *    4) You are not required to give me credit for this library in any derived
 *    work, but if you do, you must also mention my website:
 *    http://www.paulscode.com
 *<br>
 *    5) I the author will not be responsible for any damages (physical,
 *    financial, or otherwise) caused by the use if this library or any part
 *    of it.
 *<br>
 *    6) I the author do not guarantee, warrant, or make any representations,
 *    either expressed or implied, regarding the use of this library or any
 *    part of it.
 * <br><br>
 *    Author: Paul Lamb
 * <br>
 *    http://www.paulscode.com
 * </b>
 */
public interface ICodec
{
/**
 * Should tell derived classes when they may need to reverse the byte order of
 * the data before returning it in the read() and readAll() methods.  The
 * reason for the reversBytOrder method is because some external codec
 * libraries produce audio data in a format that some external audio libraries
 * require to be reversed.  Derivatives of the Library and Source classes for
 * audio libraries which require this type of data to be reversed should call
 * the reverseByteOrder() method for all instances of ICodec that they use.
 * Derivatives of the ICodec interface for codec libraries which which produce
 * this type of data should use the reverseByteOrder() method to know when the
 * data needs to be reversed before returning it in the read() and readAll()
 * methods.  If a particular codec library does not produce this type of data,
 * its derived ICodec class may disregard any calls to the reverseByteOrder()
 * method.
 * @param b True if the calling audio library requires byte-reversal by some codec libraries.
 */
    public void reverseByteOrder( boolean b );
    
/**
 * Should make any preperations required before reading from the audio stream.
 * If another stream is already opened, it should be closed and a new audio
 * stream opened in its place.  This method is used internally by SoundSystem
 * not only to initialize a stream, but also to rewind streams and to switch
 * stream sources on the fly.
 * @return False if an error occurred or if end of stream was reached.
 */
    public boolean initialize( URL url );

/**
 * Should return false if the stream is busy initializing.  To prevent bad
 * data from being returned by this method, derived classes should internally
 * synchronize with any elements used by both the initialized() and initialize()
 * methods.
 * @return True if steam is initialized.
 */
    public boolean initialized();

/**
 * Should read in one stream buffer worth of audio data.  See
 * {@link paulscode.sound.SoundSystemConfig SoundSystemConfig} for more
 * information about accessing and changing default settings.
 * @return The audio data wrapped into a SoundBuffer context.
 */
    public SoundBuffer read();

/**
 * Should read in all the audio data from the stream (up to the default
 * "maximum file size".  See
 * {@link paulscode.sound.SoundSystemConfig SoundSystemConfig} for more
 * information about accessing and changing default settings.
 * @return the audio data wrapped into a SoundBuffer context.
 */
    public SoundBuffer readAll();

/**
 * Should return false if there is still more data available to be read in.  To
 * prevent bad data from being returned by this method, derived classes should
 * internally synchronize with any elements used in both the endOfStream() and
 * the read() or readAll() methods.
 * @return True if end of stream was reached.
 */
    public boolean endOfStream();

/**
 * Should close any open streams and remove references to all instantiated
 * objects.
 */
    public void cleanup();

/**
 * Should return the audio format of the data being returned by the read() and
 * readAll() methods.
 * @return Information wrapped into an AudioFormat context.
 */
    public AudioFormat getAudioFormat();
}