/**
 * Copyright (c) 2011, The University of Southampton and the individual contributors.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 *   *  Redistributions of source code must retain the above copyright notice,
 *      this list of conditions and the following disclaimer.
 *
 *   *  Redistributions in binary form must reproduce the above copyright notice,
 *      this list of conditions and the following disclaimer in the documentation
 *      and/or other materials provided with the distribution.
 *
 *   *  Neither the name of the University of Southampton nor the names of its
 *      contributors may be used to endorse or promote products derived from this
 *      software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/**
 *
 */
package org.openimaj.audio.processor;

import org.openimaj.audio.AudioStream;
import org.openimaj.audio.SampleChunk;

/**
 * Provides an audio processor that will process sample chunks of specific sizes
 * when the incoming stream's sample chunk size is unknown.
 * <p>
 * This class has applications for FFT (for example) where the input sample size
 * must be a power of 2 and the underlying audio stream reader may be returning
 * sample chunks of any size.
 * <p>
 * The processor can also provide overlapping sample windows. Call
 * {@link #setWindowStep(int)} to determine the slide of each sliding window. If
 * this is set to 0 or below, the windows will be consecutive and will not
 * overlap.
 * <p>
 * The only assumption made by the class about the samples is that they are
 * whole numbers of bytes (8, 16, 24, 32 bits etc.). This is a pretty reasonable
 * assumption.
 *
 * @author David Dupplaw (dpd@ecs.soton.ac.uk)
 *
 * @created 11 Jul 2011
 */
public class FixedSizeSampleAudioProcessor extends AudioProcessor
{
        /** The size of each required sample chunk */
        private int requiredSampleSetSize = 512;

        /** Our buffer of sample chunks stored between calls to process() */
        private SampleChunk sampleBuffer = null;

        /** The number of samples overlap required between each window */
        private int windowStep = 0;

        /** Whether or not the windows are overlapping */
        private boolean overlapping = false;

        /**
         * Create processor that will process chunks of the given size.
         *
         * @param sizeRequired
         *            The size of the chunks required (in samples)
         */
        public FixedSizeSampleAudioProcessor(final int sizeRequired)
        {
                this.requiredSampleSetSize = sizeRequired;
        }

        /**
         * Create processor that will process chunks of the given size.
         *
         * @param stream
         *            An audio stream to process
         * @param sizeRequired
         *            The size of the chunks required (in samples)
         */
        public FixedSizeSampleAudioProcessor(final AudioStream stream, final int sizeRequired)
        {
                super(stream);
                this.requiredSampleSetSize = sizeRequired;
        }

        /**
         * Constructor that takes the size of the window and the size of the window
         * overlap.
         *
         * @param nSamplesInWindow
         *            The number of samples in the window
         * @param nSamplesOverlap
         *            The size of the overlap
         */
        public FixedSizeSampleAudioProcessor(final int nSamplesInWindow,
                        final int nSamplesOverlap)
        {
                this(nSamplesInWindow);
                this.setWindowStep(nSamplesOverlap);
        }

        /**
         * Chainable constructor that takes the size of the window and the number of
         * samples overlap.
         *
         * @param as
         *            The chained audio stream
         * @param nSamplesInWindow
         *            Samples in window
         * @param nSamplesOverlap
         *            Samples in window overlap
         */
        public FixedSizeSampleAudioProcessor(final AudioStream as, final int nSamplesInWindow,
                        final int nSamplesOverlap)
        {
                this(as, nSamplesInWindow);
                this.setWindowStep(nSamplesOverlap);
        }

        /**
         * {@inheritDoc}
         *
         * @see org.openimaj.audio.processor.AudioProcessor#nextSampleChunk()
         */
        @Override
        public SampleChunk nextSampleChunk()
        {
                // System.out.println( "Sample Buffer: "+(sampleBuffer != null?
                // sampleBuffer.getNumberOfSamples() : "null"));

                // Get the samples. If there's more samples than we need in the
                // buffer, we'll just use that, otherwise we'll get a new sample
                // chunk from the stream.
                SampleChunk s = null;
                if (this.sampleBuffer != null &&
                                this.sampleBuffer.getNumberOfSamples() >= this.requiredSampleSetSize)
                {
                        s = this.sampleBuffer;
                        this.sampleBuffer = null;
                }
                else
                {
                        s = this.getUnderlyingStream().nextSampleChunk();
                        if (s != null)
                                s = s.clone();

                        // If we have something in our buffer, prepend it to the new
                        // sample chunk
                        if (this.sampleBuffer != null && this.sampleBuffer.getNumberOfSamples() > 0
                                        && s != null)
                        {
                                // Prepend the contents of the sample buffer to the new sample
                                // chunk
                                s.prepend(this.sampleBuffer);
                                this.sampleBuffer = null;
                        }
                }

                // Sample buffer will always be null here
                // It will be reinstated later with the left-overs after processing.
                // From this point on we'll only work on the SampleChunk s.

                // Catch the end of the stream. As the sample buffer is always empty
                // at this point, the only time s can be null is that if the
                // nextSampleChunk() above returned null. In which case, there's no
                // more audio, so we return null.
                if (s == null)
                {
                        if (this.sampleBuffer != null)
                        {
                                s = this.sampleBuffer;
                                this.sampleBuffer = null;
                                return s;
                        }
                        else
                                return null;
                }

                // Now check how many samples we have to start with
                int nSamples = s.getNumberOfSamples();

                // If we don't have enough samples, we'll keep getting chunks until
                // we have enough or until the end of the stream is reached.
                boolean endOfStream = false;
                while (!endOfStream && nSamples < this.requiredSampleSetSize)
                {
                        final SampleChunk nextSamples = this.getUnderlyingStream().nextSampleChunk();
                        if (nextSamples != null)
                        {
                                // Append the new samples onto the end of the sample chunk
                                s.append(nextSamples);

                                // Check how many samples we now have.
                                nSamples = s.getNumberOfSamples();
                        }
                        else
                                endOfStream = true;
                }

                // If we have the right number of samples,
                // or we've got to the end of the stream
                // then we just return the chunk we have.
                SampleChunk ss;
                if (!endOfStream && (this.overlapping || nSamples > this.requiredSampleSetSize))
                {
                        // We must now have too many samples...
                        // Store the excess back into the buffer
                        int start = 0;
                        if (this.overlapping)
                                start = this.windowStep;
                        else
                                start = this.requiredSampleSetSize;

                        // Store the rest into the sample buffer
                        this.sampleBuffer = s.getSampleSlice(start, nSamples - start);

                        // Process a slice of the sample chunk
                        ss = s.getSampleSlice(0, this.requiredSampleSetSize);
                }
                else
                {
                        ss = s;

                        if (ss.getNumberOfSamples() < this.requiredSampleSetSize)
                                ss.pad(this.requiredSampleSetSize);
                }

                try
                {
                        // Return the processed samples
                        return this.process(ss);
                } catch (final Exception e)
                {
                        // If there's an error, log it and return the unprocessed samples
                        e.printStackTrace();
                        return ss;
                }
        }

        /**
         * Set the step of each overlapping window.
         *
         * @param overlap
         *            The step of each overlapping window.
         */
        public void setWindowStep(final int overlap)
        {
                this.windowStep = overlap;
                this.overlapping = true;
                if (overlap <= 0)
                        this.overlapping = false;
        }

        /**
         * Returns the step of each overlapping window.
         *
         * @return The step of each overlapping window.
         */
        public int getWindowStep()
        {
                return this.windowStep;
        }

        /**
         * Set the size of the window required. Should be called before the object
         * has been used to process anything. The result is undefined if it's called
         * during processing and will probably lead to some sort of bounds error.
         *
         * @param sizeRequired
         *            The size required.
         */
        public void setWindowSize(final int sizeRequired)
        {
                this.requiredSampleSetSize = sizeRequired;
        }

        /**
         * Returns the size of the sample window.
         *
         * @return The size of the sample window.
         */
        public int getWindowSize()
        {
                return this.requiredSampleSetSize;
        }

        /**
         * Returns whether the windows are overlapping or not.
         *
         * @return whether the windows are overlapping or not.
         */
        public boolean isOverlapping()
        {
                return this.overlapping;
        }

        /**
         * {@inheritDoc}
         *
         * The default operation of the {@link FixedSizeSampleAudioProcessor} is
         * simply to change the shape of the sample chunk. You may override this
         * method to process the samples directly.
         *
         * @see org.openimaj.audio.processor.AudioProcessor#process(org.openimaj.audio.SampleChunk)
         */
        @Override
        public SampleChunk process(final SampleChunk sample) throws Exception
        {
                return sample;
        }
}