Asterisk course

Asterisk Playback Application: Playing Audio and Video Prompts

Learn how to use Asterisk Playback to deliver prerecorded announcements, locate sound files, handle DTMF behavior, and test a simple dialplan.

Playback is an Asterisk dialplan application that sends a prerecorded media file to the current channel, which is Asterisk's representation of a call leg or communications path. It is commonly used for announcements, notices, warnings, and informational messages.

Playback normally delivers audio. When the channel and endpoint support video media, it can also deliver a video file. The exact media formats that work depend on the installed Asterisk modules, the channel technology, and the endpoint capabilities.

Playback syntax

The basic dialplan form is:

Playback(sound_file)

The required argument is the media file name. In most cases, omit the filename extension. Asterisk can then select an available compatible format from the files it finds.

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

This refers to a prompt named this-call-may-be-monitored-or-recorded, without explicitly specifying an extension such as .wav or .gsm.

Where Asterisk looks for sound files

The standard Asterisk sounds directory is commonly:

/var/lib/asterisk/sounds

Installations can also have language-specific directories below it. For example, English prompts may be stored under:

/var/lib/asterisk/sounds/en

With a bare file name, Asterisk searches its configured sounds paths. This is the preferred style for standard prompts installed with Asterisk or a sound-prompt package.

Name-only reference — Example: Playback(company-hours). Use this for a file in the standard Asterisk sounds locations or a configured language directory.

Full-path reference — Example: Playback(/opt/company-prompts/office-closed). Use this when the recording is outside the configured sounds locations.

A full filesystem path should point to the media file's location, but the extension can still normally be omitted when Asterisk should choose a compatible available format.

To inspect the standard directory and check whether prompts are installed, run:

find /var/lib/asterisk/sounds -type f | head

How Playback handles caller input

Playback plays the selected file to completion. Caller DTMF, meaning telephone keypad signaling such as digits pressed by the caller, does not interrupt the file or select an option while Playback is running.

This makes Playback suitable for a message that callers must hear from beginning to end. It is not an interactive menu application.

Playback versus Background

Background is an Asterisk dialplan application that plays a prompt while allowing digit input to be handled for an interactive call flow.

Playback — Primary use: complete, non-interruptible announcements. DTMF during playback does not select menu choices. Typical example: a call-monitoring notice or an office-closed message.

Background — Primary use: interactive prompts and auto attendants. DTMF can be received while the prompt plays and can route the caller to digit-handling extensions. Typical example: “Press 1 for sales.”

Use this decision rule: if DTMF input is expected while the prompt is playing, use Background. If the caller should simply hear the entire announcement, use Playback.

Complete extension example

An extension is a dialplan number or pattern that routes a call through ordered priorities. The following extension answers the call, plays a standard announcement, and ends the call:

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

Place this configuration in extensions.conf within the context used by the test call.

What each priority does

  1. Answer() answers the inbound channel before media is delivered. See The Answer application for more about answering channels.
  2. Playback(...) locates and plays the named prerecorded prompt. The caller cannot interrupt it with keypad input.
  3. Hangup() terminates the current channel after the announcement finishes. See The Hangup application for related call-ending behavior.

Answering explicitly is useful when the call flow requires the channel to be connected before media is sent. If later dialplan logic is needed, replace or extend the Hangup priority with the next application instead.

Example: a custom prompt outside the sounds directory

Suppose a custom recording is stored in /opt/company-prompts rather than the standard sounds directory:

[default]
exten => 700,1,Answer()
 same => n,Playback(/opt/company-prompts/office-closed)
 same => n,Hangup()

Calling extension 700 answers the channel, plays the custom file, and hangs up. The full path tells Asterisk where to find media stored outside its configured sounds paths.

Testing the announcement

  1. Edit extensions.conf and add the test extension to the context used by your endpoint.
  2. Reload the dialplan from the Asterisk CLI or a shell:
asterisk -rx "dialplan reload"
  1. Call extension 999 from a registered endpoint.
  2. Confirm that the call is answered and that the selected prerecorded announcement plays from start to finish.
  3. Expect the call to end after Playback completes because the next priority is Hangup().

If the endpoint is not registered yet, first review registering phones to Asterisk. If the call enters a different context, make sure the extension is defined there or that the call is routed to the correct context.

Playback and interactive menus

Consider an auto attendant that says, “Press 1 for sales or 2 for support.” Playback is the wrong choice for that prompt because digits pressed during playback are not used to choose an option. Use Background and define the corresponding digit routes in the active context.

For a complete guided project, see Create an automated attendant. The key distinction remains simple: Playback delivers a complete announcement; Background supports DTMF-aware menu handling.

Troubleshooting

The file cannot be found or no announcement is heard

  • Check the prompt spelling in the Playback() argument.
  • Verify that the file exists under /var/lib/asterisk/sounds, a language directory, or the intended custom location.
  • Use a full path when the file is stored outside the configured sounds locations.
  • Confirm that the dialplan uses the correct prompt name and does not contain an unnecessary extension.
  • Watch the Asterisk console while placing the test call for file lookup and media errors.
  • Ensure that a compatible media format is available for Asterisk and the endpoint.

Digits do nothing during the prompt

This is expected when Playback is being used. If the prompt is an interactive menu, replace Playback with Background and confirm that the required digit-handling extensions exist in the active context.

The call is not connected before media should play

  • Put Answer() before Playback() when the call flow requires an explicit answer.
  • Check the channel signaling and Asterisk console output to confirm that the call reaches the intended priority.

Dialplan changes do not take effect

  • Reload the dialplan after editing extensions.conf.
  • Verify that the extension exists in the expected context.
  • Confirm that the endpoint or inbound route enters that context.

Exam-relevant summary

  • Playback sends a specified prerecorded media file to the current channel.
  • The syntax is Playback(sound_file); the media file name is required.
  • The extension is normally omitted so Asterisk can resolve an available compatible format.
  • A bare name uses configured Asterisk sounds paths, commonly below /var/lib/asterisk/sounds.
  • Use a full path for media stored outside those locations.
  • Playback is non-interruptible for caller DTMF; use Background for interactive prompts.
  • A typical announcement flow is Answer(), Playback(), then Hangup().