/**
 * 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;

import java.nio.ByteBuffer;
import java.nio.ByteOrder;

import org.openimaj.audio.samples.SampleBuffer;
import org.openimaj.audio.samples.SampleBufferFactory;
import org.openimaj.audio.timecode.AudioTimecode;

/**
 * Represents a chunk of an audio file and stores the raw audio data. The data
 * is unnormalised - that is, it is stored in this class in its original format
 * in the form of a byte array. This is for speed during audio playback.
 *
 * If you require normalised data (data as an integer array for example) use the
 * method {@link #getSamplesAsByteBuffer()} and use the {@link ByteBuffer}'s
 * methods asXXXBuffer (e.g. ByteBuffer#asShortBuffer) to get the samples in a
 * normalised form.
 *
 * @author David Dupplaw (dpd@ecs.soton.ac.uk)
 * @created 8 Jun 2011
 *
 */
public class SampleChunk extends Audio
{
        /** The samples in the chunk */
        private byte[] samples = new byte[1];

        /** The timecode of the start of the sample chunk */
        private AudioTimecode startTimecode = new AudioTimecode(0);

        /**
         * Create a new SampleChunk buffer with the given audio format, but do not
         * initialise the samples.
         *
         * @param af
         *            The audio format of the samples
         */
        public SampleChunk(final AudioFormat af)
        {
                this(new byte[1], af);
        }

        /**
         * Create a new sample chunk using the given samples and the given audio
         * format.
         *
         * @param samples
         *            The samples to initialise with
         * @param af
         *            The audio format of the samples
         */
        public SampleChunk(final byte[] samples, final AudioFormat af)
        {
                this.setSamples(samples);
                super.format = af;
        }

        /**
         * Create a new sample chunk using the given samples and the given audio
         * format.
         *
         * @param samples
         *            The samples to initialise with
         * @param af
         *            The audio format of the samples
         * @param tc
         *            The audio timecode of these samples
         */
        public SampleChunk(final byte[] samples, final AudioFormat af, final AudioTimecode tc)
        {
                this.setSamples(samples);
                this.startTimecode = tc;
                super.format = af;
        }

        /**
         * Set the samples in this sample chunk.
         *
         * @param samples
         *            the samples in this sample chunk.
         */
        public void setSamples(final byte[] samples)
        {
                synchronized (this.samples)
                {
                        this.samples = samples;
                }
        }

        /**
         * Get the samples in this sample chunk
         *
         * @return the samples in this sample chunk
         */
        public byte[] getSamples()
        {
                return this.samples;
        }

        /**
         * Returns the number of samples in this sample chunk. If there are 128
         * stereo samples, this method will return 256. That is, it does not
         * normalise for the number of channels. However, it does normalise for the
         * size of each sample. So if this is a 16-bit buffer of 256 bytes length,
         * this method will return 128.
         *
         * @return the number of samples in this sample chunk.
         */
        public int getNumberOfSamples()
        {
                return this.samples.length / (this.format.getNBits() / 8);
        }

        /**
         * Returns a {@link ByteBuffer} that can be used to create views of the
         * samples in the object. For example, to get short integers, you can get
         * {@link #getSamplesAsByteBuffer()}.asShortBuffer()
         *
         * @return A {@link ByteBuffer}
         */
        public ByteBuffer getSamplesAsByteBuffer()
        {
                if (this.samples == null)
                        return null;

                ByteOrder bo = null;

                if (this.format.isBigEndian())
                        bo = ByteOrder.BIG_ENDIAN;
                else
                        bo = ByteOrder.LITTLE_ENDIAN;

                return ByteBuffer.wrap(this.samples).order(bo);
        }

        /**
         * Returns an appropriate sample buffer for this sample chunk. If an
         * appropriate sample buffer cannot be found, null will be returned. This
         * will wrap the samples array from the underlying chunk, so you should only
         * side-affect the samples if you're sure they will not be reused.
         *
         * @return An appropriate {@link SampleBuffer}
         */
        public SampleBuffer getSampleBuffer()
        {
                return SampleBufferFactory.createSampleBuffer(this, this.format);
        }

        /**
         * Set the timecode at the start of this audio chunk.
         *
         * @param startTimecode
         *            the timecode at the start of the chunk.
         */
        public void setStartTimecode(final AudioTimecode startTimecode)
        {
                this.startTimecode = startTimecode;
        }

        /**
         * Get the timecode at the start of this audio chunk.
         *
         * @return the timecode at the start of the chunk.
         */
        public AudioTimecode getStartTimecode()
        {
                return this.startTimecode;
        }

        /**
         * Return a slice of data from the sample array. The indices are based on
         * the samples in the byte array, not the bytes themselves.
         * <p>
         * The assumption is that samples are whole numbers of bytes. So, if the
         * sample size was 16-bits, then passing in 2 for the start index would
         * actually index the byte at index 4 in the underlying sample array. The
         * order of the bytes is unchanged.
         *
         * @param start
         *            The start index of the sample.
         * @param length
         *            The length of the samples get.
         * @return The sample slice as a new {@link SampleChunk}
         */
        public SampleChunk getSampleSlice(final int start, final int length)
        {
                final int nBytesPerSample = this.format.getNBits() / 8;
                final int startSampleByteIndex = start * nBytesPerSample;
                final byte[] newSamples = new byte[length * nBytesPerSample];

                synchronized (this.samples)
                {
                        System.arraycopy(this.samples, startSampleByteIndex,
                                        newSamples, 0, length * nBytesPerSample);
                }

                final SampleChunk s = new SampleChunk(this.format);
                s.setSamples(newSamples);

                // Set the timestamp to the start of this new slice
                final double samplesPerChannelPerMillisec = this.format.getSampleRateKHz();
                s.setStartTimecode(new AudioTimecode(
                                this.getStartTimecode().getTimecodeInMilliseconds() +
                                (long) (start / samplesPerChannelPerMillisec)));

                return s;
        }

        /**
         * Prepends the given samples to the front of this sample chunk. It is
         * expected that the given samples are in the same format as this sample
         * chunk; if they are not an exception is thrown. Side-affects this sample
         * chunk and will return a reference to this sample chunk.
         *
         * @param sample
         *            the samples to add
         * @return This sample chunk with the bytes prepended
         */
        public SampleChunk prepend(final SampleChunk sample)
        {
                // Check the sample formats are the same
                if (!sample.getFormat().equals(this.format))
                        throw new IllegalArgumentException("Sample types are not equivalent");

                // Get the samples from the given chunk
                final byte[] x1 = sample.getSamplesAsByteBuffer().array();

                // Create an array for the concatenated pair
                final byte[] newSamples = new byte[this.samples.length + x1.length];

                // Loop through adding the new samples
                System.arraycopy(x1, 0, newSamples, 0, x1.length);

                synchronized (this.samples)
                {
                        System.arraycopy(this.samples, 0, newSamples, x1.length, this.samples.length);
                }

                // Update this object
                this.samples = newSamples;
                this.setStartTimecode(sample.getStartTimecode().clone());
                return this;
        }

        /**
         * Appends the given samples to the end of this sample chunk. It is expected
         * that the given samples are in the same format as this sample chunk; if
         * they are not an exception is thrown. Side-affects this sample chunk and
         * will return a reference to this sample chunk.
         *
         * @param sample
         *            the samples to add
         * @return This sample chunk with the bytes appended
         */
        public SampleChunk append(final SampleChunk sample)
        {
                // Check the sample formats are the same
                if (!sample.getFormat().equals(this.format))
                        throw new IllegalArgumentException("Sample types are not equivalent");

                // Get the samples from the given chunk
                final byte[] x1 = sample.getSamplesAsByteBuffer().array();

                // Create an array for the concatenated pair
                final byte[] newSamples = new byte[this.samples.length + x1.length];

                synchronized (this.samples)
                {
                        System.arraycopy(this.samples, 0, newSamples, 0, this.samples.length);
                }

                System.arraycopy(x1, 0, newSamples, this.samples.length, x1.length);

                // Update this object
                this.samples = newSamples;
                return this;
        }

        /**
         * {@inheritDoc}
         */
        @Override
        public SampleChunk clone()
        {
                return new SampleChunk(this.samples.clone(), this.format.clone(), this.startTimecode == null ? new AudioTimecode(
                                0)
                : this.startTimecode.clone());
        }

        /**
         * Pads the sample chunk to the given size with zeros.
         *
         * @param requiredSampleSetSize
         *            The required sample size
         */
        public void pad(final int requiredSampleSetSize)
        {
                final byte[] samples = new byte[requiredSampleSetSize * (this.format.getNBits() / 8)];
                System.arraycopy(this.samples, 0, samples, 0, this.samples.length);
                this.samples = samples;
        }
}