NetSend


Overview


NetSend is a Cocoa class which simplifies the use of the Core Audio's AUNetSend Audio Unit.

NetSend defaults to sending a floating point, stereo audio stream at a sampling rate of 44100 samples/sec. NetSend also defaults to using the port of 52800 (same as AUNetSend) -- Core Audio will assign the next free port that is larger than 52800 if that port is already in use. NetSend defaults to using a Bonjour service name of "AUNetSend." This name can be set to anything else either during initialization or subsequent to that.

You can ask NetSend to use a different port number. If that port is busy, Core Audio will use the next higher port number that is available.

In the simplest usage, you would allocate and initialize NetSend and just send it a startSampling message when you want to send an audio stream over AUNetSend. When a buffer is needed, NetSend will call the delegate's netSend:needSamplesleftright: method. A stopSampling message will stop the stream.

The way NetSend works is this: NetSend creates a AUNetSend audio unit and initializes it with the proper parameters. It also sets an input render callback routine from AUNetSend.

When the NetSend object is asked to start sampling, a repeating NSTimer object is created. This timer is activated periodically, at the rate of the sampling rate divided by the number of samples per buffer.

The NSTimer object is responsible for calling the output renderer of the AUNetSend object. This will in turn cause the Audio Unit to invoke the input render callback routine. In turn, this input callback routine calls the NetSend delegate to ask for the next frame of data. AUNetSend will send this input rendered data out as a stream to the net service port.

The NSTimer object runs in its own Run Loop in a separate high priority thread. This, in turn, means that the delegate call back for data (netSend:needSamplesleftright:)is also not running inside the main thread. Be sure that any calls to objects in the Cocoa's framework that are not thread safe (e.g., NSView and its subclasses, NSBezierPath, etc) are dispatched from the main thread (see for example the Oscilloscope.m in the NetReceive sample code).

The AUNetSend data buffers also arrive at the NSTimer routine, but are discarded. However, NetSend can be easily sub-classed so that instead of using the NSTimer process, the output of the AUNetSend can be connected to another audio unit and the data pulled by that other another audio unit.



Tasks


Creating instances

Assigning a delegate

Setting service patrameters

Starting and stopping sampling

Fetching sampled data


Instance Methods


delegate

Returns the delegate object of NetSend.

- (id)delegate

Return Value

The current delegate object, or nil if no delegate has been set.



initWithService:delegate:samplesPerBuffer

Initializes and returns a newly allocated NetSend object with the specified service name, delegate and the number of samples per call back to the delegate.

- (id)initWithService:(NSString*)serviceName delegate:(id)inDelegate samplesPerBuffer:(int)samplesPerBuffer

Parameters

serviceName
The Bonjour service name of the AUNetSend component that NetSend represents. If -init is called instead of -initWithService, the service name will be set to AUNetSend.

inDelegate
The delegate that NetSend sends data requests to. If -init is called instead of -initWithService, the delegate is set to nil.

samplesPerBuffer
The number of samples that NetSend needs per data request to the delegate. If -init is called instead of -initWithService, the number of samples is set to 512.


Return Value

An initialized NetSend object, or nil if an AUNetSend component could not be created.



setDelegate:

Sets the delegate object that is to receive data requests from NetSend. The delegate can also be set in - initWithService:delegate:samplesPerBuffer:

- (void)setDelegate:(id)anObject

Parameters

anObject
The new delegate object.



setPassword:

Sets the password for the AUNetSend stream.

- (void)setPassword(NSString*)password

Parameters

password
The new password.

Discussion

NetSend is initialized with no password. A secure stream can set a password by sending setPassword: to the receiver.



setPortNumber:

Sets the port number for the AUNetSend stream.

- (void)setPortNumber(int)port

Parameters

port
The new port number.

Discussion

NetSend is initialized to use a port number of 52800. This is the default port number that AUNetSend uses. Core Audio will choose the next higher unused number if 52800 is already in used. setPortNumber: allows you to start at some other number.



setServiceName:

Sets the Bonjour service name for the AUNetSend stream.

- (void)setServiceName:(NSString*)name

Parameters

name
The Bonjour service name.

Discussion

The service name can be set during initialization by initializing using initWithService:delegate:samplesPerBuffer:. The service name can be changed anytime by calling setServiceName:.



startSampling

Starts the NetSend object. The delegate should be set up to receive netSend:needSamples:left:right calls to fill the buffers that NetSend needs.

- (Boolean)startSampling

Return Value

NetSend returns false if for some reason it could not start the output stream.



stopSampling

Stops the NetSend object.

- (void)stopSampling



Delegate Methods



netSend:needSamples:left:right:

invoked when NetSend needs a new buffer from the delegate.

- (void)netSend:(NetSend*)aNetSend needSamples:(int)samplesPerBuffer left:(float*)leftBuffer right:(float*)rightBuffer

Parameters

aNetSend
The NetSend object that is making the request. The delegate can use this to distinguish between multiple NetSend objects.

samplesPerBuffer
This is the number of samples that is requested. NetSends uses stereo streams, so it expects the delegate to return this number of samples in both buffers.

leftBuffer
The left channel's buffer.

rightBuffer
The right channel's buffer.