MusicKit  0.0.0
Snd.h
00001 
00002 //
00003 //  $Id$
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 
00206 + findSoundFor: (NSString *) aName;
00207 
00214 + addName: (NSString *) name sound: (Snd *) aSnd;
00215 
00222 + addName: (NSString *) name fromSoundfile: (NSString *) filename;
00223 
00230 + addName: (NSString *) name fromSection: (NSString *) sectionName;
00231 
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 
00491 + (SndFormat) nativeFormatForOutput: (BOOL) forOutputDevices;
00492 
00502 + (SndFormat) nativeInputFormat;
00503 
00511 - (int) convertToNativeFormat;
00512 
00517 - (id) copyWithZone: (NSZone *) zone;
00518 
00527 - (NSData *) dataEncodedAsFormat: (NSString *) dataFormat;
00528 
00551 - (void *) bytes;
00552 
00561 - (long) dataSize;
00562 
00571 - (SndSampleFormat) dataFormat;
00572 
00580 - (BOOL) hasSameFormatAsBuffer: (SndAudioBuffer *) buff;
00581 
00586 - (SndFormat) format;
00587 
00592 - (NSString *) formatDescription;
00593 
00600 - (int) processingError;
00601 
00608 - (Snd *) soundBeingProcessed;
00609 
00610 // delegations which are not nominated per performance.
00611 
00622 - (void) tellDelegate: (SEL) theMessage;
00623 
00624 // delegations which are nominated per performance.
00625 
00636 - (void) tellDelegate: (SEL) theMessage duringPerformance: (SndPerformance *) performance;
00637 
00649 - (void) tellDelegateString: (NSString *) theMessage duringPerformance: (SndPerformance *) performance;
00650 
00657 - (void) setConversionQuality: (SndConversionQuality) quality;
00658 
00663 - (SndConversionQuality) conversionQuality;
00664 
00670 - initWithAudioBuffer: (SndAudioBuffer *) aBuffer;
00671 
00676 - (void) normalise;
00677 
00682 - (double) maximumAmplitude;
00683 
00684 @end
00685 
00686 @interface Snd(FileIO)
00687 
00688 + (int) fileFormatForEncoding: (NSString *) extensionString
00689                    dataFormat: (SndSampleFormat) sndFormatCode;
00690 
00700 + (NSArray *) soundFileExtensions;
00701 
00706 + (BOOL) isPathForSoundFile: (NSString*) path;
00707 
00711 + (NSString *) defaultFileExtension;
00712 
00720 - (SndFormat) soundFormatOfFilename: (NSString *) filename;
00721 
00734 - (int) readSoundfile: (NSString *) filename
00735            startFrame: (unsigned long) startFrame
00736            frameCount: (long) frameCount;
00737 
00745 - (int) readSoundfile: (NSString *) filename;
00746 
00759 - (int) writeSoundfile: (NSString *) filename
00760             fileFormat: (NSString *) fileFormat
00761             dataFormat: (SndSampleFormat) fileDataFormat;
00762 
00772 - (int) writeSoundfile: (NSString *) filename;
00773 
00774 @end
00775 
00776 @interface Snd(Playing)
00777 
00782 + (BOOL) isMuted;
00783 
00790 + setMute: (BOOL) aFlag;
00791 
00802 - (int) waitUntilStopped;
00803 
00809 + (void) stopPerformance: (SndPerformance *) performance inFuture: (double) inSeconds;
00810 
00817 - (void) stop: (id) sender;
00818 
00826 - (int) stop;
00827 
00835 - pause: (id) sender;
00836 
00841 - (int) pause;
00842 
00847 - resume: (id) sender;
00848 
00853 - (int) resume;
00854 
00866 - (BOOL) isPlayable;
00867 
00873 - (BOOL) isPlaying;
00874 
00887 - (SndPerformance *) play;
00888 
00894 - (SndPerformance *) play: (id) sender;
00895 
00903 - (SndPerformance *) playInFuture: (double) inSeconds
00904                       beginSample: (unsigned long) begin
00905                       sampleCount: (unsigned long) count;
00906 
00915 - (SndPerformance *) playInFuture: (double) inSeconds
00916            startPositionInSeconds: (double) startPosition
00917                 durationInSeconds: (double) duration;
00924 - (SndPerformance *) playAtTimeInSeconds: (double) t withDurationInSeconds: (double) d;
00925 
00935 - (SndPerformance *) play: (id) sender beginSample: (int) begin sampleCount: (int) count;
00936 
00942 - (SndPerformance *) playInFuture: (double) inSeconds;
00943 
00949 - (SndPerformance *) playAtDate: (NSDate *) date;
00950 
00954 - record: (id) sender;
00955 
00980 - (int) record;
00981 
00987 - (BOOL) isRecording;
00988 
00998 - (int) samplesPerformedOfPerformance: (SndPerformance *) performance;
00999 
01006 - (NSArray*) performances;
01007 
01015 - addPerformance: (SndPerformance *) p;
01016 
01024 - removePerformance: (SndPerformance *) p;
01025 
01032 - (int) performanceCount;
01033 
01038 - (void) setLoopWhenPlaying: (BOOL) yesOrNo;
01039 
01044 - (BOOL) loopWhenPlaying;
01045 
01053 - (void) setLoopStartIndex: (long) loopStartIndex;
01054 
01059 - (long) loopStartIndex;
01060 
01070 - (void) setLoopEndIndex: (long) newLoopEndIndex;
01071 
01076 - (long) loopEndIndex;
01077 
01078 // We declare this because it is used by the SndEditing category.
01079 - (void) adjustLoopsAfterAdding: (BOOL) adding 
01080                          frames: (long) sampleCount
01081                      startingAt: (long) startSample;
01082 
01089 - (void) setAudioProcessorChain: (SndAudioProcessorChain *) newAudioProcessorChain;
01090 
01097 - (SndAudioProcessorChain *) audioProcessorChain;
01098 
01099 @end
01100 
01101 @interface Snd(Editing)
01102 
01107 - (void) lockEditing;
01108 
01113 - (void) unlockEditing;
01114 
01121 - (int) deleteSamples;
01122 
01132 - (int) deleteSamplesInRange: (NSRange) frameRange;
01133 
01146 - (int) insertSamples: (Snd *) aSnd at: (int) startSample;
01147 
01159 - (Snd *) soundFromSamplesInRange: (NSRange) frameRange;
01160 
01176 - (int) compactSamples;
01177 
01182 - (BOOL) needsCompacting;
01183 
01199 - (void *) fragmentOfFrame: (unsigned long) frame 
01200            indexInFragment: (unsigned long *) currentFrame 
01201             fragmentLength: (unsigned long *) fragmentLength
01202                 dataFormat: (SndSampleFormat *) dataFormat;
01203 
01215 - (long) fillAudioBuffer: (SndAudioBuffer *) buff
01216                 toLength: (long) fillLength
01217           samplesInRange: (NSRange) sndReadingRange;
01218 
01240 - (long) insertIntoAudioBuffer: (SndAudioBuffer *) buff
01241                 intoFrameRange: (NSRange) bufferFrameRange
01242                 samplesInRange: (NSRange) sndFrameRange;
01243 
01250 - (long) insertAudioBuffer: (SndAudioBuffer *) buffer
01251             intoFrameRange: (NSRange) writeIntoSndFrameRange;
01252 
01258 - (long) appendAudioBuffer: (SndAudioBuffer *) buffer;
01259 
01268 - (SndAudioBuffer *) audioBufferForSamplesInRange: (NSRange) sndFrameRange
01269                                           looping: (BOOL) isLooping;
01270 
01277 - (SndAudioBuffer *) audioBufferForSamplesInRange: (NSRange) r;
01278 
01283 - (NSArray *) audioBuffers;
01284 
01285 @end
01286 
01287 @interface SndDelegate : NSObject
01288 
01293 - willRecord: sender;
01294 
01299 - didRecord:  sender;
01300 
01306 - hadError:   sender;
01307 
01313 - willPlay:   sender duringPerformance: (SndPerformance *) performance;
01314 
01320 - didPlay:    sender duringPerformance: (SndPerformance *) performance;
01321 
01322 @end
01323 
01324 #endif