/*
 * Copyright (C) 2013 Darth Affe <http://wyrez.org> and contributors
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 * 
 * 
 * This Code is based on the source provided with a tutorial by
 * http://www.badlogicgames.com (as of 16.05.2013).
 * The original source can be found here:
 * http://code.google.com/p/audio-analysis/source/browse/trunk/src/com/badlogic/audio/io/Decoder.java
 */
package org.wyrez.audio.decoder;

/**
 * Interface for audio decoders that return successive amplitude frames.
 *
 * @author Darth Affe
 */
public interface Decoder {

    /**
     * Reads in samples.length stereo samples from the decoder. Returns the
     * actual number read in. If this number is smaller than samples.length then
     * the end of stream has been reached.
     *
     * @param samples The samples array to write the samples to
     * @returns The number of samples actually read
     */
    public int readSamplesStereo(float[] samples);

    /**
     * Reads in samples.length mono samples from the decoder. If the audio
     * source isn't mono they channels are merged. Returns the actual number
     * read in. If this number is smaller than samples.length then the end of
     * stream has been reached. All Channels are merged by calculating the
     * average.
     *
     * @param samples The samples array to write the samples to
     * @returns The number of samples actually read
     */
    public int readSamplesMergedMono(float[] samples);

    /**
     * Returns the number of channels in the audio source.
     *
     * @returns The channel count
     */
    public int getChannelCount();

    /**
     * Returns the sampling rate in Hz of the audio source.
     *
     * @returns the sampling rate as float
     */
    public float getSamplingRate();
}
