ftp.nice.ch/pub/next/audio/editor/Resound.2.5.NIHS.b.tar.gz#/Resound.2.5/API/ModuleSound.rtf

This is ModuleSound.rtf in view mode; [Download] [Up]

Release 2.5, Copyright ©1997 by Sean Luke.  All Rights Reserved.


ModuleSound






Category Of:	Sound


Declared In:	ModuleSound.h





Category Description

This category contains methods which Resound has added to the Sound object, and which module designers may find useful.  There are two general categories of methods.  First, there are a few methods (sampleSize, sampleSizePerChannel) which return typical Sound information.  Then there are three methods designed to make possible easy rectangular Fast Fourier Transforms (FFTs) of sound information.  An FFT converts a section of sound into an array showing its respective harmonics (amplitude, phase, and frequency information of the sine waves that make up the sound).  This can be used for very sophisticated sound effects, if you know what you're doing.   For more information, you should consult a signal processing textbook.

It is important to note that you should not access a sound's info string.  Due to bugs in the SoundKit, Resound must maintain the Sound object's Info String separately in Resound's custom SoundView.  There are access and modification methods there; see ModuleSoundView.rtf.


Method Types

Performing an FFT	+ performFFTFromSoundData:::::toFFTData::
+ performIFFTToSoundData:::::fromFFTData::
+ nextPositivePowerOfTwo:

Sample Size	± sampleSize
	±€sampleSizePerChannel


Class Methods

performFFTFromSoundData:::::toFFTData::
- (int) performFFTFromSoundData:(char*)data:(int)start_sample:
	(int)sample_length:(int)dataFormat:(int)numChannels
		toFFTData:(float*)fft_data:(int)fft_length

Performs a Fast Fourier Transform over data starting at start_sample and ending at sample_length.  Data must be of format dataFormat, and have exactly 1 channel (so numChannels must be 1).   Acceptable data formats include floating-point (the preferred format), double precision floating-point, 8-bit and 16-bit linear, and 8-bit MuLaw.  If the number of channels or the data format is unacceptable, this method simply returns a 0, otherwise it performs the FFT and returns a 1.  This FFT is a very simple one, using only a rectangular window, and based on code from Numerical Recipies in C. 

A Fast Fourier Transform requires that the length of the sampled sound be a power of 2.  If sample_length is not a power of two, this method will perform an FFT with the remaining buffer area zeroed out; this means that when you're performing an iterated FFT over repeated samples in a sound, you should endeavour to have all of them have a sample_length of a power of 2, except perhaps the last one.

fft_length is the length of the FFT buffer.  This must be a power of 2, so fft_length should be set to the smallest positive power of 2 that is greater than or equal to sample_length.  You can determine this length with 

	fft_length = [Sound nextPositivePowerOfTwo:sample_length];
	
fft_data is an array of  pairs of floats representing the amplitude and phase of various frequencies.  This means that fft_data must be twice the length of  fft_length.  

If r is the sampling rate of your sound, then the frequencies in fft_data range from -r up to just below r (since fft_length is even, and 0 is represented at position fft_length/2, there's one more data point for negative frequencies than for positive frequencies.  However, the far left value ( -r ) in the array will always be theoretically identical to the "missing" far-right value in the array ( r ) .)  The amplitude component of each pair ranges from 0 to 1.  The phase component of each pair ranges from -p to p.

performIFFTToSoundData:::::fromFFTData::
- (int) performIFFTToSoundData:(char*)data:(int)start_sample:
	(int)sample_length:(int)dataFormat:(int)numChannels
		fromFFTData:(float*)fft_data:(int)fft_length

Performs an inverse Fast Fourier Transform (IFFT) over data starting at start_sample and ending at sample_length.  Data must be of format dataFormat, and have exactly 1 channel (so numChannels must be 1).  Acceptable data formats include floating-point (the preferred format), double precision floating-point, 8-bit and 16-bit linear, and 8-bit MuLaw.  If the number of channels or the data format is unacceptable, this method simply returns a 0, otherwise it performs the IFFT and returns a 1.  This IFFT is a very simple one, using only a rectangular window, and based on code from Numerical Recipies in C. 

You should perform this IFFT over exactly the same data you performed the FFT over, using performFFTFromSoundData:::::toFFTData::. 

fft_length is the length of the FFT buffer.  This must be a power of 2, so fft_length should be set to the smallest positive power of 2 that is greater than or equal to sample_length.  You can determine this length with 

	fft_length = [Sound nextPositivePowerOfTwo:sample_length];   
	
fft_data is an array of  pairs of floats representing the amplitude and phase of various frequencies.  This means that fft_data must be twice the length of  fft_length.   The amplitude component of each pair must range from 0 to 1.  The phase component of each pair must range from -p to p.

nextPositivePowerOfTwo:
- (int) nextPositivePowerOfTwo:(char*)value

Returns the smallest positive power of two that is greater than or equal to value.

Instance Methods

sampleSize
- (int) sampleSize

Returns the size of a single sample of the sound, that is, the size in bytes of each channel-independent sample times the number of channels.


sampleSizePerChannel
- (int) sampleSizePerChannel

Returns the size of a single sample of the sound for one channel in bytes.


These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.