net.sf.nohands.hfpd.SoundIo

net.sf.nohands.hfpd.SoundIo Interface Reference

Interface for managing HFPD's audio data pump. More...

List of all members.

Public Member Functions

 SetDriver (in string drivername, in string driveropts)
 Set the local sound card driver and options used by the SoundIo.
 ProbeDevices (in string drivername, out string[2][] found_devices)
 Probe for local sound card devices available from a specific driver.
 Stop ()
 Stop any in-progress audio streaming through the local sound card.
 AudioGatewayStart (in objectpath audio_gateway, in bool initiate_connection)
 Start an audio stream with an AudioGateway device.
 FileStart (in string file_path, in bool write)
 Start a WAV file audio stream.
 LoopbackStart ()
 Start a loopback audio stream.
 MembufStart (in bool capture, in bool playback, in uint32 membuf_size, in uint32 report_interval)
 Start streaming to and/or from a memory buffer.
 MembufClear ()
 Drop the contents of an existing memory buffer.
 SetSnoopFile (in string filename, in bool capture, in bool playback)
 Configure a WAV file to receive audio pump traffic.
signal StateChanged (out byte state)
 Notification of change of state of the SoundIo.
signal StreamAborted (out string error_name, out string description)
 Notification of asynchronous stream abort of the SoundIo.
signal MuteChanged (out bool mute)
 Notification of change of the mute state of the SoundIo.
signal AudioGatewaySet (out objectpath audio_gateway)
 Notification of an audio gateway being selected.
signal SkewNotify (out byte skew_type, out double skew_value)
 Notification of audio clock skew.
signal MonitorNotify (out uint32 position, out uint16 max_amplitude)
 Notification of audio stream progress.

Public Attributes

const byte State
 State of the SoundIo object.
bool Mute
 Mute state of the SoundIo object.
const variant AudioGateway
 Configured audio gateway endpoint.
const string SnoopFileName
 Target file for stream snooper.
const string Drivers [2][]
 List of available local sound card drivers.
const string DriverName
 Name of active local sound card driver.
const string DriverOpts
 Options provided to active local sound card driver.
const uint32 PacketInterval
 Active sample packet interval in use by the local sound card.
const uint32 MinBufferFill
 Active minimum acceptable buffer fill level in use by the local sound card.
const uint32 JitterWindow
 Active jitter window in use by the local sound card.
uint32 PacketIntervalHint
 Hint on the packet interval to be use with the local sound card.
uint32 MinBufferFillHint
 Hint on the minimum acceptable buffer fill level to be use with the local sound card.
uint32 JitterWindowHint
 Hint on the minimum acceptable buffer fill level to be use with the local sound card.
bool Denoise
 Digital signal processor denoise setting.
uint32 AutoGain
 Digital signal processor auto-gain setting.
uint32 EchoCancelTail
 Digital signal processor echo cancel tail setting.

Detailed Description

Interface for managing HFPD's audio data pump.

The SoundIo interface allows a D-Bus client to control settings related to the local sound card, routing of audio packets from AudioGateway devices, the software digital signal processor, and other audio-related functions provided by HFPD.

The HFPD process will instantiate one object that implements this interface at path /net/sf/nohands/hfpd/soundio

Member Function Documentation

net.sf.nohands.hfpd.SoundIo.SetDriver ( in string  drivername,
in string  driveropts 
)

Set the local sound card driver and options used by the SoundIo.

Parameters:
[in] drivername Name of the sound driver to use. Available drivers can be enumerated by reading the SoundIo.Drivers property.
[in] driveropts Options string for the driver. Options strings are specific to each driver, but specifying an empty options string will cause the driver to use intelligent defaults.
Note:
The sound card driver settings are persistent options that are saved to the HFPD configuration file.

On success, drivername will be assigned to the SoundIo.DriverName property, and driveropts to the SoundIo.DriverOpts property.

net.sf.nohands.hfpd.SoundIo.ProbeDevices ( in string  drivername,
out string  found_devices[2][] 
)

Probe for local sound card devices available from a specific driver.

This method actively searches for available sound card device names, and returns the list. For most drivers, one of the return values of this method can be supplied as the driveropts parameter to SetDriver().

Parameters:
[in] drivername Name of audio driver to probe. Available drivers can be enumerated by reading the SoundIo.Drivers property.
[out] found_devices Array of string pairs describing the result of the device probe. This field has D-Bus signature "a(ss)".
  • The first subscript of each array element is the name of the device as specifiable to SetDriver(), e.g. "/dev/dsp"
  • The second subscript of each array element is a human-readable description of the device, if available, e.g. "Intel HD Audio"
Exceptions:
net.sf.nohands.hfpd.Error Thrown on any sort of error, unspecific of the reason of failure.

net.sf.nohands.hfpd.SoundIo.Stop (  ) 

Stop any in-progress audio streaming through the local sound card.

This method will cause an active audio stream to be halted, regardless of the configured endpoint. If streaming is not in progress, this method succeeds and takes no action.

If the configured endpoint is an AudioGateway, the audio connection to the device will be closed.

net.sf.nohands.hfpd.SoundIo.AudioGatewayStart ( in objectpath  audio_gateway,
in bool  initiate_connection 
)

Start an audio stream with an AudioGateway device.

This method attempts to start a full duplex audio stream with an AudioGateway device.

If an audio connection to the device is already open, streaming will start immediately. If the audio connection is not open, and the initiate_connection parameter is true, an attempt will be made to initiate the connection, and if successful, streaming will be started.

If the local sound card is already streaming, or preparing to stream with a different audio gateway device, the operation will be aborted similar to Stop().

Parameters:
[in] audio_gateway Object path of audio gateway device on which to start streaming.
[in] initiate_connection Set to true to allow an audio connection to the device to be initiated if needed, false to only use an existing audio connection to the device.
Exceptions:
net.sf.nohands.hfpd.Error Thrown on any sort of error, unspecific of the reason of failure.
Audio gateway devices will typically perform all of the audio connection initiation themselves, and D-Bus clients should not need to direct HFPD to initiate audio connections. D-Bus clients can be informed of remotely-initiated audio connections by the AudioGateway.AudioStateChanged() signal, and should typically invoke this method (AudioGatewayStart) on reception of that signal.

net.sf.nohands.hfpd.SoundIo.FileStart ( in string  file_path,
in bool  write 
)

Start a WAV file audio stream.

Opens a .WAV file and initiates unidirectional streaming either from the file to the primary sound card or from the primary sound card to the file.

This mode of streaming is useful for playing a ring tone, or for recording a voice note.

Parameters:
[in] file_path Path to WAV file to be created and streamed to, or existing WAV file to be played back.
[in] write Set to true to cause the file to be streamed into and created if necessary, false to play back from the file.
If the local sound card is already streaming, or preparing to stream with an audio gateway, the operation in progress will be aborted similar to Stop().

Exceptions:
net.sf.nohands.hfpd.Error Thrown on any sort of error, unspecific of the reason of failure.
Note:
A stream started using this method is bound to the D-Bus client that made the method call. If that D-Bus client is disconnected from D-Bus before the stream is halted, the stream will be automatically halted, to clean up after the D-Bus client.

net.sf.nohands.hfpd.SoundIo.LoopbackStart (  ) 

Start a loopback audio stream.

Starts streaming the input from the local sound card to the output to the local sound card.

This mode of streaming is useful for testing the local sound card configuration and to subjectively evaluate the latency resulting from the buffering settings.

If the local sound card is already streaming, or preparing to stream with a different audio gateway device, the operation will be aborted similar to Stop().

Exceptions:
net.sf.nohands.hfpd.Error Thrown on any sort of error, unspecific of the reason of failure.
Note:
A stream started using this method is bound to the D-Bus client that made the method call. If that D-Bus client is disconnected from D-Bus before the stream is halted, the stream will be automatically halted, to clean up after the D-Bus client.

net.sf.nohands.hfpd.SoundIo.MembufStart ( in bool  capture,
in bool  playback,
in uint32  membuf_size,
in uint32  report_interval 
)

Start streaming to and/or from a memory buffer.

A memory buffer object can be used to store small durations of audio data captured from the local sound card, and to conveniently play it back. Specifically, the memory buffer is useful for testing digital signal processing settings by simulating a two-way conversation without initiating a phone call.

If the local sound card is already streaming, or preparing to stream with a different audio gateway device, the operation will be aborted similar to Stop().

Parameters:
[in] capture Set to true to capture audio data from the local sound card into the memory buffer. If true, an existing capture buffer will be shifted to the playback buffer position.
[in] playback Set to true to play back from the playback buffer. If no playback buffer exists, nothing will be played back.
[in] membuf_size Size of the memory buffer, in 8KHz samples. For example, to get enough space to record up to 10 seconds, this value should be 80000.
[in] report_interval Number of samples to wait between sending MonitorNotify() signals while streaming. Set to zero to disable MonitorNotify() reporting. Setting this value too small may overload the D-Bus daemon process.
Exceptions:
net.sf.nohands.hfpd.Error Thrown on any sort of error, unspecific of the reason of failure.
Note:
A stream started using this method is bound to the D-Bus client that made the method call. If that D-Bus client is disconnected from D-Bus before the stream is halted, the stream will be automatically halted, to clean up after the D-Bus client.

net.sf.nohands.hfpd.SoundIo.MembufClear (  ) 

Drop the contents of an existing memory buffer.

HFPD retains the contents of its memory buffer. This method can be used to reset the contents of the existing memory buffer in preparation for a new test, or out of general concern for resource allocations within HFPD.

net.sf.nohands.hfpd.SoundIo.SetSnoopFile ( in string  filename,
in bool  capture,
in bool  playback 
)

Configure a WAV file to receive audio pump traffic.

The HFPD audio handling components support snooping the stream traffic to a WAV file. This can be used to create voice notes and recordings of telephony sessions. Each time the stream is started, if a snoop file is configured, it is created, or truncated if it already exists, and filled with stream data as it is received.

The snoop file can be configured to receive audio data from one or both directions of the stream. If configured to receive both directions, the audio data will be mixed before being saved to the target file.

Parameters:
[in] filename Path and name of snoop file. If this value is zero-length, snooping is disabled.
[in] capture If true, data captured from the local sound card will be snooped.
[in] playback If true, data played through the local sound card will be snooped.
Note:
If the contents of the snoop file are to be preserved, the snoop file should be deconfigured after streaming has been stopped to avoid having the file overwritten the next time streaming is started.

Check local laws before creating recordings of telephone calls.

See also:
SoundIo.SnoopFileName

signal net.sf.nohands.hfpd.SoundIo.StateChanged ( out byte  state  ) 

Notification of change of state of the SoundIo.

This signal apprises D-Bus clients of the state of the SoundIo object.

Parameters:
[out] state Value of the state, which can also be read from the SoundIo.State property. See the documentation for that property for more information on the meaning of the state values.
A state change to the Stopped state may also be indicated by the StreamAborted() signal, which also includes information about the failure that caused the asynchronous abort.

signal net.sf.nohands.hfpd.SoundIo.StreamAborted ( out string  error_name,
out string  description 
)

Notification of asynchronous stream abort of the SoundIo.

This signal apprises D-Bus clients that a SoundIo object that was streaming has transitioned to the Stopped state due to a failure that occurred asynchronously.

Other changes to SoundIo.State, including transitions to the Stopped state not caused by asynchronous failures, are indicated by the StateChanged() signal.

Parameters:
[out] error_name Name of the D-Bus exception equivalent to the cause of the asynchronous failure.
[out] description Explanation of the failure.

signal net.sf.nohands.hfpd.SoundIo.MuteChanged ( out bool  mute  ) 

Notification of change of the mute state of the SoundIo.

This signal apprises D-Bus clients of the mute state of the SoundIo object.

Parameters:
[out] mute Set to true if mute is enabled, false otherwise. This value can also be queried and controlled using the SoundIo.Mute property.

signal net.sf.nohands.hfpd.SoundIo.AudioGatewaySet ( out objectpath  audio_gateway  ) 

Notification of an audio gateway being selected.

This signal apprises D-Bus clients of an audio gateway device that has been recently configured as a streaming endpoint. The audio gateway can be considered to have been deconfigured from the SoundIo when the state of the SoundIo changes back to stopped or deconfigured.

This signal will precede a StateChanged() signal, in cases when the state is changing to Audio Gateway configured or Audio Gateway connected. For more information on states, see SoundIo.State.

Parameters:
[out] audio_gateway D-Bus path to the AudioGateway object that has been configured as the streaming endpoint. This value can also be accessed through the SoundIo.AudioGateway property.

signal net.sf.nohands.hfpd.SoundIo.SkewNotify ( out byte  skew_type,
out double  skew_value 
)

Notification of audio clock skew.

When the SoundIo object is streaming, it is possible that the different directions of an endpoint, or that the two attached endpoints, have a slight difference of sample clocks. This has a negative effect on audio quality, and it is useful to make this type of problem clearly apparent to the user.

Parameters:
[out] skew_type Type of skew detected. Values are described below.
[out] skew_value Detail of the skew.
  • skew_type = 1: Number of buffer overrun/underrun events that occurred in the last second.
  • skew_type = 2: Value describes a sample rate difference between the playback and capture halves of the primary sound card. If the value is positive, the capture clock is faster than the playback clock, and vice-versa if the value is negative. The magnitude of the value is the percentage difference of the slower clock relative to the faster clock.
  • skew_type = 3: Value describes a sample rate difference between the playback and capture halves of the attached endpoint, e.g. the audio gateway. The value has the same interpretation as with skew_type = 2.
  • skew_type = 4: Value describes an overall sample rate difference between the primary sound card and the attached endpoint. If the value is positive, the clock of the attached endpoint is faster than the primary sound card, and vice-versa if negative. The magnitude of the value is the percentage difference of the slower clock relative to the faster clock.

signal net.sf.nohands.hfpd.SoundIo.MonitorNotify ( out uint32  position,
out uint16  max_amplitude 
)

Notification of audio stream progress.

This signal is emitted when a memory buffer endpoint is configured, and the report_interval parameter is nonzero. Each report_interval number of samples, this signal will be emitted.

Parameters:
[out] position Number of samples processed since the stream was started.
[out] max_amplitude Largest observed amplitude in the captured audio stream since the last monitor notification signal was emitted. This value can be used to provide visual feedback for captured audio.

Member Data Documentation

const byte net.sf.nohands.hfpd.SoundIo.State

State of the SoundIo object.

This property can be accessed using the standard D-Bus property interface.

This property describes the state of the SoundIo object, including whether the local sound card is available, and if so, what type of secondary endpoint is configured, if any. Values include:

The state cannot be modified directly. Instead use the methods Stop(), AudioGatewayStart(), FileStart(), LoopbackStart(), and MembufStart().

bool net.sf.nohands.hfpd.SoundIo.Mute

Mute state of the SoundIo object.

This property can be accessed using the standard D-Bus property interface.

This property controls the software mute feature of the SoundIo object. When set to true, audio data captured from the local sound card is replaced with silence.

Changing this property will cause a notification to be sent to all interested D-Bus clients through the MuteChanged() signal.

const variant net.sf.nohands.hfpd.SoundIo.AudioGateway

Configured audio gateway endpoint.

This property can be accessed using the standard D-Bus property interface.

The D-Bus type of this property is a variant, and its real type depends on the state of the SoundIo object.

If the SoundIo object has an audio gateway object configured as its endpoint, either actively streaming or awaiting a connection, this property can be used to retrieve the object path of the AudioGateway. In this case, its real type is a D-Bus object path.

If the SoundIo object is stopped, or streaming with another type of endpoint, this property will contain the boolean value false.

This property cannot be modified directly. Instead use AudioGatewayStart() or Stop().

const string net.sf.nohands.hfpd.SoundIo.SnoopFileName

Target file for stream snooper.

See SetSnoopFile().

const string net.sf.nohands.hfpd.SoundIo.Drivers[2][]

List of available local sound card drivers.

This property can be accessed using the standard D-Bus property interface.

This property allows a D-Bus client to interrogate the sound card driver back-ends that are available to HFPD. Typical values include ALSA and OSS.

const string net.sf.nohands.hfpd.SoundIo.DriverName

Name of active local sound card driver.

This property can be accessed using the standard D-Bus property interface.

This property contains the name of the active local sound card driver back-end.

To set this value, use SetDriver().

const string net.sf.nohands.hfpd.SoundIo.DriverOpts

Options provided to active local sound card driver.

This property can be accessed using the standard D-Bus property interface.

This property contains the options provided to the active local sound card driver back-end.

To set this value, use SetDriver().

const uint32 net.sf.nohands.hfpd.SoundIo.PacketInterval

Active sample packet interval in use by the local sound card.

This property can be accessed using the standard D-Bus property interface.

When the local sound card is streaming, this property can be used to retrieve the packet interval used by the local sound card, in milliseconds. The packet interval is the interval between hardware interrupts, or the closest equivalent depending on the resampling and mixing operations that are being carried out.

D-Bus clients cannot force a specific packet interval, but can provide a hint through the SoundIo.PacketIntervalHint property.

When the local sound card is not streaming, the value is meaningless and returned as zero.

const uint32 net.sf.nohands.hfpd.SoundIo.MinBufferFill

Active minimum acceptable buffer fill level in use by the local sound card.

This property can be accessed using the standard D-Bus property interface.

When the local sound card is streaming, this property can be used to retrieve the chosen minimum buffer fill level of the local sound card, in milliseconds.

D-Bus clients cannot force a specific minimum buffer fill level, but can provide a hint through the SoundIo.MinBufferFillHint property.

When the local sound card is not streaming, the value is meaningless and returned as zero.

const uint32 net.sf.nohands.hfpd.SoundIo.JitterWindow

Active jitter window in use by the local sound card.

This property can be accessed using the standard D-Bus property interface.

When the local sound card is streaming, this property can be used to retrieve the chosen jitter window of the local sound card, in milliseconds.

D-Bus clients cannot force a specific jitter window, but can provide a hint through the SoundIo.JitterWindowHint property.

When the local sound card is not streaming, the value is meaningless and returned as zero.

uint32 net.sf.nohands.hfpd.SoundIo.PacketIntervalHint

Hint on the packet interval to be use with the local sound card.

This property can be accessed using the standard D-Bus property interface.

This property provides the client some level of control over the packet size of the primary endpoint, i.e. the interrupt period length. This value has two consequences:

The local sound card driver is the ultimate consumer of this value, and it is free to reject it or round it as required.

The value is specified in milliseconds. Setting it to zero will cause the default packet interval selection logic to be used.

Note:
The packet interval hint is a persistent option that is saved to the HFPD configuration file.

uint32 net.sf.nohands.hfpd.SoundIo.MinBufferFillHint

Hint on the minimum acceptable buffer fill level to be use with the local sound card.

This property can be accessed using the standard D-Bus property interface.

This property provides the client some level of control over the minimum acceptable output buffer fill level. Choices of minimum output buffer fill level can have two consequences:

Some situations will cause a client-provided value to be ignored:

The value is specified in milliseconds. Setting it to zero will cause default minimum buffer fill level logic to be used to determine its value.

Note:
The minimum acceptable buffer fill level hint is a persistent option that is saved to the HFPD configuration file.

uint32 net.sf.nohands.hfpd.SoundIo.JitterWindowHint

Hint on the minimum acceptable buffer fill level to be use with the local sound card.

This property can be accessed using the standard D-Bus property interface.

The property provides the client some level of control over the output window size, i.e. the limit of the fill level of output buffers above and beyond the minimum. This value has two consequences:

Some situations will cause a client-provided value to be ignored:

The value is specified in milliseconds. Setting it to zero will cause the default jitter window size selection logic to be used.

Note:
The jitter window hint is a persistent option that is saved to the HFPD configuration file.

bool net.sf.nohands.hfpd.SoundIo.Denoise

Digital signal processor denoise setting.

This property can be accessed using the standard D-Bus property interface.

This option controls whether the denoise feature of the Speex software digital signal processor is used. The denoise feature can eliminate background noise and improve the focus on the voice of the speaker.

Note:
The denoise setting is a persistent option that is saved to the HFPD configuration file.

uint32 net.sf.nohands.hfpd.SoundIo.AutoGain

Digital signal processor auto-gain setting.

This property can be accessed using the standard D-Bus property interface.

This option controls whether the auto-gain feature of the Speex software digital signal processor is used. The auto-gain feature causes the volume level of the captured audio to be analyzed, and if it is too low, to have a gain applied to it automatically.

Reasonable values for this property might be:

Note:
The auto-gain setting is a persistent option that is saved to the HFPD configuration file.

uint32 net.sf.nohands.hfpd.SoundIo.EchoCancelTail

Digital signal processor echo cancel tail setting.

This property can be accessed using the standard D-Bus property interface.

This option controls whether the echo canceler of the Speex software digital signal processor is used. Specifically, it sets the length of the sample period, in milliseconds, to be evaluated for acoustic echo.

Reasonable values for this property might be:

Note:
The echo cancel tail setting is a persistent option that is saved to the HFPD configuration file.

Generated on Fri Jan 9 05:57:31 2009 for HFPD by  doxygen 1.5.4