VoIP.infoThe independent guide to business communications.
VoIP.info Guide

Asterisk AMI ControlPlayback: target, initiator and result evidence

Control an existing channel playback without confusing action acceptance, playback initiation, skip timing, completion variables or audible output.

Reviewed 2026-10-25Current branch-23-generated, Asterisk 22 and Certified Asterisk 22.8 ControlPlayback action references, current and Asterisk 22 ControlPlayback application references, the current CONTROL STREAM FILE command, Certified Asterisk 22.8 Playback, CoreShowChannel and Manager API references were reviewed October 25, 2026; installed release, loaded modules and actions, manager permission, live channel identity, playback initiator, media file, language, format, skip interval, application state, bridge topology, packet path and endpoint output remain deployment-specific; no PBX, manager session, action, dialplan, AGI process, channel, playback, file, packet, media frame, endpoint, speaker or live call was inspected or testedAdvancedDocumentation based · not lab tested

Prove that playback already exists on the exact channel

Record the Asterisk node, installed release, manager identity, ActionID, exact Channel, Uniqueid, Linkedid, current application and application data, playback owner, media identifier and synchronized time. Resolve the channel immediately before control.

AMI ControlPlayback does not start media. Its documented target is the named channel that currently has a file playing, so an accepted request against a stale, bridged peer or channel without an active playback is not a substitute for proving the initiator and live target.

Choose only the documented control operation

The action documents stop, forward, reverse, pause and restart. Forward and reverse use the skipms value supplied by the operation that initiated playback; the documented default is 3000 ms. Preserve the configured interval instead of inferring movement from wall-clock listening alone.

Pause is a pause/unpause control when supported, not separate idempotent pause and resume states. Repeating it blindly can invert the intended result. Stop remains terminal for the current playback operation rather than a whole-call or channel hangup.

Match pause and restart to the playback initiator

Asterisk warns that pause and restart stop the playback when the media operation was not initiated by the ControlPlayback dialplan application or the CONTROL STREAM FILE AGI command. Identify the initiator before sending either control.

Ordinary Playback, Background, ARI playback objects, conference prompts and endpoint-local media have different control surfaces. Similar audible content does not make those mechanisms interchangeable with this AMI action.

Keep response, completion state and sound separate

Preserve the raw AMI response and matching ActionID as request-processing evidence. The ControlPlayback application and CONTROL STREAM FILE command document CPLAYBACKSTATUS, CPLAYBACKOFFSET and CPLAYBACKSTOPKEY after completion; read them only from the exact channel and workflow that owns them.

SUCCESS, USERSTOPPED, REMOTESTOPPED and ERROR describe completion state, while offset minus one identifies end of file. None alone proves that a listener heard the expected prompt, language, content, level or timing.

Rebuild identity after channel and bridge changes

CoreShowChannel can expose Channel, Uniqueid, Linkedid, BridgeId, Application, ApplicationData and Duration for a timestamped snapshot. Rebuild the intended target after transfer, Local-channel optimization, masquerade, bridge replacement or application transition.

The channel receiving audio and the channel executing the playback application may not match human caller and callee labels after topology changes. Bridge membership remains potential media relationship evidence rather than playback ownership or audible-result proof.

Validate control and recovery on disposable media

In an approved nonproduction call, use a known short file with authorized content and a recorded skip interval. Exercise one control at a time, preserving the response, current application, completion variables, packet or frame evidence and listener observation. Start a fresh playback before testing a terminal stop or an unsupported pause or restart path.

Use a dedicated least-privilege manager identity, bound retries and an application-owned recovery path. Documentation does not establish installed availability, compatibility, audible quality or safe behavior on production calls, and no live system was tested for this guide.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Guide · Current Asterisk interface documentation reviewed September 30, 2026; implementation must be checked against the installed branch and integration library

Asterisk AMI, ARI and AGI: choose the control boundary

Separate management events, synchronous dialplan work and application-owned call control before exposing an integration.

Read guide →
Guide · Asterisk branch-23-generated and branch-22-generated ListCommands references plus official AMI syntax, v2 specification, manager-command, change/versioning, permission, module-loader and network-security documentation reviewed October 16, 2026; installed branch and maintenance release, build, package and module set, manager user, read and write authorizations, session mask, action registration, request framing, parameters, target objects, response, related events and service outcome remain deployment specific; no PBX, module, package, manager user, manager session, request, response, event, configuration file, channel, packet, media stream or live call was inspected or tested

Asterisk AMI command inventory and permission evidence

Use ListCommands and the administrator CLI to distinguish the actions visible to one manager user from the actions registered by the running Asterisk instance.

Read guide →
Guide · Current Asterisk Latest API CHANNEL_EXISTS, CHANNELS and CHANNEL references, CLI channel-operation and Local-channel optimization documentation, AMI CoreShowChannels surfaces and the upstream func_channel implementation were reviewed October 19, 2026. The generated API pages reported branch 23; installed branch, loaded modules, channel drivers, names, unique IDs, linked IDs, Local optimization, permissions, timing and call outcomes remain deployment specific. No PBX, module, dialplan, channel, bridge, manager session, packet, media stream or live call was inspected or tested

Asterisk channel inventory, identity and lifetime

Treat a channel list as a changing observation, distinguish name from unique identity, and revalidate the exact leg before an authorized operation.

Read guide →
Guide · Current Asterisk branch-23-generated CoreShowChannelMap, CoreShowChannelMapComplete, CoreShowChannels, CoreShowChannel, CoreShowChannelsComplete, Status, StatusComplete, Newchannel and Rename references plus the branch 22 map action and completion event reviewed October 16, 2026; installed branch, loaded actions and events, manager permissions, session ordering, channel names, stable identifiers, bridge membership, variables, signaling and media remain deployment specific; no PBX, AMI session, manager user, permission, channel, bridge, variable, packet, media stream or live call was inspected or tested

Asterisk AMI channel snapshots and connected maps

Choose CoreShowChannels, CoreShowChannelMap or Status deliberately, preserve list boundaries, and correlate mutable channel, linked and bridge identities without treating a snapshot as a final call result.

Read guide →
Guide · Official current Asterisk AGI overview, Asterisk 23 AGI and EAGI application references, AGI command index, VERBOSE command, AsyncAGI AMI action and events, ASYNCAGI BREAK command and deprecated DeadAGI reference reviewed October 10, 2026; no host, process, executable, service account, FastAGI server, DNS or SRV record, TCP path, AMI session, channel, script, command, audio stream or call was inspected or tested

Asterisk AGI and FastAGI: bound synchronous call control and external dependencies

Choose local AGI, FastAGI, EAGI or AsyncAGI deliberately; constrain process, network and hangup behavior; and keep launch, protocol, application and call outcomes separate.

Read guide →
Guide · Current first-party Asterisk ARI playback, channel, bridge, sound, DTMF and configuration documentation reviewed October 9, 2026; no HTTP server, ARI user, WebSocket, Stasis application, channel, bridge, sound index, media file, playback, DTMF event, packet, endpoint, speaker or call was inspected or tested

Asterisk ARI playbacks: identity, scope and audible-result evidence

Start and control channel or bridge media with an application-owned playback ID, then prove resource state, event order and audible scope separately.

Read guide →
Guide · Current Asterisk ARI Sounds API, Asterisk 22 REST data models, ARI playback guidance, sound-prompt language search and prompt-format guidance reviewed October 10, 2026; no Asterisk host, sounds directory, package, index, prompt file, channel, language, codec, translation path, playback or call was inspected or tested

Asterisk ARI sounds: inventory, language and format boundaries

Use the ARI sound index to prove an exact prompt ID and its language-format variants without confusing discovery with channel fallback, translation or audible playback.

Read guide →
Guide · FreePBX 17 on Debian 12; System Recordings module, consuming module and Asterisk version must be verified on the installed host

FreePBX System Recordings: reusable audio, language and replacement boundaries

Manage the reusable recording object, its ordered media, language and rerecording controls separately from Announcements, IVRs and other call-flow consumers.

Read guide →
Guide · Sangoma PBX GUI 13 Sound Languages and Languages guides, FreePBX release/17.0 Sound Languages 17.0.5 and Languages 17.0.1 metadata and dialplan source, and current Asterisk prompt-search documentation reviewed October 10, 2026; the older screen guides establish documented concepts rather than an exact FreePBX 17 field map, and repository versions do not prove the installed module, signature, saved state, generated or loaded dialplan, sound files, channel language, selected prompt or audible result on any PBX

FreePBX Sound Languages: separate prompt packs from call-flow selection

Set a global default, install only the required language and format packs, and change channel language at explicit call-flow boundaries with controlled fallback tests.

Read guide →
Troubleshooting · Current branch-23-generated, Asterisk 22 and Certified Asterisk 22.8 ControlPlayback action references, current and Asterisk 22 ControlPlayback application references, the current CONTROL STREAM FILE command, Certified Asterisk 22.8 Playback, CoreShowChannel and Manager API references were reviewed October 25, 2026; installed release, loaded modules and actions, manager permission, live channel identity, playback initiator, media file, language, format, skip interval, application state, bridge topology, packet path and endpoint output remain deployment-specific; no PBX, manager session, action, dialplan, AGI process, channel, playback, file, packet, media frame, endpoint, speaker or live call was inspected or tested

Asterisk AMI ControlPlayback stops, targets the wrong channel or has no effect

Find the first divergence across action availability, live channel identity, playback initiator, control support, skip timing, completion state and audible output.

Read guide →