FileDocCategorySizeDatePackage
AudioInputStream.javaAPI DocJava SE 5 API14280Fri Aug 26 14:57:50 BST 2005javax.sound.sampled

AudioInputStream

public class AudioInputStream extends InputStream
An audio input stream is an input stream with a specified audio format and length. The length is expressed in sample frames, not bytes. Several methods are provided for reading a certain number of bytes from the stream, or an unspecified number of bytes. The audio input stream keeps track of the last byte that was read. You can skip over an arbitrary number of bytes to get to a later position for reading. An audio input stream may support marks. When you set a mark, the current position is remembered so that you can return to it later.

The AudioSystem class includes many methods that manipulate AudioInputStream objects. For example, the methods let you:

  • obtain an audio input stream from an external audio file, stream, or URL
  • write an external file from an audio input stream
  • convert an audio input stream to a different audio format
author
David Rivas
author
Kara Kytle
author
Florian Bomers
version
1.32, 03/12/19
see
AudioSystem
see
Clip#open(AudioInputStream) Clip.open(AudioInputStream)
since
1.3

Fields Summary
private InputStream
stream
The InputStream from which this AudioInputStream object was constructed.
protected AudioFormat
format
The format of the audio data contained in the stream.
protected long
frameLength
This stream's length, in sample frames.
protected int
frameSize
The size of each frame, in bytes.
protected long
framePos
The current position in this stream, in sample frames (zero-based).
private long
markpos
The position where a mark was set.
private byte[]
pushBackBuffer
When the underlying stream could only return a non-integral number of frames, store the remainder in a temporary buffer
private int
pushBackLen
number of valid bytes in the pushBackBuffer
private byte[]
markPushBackBuffer
MarkBuffer at mark position
private int
markPushBackLen
number of valid bytes in the markPushBackBuffer
Constructors Summary
public AudioInputStream(InputStream stream, AudioFormat format, long length)
Constructs an audio input stream that has the requested format and length in sample frames, using audio data from the specified input stream.

param
stream the stream on which this AudioInputStream object is based
param
format the format of this stream's audio data
param
length the length in sample frames of the data in this stream

    

                                                                 
           

	super();

	this.format = format;
	this.frameLength = length;
	this.frameSize = format.getFrameSize();

	// any frameSize that is not well-defined will
	// cause that this stream will be read in bytes
	if( this.frameSize == AudioSystem.NOT_SPECIFIED || frameSize <= 0) {
	    this.frameSize = 1;
	}

	this.stream = stream;
	framePos = 0;
	markpos = 0;
    
public AudioInputStream(TargetDataLine line)
Constructs an audio input stream that reads its data from the target data line indicated. The format of the stream is the same as that of the target data line, and the length is AudioSystem#NOT_SPECIFIED.

param
line the target data line from which this stream obtains its data.
see
AudioSystem#NOT_SPECIFIED


	TargetDataLineInputStream tstream = new TargetDataLineInputStream(line);
	format = line.getFormat();
	frameLength = AudioSystem.NOT_SPECIFIED;
	frameSize = format.getFrameSize();

	if( frameSize == AudioSystem.NOT_SPECIFIED || frameSize <= 0) {
	    frameSize = 1;
	}
	this.stream = tstream;
	framePos = 0;
	markpos = 0;
    
Methods Summary
public intavailable()
Returns the maximum number of bytes that can be read (or skipped over) from this audio input stream without blocking. This limit applies only to the next invocation of a read or skip method for this audio input stream; the limit can vary each time these methods are invoked. Depending on the underlying stream,an IOException may be thrown if this stream is closed.

return
the number of bytes that can be read from this audio input stream without blocking
throws
IOException if an input or output error occurs
see
#read(byte[], int, int)
see
#read(byte[])
see
#read()
see
#skip


	int temp = stream.available();

	// don't return greater than our set length in frames
	if( (frameLength != AudioSystem.NOT_SPECIFIED) && ( (temp/frameSize) > (frameLength-framePos)) ) {
	    return (int) (frameLength-framePos) * frameSize;
	} else {
	    return temp;
	}
    
public voidclose()
Closes this audio input stream and releases any system resources associated with the stream.

throws
IOException if an input or output error occurs

	stream.close();
    
public javax.sound.sampled.AudioFormatgetFormat()
Obtains the audio format of the sound data in this audio input stream.

return
an audio format object describing this stream's format

	return format;
    
public longgetFrameLength()
Obtains the length of the stream, expressed in sample frames rather than bytes.

return
the length in sample frames

	return frameLength;
    
public voidmark(int readlimit)
Marks the current position in this audio input stream.

param
readlimit the maximum number of bytes that can be read before the mark position becomes invalid.
see
#reset
see
#markSupported


	stream.mark(readlimit);
	if (markSupported()) {
	    markpos = framePos;
	    // remember the pushback buffer
	    markPushBackLen = pushBackLen;
	    if (markPushBackLen > 0) {
		if (markPushBackBuffer == null) {
		    markPushBackBuffer = new byte[frameSize];
		}
		System.arraycopy(pushBackBuffer, 0, markPushBackBuffer, 0, markPushBackLen);
	    }
	}
    
public booleanmarkSupported()
Tests whether this audio input stream supports the mark and reset methods.

return
true if this stream supports the mark and reset methods; false otherwise
see
#mark
see
#reset


	return stream.markSupported();
    
public intread()
Reads the next byte of data from the audio input stream. The audio input stream's frame size must be one byte, or an IOException will be thrown.

return
the next byte of data, or -1 if the end of the stream is reached
throws
IOException if an input or output error occurs
see
#read(byte[], int, int)
see
#read(byte[])
see
#available

	if( frameSize != 1 ) {
	    throw new IOException("cannot read a single byte if frame size > 1");
	}

	byte[] data = new byte[1];
	int temp = read(data);
	if (temp <= 0) {
	    // we have a weird situation if read(byte[]) returns 0!
	    return -1;
	}
    	return temp & 0xFF;
    
public intread(byte[] b)
Reads some number of bytes from the audio input stream and stores them into the buffer array b. The number of bytes actually read is returned as an integer. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

This method will always read an integral number of frames. If the length of the array is not an integral number of frames, a maximum of b.length - (b.length % frameSize) bytes will be read.

param
b the buffer into which the data is read
return
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached
throws
IOException if an input or output error occurs
see
#read(byte[], int, int)
see
#read()
see
#available

	return read(b,0,b.length);
    
public intread(byte[] b, int off, int len)
Reads up to a specified maximum number of bytes of data from the audio stream, putting them into the given byte array.

This method will always read an integral number of frames. If len does not specify an integral number of frames, a maximum of len - (len % frameSize) bytes will be read.

param
b the buffer into which the data is read
param
off the offset, from the beginning of array b, at which the data will be written
param
len the maximum number of bytes to read
return
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached
throws
IOException if an input or output error occurs
see
#read(byte[])
see
#read()
see
#skip
see
#available


	// make sure we don't read fractions of a frame.
	if( (len%frameSize) != 0 ) {
	    len -= (len%frameSize);
	    if (len == 0) {
	    	return 0;
	    }
	}

	if( frameLength != AudioSystem.NOT_SPECIFIED ) {
	    if( framePos >= frameLength ) {
		return -1;
	    } else {

		// don't try to read beyond our own set length in frames
		if( (len/frameSize) > (frameLength-framePos) ) {
		    len = (int) (frameLength-framePos) * frameSize;
		}
	    }
	}
	
	int bytesRead = 0;
	int thisOff = off;
	
	// if we've bytes left from last call to read(),
	// use them first
	if (pushBackLen > 0 && len >= pushBackLen) {
	    System.arraycopy(pushBackBuffer, 0,
	                     b, off, pushBackLen);
	    thisOff += pushBackLen;
	    len -= pushBackLen;
	    bytesRead += pushBackLen;
	    pushBackLen = 0;
	}
	
	int thisBytesRead = stream.read(b, thisOff, len);
	if (thisBytesRead == -1) {
	    return -1;
	}
	if (thisBytesRead > 0) {
	    bytesRead += thisBytesRead;
	}
	if (bytesRead > 0) {
	    pushBackLen = bytesRead % frameSize;
	    if (pushBackLen > 0) {
		// copy everything we got from the beginning of the frame
		// to our pushback buffer
		if (pushBackBuffer == null) {
		    pushBackBuffer = new byte[frameSize];
		}
		System.arraycopy(b, off + bytesRead - pushBackLen, 
		                 pushBackBuffer, 0, pushBackLen);
		bytesRead -= pushBackLen;
	    }
	    // make sure to update our framePos
	    framePos += bytesRead/frameSize;
	}
	return bytesRead;
    
public voidreset()
Repositions this audio input stream to the position it had at the time its mark method was last invoked.

throws
IOException if an input or output error occurs.
see
#mark
see
#markSupported


	stream.reset();
	framePos = markpos;
	// re-create the pushback buffer
	pushBackLen = markPushBackLen;
	if (pushBackLen > 0) {
	    if (pushBackBuffer == null) {
		pushBackBuffer = new byte[frameSize - 1];
	    }
	    System.arraycopy(markPushBackBuffer, 0, pushBackBuffer, 0, pushBackLen);
	}
    
public longskip(long n)
Skips over and discards a specified number of bytes from this audio input stream.

param
n the requested number of bytes to be skipped
return
the actual number of bytes skipped
throws
IOException if an input or output error occurs
see
#read
see
#available


	// make sure not to skip fractional frames
	if( (n%frameSize) != 0 ) {
	    n -= (n%frameSize);
	}

	if( frameLength != AudioSystem.NOT_SPECIFIED ) {
	    // don't skip more than our set length in frames.
	    if( (n/frameSize) > (frameLength-framePos) ) {
		n = (frameLength-framePos) * frameSize;
	    }
	}
	long temp = stream.skip(n);

	// if no error, update our position.
	if( temp%frameSize != 0 ) {

	    // Throw an IOException if we've skipped a fractional number of frames
	    throw new IOException("Could not skip an integer number of frames.");
	}
	if( temp >= 0 ) {
	    framePos += temp/frameSize;
	}
	return temp;