BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJMEDIA Reference

Multi-frequency tone generator

Multi-frequency tone generator. More...

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)
 

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.

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
poolPool to allocate memory for the port structure.
clock_rateSampling rate.
channel_countNumber of channels. Currently only mono and stereo are supported.
samples_per_frameNumber of samples per frame.
bits_per_sampleNumber of bits per sample. This version of PJMEDIA only supports 16bit per sample.
optionsOption flags. Application may specify PJMEDIA_TONEGEN_LOOP to play the tone in a loop.
p_portPointer 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
poolPool to allocate memory for the port structure.
nameOptional name for the tone generator.
clock_rateSampling rate.
channel_countNumber of channels. Currently only mono and stereo are supported.
samples_per_frameNumber of samples per frame.
bits_per_sampleNumber of bits per sample. This version of PJMEDIA only supports 16bit per sample.
optionsOption flags. Application may specify PJMEDIA_TONEGEN_LOOP to play the tone in a loop.
p_portPointer 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
tonegenThe 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
tonegenThe 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
tonegenThe 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
tonegenThe tone generator instance.
countThe number of tones in the array.
tonesArray of tones to be played.
optionsOption 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
tonegenThe tone generator instance.
countNumber of digits in the array.
digitsArray of MF digits.
optionsOption 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
tonegenThe tone generator instance.
mOn 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
tonegenThe tone generator instance.
mDigitmap to be used by the tone generator.
Returns
PJ_SUCCESS on success.

 


PJMEDIA small footprint Open Source media stack
Copyright (C) 2006-2008 Teluu Inc.