VMware ESXi and vSphere Cluster Management

Asterisk Playback Application: Playing Audio and Video Files in the Dialplan

Learn how to use Asterisk Playback in extensions.conf to play announcements, locate sound files, test dialplans, and choose Playback versus Background.

What the Playback application does

Playback is an Asterisk dialplan application that sends a media file to the active channel. It is commonly used for prerecorded announcements, such as business hours, call-monitoring notices, holiday messages, and information prompts.

The dialplan is the extension-processing logic that determines which applications Asterisk runs for a call. Although dialplans are often used for routing calls, Asterisk can also deliver media, collect digits, connect channels, and perform other call-handling tasks.

Playback normally runs to completion before the next dialplan priority executes. This makes it a good choice for a complete announcement when the caller is not expected to make a selection during the recording.

Playback syntax

The basic form is:

Playback(sound-file-name)

The required argument is the media file name. When the file is installed under Asterisk's sounds directory, use the sound name relative to that directory and normally omit the filename extension.

Playback(this-call-may-be-monitored-or-recorded)

Asterisk searches for a suitable available media format for the channel. For example, the same prompt might be installed in one or more formats, and Asterisk selects a compatible format according to the channel and installed media files. The exact result depends on the Asterisk version, channel technology, language configuration, and available sound packages.

Where Asterisk finds sound files

The default Asterisk sounds directory is:

/var/lib/asterisk/sounds

Language-specific prompts are commonly stored in subdirectories such as:

/var/lib/asterisk/sounds/en

A prompt name relative to the sounds directory is usually the clearest option:

Playback(this-call-may-be-monitored-or-recorded)

In this case, Asterisk resolves the name below its configured sounds tree and language path. The actual language lookup can depend on the channel's language setting and the installed sound package.

You can also provide a full filesystem path when the media is outside the standard sounds directory. For example:

Playback(/opt/pbx-prompts/maintenance-notice)

A full path is useful for custom media stored elsewhere, but the Asterisk service account must be able to traverse the directories and read the file. Use the naming and format conventions supported by the Asterisk version and media configuration in use.

Media reference options

Reference style: Name relative to the sounds directory. Example: Playback(company-hours). Media location: Usually below /var/lib/asterisk/sounds, including a configured language directory. When to use it: Bundled or custom prompts installed in the standard Asterisk sounds tree.

Reference style: Full filesystem path. Example: Playback(/opt/pbx-prompts/company-hours). Media location: A file outside the standard sounds directory. When to use it: Custom media stored elsewhere and readable by the Asterisk process.

Playback call-flow behavior

When Asterisk reaches Playback, it sends the selected file through the active channel. Playback normally continues until the file finishes. Caller DTMF input is ignored while Playback is running, so pressing a digit does not automatically select a dialplan option.

After the announcement ends, execution continues at the next priority in the same extension. A priority is the execution order of a dialplan step. The notation same => n continues the preceding extension and assigns the next priority automatically.

exten => 999,1,Answer()
same => n,Playback(company-hours)
same => n,Hangup()

In this example, priority 1 answers the call, the next priority plays the announcement, and the following priority ends the call.

Playback versus Background

Background is an Asterisk application that plays a prompt while allowing caller DTMF input to interrupt it. This difference is critical when building an auto-attendant or interactive voice response menu.

Use Playback for a fixed announcement when the caller does not need to respond during the recording. Use Background when the caller must be able to press digits while the prompt is playing.

Application: Playback. Primary use: Complete, noninterruptible announcements. Caller DTMF behavior during prompt: Input is ignored while Playback is running. Appropriate for an auto-attendant: No, when callers must choose an option during the prompt.

Application: Background. Primary use: Interactive prompts and menu announcements. Caller DTMF behavior during prompt: Digits can interrupt the prompt and be handled by the dialplan. Appropriate for an auto-attendant: Yes, when callers need to select options during the recording.

Basic dialplan implementation

A common Asterisk configuration file is extensions.conf. It contains named contexts, which are groups of dialplan extensions. An extension is a dialable identifier and its ordered call-processing steps.

The following example creates extension 999 in a context named example-context:

[example-context]
exten => 999,1,Answer()
same => n,Playback(this-call-may-be-monitored-or-recorded)
same => n,Hangup()

Here is what each step does:

  • exten => 999,1,Answer() defines extension 999 and answers the channel at priority 1.
  • Playback(this-call-may-be-monitored-or-recorded) plays the installed English monitoring-or-recording notice.
  • Hangup() terminates the call after the announcement because no further processing is required.
  • same => n keeps the steps attached to extension 999 and automatically advances the priority.

The extension must be placed in a context reachable by the calling endpoint. If an endpoint uses a different context, dialing 999 may not reach this definition even when the text is correct.

Example: a custom prompt outside the sounds directory

A custom announcement can be stored outside /var/lib/asterisk/sounds. Answer the channel, play the file by its full path, and continue to the next dialplan step after playback completes.

[example-context]
exten => 998,1,Answer()
same => n,Playback(/opt/pbx-prompts/maintenance-notice)
same => n,Hangup()

For this example to work, the path must be correct, the media must use a supported format, and the Asterisk service account must have permission to read the file. A full path should be reserved for media that is intentionally maintained outside the standard sounds tree.

Testing Playback

  1. Save the extension in the active extensions.conf configuration.
  2. Reload the dialplan from the Asterisk CLI:
dialplan reload
  1. From a registered endpoint or another reachable channel, dial the test extension, such as 999.
  2. Verify that the call is answered and that the expected monitoring-or-recording announcement is heard.
  3. If the prompt does not play, watch the Asterisk CLI during the test call and inspect the reported file or channel error.

You can view the Playback documentation available in the installed Asterisk version with:

core show application Playback

This command is useful because application behavior and available options can vary between Asterisk versions.

Troubleshooting Playback

The call reaches the extension, but no announcement is heard

  • Verify that the referenced file exists below /var/lib/asterisk/sounds or at the supplied full path.
  • Check the language-specific directory, such as /var/lib/asterisk/sounds/en, when the channel uses a language setting.
  • Confirm that the sound name is spelled correctly and does not contain an unintended filename extension.
  • For a full path, verify that the path is correct and accessible to the Asterisk service account.
  • Check ownership and read permissions on the file and every directory in its path.
  • Confirm that a compatible media format is installed for the channel.
  • Review Asterisk CLI output during the test call.

A caller presses a digit, but the call does not route

This usually means Playback was used for an interactive menu. Playback ignores DTMF while the prompt is running. Replace it with Background, define the appropriate digit extensions, and add the follow-up call handling.

Dialing the test number does not run the Playback steps

  • Confirm that the endpoint is assigned to the context containing extension 999.
  • Run dialplan reload after editing extensions.conf.
  • Confirm that extension 999 is defined in the active context.
  • Inspect the loaded dialplan and the endpoint's context using the Asterisk CLI.

Playback starts before the channel has a connected audio path

If the call path requires explicit answering, place Answer() before Playback(). A channel that was already answered by earlier call handling may not need another Answer application.

Exam-relevant points

  • Playback plays a specified media file on the active Asterisk channel.
  • The normal syntax is Playback(sound-file-name).
  • Prompt names in the standard sounds tree normally omit the file extension.
  • The default sounds directory is /var/lib/asterisk/sounds; language subdirectories can include en.
  • Playback runs through the announcement and ignores caller DTMF during playback.
  • Background is the appropriate application when callers must interrupt a prompt with DTMF.
  • Use Answer() before media delivery when the channel has not already been answered.
  • Use same => n to continue an extension with automatically numbered priorities.
  • Reload changes with dialplan reload before testing.

Summary

Playback is the basic Asterisk application for delivering a prerecorded sound prompt to a caller. Reference standard prompts by name without the usual extension, or provide a full path for media stored outside the sounds tree. A typical implementation answers the call, plays the prompt, and hangs up. Choose Background instead when the prompt is part of an interactive menu and caller DTMF must be accepted during playback.