Library.java

package paulscode.sound;

import java.util.HashMap;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;
import java.util.Set;
import javax.sound.sampled.AudioFormat;

/**
 * The Library class is the class from which all library types are extended.  
 * It provides generic methods for interfacing with the audio libraries 
 * supported by the SoundSystem.  Specific libraries should extend this class 
 * and override the necessary methods.  For consistant naming conventions, each 
 * sub-class should have the name prefix "Library".  
 * 
 * This class may also be used as the "No Sound Library" (i.e. silent mode) if
 * no other audio libraries are supported by the host machine, or to mute all
 * sound.
 *<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 class Library
{
/**
 * Processes status messages, warnings, and error messages.
 */
    private SoundSystemLogger logger;
    
/**
 * Position and orientation of the listener.
 */
    protected ListenerData listener;

/**
 * Map containing sound file data for easy lookup by filename / identifier.
 */
    protected HashMap<String, SoundBuffer> bufferMap = null;

/**
 * Map containing all created sources for easy look-up by name.
 */
    protected HashMap<String, Source> sourceMap;  // (name, source data) pairs

/**
 * Interface through which MIDI files can be played.
 */
    private MidiChannel midiChannel;
    
/**
 * Array containing maximum number of non-streaming audio channels.
 */
    protected List<Channel> streamingChannels;
    
/**
 * Array containing maximum number of non-streaming audio channels.
 */
    protected List<Channel> normalChannels;
    
/**
 * Source name last played on each streaming channel.
 */
    private String[] streamingChannelSourceNames;
    
/**
 * Source name last played on each non-streaming channel.
 */
    private String[] normalChannelSourceNames;
    
/**
 * Increments through the steaming channel list as new sources are played.
 */
    private int nextStreamingChannel = 0;
    
/**
 * Increments through the non-steaming channel list as new sources are played.
 */
    private int nextNormalChannel = 0;

/**
 * Handles processing for all streaming sources.
 */
    protected StreamThread streamThread;
    
/**
 * Whether or not the library requires reversal of audio data byte order.
 */
    protected boolean reverseByteOrder = false;
    
/**
 * Constructor: Instantiates the source map and listener information.  NOTES: 
 * The 'super()' method should be at the top of constructors for all extended 
 * classes.  The varriable 'libraryType' should be given a new value in the 
 * constructors for all extended classes.
 */
    public Library() throws SoundSystemException
    {
        // grab a handle to the message logger:
        logger = SoundSystemConfig.getLogger();
        
        // instantiate the buffer map:
        bufferMap = new HashMap<String, SoundBuffer>();

        // instantiate the source map:
        sourceMap = new HashMap<String, Source>();
        
        listener = new ListenerData( 0.0f, 0.0f, 0.0f,  // position
                                     0.0f, 0.0f, -1.0f, // look-at direction
                                     0.0f, 1.0f, 0.0f,  // up direction
                                     0.0f );            // angle
        
        streamingChannels = new LinkedList<Channel>();
        normalChannels = new LinkedList<Channel>();
        streamingChannelSourceNames = new String[
                               SoundSystemConfig.getNumberStreamingChannels() ];
        normalChannelSourceNames = new String[
                                  SoundSystemConfig.getNumberNormalChannels() ];
        
        streamThread = new StreamThread();
        streamThread.start();
    }


/* ########################################################################## */
/*                        BEGIN OVERRIDE METHODS                              */
/*                                                                            */
/*         The following methods should be overrided as required              */
/* ########################################################################## */
    
/**
 * Stops all sources, shuts down sound library, and removes references to all 
 * instantiated objects.
 */
    public void cleanup()
    {
        streamThread.kill();
        streamThread.interrupt();
        
        // wait up to 5 seconds for stream thread to end:
        for( int i = 0; i < 50; i++ )
        {
            if( !streamThread.alive() )
                break;
            try
            {
                Thread.sleep(100);
            }
            catch(Exception e)
            {}
        }
        
        if( streamThread.alive() )
        {
            errorMessage( "Stream thread did not die!" );
            message( "Ignoring errors... continuing clean-up." );
        }
        
        if( midiChannel != null )
        {
            midiChannel.cleanup();
            midiChannel = null;
        }

        Channel channel = null;
        if( streamingChannels != null )
        {
            while( !streamingChannels.isEmpty() )
            {
                channel = streamingChannels.remove(0);
                channel.close();
                channel.cleanup();
                channel = null;
            }
            streamingChannels.clear();
            streamingChannels = null;
        }
        if( normalChannels != null )
        {
            while( !normalChannels.isEmpty() )
            {
                channel = normalChannels.remove(0);
                channel.close();
                channel.cleanup();
                channel = null;
            }
            normalChannels.clear();
            normalChannels = null;
        }
        
        Set<String> keys = sourceMap.keySet();
        Iterator<String> iter = keys.iterator();        
        String sourcename;
        Source source;
        
        // loop through and cleanup all the sources:
        while( iter.hasNext() )
        {
            sourcename = iter.next();
            source = sourceMap.get( sourcename );
            if( source != null )
                source.cleanup();
        }
        sourceMap.clear();
        sourceMap = null;
        
        listener = null;
        streamThread = null;
    }
    
/**
 * Initializes the sound library.
 */
    public void init() throws SoundSystemException
    {
        Channel channel = null;
        
        // create the streaming channels:
        for( int x = 0; x < SoundSystemConfig.getNumberStreamingChannels(); x++ )
        {
            channel = createChannel( SoundSystemConfig.TYPE_STREAMING );
            if( channel == null )
                break;
            streamingChannels.add( channel );
        }
        // create the non-streaming channels:
        for( int x = 0; x < SoundSystemConfig.getNumberNormalChannels(); x++ )
        {
            channel = createChannel( SoundSystemConfig.TYPE_NORMAL );
            if( channel == null )
                break;
            normalChannels.add( channel );
        }
    }
    
/**
 * Checks if the no-sound library type is compatible.
 * @return True or false.
 */
    public static boolean libraryCompatible()
    {
        return true;  // the no-sound library is always compatible.
    }
    
/**
 * Creates a new channel of the specified type (normal or streaming).  Possible 
 * values for channel type can be found in the 
 * {@link paulscode.sound.SoundSystemConfig SoundSystemConfig} class.
 * @param type Type of channel.
 * @return The new channel.
 */
    protected Channel createChannel( int type )
    {
        return new Channel( type );
    }
    
/**
 * Pre-loads a sound into memory.  
 * @param filenameURL Filename/URL of the sound file to load.
 * @return True if the sound loaded properly.
 */
    public boolean loadSound( FilenameURL filenameURL )
    {
        return true;
    }

/**
 * Saves the specified sample data, under the specified identifier.  This
 * identifier can be later used in place of 'filename' parameters to reference
 * the sample data.
 * @param buffer the sample data and audio format to save.
 * @param identifier What to call the sample.
 * @return True if there weren't any problems.
 */
    public boolean loadSound( SoundBuffer buffer, String identifier )
    {
        return true;
    }

/**
 * Returns the filenames of all previously loaded sounds.
 * @return LinkedList of String filenames.
 */
    public LinkedList<String> getAllLoadedFilenames()
    {
        LinkedList<String> filenames = new LinkedList<String>();
        Set<String> keys = bufferMap.keySet();
        Iterator<String> iter = keys.iterator();

        // loop through and update the volume of all sources:
        while( iter.hasNext() )
        {
            filenames.add( iter.next() );
        }

        return filenames;
    }

/**
 * Returns the sourcenames of all sources.
 * @return LinkedList of String sourcenames.
 */
    public LinkedList<String> getAllSourcenames()
    {
        LinkedList<String> sourcenames = new LinkedList<String>();
        Set<String> keys = sourceMap.keySet();
        Iterator<String> iter = keys.iterator();

        if( midiChannel != null )
            sourcenames.add( midiChannel.getSourcename() );

        // loop through and update the volume of all sources:
        while( iter.hasNext() )
        {
            sourcenames.add( iter.next() );
        }

        return sourcenames;
    }

/**
 * Removes a pre-loaded sound from memory.  This is a good method to use for
 * freeing up memory after a large sound file is no longer needed.  NOTE: the
 * source will remain in memory after this method has been called, for as long
 * as the sound is attached to an existing source.
 * @param filename Filename/identifier of the sound file to unload.
 */
    public void unloadSound( String filename )
    {
        bufferMap.remove( filename );
    }

/**
 * Opens a direct line for streaming audio data.
 * @param audioFormat Format that the data will be in.
 * @param sourcename A unique identifier for this source.  Two sources may not use the same sourcename.
 * @param posX X position for this source.
 * @param posY Y position for this source.
 * @param posZ Z position for this source.
 * @param attModel Attenuation model to use.
 * @param distOrRoll Either the fading distance or rolloff factor, depending on the value of "attmodel".
 */
    public void rawDataStream( AudioFormat audioFormat, boolean priority,
                               String sourcename, float posX, float posY,
                               float posZ, int attModel, float distOrRoll )
    {
        sourceMap.put( sourcename,
                       new Source( audioFormat, priority, sourcename, posX,
                                   posY, posZ, attModel, distOrRoll ) );
    }
    
/**
 * Creates a new source using the specified information.
 * @param priority Setting this to true will prevent other sounds from overriding this one.
 * @param toStream Setting this to true will load the sound in pieces rather than all at once.
 * @param toLoop Should this source loop, or play only once.
 * @param sourcename A unique identifier for this source.  Two sources may not use the same sourcename.
 * @param filenameURL Filename/URL of the sound file to play at this source.
 * @param posX X position for this source.
 * @param posY Y position for this source.
 * @param posZ Z position for this source.
 * @param attModel Attenuation model to use.
 * @param distOrRoll Either the fading distance or rolloff factor, depending on the value of "attmodel".
 */
    public void newSource( boolean priority, boolean toStream, boolean toLoop,
                           String sourcename, FilenameURL filenameURL,
                           float posX, float posY, float posZ, int attModel,
                           float distOrRoll )
    {
        sourceMap.put( sourcename,
                       new Source( priority, toStream, toLoop, sourcename,
                                   filenameURL, null, posX, posY, posZ,
                                   attModel, distOrRoll, false ) );
    }
    
/**
 * Creates and immediately plays a new source that will be removed when it 
 * finishes playing.
 * @param priority Setting this to true will prevent other sounds from overriding this one.
 * @param toStream Setting this to true will load the sound in pieces rather than all at once.
 * @param toLoop Should this source loop, or play only once.
 * @param sourcename A unique identifier for this source.  Two sources may not use the same sourcename.
 * @param filenameURL The filename/URL of the sound file to play at this source.
 * @param posX X position for this source.
 * @param posY Y position for this source.
 * @param posZ Z position for this source.
 * @param attModel Attenuation model to use.
 * @param distOrRoll Either the fading distance or rolloff factor, depending on the value of "attmodel".
 */
    public void quickPlay( boolean priority, boolean toStream, boolean toLoop,
                           String sourcename, FilenameURL filenameURL,
                           float posX, float posY, float posZ, int attModel,
                           float distOrRoll, boolean tmp )
    {
        sourceMap.put( sourcename,
                       new Source( priority, toStream, toLoop, sourcename,
                                   filenameURL, null, posX, posY, posZ,
                                   attModel, distOrRoll, tmp ) );
    }
    
/**
 * 
 * Defines whether or not the source should be removed after it finishes 
 * playing.  
 * @param sourcename The source's name.
 * @param temporary True or False.
 */
    public void setTemporary( String sourcename, boolean temporary )
    {
        Source mySource = sourceMap.get( sourcename );
        if( mySource != null )
            mySource.setTemporary( temporary );
    }
    
/**
 * Changes the specified source's position.
 * @param sourcename The source's name.
 * @param x Destination X coordinate.
 * @param y Destination Y coordinate.
 * @param z Destination Z coordinate.
 */
    public void setPosition( String sourcename, float x, float y, float z )
    {
        Source mySource = sourceMap.get( sourcename );
        if( mySource != null )
            mySource.setPosition( x, y, z );
    }
    
/**
 * Sets the specified source's priority factor.  A priority source will not be 
 * overriden if there are too many sources playing at once.
 * @param sourcename The source's name.
 * @param pri True or False.
 */
    public void setPriority( String sourcename, boolean pri )
    {
        Source mySource = sourceMap.get( sourcename );
        if( mySource != null )
            mySource.setPriority( pri );
    }
    
/**
 * Sets the specified source's looping parameter.  If parameter lp is false, 
 * the source will play once and stop.
 * @param sourcename The source's name.
 * @param lp True or False.
 */
    public void setLooping( String sourcename, boolean lp )
    {
        Source mySource = sourceMap.get( sourcename );
        if( mySource != null )
            mySource.setLooping( lp );
    }
    
/**
 * Sets the specified source's attenuation model. 
 * @param sourcename The source's name.
 * @param model Attenuation model to use.
 */
    public void setAttenuation( String sourcename, int model )
    {
        Source mySource = sourceMap.get( sourcename );
        if( mySource != null )
            mySource.setAttenuation( model );
    }
    
/**
 * Sets the specified source's fade distance or rolloff factor. 
 * @param sourcename The source's name.
 * @param dr Fade distance or rolloff factor.
 */
    public void setDistOrRoll( String sourcename, float dr)
    {
        Source mySource = sourceMap.get( sourcename );
        if( mySource != null )
            mySource.setDistOrRoll( dr );
    }

/**
 * Sets the specified source's velocity, for use in Doppler effect.
 * @param sourcename The source's name.
 * @param x Velocity along world x-axis.
 * @param y Velocity along world y-axis.
 * @param z Velocity along world z-axis.
 */
    public void setVelocity( String sourcename, float x, float y, float z )
    {
        Source mySource = sourceMap.get( sourcename );
        if( mySource != null )
            mySource.setVelocity( x, y, z );
    }

/**
 * Sets the listener's velocity, for use in Doppler effect.
 * @param x Velocity along world x-axis.
 * @param y Velocity along world y-axis.
 * @param z Velocity along world z-axis.
 */
    public void setListenerVelocity( float x, float y, float z )
    {
        listener.setVelocity( x, y, z );
    }

/**
 * Notifies the underlying library that the Doppler parameters have changed.
 */
    public void dopplerChanged()
    {}
    
/**
 * Returns the number of miliseconds since the specified source began playing.
 * @return miliseconds, or -1 if not playing or unable to calculate
 */
    public float millisecondsPlayed( String sourcename )
    {
        if( sourcename == null || sourcename.equals( "" ) )
        {
            errorMessage( "Sourcename not specified in method " +
                          "'millisecondsPlayed'" );
            return -1;
        }

        if( midiSourcename( sourcename ) )
        {
            errorMessage( "Unable to calculate milliseconds for MIDI source." );
            return -1;
        }
        else
        {
            Source source = sourceMap.get( sourcename );
            if( source == null )
            {
                errorMessage( "Source '" + sourcename + "' not found in " +
                              "method 'millisecondsPlayed'" );
            }
            return source.millisecondsPlayed();
        }
    }
/**
 * Feeds raw data through the specified source.  The source must be a
 * streaming source and it can not be already associated with a file or URL to
 * stream from.
 * @param sourcename Name of the streaming source to play from.
 * @param buffer Byte buffer containing raw audio data to stream.
 * @return Number of prior buffers that have been processed, or -1 if unable to queue the buffer (if the source was culled, for example).
 */
    public int feedRawAudioData( String sourcename, byte[] buffer )
    {
        if( sourcename == null || sourcename.equals( "" ) )
        {
            errorMessage( "Sourcename not specified in method " +
                          "'feedRawAudioData'" );
            return -1;
        }

        if( midiSourcename( sourcename ) )
        {
            errorMessage( "Raw audio data can not be fed to the " +
                          "MIDI channel." );
            return -1;
        }
        else
        {
            Source source = sourceMap.get( sourcename );
            if( source == null )
            {
                errorMessage( "Source '" + sourcename + "' not found in " +
                              "method 'feedRawAudioData'" );
            }
            return feedRawAudioData( source, buffer );
        }
    }

/**
 * Feeds raw data through the specified source.  The source must be a
 * streaming source and it can not be already associated with a file or URL to
 * stream from.
 * @param source Streaming source to play from.
 * @param buffer Byte buffer containing raw audio data to stream.
 * @return Number of prior buffers that have been processed, or -1 if unable to queue the buffer (if the source was culled, for example).
 */
    public int feedRawAudioData( Source source, byte[] buffer )
    {
        if( source == null )
        {
            errorMessage( "Source parameter null in method " +
                          "'feedRawAudioData'" );
            return -1;
        }
        if( !source.toStream )
        {
            errorMessage( "Only a streaming source may be specified in " +
                          "method 'feedRawAudioData'" );
            return -1;
        }
        if( !source.rawDataStream )
        {
            errorMessage( "Streaming source already associated with a " +
                          "file or URL in method'feedRawAudioData'" );
            return -1;
        }

        if( !source.playing() || source.channel == null )
        {
            Channel channel;
            if( source.channel != null && ( source.channel.attachedSource ==
                                            source ) )
                channel = source.channel;
            else
                channel = getNextChannel( source );

            int processed = source.feedRawAudioData( channel, buffer );
            channel.attachedSource = source;
            streamThread.watch( source );
            streamThread.interrupt();
            return processed;
        }

        return( source.feedRawAudioData( source.channel, buffer ) );
    }

/**
 * Looks up the specified source and plays it.  
 * @param sourcename Name of the source to play.
 */
    public void play( String sourcename )
    {
        if( sourcename == null || sourcename.equals( "" ) )
        {
            errorMessage( "Sourcename not specified in method 'play'" );
            return;
        }
        
        if( midiSourcename( sourcename ) )
        {
            midiChannel.play();
        }
        else
        {
            Source source = sourceMap.get( sourcename );
            if( source == null )
            {
                errorMessage( "Source '" + sourcename + "' not found in " +
                              "method 'play'" );
            }
            play( source );
        }
    }
    
/**
 * Plays the specified source. 
 * @param source The source to play.
 */
    public void play( Source source )
    {
        if( source == null )
            return;

        // raw data streams will automatically play when data is sent to them,
        // so no need to do anything here.
        if( source.rawDataStream )
            return;

        if( !source.active() )
            return;
        
        if( !source.playing() )
        {
            Channel channel = getNextChannel( source );

            if( source != null && channel != null )
            {
                if( source.channel != null &&
                    source.channel.attachedSource != source )
                    source.channel = null;
                channel.attachedSource = source;
                source.play( channel );
                if( source.toStream )
                {
                    streamThread.watch( source );
                    streamThread.interrupt();
                }
            }
        }
    }
    
/**
 * Stops the specified source. 
 * @param sourcename The source's name.
 */
    public void stop( String sourcename )
    {
        if( sourcename == null || sourcename.equals( "" ) )
        {
            errorMessage( "Sourcename not specified in method 'stop'" );
            return;
        }
        if( midiSourcename( sourcename ) )
        {
            midiChannel.stop();
        }
        else
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
                mySource.stop();
        }
    }
    
/**
 * Pauses the specified source. 
 * @param sourcename The source's name.
 */
    public void pause( String sourcename )
    {
        if( sourcename == null || sourcename.equals( "" ) )
        {
            errorMessage( "Sourcename not specified in method 'stop'" );
            return;
        }
        if( midiSourcename( sourcename ) )
        {
            midiChannel.pause();
        }
        else
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
                mySource.pause();
        }
    }
    
/**
 * Rewinds the specified source. 
 * @param sourcename The source's name.
 */
    public void rewind( String sourcename )
    {
        if( midiSourcename( sourcename ) )
        {
            midiChannel.rewind();
        }
        else
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
                mySource.rewind();
        }
    }

/**
 * Clears all previously queued data from a stream.
 * @param sourcename The source's name.
 */
    public void flush( String sourcename )
    {
        if( midiSourcename( sourcename ) )
            errorMessage( "You can not flush the MIDI channel" );
        else
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
                mySource.flush();
        }
    }
    
/**
 * Culls the specified source.  A culled source will not play until it has been 
 * activated again.
 * @param sourcename The source's name.
 */
    public void cull( String sourcename )
    {
        Source mySource = sourceMap.get( sourcename );
        if( mySource != null )
            mySource.cull();
    }
    
/**
 * Activates a previously culled source, so it can be played again.  
 * @param sourcename The source's name.
 */
    public void activate( String sourcename )
    {
        Source mySource = sourceMap.get( sourcename );
        if( mySource != null )
        {
            mySource.activate();
            if( mySource.toPlay )
                play( mySource );
        }
    }

/**
 * Sets the overall volume to the specified value, affecting all sources.
 * @param value New volume, float value ( 0.0f - 1.0f ).
 */
    public void setMasterVolume( float value )
    {
        SoundSystemConfig.setMasterGain( value );
        if( midiChannel != null )
            midiChannel.resetGain();
    }

/**
 * Manually sets the specified source's volume.  
 * @param sourcename The source's name.
 * @param value A float value ( 0.0f - 1.0f ).
 */
    public void setVolume( String sourcename, float value )
    {
        if( midiSourcename( sourcename ) )
        {
            midiChannel.setVolume( value );
        }
        else
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
            {
                float newVolume = value;
                if( newVolume < 0.0f )
                    newVolume = 0.0f;
                else if( newVolume > 1.0f )
                    newVolume = 1.0f;

                mySource.sourceVolume = newVolume;
                mySource.positionChanged();
            }
        }
    }
    
/**
 * Returns the current volume of the specified source, or zero if the specified 
 * source was not found.
 * @param sourcename Source to read volume from.
 * @return Float value representing the source volume (0.0f - 1.0f).
 */
    public float getVolume( String sourcename )
    {
        if( midiSourcename( sourcename ) )
        {
            return midiChannel.getVolume();
        }
        else
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
                return mySource.sourceVolume;
            else
                return 0.0f;
        }
    }
    
/**
 * Manually sets the specified source's pitch.
 * @param sourcename The source's name.
 * @param value A float value ( 0.5f - 2.0f ).
 */
    public void setPitch( String sourcename, float value )
    {
        if( !midiSourcename( sourcename ) )
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
            {
                float newPitch = value;
                if( newPitch < 0.5f )
                    newPitch = 0.5f;
                else if( newPitch > 2.0f )
                    newPitch = 2.0f;

                mySource.setPitch( newPitch );
                mySource.positionChanged();
            }
        }
    }

/**
 * Returns the pitch of the specified source.
 * @param sourcename The source's name.
 * @return Float value representing the source pitch (0.5f - 2.0f).
 */
    public float getPitch( String sourcename )
    {
        if( !midiSourcename( sourcename ) )
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
                return mySource.getPitch();
        }
        return 1.0f;
    }

/**
 * Moves the listener relative to the current position. 
 * @param x X offset.
 * @param y Y offset.
 * @param z Z offset.
 */
    public void moveListener( float x, float y, float z )
    {
        setListenerPosition( listener.position.x + x, listener.position.y + y,
                             listener.position.z + z );
    }
    
/**
 * Changes the listener's position. 
 * @param x Destination X coordinate.
 * @param y Destination Y coordinate.
 * @param z Destination Z coordinate.
 */
    public void setListenerPosition( float x, float y, float z )
    {
        // update listener's position
        listener.setPosition( x, y, z );
        
        Set<String> keys = sourceMap.keySet();
        Iterator<String> iter = keys.iterator();        
        String sourcename;
        Source source;
        
        // loop through and update the volume of all sources:
        while( iter.hasNext() )
        {
            sourcename = iter.next();
            source = sourceMap.get( sourcename );
            if( source != null )
                source.positionChanged();
        }
    }
    
/**
 * Turn the listener 'angle' radians counterclockwise around the y-Axis, 
 * relative to the current angle.
 * @param angle Angle in radians.
 */
    public void turnListener( float angle )
    {
        setListenerAngle( listener.angle + angle );

        Set<String> keys = sourceMap.keySet();
        Iterator<String> iter = keys.iterator();
        String sourcename;
        Source source;

        // loop through and update the volume of all sources:
        while( iter.hasNext() )
        {
            sourcename = iter.next();
            source = sourceMap.get( sourcename );
            if( source != null )
                source.positionChanged();
        }
    }
    
/**
 * Changes the listeners orientation to the specified 'angle' radians 
 * counterclockwise around the y-Axis.
 * @param angle Angle in radians.
 */
    public void setListenerAngle( float angle )
    {
        listener.setAngle( angle );
        
        Set<String> keys = sourceMap.keySet();
        Iterator<String> iter = keys.iterator();        
        String sourcename;
        Source source;
        
        // loop through and update the volume of all sources:
        while( iter.hasNext() )
        {
            sourcename = iter.next();
            source = sourceMap.get( sourcename );
            if( source != null )
                source.positionChanged();
        }
    }
    
/**
 * Changes the listeners orientation using the specified coordinates.
 * @param lookX X element of the look-at direction.
 * @param lookY Y element of the look-at direction.
 * @param lookZ Z element of the look-at direction.
 * @param upX X element of the up direction.
 * @param upY Y element of the up direction.
 * @param upZ Z element of the up direction.
 */
    public void setListenerOrientation( float lookX, float lookY, float lookZ,
                                        float upX, float upY, float upZ )
    {
        listener.setOrientation( lookX, lookY, lookZ, upX, upY, upZ );
        
        Set<String> keys = sourceMap.keySet();
        Iterator<String> iter = keys.iterator();        
        String sourcename;
        Source source;
        
        // loop through and update the volume of all sources:
        while( iter.hasNext() )
        {
            sourcename = iter.next();
            source = sourceMap.get( sourcename );
            if( source != null )
                source.positionChanged();
        }
    }

/**
 * Changes the listeners position and orientation using the specified listener 
 * data.
 * @param l Listener data to use.
 */
    public void setListenerData( ListenerData l )
    {
        listener.setData( l );
    }
    
/**
 * Creates sources based on the source map provided.
 * @param srcMap Sources to copy.
 */
    public void copySources( HashMap<String, Source> srcMap )
    {
        if( srcMap == null )
            return;
        Set<String> keys = srcMap.keySet();
        Iterator<String> iter = keys.iterator();        
        String sourcename;
        Source srcData;
        
        // remove any existing sources before starting:
        sourceMap.clear();
        
        // loop through and copy all the sources:
        while( iter.hasNext() )
        {
            sourcename = iter.next();
            srcData = srcMap.get( sourcename );
            if( srcData != null )
            {
                loadSound( srcData.filenameURL );
                sourceMap.put( sourcename, new Source( srcData, null ) );
            }
        }
    }

/**
 * Stops and deletes the specified source.
 * @param sourcename The source's name.
 */
    public void removeSource( String sourcename )
    {
        Source mySource = sourceMap.get( sourcename );
        if( mySource != null ) {
            // if this is a streaming source just mark it removed - https://github.com/MinecraftForge/MinecraftForge/pull/4765
            if ( mySource.toStream )
                mySource.removed = true;
            else
                mySource.cleanup(); // end the source, free memory
        }
        sourceMap.remove( sourcename );
    }

/**
 * Searches for and removes all temporary sources that have finished playing.
 */
    public void removeTemporarySources()
    {
        Set<String> keys = sourceMap.keySet();
        Iterator<String> iter = keys.iterator();
        String sourcename;
        Source srcData;

        // loop through and cleanup all the sources:
        while( iter.hasNext() )
        {
            sourcename = iter.next();
            srcData = sourceMap.get( sourcename );
            if( (srcData != null) && (srcData.temporary)
                 && (!srcData.playing()) )
            {
                srcData.cleanup(); // end the source, free memory
                iter.remove();
            }
        }
    }

/* ########################################################################## */
/*                         END OVERRIDE METHODS                               */
/* ########################################################################## */

/**
 * Returns a handle to the next available channel.  If the specified
 * source is a normal source, a normal channel is returned, and if it is a
 * streaming source, then a streaming channel is returned.  If all channels of
 * the required type are currently playing, then the next channel playing a
 * non-priority source is returned.  If no channels are available (i.e. they
 * are all playing priority sources) then getNextChannel returns null.
 * @param source Source to find a channel for.
 * @return The next available channel, or null.
 */
    private Channel getNextChannel( Source source )
    {
        if( source == null )
            return null;

        String sourcename = source.sourcename;
        if( sourcename == null )
            return null;

        int x;
        int channels;
        int nextChannel;
        List<Channel> channelList;
        String[] sourceNames;
        String name;

        if( source.toStream )
        {
            nextChannel = nextStreamingChannel;
            channelList = streamingChannels;
            sourceNames = streamingChannelSourceNames;
        }
        else
        {
            nextChannel = nextNormalChannel;
            channelList = normalChannels;
            sourceNames = normalChannelSourceNames;
        }

        channels = channelList.size();

        // Check if this source is already on a channel:
        for( x = 0; x < channels; x++ )
        {
            if( sourcename.equals( sourceNames[x] ) )
                return channelList.get( x );
        }

        int n = nextChannel;
        Source src;
        // Play on the next new or non-playing channel:
        for( x = 0; x < channels; x++ )
        {
            name = sourceNames[n];
            if( name == null )
                src = null;
            else
                src = sourceMap.get( name );

            if( src == null || !src.playing() )
            {
                if( source.toStream )
                {
                    nextStreamingChannel = n + 1;
                    if( nextStreamingChannel >= channels )
                        nextStreamingChannel = 0;
                }
                else
                {
                    nextNormalChannel = n + 1;
                    if( nextNormalChannel >= channels )
                        nextNormalChannel = 0;
                }
                sourceNames[n] = sourcename;
                return channelList.get( n );
            }
            n++;
            if( n >= channels )
                n = 0;
        }

        n = nextChannel;
        // Play on the next non-priority channel:
        for( x = 0; x < channels; x++ )
        {
            name = sourceNames[n];
            if( name == null )
                src = null;
            else
                src = sourceMap.get( name );

            if( src == null || !src.playing() || !src.priority )
            {
                if( source.toStream )
                {
                    nextStreamingChannel = n + 1;
                    if( nextStreamingChannel >= channels )
                        nextStreamingChannel = 0;
                }
                else
                {
                    nextNormalChannel = n + 1;
                    if( nextNormalChannel >= channels )
                        nextNormalChannel = 0;
                }
                sourceNames[n] = sourcename;
                return channelList.get( n );
            }
            n++;
            if( n >= channels )
                n = 0;
        }

        return null;
    }

/**
 * Plays all sources whose 'toPlay' varriable is true but are not currently
 * playing (such as sources which were culled while looping and then
 * reactivated).
 */
    public void replaySources()
    {
        Set<String> keys = sourceMap.keySet();
        Iterator<String> iter = keys.iterator();
        String sourcename;
        Source source;

        // loop through and cleanup all the sources:
        while( iter.hasNext() )
        {
            sourcename = iter.next();
            source = sourceMap.get( sourcename );
            if( source != null )
            {
                if( source.toPlay && !source.playing() )
                {
                    play( sourcename );
                    source.toPlay = false;
                }
            }
        }
    }

/**
 * If the specified source is a streaming source or MIDI source, this method
 * queues up the next sound to play when the previous playback ends.  This
 * method has no effect on non-streaming sources.
 * @param sourcename Source identifier.
 * @param filenameURL Filename/URL of the sound file to play next.
 */
    public void queueSound( String sourcename, FilenameURL filenameURL )
    {
        if( midiSourcename( sourcename ) )
        {
            midiChannel.queueSound( filenameURL );
        }
        else
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
                mySource.queueSound( filenameURL );
        }
    }

/**
 * Removes the first occurrence of the specified filename from the specified
 * source's list of sounds to play when previous playback ends.  This method
 * has no effect on non-streaming sources.
 * @param sourcename Source identifier.
 * @param filename Filename/identifier of the sound file to remove from the queue.
 */
    public void dequeueSound( String sourcename, String filename )
    {
        if( midiSourcename( sourcename ) )
        {
            midiChannel.dequeueSound( filename );
        }
        else
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
                mySource.dequeueSound( filename );
        }
    }

/**
 * Fades out the volume of whatever the specified source is currently playing,
 * then begins playing the specified file at the source's previously
 * assigned volume level.  If the filenameURL parameter is null or empty, the
 * specified source will simply fade out and stop.  The miliseconds parameter
 * must be non-negative or zero.  This method will remove anything that is
 * currently in the specified source's list of queued sounds that would have
 * played next when the current sound finished playing.  This method may only
 * be used for streaming and MIDI sources.
 * @param sourcename Name of the source to fade out.
 * @param filenameURL Filename/URL of the sound file to play next, or null for none.
 * @param milis Number of miliseconds the fadeout should take.
 */
    public void fadeOut( String sourcename, FilenameURL filenameURL,
                         long milis )
    {
        if( midiSourcename( sourcename ) )
        {
            midiChannel.fadeOut( filenameURL, milis );
        }
        else
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
                mySource.fadeOut( filenameURL, milis );
        }
    }

/**
 * Fades out the volume of whatever the specified source is currently playing,
 * then fades the volume back in playing the specified file.  Final volume
 * after fade-in completes will be equal to the source's previously assigned
 * volume level.  The filenameURL parameter may not be null or empty.  The
 * miliseconds parameters must be non-negative or zero.  This method will
 * remove anything that is currently in the specified source's list of queued
 * sounds that would have played next when the current sound finished playing.
 * This method may only be used for streaming and MIDI sources.
 * @param sourcename Name of the source to fade out/in.
 * @param filenameURL Filename/URL of the sound file to play next, or null for none.
 * @param milisOut Number of miliseconds the fadeout should take.
 * @param milisIn Number of miliseconds the fadein should take.
 */
    public void fadeOutIn( String sourcename, FilenameURL filenameURL,
                           long milisOut, long milisIn )
    {
        if( midiSourcename( sourcename ) )
        {
            midiChannel.fadeOutIn( filenameURL, milisOut, milisIn );
        }
        else
        {
            Source mySource = sourceMap.get( sourcename );
            if( mySource != null )
                mySource.fadeOutIn( filenameURL, milisOut, milisIn );
        }
    }

/**
 * Makes sure the current volume levels of streaming sources and MIDI are
 * correct.  This method is designed to help reduce the "jerky" fading behavior
 * that happens when using some library and codec pluggins (such as
 * LibraryJavaSound and CodecJOrbis).  This method has no effect on normal
 * "non-streaming" sources.  It would normally be called somewhere in the main
 * "game loop".  IMPORTANT: To optimize frame-rates, do not call this method
 * for every frame.  It is better to just call this method at some acceptable
 * "granularity" (play around with different granularities to find what sounds
 * acceptable for a particular situation).
 */
    public void checkFadeVolumes()
    {
        if( midiChannel != null )
            midiChannel.resetGain();
        Channel c;
        Source s;
        for( int x = 0; x < streamingChannels.size(); x++ )
        {
            c = streamingChannels.get( x );
            if( c != null )
            {
                s = c.attachedSource;
                if( s != null )
                    s.checkFadeOut();
            }
        }
        c = null;
        s = null;
    }

/**
 * Loads the specified MIDI file, and saves the source information about it.
 * @param toLoop Midi file should loop or play once.
 * @param sourcename Source identifier.
 * @param filenameURL Filename/URL of the MIDI file to load.
 */
    public void loadMidi( boolean toLoop, String sourcename,
                          FilenameURL filenameURL )
    {
        if( filenameURL == null )
        {
            errorMessage( "Filename/URL not specified in method 'loadMidi'." );
            return;
        }

        if( !filenameURL.getFilename().matches(
                                            SoundSystemConfig.EXTENSION_MIDI ) )
        {
            errorMessage( "Filename/identifier doesn't end in '.mid' or" +
                          "'.midi' in method loadMidi." );
            return;
        }

        if( midiChannel == null )
        {
            midiChannel = new MidiChannel( toLoop, sourcename, filenameURL );
        }
        else
        {
            midiChannel.switchSource( toLoop, sourcename, filenameURL );
        }
    }

/**
 * Unloads the current Midi file.
 */
    public void unloadMidi()
    {
        if( midiChannel != null )
            midiChannel.cleanup();
        midiChannel = null;
    }

/**
 * Checks if the sourcename matches the midi source.
 * @param sourcename Source identifier.
 * @return True if sourcename and midi sourcename match.
 */
    public boolean midiSourcename( String sourcename )
    {
        if( midiChannel == null || sourcename == null )
            return false;

        if( midiChannel.getSourcename() == null || sourcename.equals( "" ) )
            return false;

        if( sourcename.equals( midiChannel.getSourcename() ) )
            return true;

        return false;
    }

/**
 *
 * Returns the Source object identified by the specified name.
 * @param sourcename The source's name.
 * @return The source, or null if not found.
 */
    public Source getSource( String sourcename )
    {
        return sourceMap.get( sourcename );
    }

/**
 *
 * Returns a handle to the MIDI channel, or null if one does not exist.
 * @return The MIDI channel.
 */
    public MidiChannel getMidiChannel()
    {
        return midiChannel;
    }

/**
 *
 * Specifies the MIDI channel to use.
 * @param c New MIDI channel.
 */
    public void setMidiChannel( MidiChannel c )
    {
        if( midiChannel != null && midiChannel != c )
            midiChannel.cleanup();

        midiChannel = c;
    }

/**
 * Tells all the sources that the listener has moved.
 */
    public void listenerMoved()
    {
        Set<String> keys = sourceMap.keySet();
        Iterator<String> iter = keys.iterator();        
        String sourcename;
        Source srcData;
        
        // loop through and copy all the sources:
        while( iter.hasNext() )
        {
            sourcename = iter.next();
            srcData = sourceMap.get( sourcename );
            if( srcData != null )
            {
                srcData.listenerMoved();
            }
        }
    }
    
/**
 * Returns the sources map.
 * @return Map of all sources.
 */
    public HashMap<String, Source> getSources()
    {
        return sourceMap;
    }
    
/**
 * Returns information about the listener.
 * @return A ListenerData object.
 */
    public ListenerData getListenerData()
    {
        return listener;
    }
    
/**
 * Indicates whether or not this library requires some codecs to reverse-order
 * the audio data they generate.
 * @return True if audio data should be reverse-ordered.
 */
    public boolean reverseByteOrder()
    {
        return reverseByteOrder;
    }
/**
 * Returns the short title of this library type.
 * @return A short title.
 */
    public static String getTitle()
    {
        return "No Sound";
    }
    
/**
 * Returns a longer description of this library type.
 * @return A longer description.
 */
    public static String getDescription()
    {
        return "Silent Mode";
    }
    
/**
 * Returns the name of the class.
 * @return "Library" + library title.
 */
    public String getClassName()
    {
        return "Library";
    }
    
/**
 * Prints a message.
 * @param message Message to print.
 */
    protected void message( String message )
    {
        logger.message( message, 0 );
    }
    
/**
 * Prints an important message.
 * @param message Message to print.
 */
    protected void importantMessage( String message )
    {
        logger.importantMessage( message, 0 );
    }
    
/**
 * Prints the specified message if error is true.
 * @param error True or False.
 * @param message Message to print if error is true.
 * @return True if error is true.
 */
    protected boolean errorCheck( boolean error, String message )
    {
        return logger.errorCheck( error, getClassName(), message, 0 );
    }
    
/**
 * Prints an error message.
 * @param message Message to print.
 */
    protected void errorMessage( String message )
    {
        logger.errorMessage( getClassName(), message, 0 );
    }
    
/**
 * Prints an exception's error message followed by the stack trace.
 * @param e Exception containing the information to print.
 */
    protected void printStackTrace( Exception e )
    {
        logger.printStackTrace( e, 1 );
    }
}