Skip to main content

mod_dptools: playback

0. About​

Plays a sound file on the current channel.

In order to be able to play MP3 files, mod_shout needs to be built and loaded.

TODO Use mod_vlc) for anything else (i.e., M4A, AAC, etc.)?

Stop playback

To stop playback, use the uuid_break API command. See mod_commands) for usage.

1. Usage​

<action application="playback" data="<sound-file-to-play>[@@<seek-offset>]"/>
ParameterDescriptionExamples
sound-file-to-playPath to sound file, in a format that is understood by libsndfile (see 3. Supported File Types section below). Path can be relative to the working directory or fully qualified absolute path to the file.sounds/soundfile.wav/tmp/test.wav
seek-offsetThe number of samples to specify a playback start position (i.e., seek into the file). This would be useful for a sound file that contained a number of short prompts, to build a phrase from individual words or phonemes.You could also use the mod_dptools:say for such applications.7000

2. Examples​

2.1 Play a file, and don't allow it to be interrupted​

<action application="set" data="playback_terminators=none"/> 
<action application="playback" data="sounds/soundfile.wav"/>

The playback_terminators channel variable is set to none to disable stopping the playback on DTMF input. (The default terminator is *.)

The terminator used is available in playback_terminator_used. See Channel Variables Catalog for more.

2.2 Play file from a specific position​

You can also append @@<seek-offset> (where seek-offset is the number of samples) to the file name to specify a playback start position. This works in a predictable way in PCM files, less predictably with compressed files such as mp3.

playback example

<action application="playback" data="/tmp/test.wav@@8000"/>

Assuming this file was sampled at 8000 samples/second, the @@8000 suffix will seek 1 second into the file, and start playback there.

2.3 Setting Specific Playback Variables​

<action application="playback" data="{var1=val1,var2=val2}sounds/soundfile.wav"/>

The prefix {var1=val1,var2=val2} defines variables that will be sent in PLAYBACK_START and PLAYBACK_STOP events, thus this is especially handy when building event socket applications. In the events, the variables will be named the same way as the variable names you configured (in this case, var1 and var2).

Please note that in FreeSWITCH versions older than the commit below, variables could be set in the suffix after the filename, instead of in the prefix. So if you experience problems on older versions, you must upgrade your application to reflect these changes.

Variable names in the events themselves used to be prefixed with playback_variable_, but not anymore.

commit 042347802b2b4972a11212df0c84921b91b71d64
Author: Anthony Minessale <anthm@freeswitch.org>
Date: Wed Feb 20 16:34:13 2013 -0600

Playback from remote server​

<action application="playback" data="http://example.com/media/hello_world.wav"/>

3. Supported file types​

FreeSWITCH has an abstraction layer for file formats. Anyone can write a format module which allows file formats to be utilized from any of the places that would process them.

Most formats support both reading and writing; the ones that do not are identified below.

TODO

  • Where is this "abstraction layer for file formats" documented?
  • Where is it implemented?
  • What modules are using it? (Assume that all of the ones below.)
  • Which are the ones supporting "both reading and writing"?

3.1 mod_sndfile​

This uses libsndfile, and therefore supports any format usable by it. See the latest list of supported formats at libsndfile, but here is a subset of it:

  • AIFF (Apple/SGI) (extension "aiff")
  • AU (Sun/NeXT) (extension "au")
  • AVR (Audio Visual Research) (extension "avr")
  • CAF (Apple Core Audio File) (extension "caf")
  • HTK (HMM Tool Kit) (extension "htk")
  • IFF (Amiga IFF/SVX8/SV16) (extension "iff")
  • MAT4 (GNU Octave 2.0 / Matlab 4.2) (extension "mat")
  • MAT5 (GNU Octave 2.1 / Matlab 5.0) (extension "mat")
  • PAF (Ensoniq PARIS) (extension "paf")
  • PVF (Portable Voice Format) (extension "pvf")
  • RAW (header-less) (extension "raw" or "r8" )
  • SD2 (Sound Designer II) (extension "sd2")
  • SDS (Midi Sample Dump Standard) (extension "sds")
  • SF (Berkeley/IRCAM/CARL) (extension "sf")
  • VOC (Creative Labs) (extension "voc")
  • W64 (SoundFoundry WAVE 64) (extension "w64")
  • WAV (Microsoft) (extension "wav")
  • WAV (NIST Sphere) (extension "wav")
  • WAVEX (Microsoft) (extension "wav")
  • XI (FastTracker 2) (extension "xi")

3.2 mod_shout​

Additionally, mod_shout supplies MP3 support for files and Shoutcast streams.

3.3 See also​