MashDoc: AudioAgent

OpenMash Documentations

Class Index Method Index Class Hierarchy

TCL CLASS

AudioAgent

The AudioAgent class provides a coarse-grained interface that abstracts away all the details of networked audio. This agent is responsible for creating the underlying RTP session for the audio channel, for opening and initializing the audio codec hardware, and for creating the AudioController that orchestrates the timing and synchronization of all audio events.

Since AudioAgent is derived from the RTPAgent base class, the standard RTP observer API is supported. Any ``interesting'' events (e.g., the arrival of a new RTP flow) within the underlying RTP sessions are relayed to all the observers attached to this agent. (Note that the AudioAgent class catches and handles some of the events on its own.)

Typically, a mash script will create a separate user interface object and attach it to the AudioAgent as an Observer.

SUPERCLASSES

RTPAgent, RTP/Audio

SUBCLASSES

AudioAgent16, AudioAgentTGW

METHODS

init, destroy, activate, deactivate, trigger_media, attach_local_channel, attach_global_channel, set_maxchannel, create_decoder, create_session, reset, reset_source_offsets, bind_transducer, have_audio, set_input_mute, set_output_mute, set_input_gain, set_output_gain, get_input_gain, get_output_gain, set_input_port, set_output_port, , , get_input_ports, get_output_ports, get_input_portno, get_output_portno, set_speakerphone, audio_test, port_name_to_num, obtain, release, is_active, clear_active, select_format, set_silence_thresh, unix_time, ntp_time, start_mega, reset_mega, is_halfduplex

init

AudioAgent public init { app spec {callback {} } }

Initialize a new instance of an AudioAgent. initialize the network (alot of it is done in the parent classes) and setup the audioStream

destroy

AudioAgent public destroy { }

Deallocate all the resources associated with the AudioAgent class. Close the audio device (and implicitly delete it) and free up the buffer pool.

activate

AudioAgent private activate { src }

Handle an activate event on source src. Called from C++ (through Source/RTP) when we start actively receiving data pkts from the given source. Create the decoder and dispatch the method to the observers as normal. Extends method in RTPAgent.

deactivate

AudioAgent private deactivate { src }

Handle a deactivate event on source src. Called from C++ (through Source/RTP) when a source has left the session (either via an RTCP BYE message or via an expiration timer). This method can also get called back if the Source object is explicitly deleted from the local program. Extends method in RTPAgent.

trigger_media

AudioAgent instproc trigger_media { src }

Handle a media-trigger event on source src. Called from C++ (through Source/RTP) when a data packet arrives from source src and its media trigger is enabled. Extends method in RTPAgent.

attach_local_channel

attach_global_channel

AudioAgent instproc attach_local_channel { lc }

AudioAgent instproc attach_global_channel { gc }

Attach a CoordinationBus object to this agent. When present, the coordination bus enables a number of inter-agent interactions, e.g., voice-switched-video windows orchestrated between video and audio agents.

set_maxchannel

AudioAgent private set_maxchannel { n }

Called by the underlying network object when the number of media layers expected across all sources changes. For example, an underlying network protocol might adjust the number of multicast channels received to carry out congestion control. When the level of subscription changes, the codecs must be informed so that they do not wait unnecessarily for packets that will never arrive (because the corresponding layer is not present).

Extends method in RTPAgent.

create_decoder

AudioAgent public create_decoder { src }

Create an audio decoder that can decode the RTP flow from source src. Assumes this source has received media packets so we can determine the RTP payload type and allocate an appropriate decoder. If the system does not support the media type, a ``null decoder'' is created and returned.

create_session

AudioAgent private create_session { }

Create a Session object that appropriate for this type of agent. Called by the RTPAgent class when initializing the network state.

reset

AudioAgent public reset { ab }

Assign a new address (or set of addresses) to the underlying communication session. The address(es) must be in the AddressBlock object given by ab.

reset_source_offsets

AudioAgent instproc reset_source_offsets { }

Reset the clock offset of each Source object in the underlying communication session. The clock offset is the skew between the sender's media timestamp and the local media time. Rather than run an elaborate synchronization scheme, the offset is computed and set at the start of each talk spurt. Since these offsets can drift when the Controller object is not running off the audio clock, this time base can shift pretty badly (especially on PC's where gettimeofday accuracy is low). This hook allows the UI to note when the device is re-gained so that the offsets can be explicitly reset. FIXME - this is too much exposure of mechanism. Figure out how to hide this. The AudioAgent should be able to tell on its own thtat the device is re-obtained and should do the reset then... Also, delay adaptation state should be kept in the source object... (and this method should live in RtpAgent)