MusicKit: Snd.h Source File

00001 
00002 //
00003 //  $Id: Snd.h 3641 2009-10-24 11:27:52Z leighsmith $
00004 //
00005 //  Description: Main class defining a sound object.
00006 //    Designed to emulate some Sound Kit behaviour.
00007 //
00008 //  Original Author: Stephen Brandon
00009 //
00010 //  Copyright (c) 1999 Stephen Brandon and the University of Glasgow
00011 //  Additions Copyright (c) 2001, The MusicKit Project.  All rights reserved.
00012 //
00013 //  Legal Statement Covering Work by Stephen Brandon and the University of Glasgow:
00014 //
00015 //    This framework and all source code supplied with it, except where specified,
00016 //    are Copyright Stephen Brandon and the University of Glasgow, 1999. You are free
00017 //    to use the source code for any purpose, including commercial applications, as
00018 //    long as you reproduce this notice on all such software.
00019 //
00020 //    Software production is complex and we cannot warrant that the Software will be
00021 //    error free.  Further, we will not be liable to you if the Software is not fit
00022 //    for the purpose for which you acquired it, or of satisfactory quality.
00023 //
00024 //    WE SPECIFICALLY EXCLUDE TO THE FULLEST EXTENT PERMITTED BY THE COURTS ALL
00025 //    WARRANTIES IMPLIED BY LAW INCLUDING (BUT NOT LIMITED TO) IMPLIED WARRANTIES
00026 //    OF QUALITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF THIRD
00027 //    PARTIES RIGHTS.
00028 //
00029 //    If a court finds that we are liable for death or personal injury caused by our
00030 //    negligence our liability shall be unlimited.
00031 //
00032 //    WE SHALL HAVE NO LIABILITY TO YOU FOR LOSS OF PROFITS, LOSS OF CONTRACTS, LOSS
00033 //    OF DATA, LOSS OF GOODWILL, OR WORK STOPPAGE, WHICH MAY ARISE FROM YOUR
00034 //    POSSESSION OR USE OF THE SOFTWARE OR ASSOCIATED DOCUMENTATION.  WE SHALL HAVE
00035 //    NO LIABILITY IN RESPECT OF ANY USE OF THE SOFTWARE OR THE ASSOCIATED
00036 //    DOCUMENTATION WHERE SUCH USE IS NOT IN COMPLIANCE WITH THE TERMS AND
00037 //    CONDITIONS OF THIS AGREEMENT.
00038 //
00039 // Legal Statement Covering Additions by The MusicKit Project:
00040 //
00041 //    Permission is granted to use and modify this code for commercial and
00042 //    non-commercial purposes so long as the author attribution and copyright
00043 //    messages remain intact and accompany all relevant code.
00044 //
00046 
00047 #ifndef __SND_H__
00048 #define __SND_H__
00049 
00050 #import <Foundation/Foundation.h>
00051 #import "SndFormat.h"
00052 
00053 @class SndPlayer;
00054 @class SndPerformance;
00055 @class SndAudioBuffer;
00056 @class SndAudioProcessorChain;
00057 
00067 typedef enum {
00068     SndConvertLowQuality = 0,
00069     SndConvertMediumQuality = 1,
00070     SndConvertHighQuality  = 2
00071 } SndConversionQuality;
00072 
00073 
00137 @interface Snd : NSObject
00138 {
00139  @protected
00141     NSMutableArray *soundBuffers; 
00143     SndFormat soundFormat;
00145     NSString *info;
00146 
00148     int priority;                
00150     id delegate;                 
00152     NSString *name;
00154     int currentError;
00156     SndConversionQuality conversionQuality;      
00157 
00159     NSMutableArray *performancesArray;
00161     NSLock *performancesArrayLock;
00162 
00164     NSRecursiveLock *editingLock;
00165     
00167     BOOL loopWhenPlaying;
00169     long loopStartIndex;
00171     long loopEndIndex;
00172 
00174     SndAudioProcessorChain *audioProcessorChain;
00175         
00176 @public
00178     int tag;
00179 }
00180 
00181 /*
00182  * --------------- Factory Methods
00183  */
00184 
00185 + soundNamed: (NSString *) aName;
00186 
00207 + findSoundFor: (NSString *) aName;
00208 
00215 + addName: (NSString *) name sound: (Snd *) aSnd;
00216 
00223 + addName: (NSString *) name fromSoundfile: (NSString *) filename;
00224 
00231 + addName: (NSString *) name fromSection: (NSString *) sectionName;
00238 + addName: (NSString *) aName fromBundle: (NSBundle *) aBundle;
00239 
00245 + (void) removeSoundForName: (NSString *) name;
00246 
00250 + (void) removeAllSounds;
00251 
00252 
00253 - (NSString *) description;
00254 
00263 - initFromSoundfile: (NSString *) filename;
00264 
00277 - initFromSoundURL: (NSURL *) url;
00278 
00287 - initWithFormat: (SndSampleFormat) format
00288     channelCount: (int) channels
00289           frames: (unsigned long) frames
00290     samplingRate: (float) samplingRate;
00291 
00302 - initWithData: (NSData *) soundData;
00303 
00317 - (void) swapBigEndianToHostFormat;
00318 
00332 - (void) swapHostToBigEndianFormat;
00333 
00334 - (void) encodeWithCoder: (NSCoder *) aCoder;
00335 - (id) initWithCoder: (NSCoder *) aDecoder;
00336 - awakeAfterUsingCoder: (NSCoder *) aDecoder;
00337 
00342 - (NSString *) name;
00343 
00352 - setName: (NSString *) theName;
00353 
00358 - delegate;
00359 
00364 - (void) setDelegate: (id) anObject;
00365 
00370 - (double) samplingRate;
00371 
00376 - (unsigned long) lengthInSampleFrames;
00377 
00382 - (double) duration;
00383 
00388 - (int) channelCount;
00389 
00398 - (NSString *) info;
00399 
00407 - (void) setInfo: (NSString *) newInfoString;
00408 
00418 - (BOOL) isEmpty;
00419 
00425 - (BOOL) isEditable;
00426 
00438 - (BOOL) compatibleWithSound: (Snd *) aSound;
00439 
00456 - (int) convertToSampleFormat: (SndSampleFormat) newFormat
00457            samplingRate: (double) newRate
00458            channelCount: (int) newChannelCount;
00459 
00468 - (int) convertToSampleFormat: (SndSampleFormat) newFormat;
00469 
00478 + (SndFormat) nativeFormat;
00479 
00487 - (int) convertToNativeFormat;
00488 
00493 - (id) copyWithZone: (NSZone *) zone;
00494 
00503 - (NSData *) dataEncodedAsFormat: (NSString *) dataFormat;
00504 
00527 - (void *) bytes;
00528 
00537 - (long) dataSize;
00538 
00547 - (SndSampleFormat) dataFormat;
00548 
00556 - (BOOL) hasSameFormatAsBuffer: (SndAudioBuffer *) buff;
00557 
00562 - (SndFormat) format;
00563 
00568 - (NSString *) formatDescription;
00569 
00576 - (int) processingError;
00577 
00584 - (Snd *) soundBeingProcessed;
00585 
00586 // delegations which are not nominated per performance.
00587 
00598 - (void) tellDelegate: (SEL) theMessage;
00599 
00600 // delegations which are nominated per performance.
00601 
00612 - (void) tellDelegate: (SEL) theMessage duringPerformance: (SndPerformance *) performance;
00613 
00625 - (void) tellDelegateString: (NSString *) theMessage duringPerformance: (SndPerformance *) performance;
00626 
00633 - (void) setConversionQuality: (SndConversionQuality) quality;
00634 
00639 - (SndConversionQuality) conversionQuality;
00640 
00646 - initWithAudioBuffer: (SndAudioBuffer *) aBuffer;
00647 
00652 - (void) normalise;
00653 
00658 - (double) maximumAmplitude;
00659 
00660 @end
00661 
00662 @interface Snd(FileIO)
00663 
00664 + (int) fileFormatForEncoding: (NSString *) extensionString
00665                    dataFormat: (SndSampleFormat) sndFormatCode;
00666 
00676 + (NSArray *) soundFileExtensions;
00677 
00682 + (BOOL) isPathForSoundFile: (NSString*) path;
00683 
00687 + (NSString *) defaultFileExtension;
00688 
00696 - (SndFormat) soundFormatOfFilename: (NSString *) filename;
00697 
00710 - (int) readSoundfile: (NSString *) filename
00711            startFrame: (unsigned long) startFrame
00712            frameCount: (long) frameCount;
00713 
00721 - (int) readSoundfile: (NSString *) filename;
00722 
00735 - (int) writeSoundfile: (NSString *) filename
00736             fileFormat: (NSString *) fileFormat
00737             dataFormat: (SndSampleFormat) fileDataFormat;
00738 
00748 - (int) writeSoundfile: (NSString *) filename;
00749 
00750 @end
00751 
00752 @interface Snd(Playing)
00753 
00758 + (BOOL) isMuted;
00759 
00766 + setMute: (BOOL) aFlag;
00767 
00778 - (int) waitUntilStopped;
00779 
00785 + (void) stopPerformance: (SndPerformance *) performance inFuture: (double) inSeconds;
00786 
00793 - (void) stop: (id) sender;
00794 
00802 - (int) stop;
00803 
00811 - pause: (id) sender;
00812 
00817 - (int) pause;
00818 
00823 - resume: (id) sender;
00824 
00829 - (int) resume;
00830 
00842 - (BOOL) isPlayable;
00843 
00849 - (BOOL) isPlaying;
00850 
00867 - (int) play;
00868 
00874 - play: (id) sender;
00875 
00883 - (SndPerformance *) playInFuture: (double) inSeconds
00884                       beginSample: (unsigned long) begin
00885                       sampleCount: (unsigned long) count;
00886 
00895 - (SndPerformance *) playInFuture: (double) inSeconds
00896            startPositionInSeconds: (double) startPosition
00897                 durationInSeconds: (double) duration;
00904 - (SndPerformance *) playAtTimeInSeconds: (double) t withDurationInSeconds: (double) d;
00905 
00915 - play: (id) sender beginSample: (int) begin sampleCount: (int) count;
00916 
00922 - (SndPerformance *) playInFuture: (double) inSeconds;
00923 
00929 - (SndPerformance *) playAtDate: (NSDate *) date;
00930 
00934 - record: (id) sender;
00935 
00960 - (int) record;
00961 
00967 - (BOOL) isRecording;
00968 
00978 - (int) samplesPerformedOfPerformance: (SndPerformance *) performance;
00979 
00986 - (NSArray*) performances;
00987 
00995 - addPerformance: (SndPerformance *) p;
00996 
01004 - removePerformance: (SndPerformance *) p;
01005 
01012 - (int) performanceCount;
01013 
01018 - (void) setLoopWhenPlaying: (BOOL) yesOrNo;
01019 
01024 - (BOOL) loopWhenPlaying;
01025 
01033 - (void) setLoopStartIndex: (long) loopStartIndex;
01034 
01039 - (long) loopStartIndex;
01040 
01050 - (void) setLoopEndIndex: (long) newLoopEndIndex;
01051 
01056 - (long) loopEndIndex;
01057 
01058 // We declare this because it is used by the SndEditing category.
01059 - (void) adjustLoopsAfterAdding: (BOOL) adding 
01060                          frames: (long) sampleCount
01061                      startingAt: (long) startSample;
01062 
01069 - (void) setAudioProcessorChain: (SndAudioProcessorChain *) newAudioProcessorChain;
01070 
01077 - (SndAudioProcessorChain *) audioProcessorChain;
01078 
01079 @end
01080 
01081 @interface Snd(Editing)
01082 
01087 - (void) lockEditing;
01088 
01093 - (void) unlockEditing;
01094 
01101 - (int) deleteSamples;
01102 
01112 - (int) deleteSamplesInRange: (NSRange) frameRange;
01113 
01126 - (int) insertSamples: (Snd *) aSnd at: (int) startSample;
01127 
01139 - (Snd *) soundFromSamplesInRange: (NSRange) frameRange;
01140 
01156 - (int) compactSamples;
01157 
01162 - (BOOL) needsCompacting;
01163 
01179 - (void *) fragmentOfFrame: (unsigned long) frame 
01180            indexInFragment: (unsigned long *) currentFrame 
01181             fragmentLength: (unsigned long *) fragmentLength
01182                 dataFormat: (SndSampleFormat *) dataFormat;
01183 
01195 - (long) fillAudioBuffer: (SndAudioBuffer *) buff
01196                 toLength: (long) fillLength
01197           samplesInRange: (NSRange) sndReadingRange;
01198 
01220 - (long) insertIntoAudioBuffer: (SndAudioBuffer *) buff
01221                 intoFrameRange: (NSRange) bufferFrameRange
01222                 samplesInRange: (NSRange) sndFrameRange;
01223 
01230 - (long) insertAudioBuffer: (SndAudioBuffer *) buffer
01231             intoFrameRange: (NSRange) writeIntoSndFrameRange;
01232 
01238 - (long) appendAudioBuffer: (SndAudioBuffer *) buffer;
01239 
01248 - (SndAudioBuffer *) audioBufferForSamplesInRange: (NSRange) sndFrameRange
01249                                           looping: (BOOL) isLooping;
01250 
01257 - (SndAudioBuffer *) audioBufferForSamplesInRange: (NSRange) r;
01258 
01263 - (NSArray *) audioBuffers;
01264 
01265 @end
01266 
01267 @interface SndDelegate : NSObject
01268 
01273 - willRecord: sender;
01274 
01279 - didRecord:  sender;
01280 
01286 - hadError:   sender;
01287 
01293 - willPlay:   sender duringPerformance: (SndPerformance *) performance;
01294 
01300 - didPlay:    sender duringPerformance: (SndPerformance *) performance;
01301 
01302 @end
01303 
01304 #endif