The following functions are provided by the Prosody signal path processing API:
| API call | W | Description |
|---|---|---|
| sm_path_agc() | Configure a signal path to perform automatic gain control | |
| sm_path_agc_adjust_settings() | Adjust AGC settings. | |
| sm_path_avf_amrnb_dec() | P | Configure a signal path to decode AVF encapsulated AMR-NB encoded data to linear audio |
| sm_path_avf_amrnb_enc() | P | Configure a signal path to encode linear audio to AVF encapsulated AMR-NB encoded data |
| sm_path_create() | Create a signal path | |
| sm_path_datafeed_connect() | Connect a datafeed to a signal path | |
| sm_path_delay() | Configure a signal path to apply a delay to signal | |
| sm_path_destroy() | Destroy a previously allocated signal path | |
| sm_path_echocancel() | Configure a signal path to perform echo cancellation | |
| sm_path_emphasis() | Configure a signal path to apply a filter to emphasise or deemphasise high frequencies | |
| sm_path_get_datafeed() | Obtain a datafeed from a signal path | |
| sm_path_get_event() | Obtain an event for a path | |
| sm_path_mix() | Configure a signal path to add in another signal | |
| sm_path_pitchshift() | Configure a signal path to perform pitch shifting | |
| sm_path_resample() | Configure a signal path to convert signal to a different sampling rate | |
| sm_path_status() | Determine path status | |
| sm_path_stop() | Instructs a path to stop all processing | |
| sm_path_tonedetect() | Configure a signal path to detect and optionally eliminate tones | |
| sm_path_ttyeliminate() | Configure a signal path to eliminate TTY signals |
Key to W column:
| P | Preliminary documentation - this functionality is under development. It could be changed or withdrawn, and may not be implemented in this release |
|---|
This document is also available as separate pages for each function.
int sm_path_agc(struct sm_path_agc_parms *agcp)
typedef struct sm_path_agc_parms {
tSMPathId path; /* in */
tSM_INT agc; /* in */
tSM_INT volume; /* in */
} SM_PATH_AGC_PARMS;
Configures automatic gain control and fixed volume adjustment on a signal path. The agc parameter controls whether or not automatic gain control is applied to the signal. If agc is non-zero then automatic gain control is applied. The volume adjustment specified is performed after the AGC and has a range of at least -24 to +8 dB. Volume adjustment is always applied, even if AGC is disabled.
Requires the module gainbg.
0 if call completed successfully, otherwise a standard error such as:
int sm_path_agc_adjust_settings(struct sm_path_agc_adjust_settings_parms *agcadjp)
typedef struct sm_path_agc_adjust_settings_parms {
tSMPathId path; /* in */
float max_level_decay; /* in */
float target_level; /* in */
} SM_PATH_AGC_ADJUST_SETTINGS_PARMS;
0 if call completed successfully, otherwise a standard error such as:
This function is under development. It could be changed or withdrawn, and may not be implemented in this release.
int sm_path_avf_amrnb_dec(struct sm_path_avf_amrnb_dec_parms *amrnbdecparms)
typedef struct sm_path_avf_amrnb_dec_parms {
tSMPathId path; /* in */
tSM_INT enable; /* in */
} SM_PATH_AVF_AMRNB_DEC_PARMS;
Configures AVF encapsulated AMR-NB decoding on a signal path.
0 if call completed successfully, otherwise a standard error.
This function is under development. It could be changed or withdrawn, and may not be implemented in this release.
int sm_path_avf_amrnb_enc(struct sm_path_avf_amrnb_enc_parms *amrnbencparms)
typedef struct sm_path_avf_amrnb_enc_parms {
tSMPathId path; /* in */
tSM_INT enable; /* in */
tSM_INT payload_type; /* in */
tSM_INT bitrate; /* in */
tSM_INT vad_enable; /* in */
} SM_PATH_AVF_AMRNB_ENC_PARMS;
Configures AVF encapsulated AMR-NB encoding on a signal path. Requires the module amr-nb-prs or amr-nb-all.
0 if call completed successfully, otherwise a standard error.
int sm_path_create(struct sm_path_create_parms *createp)
typedef struct sm_path_create_parms {
tSMPathId path; /* out */
tSMModuleId module; /* in */
} SM_PATH_CREATE_PARMS;
Creates a signal path. A signal path permits a variety of transformations to be performed on a signal. If no transformations are enabled, a path acts as a pass through.
The modules inchan and passthru are required.
0 if call completed successfully, otherwise a standard error such as:
int sm_path_datafeed_connect(struct sm_path_datafeed_connect_parms *datafeedp)
typedef struct sm_path_datafeed_connect_parms {
tSMPathId path; /* in */
tSMDatafeedId data_source; /* in */
} SM_PATH_DATAFEED_CONNECT_PARMS;
Connects a datafeed to a signal path. The
data_source
must be a datafeed obtained from
sm_channel_get_datafeed(),
sm_tdmrx_get_datafeed()
sm_vmprx_get_datafeed()
or
sm_path_get_datafeed().
Datafeed connections can only be made between objects allocated
on the same tSMModuleId.
The signal path
path
will receive any data that is generated by the output task from which
data_source
was derived.
To disconnect a signal path from a datafeed, specify
kSMNullDatafeedId as the tSMDatafeedId in
data_source
Requires the module datafeed to have been downloaded.
0 if call completed successfully, otherwise a standard error.
int sm_path_delay(struct sm_path_delay_parms *delayparms)
typedef struct sm_path_delay_parms {
tSMPathId path; /* in */
tSM_INT enable; /* in */
tSM_INT delay; /* in */
} SM_PATH_DELAY_PARMS;
Delays signal by specified number of samples. If signal path already has a delay configured, the delay is changed to new value. A new or increased delay has gap filled with silence.
Requires the module delay to be loaded.
0 if call completed successfully, otherwise a standard error.
int sm_path_destroy(tSMPathId path)
Destroys path and invalidates the tSMPathId.
0 if call completed successfully, otherwise a standard error such as:
int sm_path_echocancel(struct sm_path_echocancel_parms *cancelp)
typedef struct sm_path_echocancel_parms {
tSMPathId path; /* in */
tSM_INT enable; /* in */
tSMDatafeedId reference; /* in */
tSM_INT non_linear; /* in */
enum kSMPathEchoNonLinearMode {
kSMPathEchoNonLinearModeMuting,
kSMPathEchoNonLinearModeCNG,
} mode; /* in */
tSM_INT use_agc; /* in */
tSM_INT fix_agc; /* in */
tSM_INT span; /* in */
tSM_INT delay; /* in */
enum kSMPathEchoToneAction {
kSMPathEchoToneActionNone,
kSMPathEchoTonetActionMuteTTY,
} tone_action; /* in */
} SM_PATH_ECHOCANCEL_PARMS;
Configures echo cancellation on a signal path. The input is examined for an echo of the reference signal, and any echo found is suppressed.
Non-linear echo cancellation can operate in two modes. The default is non-linear echo cancellation with muting, which is suitable for large-scale conferencing and/or IVR applications, where it is important that the signal is completely muted whenever the caller is not speaking.
Non-linear echo cancellation with comfort noise generation (CNG) never mutes the signal. Instead it replaces any residual traces of echo with "comfort noise". This mode of operation is most appropriate to IP gateway applications where background noise is desirable to maintain the illusion of continuity.
If tone_action is set to mute TTY, the echo cancellation algorithm will expect to encounter TTY tones on its primary input and its reference. Its output will be muted whenever such tones are present on its reference and for a short time afterwards (thus muting echoes of tones). It will pass though TTY tones present on its primary input at other times. This behaviour should only be enabled if TTY tones are expected in the signal path. It would normally be used with non-linear mode disabled.
Requires the module echocan.
0 if call completed successfully, otherwise a standard error.
int sm_path_emphasis(struct sm_path_emphasis_parms *emphparms)
typedef struct sm_path_emphasis_parms {
tSMPathId path; /* in */
tSM_INT enable; /* in */
enum kSMPathEmphMode {
kSMPathEmphModeHFEmphasis,
kSMPathEmphModeHFDeemphasis,
} mode; /* in */
tSM_INT gain; /* in */
} SM_PATH_EMPHASIS_PARMS;
Configures a high-frequency emphasis/de-emphasis filter. In emphasis mode, response curve is approximately -3dB at 0Hz rising to 0dB at 300Hz and 20dB at 3330Hz. In de-emphasis mode, the inverse filter is applied: 3dB at 0Hz falling to 0dB at 300Hz and -20dB at 3330Hz. Disabling the filter also disables the gain. Note that the frequencies quoted are proportional to the input signal sample rate and those given are for an input signal sample rate of 8000 samples per second.
Requires the module emph to be loaded.
0 if call completed successfully, otherwise a standard error.
int sm_path_get_datafeed(struct sm_path_datafeed_parms *datafeedp)
typedef struct sm_path_datafeed_parms {
tSMPathId path; /* in */
tSMDatafeedId datafeed; /* out */
} SM_PATH_DATAFEED_PARMS;
Request a datafeed identifier from a signal path. This identifer
can subsequently be used in a call to
sm_channel_datafeed_connect(),
sm_tdmtx_datafeed_connect()
or
sm_vmptx_datafeed_connect()
to connect the result of the signal path procesing to a speech
channel (tSMChannelId), TDM[tx], or a VMP[tx]
respectively. It is valid until the path is destroyed.
Datafeed connections can only be made between objects allocated
on the same tSMModuleId.
Requires the module datafeed to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_path_get_event(struct sm_path_event_parms *eventp)
typedef struct sm_path_event_parms {
tSMPathId path; /* in */
tSMEventId event; /* out */
} SM_PATH_EVENT_PARMS;
If the call completes successfully event will hold the tSMEventId belonging to path. The tSMEventId is valid until the path is destroyed using sm_path_destroy(). This event will be signalled when a status change occurs on the path. When the event is signalled the user must call sm_path_status() to discover the nature of the status change.
0 if call completed successfully, otherwise a standard error such as:
int sm_path_mix(struct sm_path_mix_parms *mixp)
typedef struct sm_path_mix_parms {
tSMPathId path; /* in */
tSM_INT enable; /* in */
tSMDatafeedId mixin; /* in */
tSM_INT volume; /* in */
} SM_PATH_MIX_PARMS;
Configures signal mixing on a signal path. The specified signal is added into the signal being processed by this path, and the result is adjusted according to the volume parameter, which has a range of at least -24 to +8 dB. Typically, the signal is adjusted by -6 dB to prevent the sum of the two signals being louder than each original signal.
Requires the module gainbg.
0 if call completed successfully, otherwise a standard error.
int sm_path_pitchshift(struct sm_path_pitchshift_parms *pitchshiftp)
typedef struct sm_path_pitchshift_parms {
tSMPathId path; /* in */
float shift; /* in */
} SM_PATH_PITCHSHIFT_PARMS;
Configures pitch shifting on a signal path.
Requires the module pitchshift.
-0.08333 configures a shift down one semitone),
values greater than zero cause an upward shift, and the value
zero disables pitch shifting.
0 if call completed successfully, otherwise a standard error such as:
int sm_path_resample(struct sm_path_resample_parms *resamplep)
typedef struct sm_path_resample_parms {
tSMPathId path; /* in */
tSM_INT uprate; /* in */
tSM_INT downrate; /* in */
} SM_PATH_RESAMPLE_PARMS;
Configures sample rate conversion on a signal path. If uprate and downrate are equal, sample rate conversion is disabled. Otherwise the signal is converted to a sampling rate of uprate / downrate times the original sampling rate. For example, if uprate is two, and downrate is one, the sampling rate is doubled. To produce the best audio quality, and to use the least processor time, uprate should always be kept as small as possible. For example, uprate = 2, with downrate = 3, would decrease the sampling rate to two-thirds of the original value, but so would uprate = 4, with downrate = 6. Both the audio quality and the CPU loading will be noticeably better with uprate = 2, than with uprate = 4.
Requires the module resample.
0 if call completed successfully, otherwise a standard error.
int sm_path_status(struct sm_path_status_parms *statusp)
typedef struct sm_path_status_parms {
tSMPathId path; /* in */
enum kSMPathStatus {
kSMPathStatusRunning,
kSMPathStatusOngoingTone,
kSMPathStatusEndTone,
kSMPathStatusStopped,
} status; /* out */
union {
struct {
tSM_INT id; /* out */
unsigned duration; /* out */
} tone; /* out */
} u; /* out */
} SM_PATH_STATUS_PARMS;
Returns the current status of the path or an error to indicate that a problem occurred.
When the event, obtained from sm_path_get_event(), is signalled the user must call this function to determine the nature of the status change. The change in status may indicate that an error occurred whilst processing a user request or it may be notifiying the user of a change to the previous state of the path.
0 if call completed successfully, otherwise a standard error such as:
int sm_path_stop(struct sm_path_stop_parms *stopp)
typedef struct sm_path_stop_parms {
tSMPathId path; /* in */
} SM_PATH_STOP_PARMS;
Requests that a path stops executing. The user will be notified that a path has terminated by a final status, kSMPAthStatusStopped, from sm_path_status(). Once the stopped status notification has been received the path can be destroyed using sm_path_destroy().
Once the path has stopped the event should no longer be used to wait for status notifications as it will be signalled permanently. The event is invalidated when sm_path_destroy() is called.
0 if call completed successfully, otherwise a standard error such as:
int sm_path_tonedetect(struct sm_path_tonedetect_parms *tdparms)
typedef struct sm_path_tonedetect_parms {
tSMPathId path; /* in */
tSM_INT elim; /* in */
enum kSMPathToneDetectMode {
kSMPathToneDetectModeNone,
kSMPathToneDetectModeMinDurationNoMinimum,
kSMPathToneDetectModeMinDuration40,
kSMPathToneDetectModeMinDuration64,
} min_duration; /* in */
tSM_INT tone_set_id; /* in */
} SM_PATH_TONEDETECT_PARMS;
Configures a tone detector on signal path. Detected tones are reported through sm_path_status(). Tones that are detected may optionally be eliminated. When eliminating tones, the signal is delayed by small amount so entire tone can be eliminated.
Requires the module td to be loaded.
0 if call completed successfully, otherwise a standard error.
int sm_path_ttyeliminate(struct sm_path_ttyeliminate_parms *ttyeliminatep)
typedef struct sm_path_ttyeliminate_parms {
tSMPathId path; /* in */
tSM_INT enable; /* in */
} SM_PATH_TTYELIMINATE_PARMS;
Configures TTY elimination on a signal path.
Requires the module ttyasyrx.
0 if call completed successfully, otherwise a standard error such as:
These functions constitute the Prosody signal path processing API.