Multi-frequency tone generator
[Media Ports Framework]

---

Detailed Description

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.

Data Structures
struct	pjmedia_tone_desc
struct	pjmedia_tone_digit
struct	pjmedia_tone_digit_map
Enumerations
enum	{   PJMEDIA_TONEGEN_LOOP = 1,   PJMEDIA_TONEGEN_NO_LOCK = 2 }
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)
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)
pj_bool_t	pjmedia_tonegen_is_busy (pjmedia_port *tonegen)
pj_status_t	pjmedia_tonegen_stop (pjmedia_port *tonegen)
pj_status_t	pjmedia_tonegen_rewind (pjmedia_port *tonegen)
pj_status_t	pjmedia_tonegen_play (pjmedia_port *tonegen, unsigned count, const pjmedia_tone_desc tones[], unsigned options)
pj_status_t	pjmedia_tonegen_play_digits (pjmedia_port *tonegen, unsigned count, const pjmedia_tone_digit digits[], unsigned options)
pj_status_t	pjmedia_tonegen_get_digit_map (pjmedia_port *tonegen, const pjmedia_tone_digit_map **m)
pj_status_t	pjmedia_tonegen_set_digit_map (pjmedia_port *tonegen, pjmedia_tone_digit_map *m)

---

Enumeration Type Documentation

anonymous enum

Tone generator options.

Enumerator:

PJMEDIA_TONEGEN_LOOP	Play the tones in loop, restarting playing the first tone after the last tone has been played.
PJMEDIA_TONEGEN_NO_LOCK	Disable mutex protection to the tone generator.

---

Function Documentation

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_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.