SoundMeter

SoundMeter

Inherits From: View : Responder : Object

Declared In: soundkit/SoundMeter.h

Class Description

A SoundMeter is a view that displays the amplitude level of a sound as it's being recorded or played back. There are two working parts to the meter: A continuously-updated "running bar" that lengthens ands shrinks to depict the current amplitude level, and a "peak bubble" that displays and holds the greatest amplitude that was detected within the last few samples. An optional bezeled border is drawn around the object's frame.
To use a SoundMeter, you must first associate it with a Sound object, through the setSound: method, and then send the SoundMeter a run: message. To stop the meter's display, you send the object a stop: message. Neither run: nor stop: affect the performance of the meter's sound.
You can retrieve a SoundMeter's running and peak values through the floatValue and peakValue methods. The values that these methods return are valid only while the SoundMeter is running. A SoundMeter also keeps track of the minimum and maximum amplitude over the duration of a run; these can be retrieved through minValue and maxValue. All SoundMeter amplitude levels are normalized to fit between 0.0 (inaudible) and 1.0 (maximum amplitude).

Instance Variables

id sound;
int currentSample;
float currentValue;
float currentPeak;
float minValue;
float maxValue;
float holdTime;
float backgroundGray;
float foregroundGray;
float peakGray;
struct {
unsigned int running:1;
unsigned int bezeled:1;
unsigned int shouldStop:1;
} smFlags;

sound The object's Sound.

currentSample The Sound sample currently being displayed.

currentValue The value of the current sample.

currentPeak The current value of the peak bubble.

minValue The minimum sample value so far.

maxValue The maximum sample value so far.

holdTime The hold duration of the peak bubble.

backgroundGray The background color.

foregroundGray The foreground (average bar) color.

peakGray The peak bubble color.

smFlags.running True if the object is currently running.

smFlags.bezeled True if the object draws a border.

smFlags.shouldStop True if the object has been sent a stop: message.

Method Types

Initializing a SoundMeter instance

initFrame:

Graphic attributes setBezeled:

isBezeled
setBackgroundGray:
backgroundGray
setForegroundGray:
foregroundGray
setPeakGray:
peakGray

Metering attributes setSound:

sound
setFloatValue:
setHoldTime:
holdTime

Retrieving meter values floatValue

maxValue
minValue
peakValue

Operating the object run:

isRunning
stop:

Drawing the object drawCurrentValue

drawSelf::

Archiving read:

write:

Instance Methods

backgroundGray

(float)backgroundGray

Returns the SoundMeter's background color. The default is dark gray (NX_DKGRAY).

drawCurrentValue

drawCurrentValue

Draws the SoundMeter's running bar and peak bubble. You never invoke this method directly; it's invoked automatically while the SoundMeter is running. You can override this method to change the look of the running bar and peak bubble. Returns self.

drawSelf::

drawSelf:(const NXRect *)rects :(int)rectCount

Draws all the components of the SoundMeter (frame, running bar, and peak bubble). You never invoke this method directly; however, you can override it in a subclass to change the way the components are displayed. Returns self.

floatValue

(float)floatValue

Returns the current running amplitude value as a floating-point number between 0.0 and 1.0. This is the amplitude level that's displayed by the running bar.

foregroundGray

(float)foregroundGray

Returns the color of the running bar. The default is light gray (NX_LTGRAY).

holdTime

(float)holdTime

Returns the SoundMeter's hold time--the amount of time during which a peak amplitude is detected and displayed by the peak bubble--in seconds. The default is 0.7 seconds.

initFrame:

initFrame:(const NXRect *)frameRect

Initializes the SoundMeter, fitting its graphic components within frameRect. The object's attributes are initialized as follows:

Attribute Value

Peak hold time 0.7 seconds

Background gray NX_DKGRAY

Running bar gray NX_LTGRAY

Peak bubble gray NX_WHITE

Border bezeled

Returns self.

isBezeled

(BOOL)isBezeled

Returns YES (the default) if the SoundMeter has a border; otherwise, returns NO. Note that the SoundMeter class doesn't provide a method to change the type of border--it can display a bezeled border or none at all.

isRunning

(BOOL)isRunning

Returns YES if the SoundMeter is currently running; otherwise, returns NO. The SoundMeter's status doesn't depend on the activity of its Sound object.

maxValue

(float)maxValue

Returns the maximum running value so far. You can invoke this method after you stop this SoundMeter to retrieve the overall maximum value for the previous performance. The maximum value is cleared when you restart the SoundMeter.

minValue

(float)minValue

Returns the minimum running value so far. You can invoke this method after you stop this SoundMeter to retrieve the overall minimum value for the previous performance. The minimum value is cleared when you restart the SoundMeter.

peakGray

(float)peakGray

Returns the SoundMeter's peak bubble gray. The default is white (NX_WHITE).

peakValue

(float)peakValue

Returns the most recently detected peak value as a floating-point number between 0.0 and 1.0. This is the amplitude level that's displayed by the peak bubble.

read:

read:(NXTypedStream *)aStream

Unarchives the SoundMeter by reading it from aStream. Returns self.

run:

run:sender

Starts the SoundMeter running. The object SoundMeter must have a Sound object associated with it for this method to have an effect. Note that this method only affects the state of the SoundMeter--it doesn't trigger any activity in the Sound. Returns self.

setBackgroundGray:

setBackgroundGray:(float)aValue

Sets the SoundMeter's background color. The default is dark gray (NX_DKGRAY). Returns self.

setBezeled:

setBezeled:(BOOL)aFlag

If aFlag is YES, a bezeled border is drawn around the SoundMeter. If aFlag is NO and the SoundMeter has a frame, the frame is removed. Returns self.

setFloatValue:

setFloatValue:(float)aValue

Sets the current running value to aValue. You never invoke this method directly; it's invoked automatically when the SoundMeter is running. However, you can reimplement this method in a subclass of SoundMeter. Returns self.

setForegroundGray:

setForegroundGray:(float)aValue

Sets the SoundMeter's running bar color. The default is light gray (NX_LTGRAY). Returns self.

setHoldTime:

setHoldTime:(float)seconds

Sets the SoundMeter's peak value hold time in seconds. This is the amount of time during which peak amplitudes are detected and held by the peak bubble. Returns self.

setPeakGray:

setPeakGray:(float)aValue

Sets the SoundMeter's peak bubble color. The default is white (NX_WHITE). Returns self.

setSound:

setSound:aSound

Sets the SoundMeter's Sound object. Returns self.

sound

sound

Returns the Sound object that the SoundMeter is metering.

stop:

stop:sender

Stops the SoundMeter's metering activity. Note that this method only affects the state of the SoundMeter--it doesn't trigger any activity in the Sound. Returns self.

write:

write:(NXTypedStream *)aStream

Archives the SoundMeter by writing it to aStream. Returns self.

	Inherits From:	View : Responder : Object

	Declared In:	soundkit/SoundMeter.h

	sound	The object's Sound.

	currentSample	The Sound sample currently being displayed.

	currentValue	The value of the current sample.

	currentPeak	The current value of the peak bubble.

	minValue	The minimum sample value so far.

	maxValue	The maximum sample value so far.

	holdTime	The hold duration of the peak bubble.

	backgroundGray	The background color.

	foregroundGray	The foreground (average bar) color.

	peakGray	The peak bubble color.

	smFlags.running	True if the object is currently running.

	smFlags.bezeled	True if the object draws a border.

	smFlags.shouldStop	True if the object has been sent a stop: message.

	Attribute	Value

	Peak hold time	0.7 seconds
	Background gray	NX_DKGRAY
	Running bar gray	NX_LTGRAY
	Peak bubble gray	NX_WHITE
	Border	bezeled