sound/sampled/DataLine.java

/*
 * 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.util.Arrays;

/**
 * {@code DataLine} adds media-related functionality to its superinterface,
 * {@code Line}. This functionality includes transport-control methods that
 * start, stop, drain, and flush the audio data that passes through the line. A
 * data line can also report the current position, volume, and audio format of
 * the media. Data lines are used for output of audio by means of the
 * subinterfaces {@link SourceDataLine} or {@link Clip}, which allow an
 * application program to write data. Similarly, audio input is handled by the
 * subinterface {@link TargetDataLine}, which allows data to be read.
 * <p>
 * A data line has an internal buffer in which the incoming or outgoing audio
 * data is queued. The {@link #drain()} method blocks until this internal buffer
 * becomes empty, usually because all queued data has been processed. The
 * {@link #flush()} method discards any available queued data from the internal
 * buffer.
 * <p>
 * A data line produces {@link LineEvent.Type#START START} and
 * {@link LineEvent.Type#STOP STOP} events whenever it begins or ceases active
 * presentation or capture of data. These events can be generated in response to
 * specific requests, or as a result of less direct state changes. For example,
 * if {@link #start()} is called on an inactive data line, and data is available
 * for capture or playback, a {@code START} event will be generated shortly,
 * when data playback or capture actually begins. Or, if the flow of data to an
 * active data line is constricted so that a gap occurs in the presentation of
 * data, a {@code STOP} event is generated.
 * <p>
 * Mixers often support synchronized control of multiple data lines.
 * Synchronization can be established through the {@code Mixer} interface's
 * {@link Mixer#synchronize synchronize} method. See the description of the
 * {@link Mixer Mixer} interface for a more complete description.
 *
 * @author Kara Kytle
 * @see LineEvent
 * @since 1.3
 */
public interface DataLine extends Line {

    /**
     * Drains queued data from the line by continuing data I/O until the data
     * line's internal buffer has been emptied. This method blocks until the
     * draining is complete. Because this is a blocking method, it should be
     * used with care. If {@code drain()} is invoked on a stopped line that has
     * data in its queue, the method will block until the line is running and
     * the data queue becomes empty. If {@code drain()} is invoked by one
     * thread, and another continues to fill the data queue, the operation will
     * not complete. This method always returns when the data line is closed.
     *
     * @see #flush()
     */
    void drain();

    /**
     * Flushes queued data from the line. The flushed data is discarded. In some
     * cases, not all queued data can be discarded. For example, a mixer can
     * flush data from the buffer for a specific input line, but any unplayed
     * data already in the output buffer (the result of the mix) will still be
     * played. You can invoke this method after pausing a line (the normal case)
     * if you want to skip the "stale" data when you restart playback or
     * capture. (It is legal to flush a line that is not stopped, but doing so
     * on an active line is likely to cause a discontinuity in the data,
     * resulting in a perceptible click.)
     *
     * @see #stop()
     * @see #drain()
     */
    void flush();

    /**
     * Allows a line to engage in data I/O. If invoked on a line that is already
     * running, this method does nothing. Unless the data in the buffer has been
     * flushed, the line resumes I/O starting with the first frame that was
     * unprocessed at the time the line was stopped. When audio capture or
     * playback starts, a {@link LineEvent.Type#START START} event is generated.
     *
     * @see #stop()
     * @see #isRunning()
     * @see LineEvent
     */
    void start();

    /**
     * Stops the line. A stopped line should cease I/O activity. If the line is
     * open and running, however, it should retain the resources required to
     * resume activity. A stopped line should retain any audio data in its
     * buffer instead of discarding it, so that upon resumption the I/O can
     * continue where it left off, if possible. (This doesn't guarantee that
     * there will never be discontinuities beyond the current buffer, of course;
     * if the stopped condition continues for too long, input or output samples
     * might be dropped.) If desired, the retained data can be discarded by
     * invoking the {@code flush} method. When audio capture or playback stops,
     * a {@link LineEvent.Type#STOP STOP} event is generated.
     *
     * @see #start()
     * @see #isRunning()
     * @see #flush()
     * @see LineEvent
     */
    void stop();

    /**
     * Indicates whether the line is running. The default is {@code false}. An
     * open line begins running when the first data is presented in response to
     * an invocation of the {@code start} method, and continues until
     * presentation ceases in response to a call to {@code stop} or because
     * playback completes.
     *
     * @return {@code true} if the line is running, otherwise {@code false}
     * @see #start()
     * @see #stop()
     */
    boolean isRunning();

    /**
     * Indicates whether the line is engaging in active I/O (such as playback or
     * capture). When an inactive line becomes active, it sends a
     * {@link LineEvent.Type#START START} event to its listeners. Similarly,
     * when an active line becomes inactive, it sends a
     * {@link LineEvent.Type#STOP STOP} event.
     *
     * @return {@code true} if the line is actively capturing or rendering
     *         sound, otherwise {@code false}
     * @see #isOpen
     * @see #addLineListener
     * @see #removeLineListener
     * @see LineEvent
     * @see LineListener
     */
    boolean isActive();

    /**
     * Obtains the current format (encoding, sample rate, number of channels,
     * etc.) of the data line's audio data.
     * <p>
     * If the line is not open and has never been opened, it returns the default
     * format. The default format is an implementation specific audio format,
     * or, if the {@code DataLine.Info} object, which was used to retrieve this
     * {@code DataLine}, specifies at least one fully qualified audio format,
     * the last one will be used as the default format. Opening the line with a
     * specific audio format (e.g. {@link SourceDataLine#open(AudioFormat)})
     * will override the default format.
     *
     * @return current audio data format
     * @see AudioFormat
     */
    AudioFormat getFormat();

    /**
     * Obtains the maximum number of bytes of data that will fit in the data
     * line's internal buffer. For a source data line, this is the size of the
     * buffer to which data can be written. For a target data line, it is the
     * size of the buffer from which data can be read. Note that the units used
     * are bytes, but will always correspond to an integral number of sample
     * frames of audio data.
     *
     * @return the size of the buffer, in bytes
     */
    int getBufferSize();

    /**
     * Obtains the number of bytes of data currently available to the
     * application for processing in the data line's internal buffer. For a
     * source data line, this is the amount of data that can be written to the
     * buffer without blocking. For a target data line, this is the amount of
     * data available to be read by the application. For a clip, this value is
     * always 0 because the audio data is loaded into the buffer when the clip
     * is opened, and persists without modification until the clip is closed.
     * <p>
     * Note that the units used are bytes, but will always correspond to an
     * integral number of sample frames of audio data.
     * <p>
     * An application is guaranteed that a read or write operation of up to the
     * number of bytes returned from {@code available()} will not block;
     * however, there is no guarantee that attempts to read or write more data
     * will block.
     *
     * @return the amount of data available, in bytes
     */
    int available();

    /**
     * Obtains the current position in the audio data, in sample frames. The
     * frame position measures the number of sample frames captured by, or
     * rendered from, the line since it was opened. This return value will wrap
     * around after 2^31 frames. It is recommended to use
     * {@code getLongFramePosition} instead.
     *
     * @return the number of frames already processed since the line was opened
     * @see #getLongFramePosition()
     */
    int getFramePosition();

    /**
     * Obtains the current position in the audio data, in sample frames. The
     * frame position measures the number of sample frames captured by, or
     * rendered from, the line since it was opened.
     *
     * @return the number of frames already processed since the line was opened
     * @since 1.5
     */
    long getLongFramePosition();

    /**
     * Obtains the current position in the audio data, in microseconds. The
     * microsecond position measures the time corresponding to the number of
     * sample frames captured by, or rendered from, the line since it was
     * opened. The level of precision is not guaranteed. For example, an
     * implementation might calculate the microsecond position from the current
     * frame position and the audio sample frame rate. The precision in
     * microseconds would then be limited to the number of microseconds per
     * sample frame.
     *
     * @return the number of microseconds of data processed since the line was
     *         opened
     */
    long getMicrosecondPosition();

    /**
     * Obtains the current volume level for the line. This level is a measure of
     * the signal's current amplitude, and should not be confused with the
     * current setting of a gain control. The range is from 0.0 (silence) to 1.0
     * (maximum possible amplitude for the sound waveform). The units measure
     * linear amplitude, not decibels.
     *
     * @return the current amplitude of the signal in this line, or
     *         {@link AudioSystem#NOT_SPECIFIED}
     */
    float getLevel();

    /**
     * Besides the class information inherited from its superclass,
     * {@code DataLine.Info} provides additional information specific to data
     * lines. This information includes:
     * <ul>
     *   <li>the audio formats supported by the data line
     *   <li>the minimum and maximum sizes of its internal buffer
     * </ul>
     * Because a {@code Line.Info} knows the class of the line its describes, a
     * {@code DataLine.Info} object can describe {@code DataLine} subinterfaces
     * such as {@link SourceDataLine}, {@link TargetDataLine}, and {@link Clip}.
     * You can query a mixer for lines of any of these types, passing an
     * appropriate instance of {@code DataLine.Info} as the argument to a method
     * such as {@link Mixer#getLine(Line.Info)}.
     *
     * @author Kara Kytle
     * @see Line.Info
     * @since 1.3
     */
    class Info extends Line.Info {

        /**
         * The set of supported formats.
         */
        private final AudioFormat[] formats;

        /**
         * Minimum buffer size supported by the data line, in bytes.
         */
        private final int minBufferSize;

        /**
         * Maximum buffer size supported by the data line, in bytes.
         */
        private final int maxBufferSize;

        /**
         * Constructs a data line's info object from the specified information,
         * which includes a set of supported audio formats and a range for the
         * buffer size. This constructor is typically used by mixer
         * implementations when returning information about a supported line.
         *
         * @param  lineClass the class of the data line described by the info
         *         object
         * @param  formats set of formats supported
         * @param  minBufferSize minimum buffer size supported by the data line,
         *         in bytes
         * @param  maxBufferSize maximum buffer size supported by the data line,
         *         in bytes
         */
        public Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize) {

            super(lineClass);

            if (formats == null) {
                this.formats = new AudioFormat[0];
            } else {
                this.formats = Arrays.copyOf(formats, formats.length);
            }

            this.minBufferSize = minBufferSize;
            this.maxBufferSize = maxBufferSize;
        }

        /**
         * Constructs a data line's info object from the specified information,
         * which includes a single audio format and a desired buffer size. This
         * constructor is typically used by an application to describe a desired
         * line.
         *
         * @param  lineClass the class of the data line described by the info
         *         object
         * @param  format desired format
         * @param  bufferSize desired buffer size, in bytes
         */
        public Info(Class<?> lineClass, AudioFormat format, int bufferSize) {

            super(lineClass);

            if (format == null) {
                this.formats = new AudioFormat[0];
            } else {
                this.formats = new AudioFormat[]{format};
            }

            this.minBufferSize = bufferSize;
            this.maxBufferSize = bufferSize;
        }

        /**
         * Constructs a data line's info object from the specified information,
         * which includes a single audio format. This constructor is typically
         * used by an application to describe a desired line.
         *
         * @param  lineClass the class of the data line described by the info
         *         object
         * @param  format desired format
         */
        public Info(Class<?> lineClass, AudioFormat format) {
            this(lineClass, format, AudioSystem.NOT_SPECIFIED);
        }

        /**
         * Obtains a set of audio formats supported by the data line. Note that
         * {@code isFormatSupported(AudioFormat)} might return {@code true} for
         * certain additional formats that are missing from the set returned by
         * {@code getFormats()}. The reverse is not the case:
         * {@code isFormatSupported(AudioFormat)} is guaranteed to return
         * {@code true} for all formats returned by {@code getFormats()}.
         * <p>
         * Some fields in the {@code AudioFormat} instances can be set to
         * {@link AudioSystem#NOT_SPECIFIED NOT_SPECIFIED} if that field does
         * not apply to the format, or if the format supports a wide range of
         * values for that field. For example, a multi-channel device supporting
         * up to 64 channels, could set the channel field in the
         * {@code AudioFormat} instances returned by this method to
         * {@code NOT_SPECIFIED}.
         *
         * @return a set of supported audio formats
         * @see #isFormatSupported(AudioFormat)
         */
        public AudioFormat[] getFormats() {
            return Arrays.copyOf(formats, formats.length);
        }

        /**
         * Indicates whether this data line supports a particular audio format.
         * The default implementation of this method simply returns {@code true}
         * if the specified format matches any of the supported formats.
         *
         * @param  format the audio format for which support is queried
         * @return {@code true} if the format is supported, otherwise
         *         {@code false}
         * @see #getFormats
         * @see AudioFormat#matches
         */
        public boolean isFormatSupported(AudioFormat format) {

            for (int i = 0; i < formats.length; i++) {
                if (format.matches(formats[i])) {
                    return true;
                }
            }

            return false;
        }

        /**
         * Obtains the minimum buffer size supported by the data line.
         *
         * @return minimum buffer size in bytes, or
         *         {@code AudioSystem.NOT_SPECIFIED}
         */
        public int getMinBufferSize() {
            return minBufferSize;
        }

        /**
         * Obtains the maximum buffer size supported by the data line.
         *
         * @return maximum buffer size in bytes, or
         *         {@code AudioSystem.NOT_SPECIFIED}
         */
        public int getMaxBufferSize() {
            return maxBufferSize;
        }

        /**
         * Determines whether the specified info object matches this one. To
         * match, the superclass match requirements must be met. In addition,
         * this object's minimum buffer size must be at least as large as that
         * of the object specified, its maximum buffer size must be at most as
         * large as that of the object specified, and all of its formats must
         * match formats supported by the object specified.
         *
         * @param  info the info object which is being compared to this one
         * @return {@code true} if this object matches the one specified,
         *         otherwise {@code false}
         */
        @Override
        public boolean matches(Line.Info info) {

            if (! (super.matches(info)) ) {
                return false;
            }

            Info dataLineInfo = (Info)info;

            // treat anything < 0 as NOT_SPECIFIED
            // demo code in old Java Sound Demo used a wrong buffer calculation
            // that would lead to arbitrary negative values
            if ((getMaxBufferSize() >= 0) && (dataLineInfo.getMaxBufferSize() >= 0)) {
                if (getMaxBufferSize() > dataLineInfo.getMaxBufferSize()) {
                    return false;
                }
            }

            if ((getMinBufferSize() >= 0) && (dataLineInfo.getMinBufferSize() >= 0)) {
                if (getMinBufferSize() < dataLineInfo.getMinBufferSize()) {
                    return false;
                }
            }

            AudioFormat[] localFormats = getFormats();

            if (localFormats != null) {

                for (int i = 0; i < localFormats.length; i++) {
                    if (! (localFormats[i] == null) ) {
                        if (! (dataLineInfo.isFormatSupported(localFormats[i])) ) {
                            return false;
                        }
                    }
                }
            }

            return true;
        }

        /**
         * Obtains a textual description of the data line info.
         *
         * @return a string description
         */
        @Override
        public String toString() {

            StringBuilder sb = new StringBuilder();

            if ( (formats.length == 1) && (formats[0] != null) ) {
                sb.append(" supporting format " + formats[0]);
            } else if (getFormats().length > 1) {
                sb.append(" supporting " + getFormats().length + " audio formats");
            }

            if ( (minBufferSize != AudioSystem.NOT_SPECIFIED) && (maxBufferSize != AudioSystem.NOT_SPECIFIED) ) {
                sb.append(", and buffers of " + minBufferSize + " to " + maxBufferSize + " bytes");
            } else if ( (minBufferSize != AudioSystem.NOT_SPECIFIED) && (minBufferSize > 0) ) {
                sb.append(", and buffers of at least " + minBufferSize + " bytes");
            } else if (maxBufferSize != AudioSystem.NOT_SPECIFIED) {
                sb.append(", and buffers of up to " + minBufferSize + " bytes");
            }

            return new String(super.toString() + sb);
        }
    }
}