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:

PJMEDIA_TONEGEN_LOOP = 1

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

PJMEDIA_TONEGEN_NO_LOCK = 2

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

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.

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

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.

pj_bool_t pjmedia_tonegen_is_busy(pjmedia_port *tonegen)

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

Return

Non-zero if busy.

Parameters
  • tonegen: The tone generator instance.

pj_status_t pjmedia_tonegen_stop(pjmedia_port *tonegen)

Instruct the tone generator to stop current processing.

Return

PJ_SUCCESS on success.

Parameters
  • tonegen: The tone generator instance.

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.

Return

PJ_SUCCESS on success.

Parameters
  • tonegen: The tone generator instance.

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.

Return

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

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.

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.

Return

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.

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.

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.

Return

PJ_SUCCESS on success.

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.

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.

Return

PJ_SUCCESS on success.

Parameters
  • tonegen: The tone generator instance.

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

struct pjmedia_tone_desc
#include <tonegen.h>

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

struct pjmedia_tone_digit
#include <tonegen.h>

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

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().