<- ...Back>   Continue... ->

Codecs

 

Codec is a frankenword (portmanteau) which describes a device or program capable of

performing transformations on a data stream or signal. Essentially, codecs can both put

the stream or signal into an encoded form (often for transmission, storage or encryption)

and retrieve, or decode that form for viewing or manipulation in a format more

appropriate for these operations. Codecs are often used in videoconferencing and

streaming media solutions.

 

[wikkipedia]

 

What this means to you and me is that codecs compress data, allow you to transmit the

compressed data which is then uncompressed at the receiving end. This should have sent

some bells ringing in your head. Yes, if I compress something with ASC (“Andy's Special

Codec”) and you don't have that installed, then you wont be able to decompress it. The

same applies for Asterisk, and all other VoIP devices.

 

 

 


Different codecs have different compression ratios resulting in

different bandwidth requirements.

 

Generally the higher the compression the more cpu power required

to compress, and sometimes decompress.

 

In most cases this means:

 

Higher compression = More CPU = Lower Bandwidth

Lower compression = Less CPU = More Bandwidth

 

So the more bandwidth you have, the less need for a higher

compression ratio.

 

 

Asterisk has wide support for codecs, on your system you can see how quickly your

particular Asterisk machine can translate from one codec to another by using the

command:

 

 

 

show translation

 

 

 

 

 

 

this will result in something like

 


 


This is a simple table, you read your from codec down the left and your to codec along

the top (actually is doesn't matter which way you do it). For example on my test

machine is takes 299 milliseconds to translate from GSM to g723 – diabolical! Try it on

your machine. Don't worry if, for example, g729 is just dashes (-) g729 is a codec you

have to pay for, it it shows dashes, you don't have it installed.

 

Bandwidth Requirements for Several Common VoIP Compression Algorithms

 

Codec

Codec Bit Rate (Kbps)

Nominal Ethernet Bandwidth (Kbps)

G.711

64

87.2

G.729

8

31.2

G.723.1

6.4

21.9

GSM

13.2

N/A

iLBC

13.3

N/A

G.723.1

5.3

20.8

G.726

32

55.2

G.726

24

47.2

G.728

16

31.5

 

oh323.org provide a spreadsheet showing more detailed information, which also allows

you to recalculate based on the packet overhead. It can be found here

http://www.terracall.com/bandwidth.xls At the end of this document you'll find at the

calculations based on an overhead of 40, just in case you have no Internet access while reading this.

 


Channels

 

Channels relate to the technology (protocol) they implement, for example the channel SIP (chan_sip.so) is used to register SIP phones, register with SIP service providers and provide the communications mechanisms for Asterisk to be able to 'talk' SIP.  Just a few pages back we talked about the Dial command and contacting a SIP device, but it doesn't stop there. Asterisk supports a number of different technologies (channel types) and can convert between them. What this means is you could have a SIP phone and an IAX2 phone connected to an Asterisk PBX and ring the SIP phone and talk away to your heart's content from the IAX2 phone and vice-versa, all automatically, without you having to do anything special.

 

 

This also means that you can do things like locate Asterisk boxes at remote locations providing virtual E1 or T1 connections.

 

Common Asterisk Channels

 

         IAX2/IAX                Asterisk's own protocol, traverses NAT easily, uses a single

                                      port for control and audio. IAX is still usable, but it is                                               recommended that only IAX2 is used, indeed IAX is by default

                                      not compiled – Stick with IAX2.

 

         SIP                        Session Initiation Protocol, and industry standard protocol

                                      becoming very popular indeed. Uses different ports for

                                      control and audio. NAT can be tricky.

 

         ZAP                       Channel for Zaptel hardware, Digium boards (FXO/FXS/PRI).

 

         Skinny                   Cisco protocol, reverse engineered by members of the Asterisk

                                      community.

 

         MGCP                    Media Gateway Control Protocol, developed by Telecordia and

                                      Level 3 Communications. Was designed to compete with H323

                                      and like H323 a bit long in the tooth. Still used in new

                                      deployments.

 

         H323                     Must be built using H323 libraries, not a solid implementation

                                      in Asterisk.

 

         OSS/ALSA              Sound card channel drivers, allow dialing from the console.

 

         BTP                       Bluetooth presence channel, automatic routing based on

                                      the presence (or absence) of a Bluetooth device such as a

                                      mobile (cell) phone.

 

 

With the exception of H323 and BTP all the above protocols are built and installed automatically during the compilation/install process.

 

 

 


When dialing using the Dial command you specify the technology you want to use for example:

 

 

Dial(IAX2/guest@an-iaxprovider.com)

 

Dial(SIP/1000)

 

Dial(ZAP/g1/${EXTEN})

 

 

In the next section we'll take a look at some of the most common commands you'll  probably use in your dialplan.

 

Common Dialplan Commands

 

Asterisk has many built in commands that you can use within the dialplan, in this section we'll cover the ones that you'll probably end up using the most, enabling you to put together complex dialplans reacting to different events. This section is not supposed to be an exhaustive list of the commands available, but is a selection of the most common commands that you will probably end up using, most of the time.

 

 

 


You can find a list of the available applications in Asterisk by using  the command

 

show application

 

(with a space after application) and then hit the tab key while at the Asterisk CLI prompt.

 

Detailed information about each application can be seen by using

 

show application <application name>

 

eg:

 

show application dial

 

while at the Asterisk CLI prompt.

Answer

Answer()

 

Answers a ringing channel, if the channel has already been answered it does nothing.

 

Return code

 

Returns 0 unless answering the channel fails in which case returns -1.

 

Example

 

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

 

Background

Background(filename[|options[|langoverride]]):

 

 

Plays a given file, while waiting for the user to enter an extension to jump to. Background is often used in simple menus such as:

 

Press 1 for sales, 2 for support ...

 

You should set the timeout using ResponseTimeout(seconds) after which the process will jump to the 't' extension – if it exists. The  timeouts do not start until the last Background application has ended.

 

Options, skip or noanswer, (optional) may also be  included following a pipe symbol.

 

The skip option causes the playback of the message to  be  skipped  if  the  channel is not in the up state (i.e. it hasn't been  answered  yet). If skip is specified, the application will return immediately should the channel not be off hook. 

 

Unless the 'noanswer' option is specified, the channel channel will be answered before the sound is played. Not all channels support playing messages while still hook.

 

The 'langoverride' (optional) may be a language to use for playing the prompt which differs from the current language of the channel

 

 

Return code

 

Returns -1 if the channel was hung up, or if the file does not exist, otherwise returns 0

 

Example

 

[my-menu]

 

exten => s,1,Answer

exten => s,2,ResponseTimeout(8)

exten => s,3,Background(menu-main-sound)

 

exten => 1,1,Dial(SIP/SalesPhone)

 

exten => 2,1,Dial(SIP/SupportPhone)

 

exten => t,1,goto(s,3)

 

 

The example answers the line, sets the timeout to 8 seconds and then plays the main-menu-sound file. At any time during the playback of the sound file, or in the 8 seconds after it the caller may press 1 or 2  to dial a phone. If there is no response from the caller after 8 seconds, the t extension if executed, which in this case simply plays the menu again.

 

Dial

Dial(technology/resource[&technology2/resource2...][|timeout][|options][|URL])

 

Requests a new channel, places an outgoing call to the specified destination(s) and bridges (links) the two channels when the remote side answers. If multiple destinations are specified the first to answer is bridged with the calling user.

 

Technology (Required) specifies the channel driver to use, for example SIP, IAX2, ZAP.

 

Resource (Required) specifies the remote end, for example a registered phone, gateway server or service. The resource may be a remote machine defined via either an entry in the config file (for the technology) or on the dial line

 

Timeout (Optional) is the number of seconds to ring before giving up, the general calculation for seconds to rings is:

 

Seconds / 4 = Rings

 

although there may be slight variations based on the technology used.

 

 

 

Options (Optional) specifies a list of required functional enhancements to use. The options are case sensitive, and may be stacked, i.e. you may have multiple options

 

 

Option

Description

 

t

 

 

Allow the called user transfer the calling user by hitting #.

 

 

T

 

Allow the calling user to transfer the call by hitting #.

 

 

f

 

 

Forces callerid to be set as the  extension of the line making or redirecting the outgoing call. For example, some carriers don't allow callerids from other extensions then the ones that are assigned to you.

 

 

r

 

 

Indicate ringing to the calling party, pass no audio until answered. Only to be used if for some reason callers can't hear ringtone. This is a dumb option, if the destination line is busy the caller will hear ringing then the busy tone.

 

 

m

 

 

Provide hold music to the calling party until answered.

 

 

M(x)

 

 

Executes the macro (x) upon connect of the call.

 

h

 

 

Allow called user to hang up by hitting *.

 

 

H

 

 

Allow calling user to hang up by hitting *.

 

 

C

 

 

Reset call detail record (CDR) for this call.

 

 

P[(x)]

 

 

Enable privacy mode, using 'x' as database if provided.

 

 

g

 

 

Continues on in context if the destination channel hangs up. Normally if the remote end hangs up both ends of the call stop.

 

 

A(x)

 

 

Play an announcement to the called party when answered, using x as the file.

 

 

S(x)

 

 

Hangup the call after x seconds AFTER called party picked up.

 

 

D([digits])

 

 

Send DTMF digit string after called party has answered but before the bridge. (w=500ms sec pause). Useful for automatically entering pin codes or to make 2 stage dialing appear as one stage dialing.

 

 

L(x[:y][:z])

 

 

Limit the call to 'x' ms, warning when 'y' ms are left, repeating every 'z' ms.

 

Only 'x' is required, 'y' and 'z' are optional. The following special variables are optional:

 

Play sounds to the caller only:

 

LIMIT_PLAYAUDIO_CALLER

 

Valid values are yes|no (default yes).

 

Play sounds to the called user only.

 

LIMIT_PLAYAUDIO_CALLEE

 

Valid values are yes|no

 

File to play when time is up.

 

LIMIT_TIMEOUT_FILE       

 

File to play when call begins.

 

LIMIT_CONNECT_FILE       

 

File to play as warning if 'y' is defined.

 

LIMIT_WARNING_FILE                               

 

'timeleft' is a special sound macro to auto-say the time left and is the default.

 

 

 

URL is an optional url to send to the remote part. Not all devices support this feature. The dial command will attempt to dial using the technology and resource provided, if the timeout ocurrs then then next priority is executed. If the dial returns busy then the dial command will jump to priority + 101 – if it exists.
Examples

 

A simple dial:

 

exten => 100,1,Dial(SIP/1234)

 

 

Dial multiple destinations, ringing for a maximum of 60 seconds. Force the callerid to be the extension and allow the calling user to transfer the call using the # key:

 

exten => 200,1,Dial(SIP/1234&IAX2,60,fT)

 

Dial a single destination, ringing for a maximum of 30 seconds, playing music instead of ringing. Force the callerid to the be the extension and allow the calling user to transfer the call using the # key:

 

exten => 300,1,Dial(SIP/1234,30,mfT)

 

Dial a single destination, ringing for a maximum of 20 seconds. Limit the call length to 60 seconds, warning the caller when only 20 seconds remain:

 

exten => 200,1,Dial(SIP/1234,20,L(60000:20000))

 

Dial a remote server:

 

exten => 100,1,Dial(SIP/1234@somenetwork.com)

 

 

Dial a pattern matched extension, ringing for a maximum of 20 seconds. if that fails, dial a remote server – note the use of ${EXTEN} to indicate the number dialed:

 

exten => _XXXXX.,1,Dial(IAX2/${EXTEN},20)

exten => _XXXXX.,2,Dial(SIP/${EXTEN}@somenetwork.com)

 

 

Echo

Echo()

 

Starts an echo test, where received audio is sent back to the sender. Allows one person to perform the Marco Polo test on an Asterisk server.

 

 

Example

 

exten => 100,1,Answer

exten => 100,2,Wait(1)

exten => 100,3,Playback(demo-echo)

exten => 100,4,Echo()

exten => 100,5,Hangup

 

 

The example answers the line, waits one second, plays back a sound file describing the echo test and then begins the echo test.

 

Goto

Goto([[context|]extension|]priority)

 

Jump to another context (optional), extension or priority within the dialplan

 

Example

 

exten => 100,1,Goto(anothercontext,200,1)

 

If context is omitted then the current context is used.

 

Gotoif

GotoIf(Condition?label1:label2)

 

Jump to another priority (label1) within the dialplan if condition is met, otherwise jump to label2

 

Example

 

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

 

The example sets a variable to 0 then proceeds in the dialplan, at some point it increments the variable by one. Priority 8 tests to see if the variable is less than 4, if it is it jumps to priority 5 of the current extension, if not it jumps to priority 9.

 

 


Hangup

Hangup()

 

Unconditionally hangup a line, terminating a call.

 

Example

 

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

 

NoOp

NoOp()

 

Pronounced as No Op (not noop), this application does errm, nothing. NoOp actually means “No Operation” - i.e. do nothing. This isn't strictly true, NoOp can do useful things, it can act as a spacer in extension priorities and it can be used to print variables on the console.

 

Example

 

exten => 100,1,NoOp(${CONTEXT})

 

would display the current context on the console when extension 100 was called.

 

Playback

Playback(filename[|option])

 

 

Plays the specified sound file (you should omit the file extension). Playback will play the whole sound file, and when complete, return control to the dialplan. Even though the Playback command will pick up the line if it has not been answered it is much more useful to answer the line prior to issuing the Playback command, then issue a wait, simply because it takes time for a channel to be picked up. If you do not answer and then wait, you may find the beginning of the sound file is not heard by the caller.

 

By default sound files are stored in the /var/lib/asterisk/sounds directory. The default path can me changed by modifying /etc/asterisk.conf.

 

Example

 

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

 

 

SetVar

SetVar(var=val)

 

Sets the variable var to value val. The variable can then be referred to in the dialplan by using ${var} where var is the name you gave the variable. These variables only exist for the duration of the call and are automatically destroyed when the call is hung up.

 

Example

 

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

 

 

 


VoiceMail

VoiceMail([s|u|b]mailbox[@context][&mailbox[@context]][...])

 

 

Starts the process of leaving a voice mail message for the extention specified by mailbox, in addition you may specify a context  located within /etc/asterisk/voicemail.conf – if the context is omitted, then the context “default” is used. The mailbox to be used may be preceded with one of the following options

 

 

Option

Meaning

 

s

 

Skip introductory message explaining how to leave a message

 

 

u

 

 

The message

 

“The person at extension <extension> is unavailable”

 

will be played to the caller.

 

 

b

 

The message

 

“The person at extension <extension> is on the phone”

 

will be played to the caller.

 

 

Notes

 

If the caller presses 0 at the prompt and an extension, o (lower case letter O) exists then the caller will jump to that extension.

 

If the caller presses * at the prompt and an extension, a exists then the caller will jump to that extension.

 

If there is no entry in voicemail.conf for the extension specified and priority +101 exists then the call will jump to that priority.

 

If more than one mailbox is specified then the messages played to the caller are those for the first mailbox in the list.

 

Examples

 

[my-users]

 

exten => 100,1,Dial(SIP/1234,20)

exten => 100,2,VoiceMail(u1234)

exten => 100,3,Hangup

 

exten => 100,103,VoiceMail(b1234)

exten => 100,104,Hangup

 

exten => o,1,Playback(calling-operator)

exten => o,2,Dial(IAX2/operator)

 

VoiceMailMain

VoiceMailMain([[s]mailbox][@context])

 

 

Starts the voice mail system and allows the caller to retrieve and listen to messages for the voice mail specified by mailbox, in addition you may specify a context  located within /etc/asterisk/voicemail.conf – if the context is omitted, then the context “default” is used.

 

Notes

 

If the mailbox is omitted then the user will be prompted to enter their voice mail number

 

If a mailbox is specified then the mailbox to be used may be preceded with one of the following options

 

Option

Meaning

 

s

 

 

The user will not be asked to enter their password

 

 

p

 

 

The user input is appended to the supplied mailbox resulting in

 

<mailbox><digits dialed>

 

being used as the mailbox to use.

 

 

 

 

Examples

 

Access voice mail account 1234 without asking for a password

 

exten => 1010,1,VoiceMailMain(s1234)

 

Access voice mail asking the user for a mailbox number and a password

 

exten => 1012,1,VoiceMailMain()

 

 

Wait

Wait(sec)

 

Pauses execution of the dialplan for sec seconds

 

Example

 

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

 

 

 


 

Never use spaces between parameters in dialplan commands unless quoting. For example

 

Goto(mycontext, 199, 1)

 

would attempt to find extension “ 199”, priority “ 1” in context mycontext. It would fail since extensions can not start with a space character.

 

 

 



<- ...Back>   Continue... ->