/*
 * Project: VizKit
 * Version: 2.3
 
 * Date: 20090823
 * File: VisualAudioLab.h
 *
 */

/***************************************************************************

Copyright (c) 2004-2009 Heiko Wichmann (http://www.imagomat.de/vizkit)


This software is provided 'as-is', without any expressed or implied warranty. 
In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; 
   you must not claim that you wrote the original software. 
   If you use this software in a product, an acknowledgment 
   in the product documentation would be appreciated 
   but is not required.

2. Altered source versions must be plainly marked as such, 
   and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

 ***************************************************************************/

#ifndef VisualAudioLab_h
#define VisualAudioLab_h


#include "VisualTypes.h"


namespace VizKit {

	/**
	 * A collection of routines dealing with processing, analyzing and interpretation of audio data.
	 */
	class VisualAudioLab {

	public:

		/**
		 * Returns the VisualAudioLab. The VisualAudiolab is initialized if required. 
		 * The VisualAudioLab is a singleton.
		 */
		static VisualAudioLab* getInstance(void);

		/**
		 * Disposes the VisualAudiolab.
		 */	
		static void dispose(void);
		
		/**
		 * Processes the audio data chunks.
		 * With each RenderMessage iTunes delivers waveform data and spectrum data. 
		 * The spectrum data is a fft (Fast Fourier Transform) of the waveform data.
		 * @param numWaveformChannels The number of waveform data channels.
		 * @param numWaveformEntries The number of waveform data entries per channel.
		 * @param currWaveformData A pointer to the waveform data.
		 * @param numSpectrumChannels The number of spectrum data channels.
		 * @param numSpectrumEntries The number of spectrum data entries per channel.
		 * @param currSpectrumData A pointer to the spectrum data.
		 */
		void processAudioData(uint8 numWaveformChannels, 
							uint16 numWaveformEntries, 
							const uint8* const currWaveformData, 
							uint8 numSpectrumChannels, 
							uint16 numSpectrumEntries, 
							const uint8* const currSpectrumData);

		/**
		 * Resets the stored values of the VisualAudioLab.
		 * The VisualAudioLab stores analyzed values of an audio track.
		 * Typically the values are resetted when a new track starts playing.
		 */	
		void resetData(void);

		/**
		 * Returns the last processed timestampID of the kVisualPluginRenderMessage.
		 * @return The last processed timestampID of the kVisualPluginRenderMessage.
		 */
		uint32 getCurrTimestampIDOfRenderData(void);
		
		/**
		 * Sets the last processed timestampID of the kVisualPluginRenderMessage.
		 * @param timestampID The last processed timestampID of the kVisualPluginRenderMessage.
		 */	
		void setCurrTimestampIDOfRenderData(const uint32 timestampID);
		
		/**
		 * Stores the total time of the current track.
		 * @param totalTimeInMS The total time of the currently playing audio track measured in milliseconds.
		 */
		void setTotalTimeOfCurrentTrack(const uint32 totalTimeInMS);

		/**
		 * Stores the start time of the current track.
		 * @param startTimeInMS The start time of the currently playing audio track measured in milliseconds.
		 */
		void setStartTimeOfCurrentTrack(const uint32 startTimeInMS);

		/**
		 * Stores the stop time of the current track.
		 * @param stopTimeInMS The stop time of the currently playing audio track measured in milliseconds.
		 */
		void setStopTimeOfCurrentTrack(const uint32 stopTimeInMS);

		/**
		 * Answers the question whether the remaining time of the current track is known.
		 * Streamed audio has no info about remaining time of current track.
		 * @return True if the remaining time of the current track is known, false if not.
		 */
		bool remainingTimeOfCurrentTrackIsKnown(void);
		
		/**
		 * Returns the remaining time of the currently playing audio track measured in milliseconds.
		 * @return The remaining time of the currently playing audio track measured in milliseconds.
		 */
		uint32 getRemainingTimeOfCurrentTrack(void);

		/**
		 * Returns the total time of the currently playing audio track measured in milliseconds.
		 * @return The total time of the currently playing audio track measured in milliseconds.
		 */	
		uint32 getTotalTimeOfCurrentTrack(void);

		/**
		 * Returns the current music data history.
		 * @return The current music data history.
		 */	
		sint16 getCurrMusicDataHistory(void);

		/**
		 * Returns the previous music data history. 
		 * The previous music data history is the one that was current 
		 * before the one that is now current.
		 * @return The previous music data history.
		 */	
		sint16 getPrevMusicDataHistory(void);

		/**
		 * Returns the RMS (root-mean-square) intensity.
		 * The RMS intensity is the computed root-mean-square value.
		 * @return The RMS intensity.
		 */	
		uint8 getRMSIntensity(void);

		/**
		 * Returns the single waveform data of a specific channel at a specific index position.
		 * @param channel The channel.
		 * @param index The index of the waveform data.
		 * @return The single waveform data of a specific channel at a specific index position.
		 */	
		uint8 getWaveformDataOfChannelAtIndex(const uint16 channel, const uint16 index);

		/**
		 * Returns a pointer to the spectrum data array.
		 * @return A pointer to the spectrum data array.
		 */
		const uint8*** const getSpectrumDataArray(void);

		/**
		 * Returns a pointer to the mono waveform data array.
		 * The mono waveform data consists of the averaged values of the 
		 * waveform data of all available channels.
		 * @return A pointer to the mono waveform data array.
		 */
		const sint16** const getWaveformDataMonoArray(void);

		/**
		 * Returns the waveform data value of a specific index position.
		 * @param index The index of the requested waveform data.
		 * @return The mono waveform data at a specific index.
		 */
		uint8 getMonoWaveformDataAtIndex(const uint16 index);

		/**
		 * Returns the waveform data of a specific channel of a specific history at a specific index.
		 * @param channel The cannel of the requested waveform data.
		 * @param index The index of the requested waveform data.
		 * @param historyNum The history of the requested waveform data.
		 * @return The waveform data of a specific channel of a specific history at a specific index.
		 */
		uint8 getWaveformDataOfChannelAtIndexWithHistoryNum(const uint16 channel, const uint16 index, const uint16 historyNum);

		/**
		 * Returns the mono waveform data of a specific history at a specific index.
		 * @param index The index of the requested waveform data.
		 * @param historyNum The history of the requested waveform data.
		 * @return The mono waveform data of a specific history at a specific index.
		*/
		uint8 getMonoWaveformDataAtIndexWithHistoryNum(const uint16 index, const uint16 historyNum);

		/**
		 * Returns the DC intensity.
		 * The DC intensity is the intensity of the direct current.
		 * @return The DC intensity.
		 */
		uint8 getDCIntensity(void);

		/**
		 * Checks for the beat impulse and sends a notification in case a beat impulse is detected.
		 */
		void checkForBeatImpulse(void);

		/**
		 * Answers the question whether the current timestamp suggests a beat impulse.
		 * @return 1 if the current timestamp suggests a beat impulse, 0 if not.
		 */
		uint8 getBeatMeter(void);

		/**
		 * Processes the sample data with a Hann window.
		 * @param N The number of samples.
		 * @param TimeSamples The sample data.
		 */
		void HannWindow(const int N, double TimeSamples[]);

		/**
		 * Returns a pointer to the waveform shape array.
		 * @return A pointer to the waveform shape array.
		 */	
		const sint8* const getWaveformShapeArray(void);

		/**
		 * Sets the maximum number of audio data channels (2 channels means stereo).
		 * @param aNumberOfMaxAudioDataChannels The maximum number of audio data channels.
		 */
		static void setMaxNumberOfAudioDataChannels(uint16 aNumberOfMaxAudioDataChannels);

		/**
		 * Sets the number of audio waveform data entries.
		 * @param aNumberOfAudioWaveformDataEntries The number of audio waveform data entries.
		 */
		static void setNumberOfAudioWaveformDataEntries(uint32 aNumberOfAudioWaveformDataEntries);

		/**
		 * Sets the number of audio spectrum data entries.
		 * @param aNumberOfAudioSpectrumDataEntries The number of audio spectrum data entries.
		 */
		static void setNumberOfAudioSpectrumDataEntries(uint32 aNumberOfAudioSpectrumDataEntries);

		/**
		 * Returns the number of audio spectrum data entries.
		 * @return The number of audio spectrum data entries.
		 */
		uint32 getNumberOfAudioSpectrumDataEntries(void);

		/**
		 * Returns the number of waveform data entries.
		 * @return The number of waveform data entries.
		 */		
		uint32 getNumberOfWaveformEntries(void);

		/**
		 * Returns the number of spectrum data entries.
		 * @return The number of spectrum data entries.
		 */	
		uint32 getNumberOfSpectrumEntries(void);

		/**
		 * Returns the maximum history number.
		 * @return The maximum history number.
		 */	
		uint16 getMaxNumberOfWaveformShapeHistory(void);

		/**
		 * Returns the number of data channels.
		 * @return The number of data channels.
		 */	
		uint16 getNumberOfDataChannels(void);

		/**
		 * Returns the maximum number of histories in waveform data.
		 * @return The maximum number of histories in waveform data.
		 */	
		uint16 getMaxNumberOfMusicDataHistories(void);

		/**
		 * Returns a pointer to the histogram of the gaps between detected beat events.
		 * @return A pointer to the histogram of the gaps between detected beat events.
		 */	
		const uint32* const getBeatHistogram(void);
		
	private:

		/** The constructor. VisualAudioLab is a singleton class. The constructor is private. New instance of class can only be created internally. */
		VisualAudioLab();

		/** The destructor. VisualAudioLab is a singleton class. The destructor is private. Instance of class can only be destructed internally. */
		~VisualAudioLab();

		/**
		 * Copy constructor.
		 * @param other Another VisualAudioLab.
		 * @remarks Explicitely declared in private section and not implemented to enforce uniqueness of singleton pattern.
		 */
		VisualAudioLab(const VisualAudioLab& other);

		/**
		 * Assignment operator.
		 * @remarks Explicitely declared in private section and not implemented to enforce uniqueness of singleton pattern.
		 */			
		VisualAudioLab& operator=(const VisualAudioLab& other);

		/** VisualAudioLab is a singleton class. Pointer to private instance is handled internally. */
		static VisualAudioLab* theVisualAudioLab;

		/**
		 * Allocates and initializes the buffers of the VisualAudioLab.
		 */	
		void init(void);

		/**
		 * Processes the waveform data.
		 * @param numWaveformChannels The number of waveform data channels (e.g. two for stereo sound).
		 * @param numWaveformEntries The number of data points per channel.
		 * @param currWaveformData A pointer to the current waveform data.
		 */
		void processWaveformData(uint8 numWaveformChannels, uint16 numWaveformEntries, const uint8* const currWaveformData);

		/**
		 * Processes the spectrum data.
		 * @param numSpectrumChannels The number of spectrum data channels (e.g. two for stereo sound)..
		 * @param numSpectrumEntries The number of data points per channel.
		 * @param currSpectrumData A pointer to the current spectrum data.
		 */
		void processSpectrumData(const uint8 numSpectrumChannels, const uint16 numSpectrumEntries, const uint8* const currSpectrumData);
		
		/**
		 * Increments the current history number of music data.
		 * Music data is stored for a number of histories.
		 */		
		void incrementMusicDataHistory(void);

		/**
		 * Stores the beat impulse.
		 * @param beatImpulse True if the current waveform data indicates a beat impulse, false if not.
		 */
		void storeBeatImpulse(bool beatImpulse);

		/** The total time of the currently playing audio track measured in milliseconds. */
		uint32 totalTimeOfTrack;

		/** The accumulated play time of the current audio track measured in milliseconds. */
		uint32 elapsedTimeOfTrack;

		/** The start time of the currently playing audio track measured in milliseconds. iTunes allows to set a custom start time for a track. */
		uint32 startTimeOfTrack;

		/** The stop time of the currently playing audio track measured in milliseconds. iTunes allows to set a custom stop time for a track. */
		uint32 stopTimeOfTrack;

		/** The last processed timestampID of the kVisualPluginRenderMessage. */
		uint32 currTimestampIDOfRenderData;

		/** The number of music data history. */
		sint8 numberOfMusicDataHistoryInt;

		/** The maximum number of audio data channels (2 channels means stereo). */
		static uint16 maxNumberOfAudioDataChannels;
		
		/** The number of audio waveform data entries. */
		static uint32 numberOfAudioWaveformDataEntries;
		
		/** The number of audio spectrum data entries. */
		static uint32 numberOfAudioSpectrumDataEntries;

		/**
		 * Adds the minimum and maximum waveform data value to the waveform shape.
		 * @param minWaveformPoint The minimum waveform data value.
		 * @param maxWaveformPoint The maximum waveform data value.
		 */
		void addToWaveformShape(sint8 minWaveformPoint, sint8 maxWaveformPoint);
		
		/**
		 * Adds a value to beatsRecordedInBeatAnalyseTimeFrame.
		 */
		void addToBeatRecords(void);
		
		/**
		 * Adds a value to beatGapHistogram.
		 * @param gapInMilliseconds The gap to previous beat detection in milliseconds.
		 */
		void addToBeatGapHistogram(uint16 gapInMilliseconds);
		
		/**
		 * Resets the beatGapHistogram.
		 */
		void resetBeatGapHistogram(void);
		
		/**
		 * Calculates the confidence of the beat estimation.
		 */
		void calcBeatConfidence(void);
		
		/**
		 * Returns the best guess for the beat interval in milliseconds.
		 * The best guess for the beat interval in milliseconds.
		 */
		uint32 getBestBeatMSInterval(void);
		
		/** 
		 * The waveform data array. 
		 * The waveform data array is 3-dimensional with data values, channels and history.
		 */
		//sint8 waveformData[maxNumberOfMusicDataHistory][kVisualMaxDataChannels][kVisualNumWaveformEntries];
		sint8*** waveformData;
		
		/** 
		 * The mono waveform data array. 
		 * The mono waveform data array is 2-dimensional with data values, and history.
		 */
		//sint16 waveformDataMono[maxNumberOfMusicDataHistory][kVisualNumWaveformEntries];
		sint16** waveformDataMono;
		
		/** 
		 * The spectrum data array. 
		 * The spectrum data array is 3-dimensional with data values, channels and history.
		 */
		//uint8 spectrumData[maxNumberOfMusicDataHistory][kVisualMaxDataChannels][kVisualNumSpectrumEntries];
		uint8*** spectrumData;
		
		/** The amplitude envelope array. */
		//double amplitudeEnvelope[kVisualNumWaveformEntries];
		double* amplitudeEnvelope;
		
		/** The mean values. */
		//SInt32 mean[kVisualMaxDataChannels];
		sint32* mean;
		
		/** A special buffer for beat detection. */
		//double tappingBuffer[tappingBufferLength];
		double* tappingBuffer;
		
		/** The rms values. */
		//double rms[maxNumberOfMusicDataHistory][kVisualMaxDataChannels];
		double** rms;
		
		/** The mono rms values. */
		//double rmsMono[maxNumberOfMusicDataHistory];
		double* rmsMono;
		
		/** The average rms value. */
		double rmsMonoAvg;
		
		/** A histogram of the gaps between detected beat events. */
		//uint32 beatGapHistogram[maxNumberOfBeatHistogramBins];
		uint32* beatGapHistogram;
		
		/** The delta between beats. */
		uint32 beatTimeDeltaInMS;
		
		/** The maximum mono rms value. Timeframe numberOfMillisecondsOfRMSBuffer. */
		double rmsMonoMax;
		
		/** The current history number. */
		sint16 currMusicDataHistory;
		
		/** The minimum spectrum level. 0-128. */
		//uint8 minSpectrumLevel[kVisualMaxDataChannels];
		uint8* minSpectrumLevel;
		
		/** The maximum spectrum level. 0-128. */
		//uint8 maxSpectrumLevel[kVisualMaxDataChannels];
		uint8* maxSpectrumLevel;
		
		/** The spectrum DC level. 0-256 (?). Direct Current of FFT (mono). */
		uint8 spectrumDCLevel;
		
		/** The average spectrum DC level. */
		float avgSpectrumDCLevel;
		
		/** The sum of the spectrum DC level. sum of data (for calc of avg). */
		float spectrumDCLevelSum;
		
		/** The minimum waveform data value. 0-255. -128 ...127. */
		//sint8 minWaveformVal[kVisualMaxDataChannels];
		sint8* minWaveformVal;
		
		/** The maximum waveform data value. 0-255. -128 ...127. */
		//sint8 maxWaveformVal[kVisualMaxDataChannels];
		sint8* maxWaveformVal;
		
		/** The minimum mono waveform data value. */
		sint8 minWaveformValMono;
		
		/** The maximum mono waveform data value. */
		sint8 maxWaveformValMono;
		
		/** The sum of the absolute waveform data values that are higher or lower than 128. */
		//uint32 waveformValSum[kVisualMaxDataChannels];
		uint32* waveformValSum;

		/** The peak values of the sum of the waveform data values. */
		//uint32 peakWaveformValSum[kVisualMaxDataChannels];
		uint32* peakWaveformValSum;

		/** The previous sum of the waveform data values. */
		//uint32 prevWaveformValSum[kVisualMaxDataChannels];
		uint32* prevWaveformValSum;

		/** The average value of the sum of the waveform data values. */
		//uint32 avgWaveformValSum[kVisualMaxDataChannels];
		uint32* avgWaveformValSum;

		/** The counter for the calculation o the average value of the sum of the waveform data values. */
		//uint32 avgWaveformValSumCounter[kVisualMaxDataChannels];
		uint32* avgWaveformValSumCounter;

		/** 1 if the current waveform data indicates a beat impulse, 0 if not. */
		bool isBeatImpulse;

		/** The smallest time a beat is considered to be the same. Measured in milliseconds. */
		static const uint8 beatTimeTolerance;
		
		/** The threshold after which we are free to detect a new beat. Measured in milliseconds. */
		static const uint16 beatThreshold;
		
		/** The time frame in which beats are recorded and analysed. Measured in milliseconds. */
		static const uint16 beatAnalyseTimeFrame;
		
		/** The maximum beat interval. Measured in milliseconds. */
		static const uint16 maximumBeatInterval;
		
		/** The number of milliseconds rms values are collected. */
		static const uint16 numberOfMillisecondsOfRMSBuffer;
		
		/** 
		 * The number of records in rmsBuffer. 
		 * Must be greater than: Audio sample rate (44100) / kVisualNumWaveformEntries * (numberOfMillisecondsOfRMSBuffer / 1000).
		 */
		static const uint16 numberOfRMSBufferEntries;
		
		static const uint16 maxNumberOfWaveformShapeHistory;
		
		static const uint16 maxNumberOfMusicDataHistory;
		
		static const uint16 tappingBufferLength;
		
		static const uint16 maxNumberOfBeatHistogramBins;
		
		static const uint16 maxNumberOfBeatsRecordedInAnalyseTimeframe;
		
		/**
		 * Struct with values concerning rms (root mean square) values.
		 */
		typedef struct {
			float rmsValue; /**< The rms value. */
			uint32 timeInMillisecondsSinceStartOfTrack; /**< The number of milliseconds elapsed since start of audio track. */
		} RMSValue;
		
		/** 
		 * Array containg rms mono values for the last numberOfMillisecondsOfRMSBuffer milliseconds. Ringbuffer.
		 * RMSValues with ((currentMSSinceStartOfTrack - timeInMillisecondsSinceStartOfTrack) > numberOfMillisecondsOfRMSBuffer) are discarded.
		 */
		RMSValue rmsBuffer[2000];

		/** The current index of array rmsBuffer. */
		uint16 currRMSValue;

		/** The current index of array beatsRecordedInBeatAnalyseTimeFrame. */
		uint8 currRecordedBeat;

		/**
		 * Struct with values concerning beat estimation.
		 */
		typedef struct {
			uint32 timeInMillisecondsSinceStartOfTrack; /**< The number of milliseconds elapsed since start of audio track. */
			uint16 confidence; /**< The strength of the beatGuess. */
		} BeatGuess;

		/** Array in which the detected beats are stored with their elapsed milliseconds timestamp since start of track. Ringbuffer. */
		//BeatGuess beatsRecordedInBeatAnalyseTimeFrame[maxNumberOfBeatsRecordedInAnalyseTimeframe];
		BeatGuess* beatsRecordedInBeatAnalyseTimeFrame;

		/**
		 * 
		 * @param elapsedMSSinceStartOfTrack The number of milliseconds elapsed since start of audio track.
		 * @return 1 if time is in frame of beat meter, 0 if not.
		 */
		uint8 isBeatMeter(uint32 elapsedMSSinceStartOfTrack);
		
	};

}

#endif /* VisualAudioLab_h */