Configuring a Media Playback Service

Pexip's Media Playback Service allows you to play prerecorded video content (such as adverts and informational videos) to consumers. When the media finishes playing, the user can be transferred to another service, such as a VMR conference, or they can be disconnected.

Third-party integrators with sophisticated Pexip Infinity integrations who use external policy servers, event sinks, and the Pexip Infinity management API can extend this base functionality. For example they could play content in response to events within other systems, such as consumers who are being held in a queuing system, before transferring them into a VMR. Alternatively, consumers could be transferred from a VMR conference into a playback service.

A Media Playback Service can be accessed via any of the Connect apps or with hardware endpoints. To provide consumers with the most straightforward access to a service via the Connect web app (which removes the need to install a software client) you may want to prepare and share preconfigured links.

Whether being ultimately transferred or disconnected, multiple users can use the same playback service concurrently, but each user views the media independently, and they do not share their own video or audio with anyone while they are connected to the Media Playback Service. After transferring to a VMR, all the usual controls and two-way audio and video features are available.

Configuration and usage overview

To configure a Media Playback Service you need to:

  1. Upload MP4 files to your media library.
  2. Create a playlist with one or more videos.
  3. Configure a Media Playback Service specifying which playlist to run and an alias to access the service.

This topic also covers:

For more information about external integrations with Pexip Infinity, see Introduction to the management API and Using the external policy server API with Pexip Infinity.

Participant authentication and roles

You can control access to a playback service by using PINs and by using Single Sign On (SSO) authentication.

The PIN entered by the user when accessing the playback service also determines the role the user has if they are subsequently transferred into a VMR:

  • By default, users keep the same role when transferring to another service afterwards, alternatively you can specify a role. (If you transfer as Guest and the target conference doesn't allow Guests, the participant still keeps the Guest role in that conference.)
  • If no PIN was required for the playback service, a Host role is assigned.
  • The Host or Guest role makes no difference to the user's experience while they are in the playback service.

The playback service's configuration needs to take into account the security requirements of the service that users are transferred to, if appropriate. This is because users are prompted only once for PINs / authentication details, based on the configuration of the playback service.

To configure the playback service’s PINs and authentication, see Participant authentication.

To configure the role a user has when transferring to another service, see Action to perform on playlist completion.

Playing media into a VMR

While the general usage of a Media Playback Service is for a consumer to dial (or be transferred) into an individual playback service, you can also make use of this feature to play prerecorded content into a VMR i.e. all of the participants who are currently in the VMR will see the media content simultaneously. The playback media appears as a standard participant in the conference, so you can use the standard layout controls or spotlighting to highlight the "media playback" participant as required.

To play media into a VMR, you create your playback service with the required media content in the usual way, and then from within an ongoing conference you can add a participant (i.e. dial out) to that playback service, i.e. by specifying the alias of the playback service as the participant you want to add to the conference. Note that:

Uploading media

To upload media for a Media Playback Service, go to Services > Media Playback Upload. The options are:

Option Description
Name The name used to refer to this Media Library item.
Description A description of the media.
Media file

The media file you want to upload, it must be in MP4 video format and H.264 encoded.

We recommend the file is encoded using the "baseline" profile and "fastdecode", for example:
ffmpeg -i '<media file>' -c:v libx264 -preset slow -profile:v baseline -tune fastdecode 'baseline-fastcpu-720p.mp4'

Individual files up to 2 GB may be uploaded, and the cumulative size of all files together may be up to 10 GB.

Later, when you configure the Media Playback Service, you should set the Maximum call quality setting to match the resolution of the media files.

Creating a playlist

To configure a Media Playback Service playlist, go to Services > Media Playback Playlist. The options are:

Option Description
Name The name used to refer to this playlist.
Description A description of the playlist.
Loop If enabled, for a given call the whole playlist is repeated until the user disconnects themselves or until the call is terminated programmatically via the management API.
Shuffle

If enabled, the playlist is shuffled so that all media items are played in a random order (media items’ specified positions are not used).

If the playlist contains an item with a play count greater than one, each instance is shuffled and played once. For example, if an item has a play count of 3, all 3 instances are shuffled among the other media items.

If both shuffle and loop are enabled, all iterations of the playlist play in the same order.

Media Playlist Item
Position of item in playlist

Every item must have a unique position specified. This refers to the order in which in the Media Library Item is played relative to the other items in the playlist. Please note that Position is only used when shuffle is off.

When editing an existing playlist, if you want to change the position of multiple playlist items, you need to make each edit and save it individually.

Media Library Item Media Library Item to be played.
Play count for entry in playlist The number of times the item is played, the default is 1. If you set the value to 0 the item plays repeatedly until the user disconnects themselves or until the call is terminated programmatically via the management API.

Configuring a Media Playback Service and its aliases

To configure Media Playback Services and their associated aliases, go to Services > Media Playback Services. The options are:

Option Description
Name The name used to refer to this Media Playback Service.
Description A description of this Media Playback Service.
Theme The theme for use with this Media Playback Service. For more information, see Customizing conference images and voice prompts using themes.

Default: <use Default theme> (the global default theme is used).

Media playlist The playlist to be played when the Media Playback Service is accessed.
Action to perform on playlist completion

This defines what happens when the playlist finishes. The user can be disconnected or transferred elsewhere (to a VMR for example).

If the action is left blank, the video ends with the final frame remaining in view.

The completion action is specified in JSON format.

To disconnect the user, enter: {"disconnect": true}

Alternatively, to transfer the user, the format is:

{ "transfer": {"conference": "<alias>", "role": "<role>"}}

You must provide an alias to transfer the user to — this is typically the alias of a VMR.

Role is optional. If not supplied or if you specify a role of "auto", the user is transferred to the next service with the same role they had on accessing the playback service, unless:

  • no PINs are used to access the playback service, in which case users are transferred as Host by default
  • you specify "host" or "guest" role, in which case all users are transferred using the specified role.

For information about how the role for the Media Playback Service is determined see Participant authentication.

Participant authentication

The playback service's configuration needs to take into account the security requirements of the service that users are transferred to, if appropriate. This is because users are prompted only once for PINs / authentication details, based on the configuration of the playback service.

Host PIN
This optional field allows you to set a secure access code that must be entered before the user can access the playback service. This would give the user Host rights if they were subsequently transferred to a VMR, unless a different role is specified in the completion action.
  • PINs must use the digits 0-9 only.
  • PINs may optionally end with #.
  • PINs must be between 4–20 digits long, including any #.
Allow Guests

Set this to Yes if you want to configure a Guest PIN in addition to a Host PIN.

Guest/Host roles are treated the same in the playback service, but may be relevant if the user is subsequently transferred to a VMR.

Default: No.

Guest PIN

This optional field allows you to set a secure access code that must be entered before the user can access the playback service. This would give the user Guest rights if they were subsequently transferred to a VMR, unless a different role is specified in the completion action.

  • Host PINs and Guest PINs must be different.
  • PINs must use the digits 0-9 only.
  • PINs may optionally end with #.
  • PINs must be between 4–20 digits long, including any #.
  • If the Host PIN ends in # and a Guest PIN is used, the Guest PIN must also end with #.
  • If # is not used, Host PINs and Guest PINs must have the same number of digits.
  • You cannot configure a Guest PIN unless you have already configured a Host PIN.
Host Identity Provider Group

The set of Identity Providers to be offered to Hosts to authenticate with, in order to use the service. If this is blank, Hosts are not required to authenticate.

For more information, see see About participant authentication.

Default: none selected

Guest Identity Provider Group

The set of Identity Providers to be offered to Guests to authenticate with, in order to use the service. If this is blank, Guests are not required to authenticate.

For more information, see About participant authentication.

Default: none selected

Other participants

(Available when an Identity Provider Group has been selected)

Determines whether participants joining a SSO-protected service from devices other than the Connect web app (for example SIP or H.323 endpoints) are allowed to dial in to the service.

  • Disallow all: these devices may not join the service.
  • Allow if trusted: these devices may join the service if they are locally registered. They must still enter a Host PIN or Guest PIN if either is required.

For more information, see About participant authentication.

Default: Disallow all

Advanced options
Service tag This optional field lets you assign a unique identifier to this service, which you can then use to track use of the service.
Maximum call quality

Controls the maximum call quality for participants connecting to this service. This should be set to match the resolution of the playback video. For example, set it to HD if the playback videos are 720p and set it to Full HD if the videos are 1080p.

A failure to match the video resolution with the playback room call quality may degrade performance.

Aliases
Alias

The alias that, when received by Pexip Infinity, is used to route the call to this service.

The alias entered here must match the alias as it is received by Pexip Infinity. Wildcards and regular expressions are not supported.

In most cases, the alias received by Pexip Infinity is the same as the alias that the participant used to call the service, but there are some exceptions, described in About aliases and access numbers.

You may also want to define multiple aliases for the same service to ensure that it can be accessed by devices and protocols that enforce specific alias formats — for more information, see Using multiple aliases to access the same service.

Using the Connect app clients with a playback service

While a consumer is using a Connect app to view the media, as well as the disconnect button, they have controls for toggling their camera and mic, and they also see their self view, even though they are not sharing their own video or audio with anyone while they are connected to the Media Playback Service. After transferring to a VMR, all the usual VMR controls and two-way audio and video features are available.

Note that users cannot join a Media Playback Service as an audio-only participant (although they can disable their camera before joining as a video participant).

Conference and participant history

When viewing conference and participant history it shows both the playback service and the transferred-to VMR if appropriate. The disconnect reasons for the playback service are normally either "Call transferred" or "Call disconnected".