Can initiate both synchronous playback, in which control will be transferred to the next component only after playback has finished, and background playback, in which control will be transferred to the next component immediately after playback starts. \ Background playback control allows for pauses and stops. Resuming playback is possible from the specified millisecond of a particular file. +\ Supports sequential and cyclic playback of random files in a specified directory.

Component Playback

:icons:font :hardbreaks: :imagesdir: ../../../assets/images :toc-title: Contents :toc:

Description

Plays an audio file to the subscriber. +\

Table 1. System characteristics

Index

204

Short name

play

Script types

IVR

Start module

r_sip_ivr_script_component_play

Mode

Asynchronous

Icon

204

Branching type

Branching, closing

Properties

Table 2. Properties
Specification Description

Name: Layer

Code: playerId

Visibility condition: no

Default: "default"

Select playback layer.

A layer is a separate termination in the IVR media context that plays no more than one file at a time.

Thus, the IVR script in various playback modes, including background, can simultaneously play several files - they are all mixed.

Name: Mode

Code: mode

Visibility condition: no

Default: Complete file

Selecting the operating mode of the component.

Possible options:

  • Complete file (syncPlayFile, 0) – Plays an audio file and waits for it to complete. If a directory is specified as parameters, then a random file from the directory is played.

  • Preview (syncPlayFileLimit, 1) – Plays back while waiting for it to complete and limiting the playback time.

  • File + additional time (syncPlayFileExtra, 2) – Plays back while waiting for its completion and waiting for an additional pause used to complete the DTMF characters.

  • File List (syncPlayFiles, 7) – Plays a sequential list of files. Optionally, it can wait for an additional pause used to complete the input of DTMF characters.

  • Background Play (asyncPlayStart, 3) – Adds a layer and initiates background playback on it, immediately passing control to the next component. If playback is already in progress in the specified layer, it is automatically interrupted.

  • Stop background (asyncPlayStop, 4) – Stops playback in the specified layer.

  • Change background volume (asyncModifyVolume, 6) – Changes the volume of the file being played in the background on the specified layer.

Name: Time, s

Code: playTimeSec

Visibility condition: yes

Default: — 

Limit on playback time, in seconds.

Used in Preview mode.

Name: Additional time, s

Code: extraTimeSec

Visibility condition: yes

Default: 0

Timeout for additional pause after playback ends, in seconds.

Applicable in File + extra time and File List modes.

Name: Directory Code: folder Visibility condition: yes

Default: — 

An argument containing the directory path.

Must include one of file categories.

Name: Random

Code: randomize

Visibility condition: yes Default: Yes

Random selection mode for the next file from the directory.

Used when specifying a directory with audio files as a source.

  • Yes – at the beginning and at the end of playback of each audio file, the next file is selected randomly.

  • No – files are played in lexical-graphic sorting order by name.

Name: File Code: file Visibility condition: yes

Default: — 

File to play.

Can be selected in one of the modes:

  • static file attached to the script (downloaded from the Script Editor application or via the API);

  • argument-generated path, which must include one of file categories.

Name: Stream file

Code: fileCanGrow

Visibility condition: yes

Default: No

Streaming mode for growing files.

Applies only in playback modes: Full file, Preview, File + extra time, Background playback when playing one specific file.

The mode is useful for the needs of organizing streaming playback, for example, when data is generated gradually by an external service and must be immediately sent to the voice channel.

In this mode, only a WAV file can be played, the size of which in the header is obviously larger than the number of samples that are located in the file.

If playback reaches the current end of the file, and the file size specified in the WAV header has not been reached, the player generates silence.

As samples are added to the end of the file, playback continues.

Playback ends when the number of played samples from the file matches the specified number of samples in the Wav header.

At the same time, it is possible to overwrite the size in the Wav header when the data runs out.

Possible options:

  • No – normal playback mode.

  • Yes – playback from a growing WAV file is allowed.

Name: Data reception timeout, ms

Code: growingTimeoutMs

Visibility condition: yes Default: 0

When playing a streaming file while waiting for data to arrive, when there is not enough data, silence is played. To complete playback, you need to write the actual data size in the header.

The parameter allows you to set the time limit in milliseconds when silence is played while waiting for data to arrive.

Value 0 - timeout is not applied.

Name: Files (JSON list)

Code: filesArg

Visibility condition: yes Default: — 

An argument containing a JSON structure as an array of strings, each representing a path to a file.

Each path must include one of file categories.

The files are played in the order they appear in the list.

Name: Loop

Code: loop

Visibility condition: yes Default: No

Disables continuous loop playback mode.

When playing through directory selection, a new file is randomly selected each time.

Name: Start, ms

Code: startAt

Visibility condition: yes

Default: — 

Argument containing the offset to start playback, in milliseconds. Makes sense when playing a file without looping.

Name: End, ms

Code: stopAt

Visibility condition: yes

Default: — 

Argument containing the final position in the file, in milliseconds.

Makes sense when playing a file without looping.

Name: Volume (divider)

Code: volumeDiv

Visibility condition: yes

Default: — 

Argument containing the playback volume divisor in the layer

Name: Buffer for DTMF

Code: dtmfBuffer

Visibility condition: yes Default: — 

Variable for storing received DTMF characters.

Name: Clear DTMF buffer

Code: clearDtmfBuffer

Visibility condition: yes

Default: Yes

DTMF buffer pre-clear switch.

Name: Number of characters Code: maxSymbolCount Visibility condition: yes

Default: — 

An argument containing a limit on the number of characters entered.

After receiving the specified number of DTMF characters during the execution of a component, the recording is automatically completed and the last portion of voice data is sent to the recognition service.

Name: Interrupt characters

Code: interruptSymbols

Visibility condition: yes Default: — 

A string containing sequences of break characters separated by commas.

After detecting a character sequence at the end of the DTMF buffer that matches one of the specified interrupt sequences, the recording is automatically completed and the last portion of data is sent to the recognition service.

For example, *, 7, 123, 9395.

Name: Cut interrupt characters

Code: clearInterrupt

Visibility condition: yes Default: Yes

Switch for the operation of removing interrupt characters from the DTMF buffer after detecting an interrupt sequence.

Name: Transition

Code: transfer

Visibility condition: no

Default: — 

The component to which control is transferred upon successful completion of the operation.

Name: Transition, error Code: transferError Visibility condition: no

Default: — 

Component to which control is transferred in case of an error.

See also