Group PJMEDIA_MF_DTMF_TONE_GENERATOR

group PJMEDIA_MF_DTMF_TONE_GENERATOR

Multi-frequency tone generator.

This page describes tone generator media port. A tone generator can be used to generate a single frequency sine wave or dual frequency tones such as DTMF.

The tone generator media port provides two functions to generate tones. The function pjmedia_tonegen_play() can be used to generate arbitrary single or dual frequency tone, and pjmedia_tonegen_play_digits() is used to play digits such as DTMF. Each tone specified in the playback function has individual on and off signal duration that must be specified by application.

In order to play digits such as DTMF, the tone generator is equipped with digit map, which contain information about the frequencies of the digits. The default digit map is DTMF (0-9,a-d,*,#), but application may specifiy different digit map to the tone generator by calling pjmedia_tonegen_set_digit_map() function.

Enums

enum [anonymous]

Tone generator options.

Values:

enumerator PJMEDIA_TONEGEN_LOOP

Play the tones in loop, restarting playing the first tone after the last tone has been played.

enumerator PJMEDIA_TONEGEN_NO_LOCK

Disable mutex protection to the tone generator.

Functions

pj_status_t pjmedia_tonegen_create(pj_pool_t *pool, unsigned clock_rate, unsigned channel_count, unsigned samples_per_frame, unsigned bits_per_sample, unsigned options, pjmedia_port **p_port)

Create an instance of tone generator with the specified parameters. When the tone generator is first created, it will be loaded with the default digit map.

Parameters:

  • pool – Pool to allocate memory for the port structure.

  • clock_rate – Sampling rate.

  • channel_count – Number of channels. Currently only mono and stereo are supported.

  • samples_per_frame – Number of samples per frame.

  • bits_per_sample – Number of bits per sample. This version of PJMEDIA only supports 16bit per sample.

  • options – Option flags. Application may specify PJMEDIA_TONEGEN_LOOP to play the tone in a loop.

  • p_port – Pointer to receive the port instance.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjmedia_tonegen_create2(pj_pool_t *pool, const pj_str_t *name, unsigned clock_rate, unsigned channel_count, unsigned samples_per_frame, unsigned bits_per_sample, unsigned options, pjmedia_port **p_port)

Create an instance of tone generator with the specified parameters. When the tone generator is first created, it will be loaded with the default digit map.

Parameters:

  • pool – Pool to allocate memory for the port structure.

  • name – Optional name for the tone generator.

  • clock_rate – Sampling rate.

  • channel_count – Number of channels. Currently only mono and stereo are supported.

  • samples_per_frame – Number of samples per frame.

  • bits_per_sample – Number of bits per sample. This version of PJMEDIA only supports 16bit per sample.

  • options – Option flags. Application may specify PJMEDIA_TONEGEN_LOOP to play the tone in a loop.

  • p_port – Pointer to receive the port instance.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_bool_t pjmedia_tonegen_is_busy(pjmedia_port *tonegen)

Check if the tone generator is still busy producing some tones.

Parameters:

tonegen – The tone generator instance.

Returns:

Non-zero if busy.

pj_status_t pjmedia_tonegen_stop(pjmedia_port *tonegen)

Instruct the tone generator to stop current processing.

Parameters:

tonegen – The tone generator instance.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_tonegen_stop_loop(pjmedia_port *tonegen)

Instruct the tone generator to stop looping of the current tone set.

Parameters:

tonegen – The tone generator instance.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_tonegen_rewind(pjmedia_port *tonegen)

Rewind the playback. This will start the playback to the first tone in the playback list.

Parameters:

tonegen – The tone generator instance.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_tonegen_play(pjmedia_port *tonegen, unsigned count, const pjmedia_tone_desc tones[], unsigned options)

Instruct the tone generator to play single or dual frequency tones with the specified duration. The new tones will be appended to currently playing tones, unless pjmedia_tonegen_stop() is called before calling this function. The playback will begin as soon as the first get_frame() is called to the generator.

Parameters:

  • tonegen – The tone generator instance.

  • count – The number of tones in the array.

  • tones – Array of tones to be played.

  • options – Option flags. Application may specify PJMEDIA_TONEGEN_LOOP to play the tone in a loop.

Returns:

PJ_SUCCESS on success, or PJ_ETOOMANY if there are too many digits in the queue.

pj_status_t pjmedia_tonegen_play_digits(pjmedia_port *tonegen, unsigned count, const pjmedia_tone_digit digits[], unsigned options)

Instruct the tone generator to play multiple MF digits with each of the digits having individual ON/OFF duration. Each of the digit in the digit array must have the corresponding descriptor in the digit map. The new tones will be appended to currently playing tones, unless pjmedia_tonegen_stop() is called before calling this function. The playback will begin as soon as the first get_frame() is called to the generator.

Parameters:

  • tonegen – The tone generator instance.

  • count – Number of digits in the array.

  • digits – Array of MF digits.

  • options – Option flags. Application may specify PJMEDIA_TONEGEN_LOOP to play the tone in a loop.

Returns:

PJ_SUCCESS on success, or PJ_ETOOMANY if there are too many digits in the queue, or PJMEDIA_RTP_EINDTMF if invalid digit is specified.

pj_status_t pjmedia_tonegen_get_digit_map(pjmedia_port *tonegen, const pjmedia_tone_digit_map **m)

Get the digit-map currently used by this tone generator.

Parameters:

  • tonegen – The tone generator instance.

  • m – On output, it will be filled with the pointer to the digitmap currently used by the tone generator.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_tonegen_set_digit_map(pjmedia_port *tonegen, pjmedia_tone_digit_map *m)

Set digit map to be used by the tone generator.

Parameters:

  • tonegen – The tone generator instance.

  • m – Digitmap to be used by the tone generator.

Returns:

PJ_SUCCESS on success.

struct pjmedia_tone_desc
#include <tonegen.h>

This structure describes individual MF digits to be played with pjmedia_tonegen_play().

Public Members

short freq1

First frequency.

short freq2

Optional second frequency.

short on_msec

Playback ON duration, in miliseconds.

short off_msec

Playback OFF duration, ini miliseconds.

short volume

Volume (1-32767), or 0 for default, which PJMEDIA_TONEGEN_VOLUME will be used.

short flags

Currently internal flags, must be 0

struct pjmedia_tone_digit
#include <tonegen.h>

This structure describes individual MF digits to be played with pjmedia_tonegen_play_digits().

Public Members

char digit

The ASCI identification for the digit.

short on_msec

Playback ON duration, in miliseconds.

short off_msec

Playback OFF duration, ini miliseconds.

short volume

Volume (1-32767), or 0 for default, which PJMEDIA_TONEGEN_VOLUME will be used.

struct pjmedia_tone_digit_map
#include <tonegen.h>

This structure describes the digit map which is used by the tone generator to produce tones from an ASCII digits. Digit map used by a particular tone generator can be retrieved/set with pjmedia_tonegen_get_digit_map() and pjmedia_tonegen_set_digit_map().

Public Members

unsigned count

Number of digits in the map.

char digit

The ASCI identification for the digit.

short freq1

First frequency.

short freq2

Optional second frequency.

struct pjmedia_tone_digit_map::[anonymous] digits[16]

Array of digits in the digit map.