src/share/classes/javax/sound/sampled/SourceDataLine.java

Print this page




   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.sound.sampled;
  27 
  28 
  29 /**
  30  * A source data line is a data line to which data may be written.  It acts as
  31  * a source to its mixer. An application writes audio bytes to a source data line,
  32  * which handles the buffering of the bytes and delivers them to the mixer.
  33  * The mixer may mix the samples with those from other sources and then deliver
  34  * the mix to a target such as an output port (which may represent an audio output
  35  * device on a sound card).
  36  * <p>
  37  * Note that the naming convention for this interface reflects the relationship
  38  * between the line and its mixer.  From the perspective of an application,
  39  * a source data line may act as a target for audio data.
  40  * <p>
  41  * A source data line can be obtained from a mixer by invoking the
  42  * <code>{@link Mixer#getLine getLine}</code> method of <code>Mixer</code> with
  43  * an appropriate <code>{@link DataLine.Info}</code> object.
  44  * <p>
  45  * The <code>SourceDataLine</code> interface provides a method for writing
  46  * audio data to the data line's buffer. Applications that play or mix
  47  * audio should write data to the source data line quickly enough to keep the
  48  * buffer from underflowing (emptying), which could cause discontinuities in
  49  * the audio that are perceived as clicks.  Applications can use the
  50  * <code>{@link DataLine#available available}</code> method defined in the
  51  * <code>DataLine</code> interface to determine the amount of data currently
  52  * queued in the data line's buffer.  The amount of data which can be written
  53  * to the buffer without blocking is the difference between the buffer size
  54  * and the amount of queued data.  If the delivery of audio output
  55  * stops due to underflow, a <code>{@link LineEvent.Type#STOP STOP}</code> event is
  56  * generated.  A <code>{@link LineEvent.Type#START START}</code> event is generated
  57  * when the audio output resumes.
  58  *
  59  * @author Kara Kytle
  60  * @see Mixer
  61  * @see DataLine
  62  * @see TargetDataLine
  63  * @since 1.3
  64  */
  65 public interface SourceDataLine extends DataLine {
  66 
  67 
  68     /**
  69      * Opens the line with the specified format and suggested buffer size,
  70      * causing the line to acquire any required
  71      * system resources and become operational.
  72      * <p>
  73      * The buffer size is specified in bytes, but must represent an integral
  74      * number of sample frames.  Invoking this method with a requested buffer
  75      * size that does not meet this requirement may result in an
  76      * IllegalArgumentException.  The actual buffer size for the open line may
  77      * differ from the requested buffer size.  The value actually set may be
  78      * queried by subsequently calling <code>{@link DataLine#getBufferSize}</code>.
  79      * <p>
  80      * If this operation succeeds, the line is marked as open, and an
  81      * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched to the
  82      * line's listeners.
  83      * <p>
  84      * Invoking this method on a line which is already open is illegal
  85      * and may result in an <code>IllegalStateException</code>.
  86      * <p>
  87      * Note that some lines, once closed, cannot be reopened.  Attempts
  88      * to reopen such a line will always result in a
  89      * <code>LineUnavailableException</code>.
  90      *
  91      * @param format the desired audio format
  92      * @param bufferSize the desired buffer size
  93      * @throws LineUnavailableException if the line cannot be
  94      * opened due to resource restrictions
  95      * @throws IllegalArgumentException if the buffer size does not represent
  96      * an integral number of sample frames,
  97      * or if <code>format</code> is not fully specified or invalid
  98      * @throws IllegalStateException if the line is already open
  99      * @throws SecurityException if the line cannot be
 100      * opened due to security restrictions
 101      *
 102      * @see #open(AudioFormat)
 103      * @see Line#open
 104      * @see Line#close
 105      * @see Line#isOpen
 106      * @see LineEvent
 107      */
 108     public void open(AudioFormat format, int bufferSize) throws LineUnavailableException;
 109 
 110 
 111     /**
 112      * Opens the line with the specified format, causing the line to acquire any
 113      * required system resources and become operational.
 114      *
 115      * <p>
 116      * The implementation chooses a buffer size, which is measured in bytes but
 117      * which encompasses an integral number of sample frames.  The buffer size
 118      * that the system has chosen may be queried by subsequently calling
 119      * <code>{@link DataLine#getBufferSize}</code>.
 120      * <p>
 121      * If this operation succeeds, the line is marked as open, and an
 122      * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched to the
 123      * line's listeners.
 124      * <p>
 125      * Invoking this method on a line which is already open is illegal
 126      * and may result in an <code>IllegalStateException</code>.
 127      * <p>
 128      * Note that some lines, once closed, cannot be reopened.  Attempts
 129      * to reopen such a line will always result in a
 130      * <code>LineUnavailableException</code>.
 131      *
 132      * @param format the desired audio format
 133      * @throws LineUnavailableException if the line cannot be
 134      * opened due to resource restrictions
 135      * @throws IllegalArgumentException if <code>format</code>
 136      * is not fully specified or invalid
 137      * @throws IllegalStateException if the line is already open
 138      * @throws SecurityException if the line cannot be
 139      * opened due to security restrictions
 140      *
 141      * @see #open(AudioFormat, int)
 142      * @see Line#open
 143      * @see Line#close
 144      * @see Line#isOpen
 145      * @see LineEvent
 146      */
 147     public void open(AudioFormat format) throws LineUnavailableException;
 148 
 149 
 150     /**
 151      * Writes audio data to the mixer via this source data line.  The requested
 152      * number of bytes of data are read from the specified array,
 153      * starting at the given offset into the array, and written to the data
 154      * line's buffer.  If the caller attempts to write more data than can
 155      * currently be written (see <code>{@link DataLine#available available}</code>),
 156      * this method blocks until the requested amount of data has been written.
 157      * This applies even if the requested amount of data to write is greater
 158      * than the data line's buffer size.  However, if the data line is closed,
 159      * stopped, or flushed before the requested amount has been written,
 160      * the method no longer blocks, but returns the number of bytes
 161      * written thus far.
 162      * <p>
 163      * The number of bytes that can be written without blocking can be ascertained
 164      * using the <code>{@link DataLine#available available}</code> method of the
 165      * <code>DataLine</code> interface.  (While it is guaranteed that
 166      * this number of bytes can be written without blocking, there is no guarantee
 167      * that attempts to write additional data will block.)
 168      * <p>
 169      * The number of bytes to write must represent an integral number of
 170      * sample frames, such that:
 171      * <br>
 172      * <center><code>[ bytes written ] % [frame size in bytes ] == 0</code></center>
 173      * <br>
 174      * The return value will always meet this requirement.  A request to write a
 175      * number of bytes representing a non-integral number of sample frames cannot
 176      * be fulfilled and may result in an <code>IllegalArgumentException</code>.

 177      *
 178      * @param b a byte array containing data to be written to the data line
 179      * @param len the length, in bytes, of the valid data in the array
 180      * (in other words, the requested amount of data to write, in bytes)
 181      * @param off the offset from the beginning of the array, in bytes
 182      * @return the number of bytes actually written
 183      * @throws IllegalArgumentException if the requested number of bytes does
 184      * not represent an integral number of sample frames,
 185      * or if <code>len</code> is negative
 186      * @throws ArrayIndexOutOfBoundsException if <code>off</code> is negative,
 187      * or <code>off+len</code> is greater than the length of the array
 188      * <code>b</code>.
 189      *
 190      * @see TargetDataLine#read
 191      * @see DataLine#available
 192      */
 193     public int write(byte[] b, int off, int len);
 194 
 195     /**
 196      * Obtains the number of sample frames of audio data that can be written to
 197      * the mixer, via this data line, without blocking.  Note that the return
 198      * value measures sample frames, not bytes.

 199      * @return the number of sample frames currently available for writing
 200      * @see TargetDataLine#availableRead
 201      */
 202     //public int availableWrite();
 203 }


   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.sound.sampled;
  27 

  28 /**
  29  * A source data line is a data line to which data may be written. It acts as a
  30  * source to its mixer. An application writes audio bytes to a source data line,
  31  * which handles the buffering of the bytes and delivers them to the mixer. The
  32  * mixer may mix the samples with those from other sources and then deliver the
  33  * mix to a target such as an output port (which may represent an audio output
  34  * device on a sound card).
  35  * <p>
  36  * Note that the naming convention for this interface reflects the relationship
  37  * between the line and its mixer. From the perspective of an application, a
  38  * source data line may act as a target for audio data.
  39  * <p>
  40  * A source data line can be obtained from a mixer by invoking the
  41  * {@link Mixer#getLine getLine} method of {@code Mixer} with an appropriate
  42  * {@link DataLine.Info} object.
  43  * <p>
  44  * The {@code SourceDataLine} interface provides a method for writing audio data
  45  * to the data line's buffer. Applications that play or mix audio should write
  46  * data to the source data line quickly enough to keep the buffer from
  47  * underflowing (emptying), which could cause discontinuities in the audio that
  48  * are perceived as clicks. Applications can use the
  49  * {@link DataLine#available available} method defined in the {@code DataLine}
  50  * interface to determine the amount of data currently queued in the data line's
  51  * buffer. The amount of data which can be written to the buffer without
  52  * blocking is the difference between the buffer size and the amount of queued
  53  * data. If the delivery of audio output stops due to underflow, a
  54  * {@link LineEvent.Type#STOP STOP} event is generated. A
  55  * {@link LineEvent.Type#START START} event is generated when the audio output
  56  * resumes.
  57  *
  58  * @author Kara Kytle
  59  * @see Mixer
  60  * @see DataLine
  61  * @see TargetDataLine
  62  * @since 1.3
  63  */
  64 public interface SourceDataLine extends DataLine {
  65 

  66     /**
  67      * Opens the line with the specified format and suggested buffer size,
  68      * causing the line to acquire any required system resources and become
  69      * operational.
  70      * <p>
  71      * The buffer size is specified in bytes, but must represent an integral
  72      * number of sample frames. Invoking this method with a requested buffer
  73      * size that does not meet this requirement may result in an
  74      * {@code IllegalArgumentException}. The actual buffer size for the open
  75      * line may differ from the requested buffer size. The value actually set
  76      * may be queried by subsequently calling {@link DataLine#getBufferSize}.
  77      * <p>
  78      * If this operation succeeds, the line is marked as open, and an
  79      * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's
  80      * listeners.
  81      * <p>
  82      * Invoking this method on a line which is already open is illegal and may
  83      * result in an {@code IllegalStateException}.
  84      * <p>
  85      * Note that some lines, once closed, cannot be reopened. Attempts to reopen
  86      * such a line will always result in a {@code LineUnavailableException}.

  87      *
  88      * @param  format the desired audio format
  89      * @param  bufferSize the desired buffer size
  90      * @throws LineUnavailableException if the line cannot be opened due to
  91      *         resource restrictions
  92      * @throws IllegalArgumentException if the buffer size does not represent an
  93      *         integral number of sample frames, or if {@code format} is not
  94      *         fully specified or invalid
  95      * @throws IllegalStateException if the line is already open
  96      * @throws SecurityException if the line cannot be opened due to security
  97      *         restrictions

  98      * @see #open(AudioFormat)
  99      * @see Line#open
 100      * @see Line#close
 101      * @see Line#isOpen
 102      * @see LineEvent
 103      */
 104     void open(AudioFormat format, int bufferSize)
 105             throws LineUnavailableException;
 106 
 107     /**
 108      * Opens the line with the specified format, causing the line to acquire any
 109      * required system resources and become operational.

 110      * <p>
 111      * The implementation chooses a buffer size, which is measured in bytes but
 112      * which encompasses an integral number of sample frames. The buffer size
 113      * that the system has chosen may be queried by subsequently calling
 114      * {@link DataLine#getBufferSize}.
 115      * <p>
 116      * If this operation succeeds, the line is marked as open, and an
 117      * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's
 118      * listeners.
 119      * <p>
 120      * Invoking this method on a line which is already open is illegal and may
 121      * result in an {@code IllegalStateException}.
 122      * <p>
 123      * Note that some lines, once closed, cannot be reopened. Attempts to reopen
 124      * such a line will always result in a {@code LineUnavailableException}.

 125      *
 126      * @param  format the desired audio format
 127      * @throws LineUnavailableException if the line cannot be opened due to
 128      *         resource restrictions
 129      * @throws IllegalArgumentException if {@code format} is not fully specified
 130      *         or invalid
 131      * @throws IllegalStateException if the line is already open
 132      * @throws SecurityException if the line cannot be opened due to security
 133      *         restrictions

 134      * @see #open(AudioFormat, int)
 135      * @see Line#open
 136      * @see Line#close
 137      * @see Line#isOpen
 138      * @see LineEvent
 139      */
 140     void open(AudioFormat format) throws LineUnavailableException;

 141 
 142     /**
 143      * Writes audio data to the mixer via this source data line. The requested
 144      * number of bytes of data are read from the specified array, starting at
 145      * the given offset into the array, and written to the data line's buffer.
 146      * If the caller attempts to write more data than can currently be written
 147      * (see {@link DataLine#available available}), this method blocks until the
 148      * requested amount of data has been written. This applies even if the
 149      * requested amount of data to write is greater than the data line's buffer
 150      * size. However, if the data line is closed, stopped, or flushed before the
 151      * requested amount has been written, the method no longer blocks, but
 152      * returns the number of bytes written thus far.
 153      * <p>
 154      * The number of bytes that can be written without blocking can be
 155      * ascertained using the {@link DataLine#available available} method of the
 156      * {@code DataLine} interface. (While it is guaranteed that this number of
 157      * bytes can be written without blocking, there is no guarantee that
 158      * attempts to write additional data will block.)

 159      * <p>
 160      * The number of bytes to write must represent an integral number of sample
 161      * frames, such that:
 162      * <br>
 163      * <center>{@code [ bytes written ] % [frame size in bytes ] == 0}</center>
 164      * <br>
 165      * The return value will always meet this requirement. A request to write a
 166      * number of bytes representing a non-integral number of sample frames
 167      * cannot be fulfilled and may result in an
 168      * {@code IllegalArgumentException}.
 169      *
 170      * @param  b a byte array containing data to be written to the data line
 171      * @param  len the length, in bytes, of the valid data in the array (in
 172      *         other words, the requested amount of data to write, in bytes)
 173      * @param  off the offset from the beginning of the array, in bytes
 174      * @return the number of bytes actually written
 175      * @throws IllegalArgumentException if the requested number of bytes does
 176      *         not represent an integral number of sample frames, or if
 177      *         {@code len} is negative
 178      * @throws ArrayIndexOutOfBoundsException if {@code off} is negative, or
 179      *         {@code off+len} is greater than the length of the array {@code b}


 180      * @see TargetDataLine#read
 181      * @see DataLine#available
 182      */
 183     int write(byte[] b, int off, int len);
 184 
 185     /**
 186      * Obtains the number of sample frames of audio data that can be written to
 187      * the mixer, via this data line, without blocking. Note that the return
 188      * value measures sample frames, not bytes.
 189      *
 190      * @return the number of sample frames currently available for writing
 191      * @see TargetDataLine#availableRead
 192      */
 193     //public int availableWrite();
 194 }