Logo Search packages:      
Sourcecode: libjlayer-java version File versions  Download package

AudioDevice.java

/*
 * 11/19/04       1.0 moved to LGPL.
 * 29/01/00       Initial version. mdm@techie.com
 *-----------------------------------------------------------------------
 *   This program is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU Library General Public License as published
 *   by the Free Software Foundation; either version 2 of the License, or
 *   (at your option) any later version.
 *
 *   This program 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 Library General Public License for more details.
 *
 *   You should have received a copy of the GNU Library General Public
 *   License along with this program; if not, write to the Free Software
 *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *----------------------------------------------------------------------
 */

package javazoom.jl.player;

import javazoom.jl.decoder.Decoder;
import javazoom.jl.decoder.JavaLayerException;

/**
 * The <code>AudioDevice</code> interface provides an abstraction for
 * a device capable of sounding audio samples. Samples are written to 
 * the device wia the write() method. The device assumes
 * that these samples are signed 16-bit samples taken at the output frequency
 * of the decoder. If the decoder outputs more than one channel, the samples for
 * each channel are assumed to appear consecutively, with the lower numbered
 * channels preceeding higher-numbered channels. E.g. if there are two
 * channels, the samples will appear in this order:
 * <pre><code>
 * 
 *          l0, r0, l1, r1, l2, r2...
 * 
 * where 
 *    l<i>x</i> indicates the <i>x</i>th sample on channel 0
 *  r<i>x</i> indicates the <i>x</i>th sample on channel 1
 * </code></pre>
 *   
 * @since   0.0.8
 * @author  Mat McGowan
 */
00047 public interface AudioDevice
{
      /**
       * Prepares the AudioDevice for playback of audio samples. 
       * @param decoder The decoder that will be providing the audio
       *                            samples. 
       * 
       * If the audio device is already open, this method returns silently. 
       * 
       */
      public void open(Decoder decoder) throws JavaLayerException;
            
      /**
       * Retrieves the open state of this audio device. 
       * 
       * @return <code>true</code> if this audio device is open and playing
       *                audio samples, or <code>false</code> otherwise. 
       */
      public boolean isOpen();
      
      /**
       * Writes a number of samples to this <code>AudioDevice</code>. 
       * 
       * @param samples The array of signed 16-bit samples to write
       *                            to the audio device. 
       * @param offs          The offset of the first sample.
       * @param len           The number of samples to write. 
       * 
       * This method may return prior to the samples actually being played 
       * by the audio device. 
       */
      public void write(short[] samples, int offs, int len) throws JavaLayerException;
            
      
      /**
       * Closes this audio device. Any currently playing audio is stopped 
       * as soon as possible. Any previously written audio data that has not been heard
       * is discarded. 
       * 
       * The implementation should ensure that any threads currently blocking
       * on the device (e.g. during a <code>write</code> or <code>flush</code>
       * operation should be unblocked by this method. 
       */
      public void close();
      
      
      /**
       * Blocks until all audio samples previously written to this audio device have
       * been heard. 
       */
      public void flush();
                  
      /**
       * Retrieves the current playback position in milliseconds. 
       */
      public int getPosition();
}

Generated by  Doxygen 1.6.0   Back to index