mod_dptools功能总结
前言
freeSWITCH的mod_dptools模块各功能总结,这里只是整理下功能,具体用法参考官方wiki
-
answer
“接通”。建立aleg和fs之间的音频流,和bleg没关系。一般来说fs在接受dtmf或者播放语音之前都要先接通。在接通之后仍可以bridge到其它终端(接通后再bridge其实就是转接),回铃音由transfer_ringback设置。 -
att_xfer
转接。本来是A->B,att_xfer会让C加入进来,从而变成A->C。可以直接使用或者和绑定dtmf的功能搭配使用。详细使用方式和例子参考官方文档。 -
bgsystem
后台执行一个系统命令。不会阻塞当前dialplan。bg就是backgroud的意思。 -
bind_digit_action****和bind_meta_app
绑定dtmf。不同之处在于,bind_digit_action比bind_meta_app更灵活,是bind_meta_app的升级版。 -
break
终止application。终止一个当前channel正在运行的application,下一个application继续执行不受影响。也可以用来终止所有application。 -
bridge
桥接。把一个新channel和当前channel连接。经常用来把一通来电转给多个被叫(可以同时或者轮流)。bridge有很多可选功能:设置等待时长、无媒体模式、设置callerID和回铃音、通话驻留(及被叫被占用时主叫等待)。 -
bridge_export
和export的区别在于bridge_export适用于任何类型的bridge。例如使用uuid_transfer时export不生效而bridge_export生效。 -
callcenter
呼叫中心功能。具体的用法和配置可以参考mod_callcenter模块。 -
capture
操作通道变量中的数组。 -
chat
向一个IM客户端发送文本消息。 -
check_acl
检查呼叫来源是否匹配acl,不匹配则终止通话(cause code为normal_clearing)。 -
clear_digit_action
删除所有dtmf功能绑定。 -
clear_speech_cache
Clears out the speech handle cache( 没用过,不太清楚) -
cng_plc
生成舒适噪音。 -
deflect
转接。只能用于已经建立(或者说已接通)的通话。deflect会挂断当前的通话,并向通话发起者发送一个REFER消息和一个新的INVITE消息。注意和redirect命令的区别,当通话没有建立时,转接不能用deflect,但是可以用redirect。 -
delay_echo
延时“回声”。 -
detect_silence
监听静默音。暂停(阻塞)diaplan的执行,在一段时间内持续检测静默音。当检测到静默音或者检测超时后,dialplan继续执行。静默音由silence_thresh(理解为通道能量阈值)和silence_hits(理解为时长)两个参数决定。 -
detect_speech
语音识别。 -
digit_action_set_realm
和bind_digit_action一起,在绑定dtmf时使用,具体可以参考官网bind_digit_action的部分 -
displace_session
(向一个channel中) 播放一个文件或音频流。 -
eavesdrop
监听。监听指定的uuid通道,如果是持续或者永久的监听,一般使用mod_spy。 -
echo
播放回声。会返回任何东西,除了声音外,也会返回dtmf。可以用这个功能来测试通道的延时。 -
endless_playback
持续播放一个文件。 -
env-set
把一个系统环境变量的值赋给一个自定义变量。 -
eval
执行api,在控制台打印日志。例如在控制台输入eval ${distributor ucrs ${sofia profile external gwlist down}}
,eval会调用内部api和相关模块进行解析,最终输出解析结果
-
event
用于发布一个自定义事件。 -
execute_extension
在当前dialplan创建一个一次性的extension并执行,执行完之后返回当前diaplan。要注意的是如果执行的是transfer则不会返回。 -
export
把一个变量从A leg传递到B leg。(使用export后A leg和B leg都会设置此变量,如果只想在B leg上设置变量,需要使用nolocal,具体用法参考官方文档) -
fax detect
传真检测。 -
file_string
用于依次播放/写入某个声音文件(如果某个失败了,则跳过进行下一个)。例如搭配playback或者record_session使用。不同的声音文件之间用感叹号分割。更多用法参考官方文档。 -
flush dtmf
清除一个channel接收到的dtmf。 -
gentones
生成TGML铃音。和tone_stream的功能差不多。但是tone_stream用的更多。 -
group
用于群组呼叫,对群组做添加或删除。 -
hangup
挂断当前通道。可以赋值挂断原因。(当挂断失败时可以检查一下hangup_after_bridge变量,再确认一下是否接到了BYE信令) -
hold
发送hold信息。 -
info
打印通道相关信息。在调试和排障时是非常有用的。 -
inline dialplan
内联拨号计划。和普通的dialplan区别在于,inline dialplan不需要<extension>,也不需要<condition>,只要有action就行了:'app1:arg1,app2:arg2,app3:arg3' inline
,例如下面这句话就完成了先打电话,再设置通道变量,最后播放wav的操作:
originate sofia/gateway/my_gw/user@domain.com 'set:myvar=myvalue,info:,playback:foo.wav' inline
其中,'set:myvar=myvalue,info:,playback:foo.wav'
代替了正常diaplan中的xml配置。
-
intercept
将当前通道转给另一通通话的a leg或者b leg(通过uuid)。例如,当通话没有成功bridge或者成功接通时,可以用intercept将当前通话转给其它通道。具体使用方法参考官方文档。 -
IVR menu
IVR菜单。创建IVR菜单(使用XML配置文件:/autoload_configs/ivr.conf.xml)。详细内容这里不写了,参考IVR Menu或者IVR。 -
limit
设置外呼或者来电的最大数量。当到达最大数量时,通话将转向指定路由。通过limit
可以实现很多功能,例如:限制最大并发通话数、对某个fs功能的限流、限制指定时间内最大通话量等等。详细用户和说明参考官方文档。 -
log
在控制台打印日志。这个很常用不多说了。 -
loop_playback
循环播放某个文件(指定次数)。 -
mkdir
创建一个目录(有可能会因为系统权限问题创建失败)。 -
multiset
同时设置多个通道变量。多个变量之间默认以空格分割:
<action application="multiset" data="varA=valueA varB=valueB"/>
如果想指定分割符,用"^^"指定:
<action application="multiset" data="^^:varA=valueA:varB=valueB"/>
-
mutex
阻塞呼叫流,一次仅允许一个呼叫流。没有用过,但是个人理解是同一时间内只允许一通话务通过这个diaplan。用法见官方文档。 -
page
向多个通道播放一段录好的文件。 -
park
挂起。挂起的时候不会播放任何声音,用户体验比较差,一般可以考虑用hold代替。 -
phrase
播放一段预定义好的文本。通过xml的方式进行配置并生成语音。更详细的资料和使用方式可以参考 Speech Phrase Management 。 -
pickup
pickup通道是一个虚拟的通道,可以利用这个通道实现一些特殊功能。没怎么用过,详细参考官方文档吧。 -
play_and_detect_speech
在做语音识别(ASR)的时候播放音频。音频可以是文件也可以是TTS语音。 -
play_and_get_digits
播放提示音并获取用户输入的dtmf。 -
playback
在当前通道播放音频。非常常用的一个功能。支持多种格式的音频,例如常见的*.wav(需加载mod_sndfile模块)和*.mp3(需加载mod_shout模块)。 -
pre answer
在并未接通的情况下,建立早期媒体连接(early media)。例如彩铃、语音提示等就是early media(对应sip状态码183)。这个在实际中也是很常用的,比如在被叫拒接时,给主叫播放一段语音,而不是直接挂断。 -
presence
发布一个PRESENCE_IN或PRESENCE_OUT事件。这个事件是用于BLF(Busy Lamp Field)的,BLF的作用是标记voip用户是否在线,是否可以进行呼叫。 -
privacy
将主叫设为隐私。具体用法和作用有待研究。 -
queue_dtmf
发送一串dtmf(bridge成功后)。 -
read
获取dtmf。在获取到dtmf之前可以播放一段定制的音频。 -
record和 record_session
录音。二者的区别在于,前者是阻塞的,而后者是非阻塞的;录音后的录音文件可以保存在指定路径下,也可以和http_cache模块搭配,直接将录音文件通过接口进行上传。录音功能还是比较常用的,实际中录音的场景也比较多,这里不展开说了,具体用法和对录音过程的控制参考官方文档。 -
redirect
转接。只能用于通话还未接通的时候,如果通话接通后的转接用deflect功能。 -
regex
正则匹配。严格来说这不是直接用在dialplan里的,而是一个api,想要在dialplan中调用api可以借助set。实际使用参考官方文档。 -
remove_bugs
移除所有的media bugs, 这里的media bug指的是fs的媒体旁路输出机制,record_session、tone_detect等功能都使用了这一机制。media bug -
rename
重命名一个文件。没啥好说的。 -
respond
发送一个sip回应。例如,如果你想给某个终端发送一个未授权的407消息:
<action application="respond" data="407"/>
-
ring_ready
告知主叫已经振铃,即给主叫发送一个180信令。 -
say
顾名思义,“读”。播放提前录好的音频,或者读出日期、时间、dtmf等。具体用法详见官方文档。 -
sched broadcast
预定一个广播。例如一小时后向主被叫双方播放一段音频:<action application="sched_broadcast" data="+3600 /tmp/howdy.wav both"/>
。预定成功后会设置通道变量last_sched_id。 -
sched transfer
预定一个转接。例如10分钟后将通话转入default.xml:
<action application="sched_transfer" data="+600 9999 XML default"/>
。预定成功后会设置通道变量last_sched_id。 -
sched cancel
根据last_sched_id取消定时任务(由上面的sched broadcast或sched transfer设置的transfer或broadcast)。 -
sched hungup
定时挂断。可以用来限制呼叫时长。 -
send_display
发送一个信息包用于展示,如果终端支持的话会显示这个信息。 -
send dtmf
发送dtmf。例如:<action application="send_dtmf" data="0123456789ABCD*#@100"/>
。@后的数字表示每个dtmf的持续时长(ms),如果不指定这个时长,则默认2000ms。 -
session loglevel
更改当前通道的loglevel(覆盖switch.conf.xml中的设置)。 -
set
设置通道变量。很常用,没什么好说的。需要注意的是,set不会立即生效,执行完当前的dialplan之后才会生效。如果执行set之后希望立即生效,搭配inline使用。 -
set_global
设置全局变量(全局指的是这个变量对其它的channel也生效)。 -
set_name
重命名一个channel。 -
set_profile_var
给通道事件(channel event)增加一个header。只用于通道事件中。 -
set_user
Pulls all of the channel variables defined for a user as if the user had auth’d. -
set audio level
增大或减小音量级别。其实就是调音量的。调整范围:-4~4。一般调音量是用户终端的事,fs端最好不要调整。 -
set zombie exec
给当前的channel立个flag:zombie flag。这个flag立完之后,即使这个channel挂断,仍然会继续执行channel中的command。 -
sleep
顾名思义,sleep会“暂停”一个通道,这期间对音频的处理并不会暂停,仍会“消费”音频。
soft_hold
将已经成功bridge的通道挂起。
-
sound_test
将媒体流的包信息打印在控制台中(不会写入日志)。 -
speak
朗读一段文本(需用到TTS引擎)。 -
start_dtmf
在当前通道开启dtmf检测。不能和start_dtmf_generate一起用;和ring_ready一起用时要保证ring_ready在前。 -
start_dtmf_generate
允许在当前通道生成dtmf。 -
stop_displace_session
停止播放文件/音频,和displace_session功能是一对。 -
stop_dtmf
停止带内dtmf(inband dtmf)检测。延申:dtmf有三种模式:inband、sipinfo和rfc2833,根据实际来看,其中inband模式的识别率比较低,这是因为inband模式是把按键产生的信号和语音流一起传输的,同时解码是根据频谱分析进行的。 -
stop_dtmf_generate
禁止当前通道生成dtmf。 -
stop_record_session
停止录音。和record_session功能是一对。 -
stop_tone_detect
停止当前通道的tone检测。和tone_detect是一对。 -
strepoch
将当前时间转为整数(1970年1月1日至今的秒数)。一般用于需要判断时间的场景。 -
strftime
将当前时间显示为各种格式。具体用法见官网。 -
strftime_tz
和strftime类似,区别是这个功能支持不同时区。 -
strmicroepoch
和strepoch功能类似,区别是这个功能返回的是毫秒 -
system
执行一个系统命令并等待返回结果(阻塞的)。 -
three_way
三方通话功能,加入一个正在进行中的通话(已经bridged的通话)。这个功能是借助eavesdrop功能实现的。 -
tone_detect
tone检测。 -
transfer
转接。可能是最常见和核心的dptool了。将当前channel立刻转入一个新的路由(xml文件)。更多用法这里不赘述,参考官方文档。 -
unbind_meta_app
和bind_meta_app成对使用。如果用bind_meta_app绑了一个dtmf,那么使用unbind_meta_app后取消绑定(可以取消某个dtmf,也可以取消所有dtmf,具体使用见官方文档)。 -
unhold
和hold成对使用。 -
unset
和set成对使用。 -
verbose_events
“启用详细事件”。verbose events拥有全部的通道变量,而non-verbose events只拥有部分预先选定的通道变量。这个设置也可以在switch.conf.xml中开启或关闭。 -
wait_for_answer
等待session接通(接通后才继续执行dialplan)。 -
wait_for_silence
检测指定时长的静默。dialplan在检测到指定时长的静默或检测超时后,才会继续执行,否则暂停执行。