//**********************************************************************************************************************
//
//	BXAudio.h
//
//	Author:		Peter Baumgartner (peter@baumgartner.com)
//	Copyright:	©2010 by IMAGINE GbR. All rights reserved.
//	Abstract:	Provides audio playback through QTKit (64bit compatible)...
//
//**********************************************************************************************************************


#if defined(MAC_OS_X_VERSION_10_5) && MAC_OS_X_VERSION_MIN_REQUIRED >= MAC_OS_X_VERSION_10_5


//----------------------------------------------------------------------------------------------------------------------


#pragma mark HEADERS

#import <QTKit/QTKit.h>


//----------------------------------------------------------------------------------------------------------------------


#pragma mark CONSTANTS

extern const double kBXQTAudioDefaultVolumeGamma;


//----------------------------------------------------------------------------------------------------------------------


// Since this class is a subclass of QTMovie we are not going to the use _prefix for any of our ivars or private
// method, to avoid name collision with internal ivars and private methods that Apple might be using right now
// or in the future. Instead we are using the slightly less intuitive prefix BX_


#pragma mark

@interface BXQTAudio : QTMovie
{
	QTTime BX_inPoint;
	QTTime BX_outPoint;
	QTTime BX_duration;
	BOOL BX_loops;
	double BX_videoFrameRate;
	double BX_updateUserInterfaceInterval;
	
	// Playback state...
	
	BOOL BX_playing;
	BOOL BX_paused;
	BOOL BX_stopped;
	BOOL BX_running;
	
	// Volume control...
	
	double BX_referenceVolume;
	double BX_volumeGamma;
	NSArray* BX_volumeEnvelope;
	
	double BX_envelopeStartTime;
	double BX_envelopeStartVolume;
	double BX_envelopeEndTime;
	double BX_envelopeEndVolume;
	
	double BX_fadeoutStartTime;
	double BX_fadeoutStartVolume;
	double BX_fadeoutEndTime;
	double BX_fadeoutEndVolume;

	BOOL BX_fadeoutStop;

	// Audiomarkers...
	
	NSArray* BX_markers;
	NSUInteger BX_nextMarkerIndex;
	double BX_nextMarkerTime;
	NSUInteger BX_lastMarkerIndex;
	double BX_lastMarkerTime;
	double BX_lastMarkerDelay;
}


// Creating...
 
+ (BXQTAudio*) audioWithURL:(NSURL*)inURL audioDevice:(NSString*)inDeviceUID error:(NSError**)outError;
- (id) initWithURL:(NSURL*)inURL audioDevice:(NSString*)inDeviceUID error:(NSError**)outError;

+ (BXQTAudio*) audioWithFile:(NSString*)inPath audioDevice:(NSString*)inDeviceUID error:(NSError**)outError;
- (id) initWithFile:(NSString*)inPath audioDevice:(NSString*)inDeviceUID error:(NSError**)outError;

- (QTMovieLoadState) BX_loadState;
- (void) waitUntilLoaded;

// Properties...

@property (readonly) double durationInSeconds;
@property (assign) double currentTimeInSeconds;
@property (assign) double inPointInSeconds;
@property (assign) double outPointInSeconds;
@property (nonatomic, assign) QTTime inPoint;
@property (nonatomic, assign) QTTime outPoint;
@property (nonatomic, assign) BOOL audioLoops;
@property (retain) NSArray* markers;						// Objects must implement the BXQTAudioMarker protocol

@property (assign) double videoFrameRate;
@property (assign) double updateUserInterfaceInterval;

// Playback control...

- (void) play;
- (void) pause;
- (void) stop;

@property (readonly) BOOL isPlaying;
@property (readonly) BOOL isPaused;
@property (readonly) BOOL isStopped;

// Volume control...

@property (assign) double referenceVolume;					// Volume envelopes are scaled with this value
@property (assign) double volumeGamma;						// Set this value to achieve a desirable fading response
@property (retain) NSArray* volumeEnvelope;					// Objects must implement the BXQTVolumeEnvelopePoint protocol

- (void) fadeoutWithDuration:(double)inDuration andStop:(BOOL)inStop;

// Last audiomarker that fired...

@property (readonly) NSUInteger lastMarkerIndex;
@property (readonly) double lastMarkerTime;
@property (readonly) double lastMarkerDelay;

@end


//----------------------------------------------------------------------------------------------------------------------


// Audiomarkers can be any object that conform to the following protocol, i.e. they must implement   
// accessors for the time and name properties...

#pragma mark

@protocol BXQTAudioMarker
@property double time;
@property (retain) NSString* name;
@end


// A volumeEnvelope is an array of objects that conform to the following protocol, i.e. they must  
// implement accessors for the time and volume properties...

#pragma mark

@protocol BXQTVolumeEnvelopePoint
@property double time;
@property double volume;
@end


// The delegate may implement the following optional methods...

#pragma mark

@protocol BXQTAudioDelegate

@optional

- (void) didChangeLoadState:(QTMovieLoadState)inLoadState forAudio:(BXQTAudio*)inAudio;

- (void) willStartPlayingAudio:(BXQTAudio*)inAudio;
- (void) didStartPlayingAudio:(BXQTAudio*)inAudio;

- (void) didFireMarkerForAudio:(BXQTAudio*)inAudio withIndex:(NSUInteger)inIndex;
- (void) updateUserInterfaceForAudio:(BXQTAudio*)inAudio;
- (void) didLoopAudio:(BXQTAudio*)inAudio;

- (void) willStopPlayingAudio:(BXQTAudio*)inAudio;
- (void) didStopPlayingAudio:(BXQTAudio*)inAudio atEnd:(BOOL)inAtEnd;

@end


//----------------------------------------------------------------------------------------------------------------------

#endif
