Chapter 5. Audio File and Streaming Formats, Music on Hold, Recording Calls

Audio, audio, audio… If you're in telephony, you know what telephony is all about. End users' experience is determined by the quality of the sounds they are hearing, and, no matter how perfect the signaling and routing, their satisfaction will come from way down in the abstraction layers: their ears.

Creating and manipulating audio files and streams, for prompts, error messages, voicemails, call recordings, quality monitoring, and to entertain while waiting on the phone, is a sizeable part of any VoIP implementation.

FreeSWITCH gives us a lot of functions and primitives to deal with audio files and associate chores, and we'll see what the best practices are in this area, from how to combine audio fragments into meaningful phrases to how to stream live radio as music on hold.

In this chapter, we will cover:

• Audio in VoIP, traditional and HD

• FreeSWITCH audio formats, MP3, streaming

• Music on Hold (MOH)

• Recording and playing...

Traditional telephony codecs constrain audio

There are so many ways to compress and digitize audio to be sent through the wire. A lot of codecs are available for use with FreeSWITCH, from ultra-wide band high definition (the quality of an audio CD) to the ultra-low bandwidth utilization, and all the variables involved can be confusing.

So, let's start with a bold simplifying assumption (we'll see complexity later): You only need to be aware of two codecs — G711 (which is available in two flavors: Ulaw and Alaw, also known as PCMU and PCMA) and G729.

G711 is the original, uncompressed format used since the beginning of time by telecom companies worldwide. It was designed to carry speech so that it only gets a very narrow audio band (300-3400 Hz), and to cut out the rest (humans can hear from 20 to 20,000 Hz; that's why music on hold sounds so bad on the phone). It samples that narrow speech band 8,000 times per second (8 khz sampling) in a logarithmic way (mimicking human hearing for different...

HD audio frontiers are pushed by cellphones, right now

We've just seen that for regular, traditional telephony, we only need an audio source that is mono, narrowband, 8 bit, 8 khz. That is considered good quality, toll-grade quality.

It compares well with cellular phones' quality, which in the last decade has drastically lowered our expectations. Cellular phones' codecs did not sound very good; actually they were much worse than G711 or G729. But we're on the verge of a revolution in the sound quality of telecommunication.

First it was Skype, who introduced us all to 16 khz, wideband audio. Ever tried to listen to music via Skype? It sounds good. And speech too: You immediately hear and feel, you're not on PSTN (and neither on cellphone).

But there is much more to come: 4G and LTE cellular networks are starting to become available everywhere, with audio in ultra-wideband and high definition (HD). The cellular network will once again change our expectations, but this time it will raise the bar...

FreeSWITCH audio, file, and stream formats

FreeSWITCH is able to interface automatically with a lot of codecs and file/stream formats, and it can translate between them. This means that a CD-like source at 48 khz, 16 bit, stereo and wideband will be decoded, downsampled, truncated, mixed, and then re-encoded to be sent in a G711 call.

Keeping with the general FreeSWITCH philosophy of do not reinvent the wheel, audio files and streams are read and written using open source libraries: FreeSWITCH has a specific API for audio formats; anyone can write a wrapper for a new sound format library and that format will be available everywhere in FS that a sound format is used (the same applies to codecs and to stream formats; just implement their FreeSWITCH's API).

This ensures the most efficient and timely support for new file formats and codecs (Brian West released FreeSWITCH's support for BroadVoice codec 40 minutes after it was open sourced).

Audio file formats

Most audio file formats are supported...

Recording calls

Call recording is different from message (prompt) recording. You want to record both the caller and the callee, that is, the entire conversation made by A-leg (caller) and B-leg (callee).

You may want to end up with two files (one file will contain the caller's audio, the other one the callee's speech), or one file that contains the two legs mixed together, or (and this is an elegant and practical solution) one stereo file that will contain the caller's audio on one channel (for example, the left channel), and the callee's on the other (right) channel.

Also, you may want this recording to happen automatically at each call, or to be activated by the end user (or administrator) pressing a special feature key.

Here the dialplan application you want to use is record_session. By default record_session will do the right thing (TM) and record a stereo file containing one leg per channel.

<action application="record_session" data="/tmp/${uuid}.wav"/>

To modify the default behavior...

Tapping audio

You may need to listen someone else's call. First of all be sure to be compliant with international laws and regulations and those of your country: Rumors that the Alphabet Soup is wiretapping the whole world will not shield you from a lawsuit or a criminal investigation. If you're positive you have the right to listen, FreeSWITCH has two dialplan applications to choose from: eavesdrop will allow you to listen to an arbitrary call (defined as an uuid argument to the app), while userspy will constantly eavesdrop on calls involving a specific user.

Using eavesdrop on a call (also known as call barging) requires knowing its uuid (you may use all as uuid, but you'll end up listening to all existing calls mixed together). One such technique is implemented in the standard dialplan. When a call is processed, its uuid is added to a spymap db table, indexed on extension. You can then dial a prefix + extension, and if there is a call involving that extension the uuid will be retrieved...

Summary

In this chapter we have browsed through various audio-related items and procedures of paramount importance in real life FreeSWITCH implementation. Audio is the Alpha and Omega of telephony, and by taking good care of it you will be the good guy in the VoIP world. FreeSWITCH gives you so many tools. We just scratched the surface here, and using FS positions your project at the forefront of telecommunication, ready to take on the challenge of HD audio. We demonstrated how to deal with audio files, transcoding formats, recording prompts and messages, and recording entire calls (both legs) to a stereo file. Lastly, we saw how to listen to, and interact with, someone else's call.

There is so much more to explore about Audio in FreeSWITCH, but we hope we gave you a glimpse, and the motivation to browse the official documentation.