https://openjdk.java.net/ 
/*
 * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code 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 General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.sound.sampled;

import java.io.IOException;
import java.io.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, Kara Kytle, Florian Bomers
See Also:
Since:1.3
/**
 * 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.
 * <p>
 * The {@code AudioSystem} class includes many methods that manipulate
 * {@code AudioInputStream} objects. For example, the methods let you:
 * <ul>
 *   <li>obtain an audio input stream from an external audio file, stream, or
 *   {@code URL}
 *   <li>write an external file from an audio input stream
 *   <li>convert an audio input stream to a different audio format
 * </ul>
 *
 * @author David Rivas
 * @author Kara Kytle
 * @author Florian Bomers
 * @see AudioSystem
 * @see Clip#open(AudioInputStream)
 * @since 1.3
 */
public class AudioInputStream extends InputStream {

    
The InputStream from which this AudioInputStream object was constructed. 
/**
     * The {@code InputStream} from which this {@code AudioInputStream} object
     * was constructed.
     */
    private final InputStream stream;

    
The format of the audio data contained in the stream.

/**
     * The format of the audio data contained in the stream.
     */
    protected AudioFormat format;

    
This stream's length, in sample frames.

/**
     * This stream's length, in sample frames.
     */
    protected long frameLength;

    
The size of each frame, in bytes.

/**
     * The size of each frame, in bytes.
     */
    protected int frameSize;

    
The current position in this stream, in sample frames (zero-based).

/**
     * The current position in this stream, in sample frames (zero-based).
     */
    protected long framePos;

    
The position where a mark was set.

/**
     * The position where a mark was set.
     */
    private long markpos;

    
When the underlying stream could only return a non-integral number of
frames, store the remainder in a temporary buffer.

/**
     * When the underlying stream could only return a non-integral number of
     * frames, store the remainder in a temporary buffer.
     */
    private byte[] pushBackBuffer = null;

    
number of valid bytes in the pushBackBuffer.

/**
     * number of valid bytes in the pushBackBuffer.
     */
    private int pushBackLen = 0;

    
MarkBuffer at mark position.

/**
     * MarkBuffer at mark position.
     */
    private byte[] markPushBackBuffer = null;

    
number of valid bytes in the markPushBackBuffer.

/**
     * number of valid bytes in the markPushBackBuffer.
     */
    private int markPushBackLen = 0;

    
Constructs an audio input stream that has the requested format and length
in sample frames, using audio data from the specified input stream.

Params:
  • stream – the stream on which this AudioInputStream object is based
  • format – the format of this stream's audio data
  • length – the length in sample frames of the data in this stream
/**
     * 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 {@code 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
     */
    public AudioInputStream(InputStream stream, AudioFormat format, long length) {

        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;
    }

    
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. 
Params:
  • line – the target data line from which this stream obtains its data
See Also:
/**
     * 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 {@code AudioSystem#NOT_SPECIFIED}.
     *
     * @param  line the target data line from which this stream obtains its data
     * @see AudioSystem#NOT_SPECIFIED
     */
    public AudioInputStream(TargetDataLine line) {

        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;
    }

    
Obtains the audio format of the sound data in this audio input stream.

Returns:an audio format object describing this stream's format
/**
     * Obtains the audio format of the sound data in this audio input stream.
     *
     * @return an audio format object describing this stream's format
     */
    public AudioFormat getFormat() {
        return format;
    }

    
Obtains the length of the stream, expressed in sample frames rather than
bytes.

Returns:the length in sample frames
/**
     * Obtains the length of the stream, expressed in sample frames rather than
     * bytes.
     *
     * @return the length in sample frames
     */
    public long getFrameLength() {
        return frameLength;
    }

    
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. 
Throws:
See Also:
Returns:the next byte of data, or -1 if the end of the stream is reached
/**
     * Reads the next byte of data from the audio input stream. The audio input
     * stream's frame size must be one byte, or an {@code 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
     */
    @Override
    public int read() throws IOException {
        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 data[0] & 0xFF;
    }

    
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. 
Params:
  • b – the buffer into which the data is read
Throws:
See Also:
Returns: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
/**
     * Reads some number of bytes from the audio input stream and stores them
     * into the buffer array {@code 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.
     * <p>
     * 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
     * {@code 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
     */
    @Override
    public int read(byte[] b) throws IOException {
        return read(b,0,b.length);
    }

    
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. 
Params:
  • b – the buffer into which the data is read
  • off – the offset, from the beginning of array b, at which the data will be written
  • len – the maximum number of bytes to read
Throws:
See Also:
Returns: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
/**
     * Reads up to a specified maximum number of bytes of data from the audio
     * stream, putting them into the given byte array.
     * <p>
     * This method will always read an integral number of frames. If {@code len}
     * does not specify an integral number of frames, a maximum of
     * {@code 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 {@code 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
     */
    @Override
    public int read(byte[] b, int off, int len) throws IOException {
        // make sure we don't read fractions of a frame.
        final int reminder = len % frameSize;
        if (reminder != 0) {
            len -= reminder;
            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;
    }

    
Skips over and discards a specified number of bytes from this audio input
stream.

 This method will always skip an integral number of frames. If n does not specify an integral number of frames, a maximum of n - (n % frameSize) bytes will be skipped. 
Params:
  • n – the requested number of bytes to be skipped
Throws:
See Also:
Returns:the actual number of bytes skipped
/**
     * Skips over and discards a specified number of bytes from this audio input
     * stream.
     * <p>
     * This method will always skip an integral number of frames. If {@code n}
     * does not specify an integral number of frames, a maximum of
     * {@code n - (n % frameSize)} bytes will be skipped.
     *
     * @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
     */
    @Override
    public long skip(long n) throws IOException {
        // make sure not to skip fractional frames
        final long reminder = n % frameSize;
        if (reminder != 0) {
            n -= reminder;
        }
        if (n <= 0) {
            return 0;
        }

        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 remaining = n;
        while (remaining > 0) {
            // Some input streams like FileInputStream can return more bytes,
            // when EOF is reached.
            long ret = Math.min(stream.skip(remaining), remaining);
            if (ret == 0) {
                // EOF or not? we need to check.
                if (stream.read() == -1) {
                    break;
                }
                ret = 1;
            } else if (ret < 0) {
                // the skip should not return negative value, but check it also
                break;
            }
            remaining -= ret;
        }
        final long temp =  n - remaining;

        // 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.");
        }
        framePos += temp/frameSize;
        return temp;
    }

    
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. 
Throws:
See Also:
Returns:the number of bytes that can be read from this audio input stream
        without blocking
/**
     * 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 {@code read} or {@code skip} method for this
     * audio input stream; the limit can vary each time these methods are
     * invoked. Depending on the underlying stream, an {@code 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
     */
    @Override
    public int available() throws IOException {

        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;
        }
    }

    
Closes this audio input stream and releases any system resources
associated with the stream.

Throws:
  • IOException – if an input or output error occurs
/**
     * Closes this audio input stream and releases any system resources
     * associated with the stream.
     *
     * @throws IOException if an input or output error occurs
     */
    @Override
    public void close() throws IOException {
        stream.close();
    }

    
Marks the current position in this audio input stream.

Params:
  • readlimit – the maximum number of bytes that can be read before the
        mark position becomes invalid
See Also:
/**
     * 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
     */
    @Override
    public void mark(int readlimit) {

        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);
            }
        }
    }

    
Repositions this audio input stream to the position it had at the time its mark method was last invoked. 
Throws:
See Also:
/**
     * Repositions this audio input stream to the position it had at the time
     * its {@code mark} method was last invoked.
     *
     * @throws IOException if an input or output error occurs
     * @see #mark
     * @see #markSupported
     */
    @Override
    public void reset() throws IOException {

        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);
        }
    }

    
Tests whether this audio input stream supports the mark and reset methods. 
See Also:
Returns:true if this stream supports the mark and reset methods; false otherwise
/**
     * Tests whether this audio input stream supports the {@code mark} and
     * {@code reset} methods.
     *
     * @return {@code true} if this stream supports the {@code mark} and
     *         {@code reset} methods; {@code false} otherwise
     * @see #mark
     * @see #reset
     */
    @Override
    public boolean markSupported() {

        return stream.markSupported();
    }

    
Private inner class that makes a TargetDataLine look like an InputStream.

/**
     * Private inner class that makes a TargetDataLine look like an InputStream.
     */
    private class TargetDataLineInputStream extends InputStream {

        
The TargetDataLine on which this TargetDataLineInputStream is based.

/**
         * The TargetDataLine on which this TargetDataLineInputStream is based.
         */
        TargetDataLine line;

        TargetDataLineInputStream(TargetDataLine line) {
            super();
            this.line = line;
        }

        @Override
        public int available() throws IOException {
            return line.available();
        }

        //$$fb 2001-07-16: added this method to correctly close the underlying TargetDataLine.
        // fixes bug 4479984
        @Override
        public void close() throws IOException {
            // the line needs to be flushed and stopped to avoid a dead lock...
            // Probably related to bugs 4417527, 4334868, 4383457
            if (line.isActive()) {
                line.flush();
                line.stop();
            }
            line.close();
        }

        @Override
        public int read() throws IOException {

            byte[] b = new byte[1];

            int value = read(b, 0, 1);

            if (value == -1) {
                return -1;
            }

            value = (int)b[0];

            if (line.getFormat().getEncoding().equals(AudioFormat.Encoding.PCM_SIGNED)) {
                value += 128;
            }

            return value;
        }

        @Override
        public int read(byte[] b, int off, int len) throws IOException {
            try {
                return line.read(b, off, len);
            } catch (IllegalArgumentException e) {
                throw new IOException(e.getMessage());
            }
        }
    }
}