OpenTok
Contains methods for creating OpenTok sessions, generating tokens, and working with archives.
To create a new OpenTok object, call the OpenTok() constructor with your OpenTok API key and the API secret for your OpenTok Video API account. Do not publicly share your API secret. You will use it with the OpenTok() constructor (only on your web server) to create OpenTok sessions.
If you set api_key to a VONAGE_APPLICATION_ID and api_secret to a VONAGE_PRIVATE_KEY_PATH, the SDK will hit Vonage Video with Vonage Auth instead.
Be sure to include the entire OpenTok server SDK on your web server.
Table of Contents
$vonage : bool
connectAudio() : array<string|int, mixed> : Starts an Audio Connector WebSocket connection. to send audio from a Vonage Video API session to a WebSocket.
createSession() : Session : Creates a new OpenTok session and returns the session ID, which uniquely identifies the session.
deleteArchive() : bool : Deletes an OpenTok archive.
dial() : SipCall : Initiates an outgoing SIP call.
disableForceMute() : bool : Disables the active mute state of the session. After you call this method, new streams published to the session will no longer have audio muted.
forceDisconnect() : mixed : Disconnects a specific client from an OpenTok session.
forceMuteAll() : bool : Force all streams (except for an optional list of streams) in an OpenTok session to mute published audio.
forceMuteStream() : bool : Force the publisher of a specific stream to mute its published audio.
generateToken() : string : Creates a token for connecting to an OpenTok session.
getArchive() : Archive : Gets an Archive object for the given archive ID.
getBroadcast() : Broadcast : Gets information about an OpenTok broadcast.
getRender() : Render : Fetch an existing render to view status. Status can be one of: <ul> <li><code>starting</code> — The Vonage Video API platform is in the process of connecting to the remote application at the URL provided. This is the initial state.</li> <li><code>started</code> — The Vonage Video API platform has succesfully connected to the remote application server, and is republishing that media into the Vonage Video API platform.</li> <li><code>stopped</code> — The Render has stopped.</li> <li><code>failed</code> — An error occurred and the Render could not proceed. It may occur at startup if the opentok server cannot connect to the remote application server or republish the stream. It may also occur at point during the rendering process due to some error in the Vonage Video API platform.</li> </ul>
getStream() : Stream : Gets an Stream object, providing information on a given stream.
listArchives() : ArchiveList : Returns a list of archives for a session.
listRenders() : mixed : Returns a list of Experience Composer renderers for an OpenTok project.
listStreams() : StreamList : Returns a StreamList Object for the given session ID.
playDTMF() : void : Plays a DTMF string into a session or to a specific connection
setArchiveLayout() : void : Updates the stream layout in an OpenTok Archive.
setStreamClassLists() : mixed : Sets the layout class list for streams in a session.
signal() : mixed : Sends a signal to clients (or a specific client) connected to an OpenTok session.
startArchive() : Archive : Starts archiving an OpenTok session.
startBroadcast() : Broadcast : Starts a live streaming broadcast of an OpenTok session.
startCaptions() : array<string|int, mixed> : Use this method to start real-time Live Captions for an OpenTok Session.
startRender() : Render : Starts an Experience Composer renderer for an OpenTok session.
stopArchive() : Archive : Stops an OpenTok archive that is being recorded.
stopBroadcast() : Broadcast : Stops a broadcast.
stopCaptions() : mixed : Use this method to stop live captions for a session.
stopRender() : mixed : Stops an existing render.
updateBroadcastLayout() : void : Updates the layout of the broadcast.
updateStream() : mixed : Sets the layout class list for a stream.
returnLegacyToken() : string
Properties
$vonage
private bool $vonage = false
Override to determine whether to hit Vonage servers with Vonage Auth in requests
Methods
connectAudio()
Starts an Audio Connector WebSocket connection. to send audio from a Vonage Video API session to a WebSocket.
public connectAudio(string $sessionId, string $token, array<string|int, mixed> $websocketOptions) : array<string|int, mixed>
Parameters
$sessionId : string : The session ID.
$token : string : The OpenTok token to be used for the Audio Connector to the OpenTok session. You can add token data to identify that the connection is the Audio Connector endpoint or for other identifying data.
$websocketOptions : array<string|int, mixed> : Configuration for the Websocket. Contains the following keys:
- `'uri'` (string) — A publically reachable WebSocket URI controlled by the customer for the destination of the connect call. (f.e. wss://service.com/wsendpoint)
- `'streams'` (array) — (Optional) The stream IDs of the participants' whose audio is going to be connected. If not provided, all streams in session will be selected.
- `'headers'` (array) — (Optional) An object of key/val pairs with additional properties to send to your Websocket server, with a maximum length of 512 bytes.
Return values
array<string|int, mixed> —
$response Response from the API, structured as follows:
'id'(string) — A unique ID identifying the Audio Connector WebSocket.'connectionId'(string) — Opentok client connectionId that has been created. This connection will subscribe and forward the streams defined in the payload to the WebSocket, as any other participant, will produce a connectionCreated event on the session.
createSession()
Creates a new OpenTok session and returns the session ID, which uniquely identifies the session.
public createSession([array<string|int, mixed> $options = array() ]) : Session
For example, when using the OpenTok JavaScript library, use the session ID when calling the OT.initSession() method (to initialize an OpenTok session).
OpenTok sessions do not expire. However, authentication tokens do expire (see the generateToken() method). Also note that sessions cannot explicitly be destroyed.
A session ID string can be up to 255 characters long.
Calling this method results in an OpenTokException in the event of an error. Check the error message for details.
You can also create a session by logging in to your OpenTok Video API account.
Parameters
$options : array<string|int, mixed> = array() : (Optional) This array defines options for the session. The array includes the following keys (all of which are optional):
- `'archiveMode'` (ArchiveMode) — Whether the session is automatically
archived (`ArchiveMode::ALWAYS`) or not (`ArchiveMode::MANUAL`).
By default, the setting is `ArchiveMode.MANUAL`, and you must call the
`OpenTok->startArchive()` method to start archiving. To archive the session
(either automatically or not), you must set the `mediaMode` key to
`MediaMode::ROUTED`.
- `'e2ee'` (Boolean) — Whether to enable
[end-to-end encryption](https://tokbox.com/developer/guides/end-to-end-encryption)
for a routed session.
- `archiveName` (String) — Name of the archives in auto archived sessions
- `archiveResolution` (Enum) — Resolution of the archives in
auto archived sessions. Can be one of "480x640", "640x480", "720x1280", "1280x720", "1080x1920", "1920x1080"
- `'location'` (String) — An IP address that the OpenTok servers
will use to situate the session in its global network. If you do not set a location hint,
the OpenTok servers will be based on the first client connecting to the session.
- `'mediaMode'` (MediaMode) — Whether the session will transmit
streams using the OpenTok Media Router (`MediaMode.ROUTED`) or not
(`MediaMode.RELAYED`). By default, the `mediaMode` property
is set to `MediaMode.RELAYED`.
With the `mediaMode` parameter set to `MediaMode.RELAYED`, the
session will attempt to transmit streams directly between clients. If clients cannot
connect due to firewall restrictions, the session uses the OpenTok TURN server to relay
audio-video streams.
The
[OpenTok Media Router](/opentok/guides/create-session/#media-mode) provides the following benefits:
- The OpenTok Media Router can decrease bandwidth usage in multiparty sessions.
(When the `mediaMode` parameter is set to `MediaMode.ROUTED`,
each client must send a separate audio-video stream to each client subscribing to
it.)
- The OpenTok Media Router can improve the quality of the user experience through
recovery. With these features, if a client's connectivity degrades to a degree
that it does not support video for a stream it's subscribing to, the video is dropped
on that client (without affecting other clients), and the client receives audio only.
If the client's connectivity improves, the video returns.
- The OpenTok Media Router supports the
[archiving](/opentok/guides/archiving)
feature, which lets you record, save, and retrieve OpenTok sessions.
Return values
Session —
A Session object representing the new session. Call the
getSessionId() method of this object to get the session ID. For example,
when using the OpenTok.js library, use this session ID when calling the
OT.initSession() method.
deleteArchive()
Deletes an OpenTok archive.
public deleteArchive(string $archiveId) : bool
You can only delete an archive which has a status of "available", "uploaded", or "deleted". Deleting an archive removes its record from the list of archives. For an "available" archive, it also removes the archive file, making it unavailable for download. For a "deleted" archive, the archive remains deleted.
Parameters
$archiveId : string : The archive ID of the archive you want to delete.
Tags
throws : ArchiveException
There archive status is not "available", "updated",
or "deleted".
Return values
bool —
Returns true on success.
dial()
Initiates an outgoing SIP call.
public dial(string $sessionId, string $token, string $sipUri[, array<string|int, mixed> $options = [] ]) : SipCall
For more information, see the OpenTok SIP Interconnect developer guide.
Parameters
$sessionId : string : The ID of the OpenTok session that the participant being called will join.
$token : string : The OpenTok token to be used for the participant being called. You can add token data to identify that the participant is on a SIP endpoint or for other identifying data, such as phone numbers. Generate a token using the OpenTok::generateToken() or Session::generateToken() method.
$sipUri : string : The SIP URI to be used as destination of the SIP Call initiated from OpenTok to the Third Party SIP Platform.
If the URI contains a transport=tlsheader, the negotiation between TokBox and
the SIP endpoint will be done securely. Note that this will only apply to the negotiation
itself, and not to the transmission of audio. To have audio transmission be encrypted,
see the "secure" property of the `options` parameter.
This is an example of secure call negotiation: "sip:access@thirparty.com;transport=tls".
This is an example of insecure call negotiation: "sip:access@thirparty.com".
$options : array<string|int, mixed> = [] : This array defines options for the SIP call. It includes the following keys, all of which are optional:
- `'headers'` (array) — Headers: Custom Headers to be added to the
SIP INVITE request initiated from OpenTok to the Third Party SIP Platform.
- `'auth'` (array) — Auth: Username and Password to be used in the SIP
INVITE request for HTTP Digest authentication in case this is required by the Third Party
SIP Platform.
- `'username'` (string) — The username to be used
in the the SIP INVITE request for HTTP digest authentication (if one
is required).
- `'password'` (string) — The password to be used
in the the SIP INVITE request for HTTP digest authentication.
- `'secure'` (Boolean) — Indicates whether the media
must be transmitted encrypted (true, the default) or not (false).
- `'observeForceMute'` (Boolean) — Whether the SIP endpoint should honor
[force mute moderation](https://tokbox.com/developer/guides/moderation/#force_mute)
(True) or not (False, the default).
- `'from'` (string) — The number or string that will be sent to
the final SIP number as the caller. It must be a string in the form of
"from@example.com", where from can be a string or a number. If from is set to a number
(for example, "14155550101@example.com"), it will show up as the incoming number
on PSTN phones. If from is undefined or set to a string (for example, "joe@example.com"),
+00000000 will show up as the incoming number on PSTN phones.
- `'streams'` (array) — The Stream IDs of the participants which will included in the SIP
call. If not provided, all streams in session will be selected.
Return values
SipCall —
An object contains the OpenTok connection ID and stream ID for the SIP call's connection in the OpenTok session. You can use the connection ID to terminate the SIP call, using the OpenTok::method_forceDisconnect() method.
disableForceMute()
Disables the active mute state of the session. After you call this method, new streams published to the session will no longer have audio muted.
public disableForceMute(string $sessionId, array<string|int, string> $options) : bool
After you call the OpenTok->forceMuteAll() method any streams published after the call are published with audio muted. Call the disableForceMute() method to remove the mute state of a session, so that new published streams are not automatically muted.
Parameters
$sessionId : string : The OpenTok session ID.
$options : array<string|int, string> : This array defines options and includes the following keys:
- `'excludedStreams'` (array, optional) — An array of stream IDs
corresponding to streams that should not be muted. This is an optional property.
If you omit this property, all streams in the session will be muted.
Return values
bool —
Whether the call succeeded or failed.
forceDisconnect()
Disconnects a specific client from an OpenTok session.
public forceDisconnect(string $sessionId, string $connectionId) : mixed
Parameters
$sessionId : string : The OpenTok session ID that the client is connected to.
$connectionId : string : The connection ID of the connection in the session.
Return values
mixed —
forceMuteAll()
Force all streams (except for an optional list of streams) in an OpenTok session to mute published audio.
public forceMuteAll(string $sessionId, array<string|int, string> $options) : bool
In addition to existing streams, any streams that are published after the call to this method are published with audio muted. You can remove the mute state of a session OpenTok->disableForceMute() method.
Also see the OpenTok->forceMuteStream() method.
Parameters
$sessionId : string : The OpenTok session ID.
$options : array<string|int, string> : This array defines options and includes the following keys:
- `'excludedStreams'` (array, optional) — An array of stream IDs
corresponding to streams that should not be muted. This is an optional property.
If you omit this property, all streams in the session will be muted.
Return values
bool —
Whether the call succeeded or failed.
forceMuteStream()
Force the publisher of a specific stream to mute its published audio.
public forceMuteStream(string $sessionId, string $streamId) : bool
Also see the OpenTok->forceMuteAll() method.
Parameters
$sessionId : string : The OpenTok session ID containing the stream.
$streamId : string : The stream ID.
Return values
bool —
Whether the call succeeded or failed.
generateToken()
Creates a token for connecting to an OpenTok session.
public generateToken(string $sessionId[, array<string|int, mixed> $payload = array() ][, bool $legacy = false ]) : string
In order to authenticate a user connecting to an OpenTok session, the client passes a token when connecting to the session.
For testing, you generate tokens or by logging in to your OpenTok Video API account.
Parameters
$sessionId : string : The session ID corresponding to the session to which the user will connect.
$payload : array<string|int, mixed> = array() : This array defines options for the token. This array includes the following keys, all of which are optional:
- `'role'` (string) — One of the constants defined in the RoleConstants
class. The default role is publisher
- `'expireTime'` (int) — The timestamp for when the token expires,
in milliseconds since the Unix epoch. The default expiration time is 24 hours
after the token creation time. The maximum expiration time is 30 days after the
token creation time.
- `'data'` (string) — A string containing connection metadata
describing the end-user. For example, you can pass the user ID, name, or other data
describing the end-user. The length of the string is limited to 1000 characters.
This data cannot be updated once it is set.
- `initialLayoutClassList` (array) — An array of class names (strings)
to be used as the initial layout classes for streams published by the client. Layout
classes are used in customizing the layout of videos in
[live streaming
broadcasts](https://tokbox.com/developer/guides/broadcast/live-streaming/) and
[composed
archives](https://tokbox.com/developer/guides/archiving/layout-control.html).
$legacy : bool = false
: Connection tokens are now SHA-256 signed JWTs.
Set this to true to create a token using the legacy T1 format.
Return values
string —
The token string.
getArchive()
Gets an Archive object for the given archive ID.
public getArchive(string $archiveId) : Archive
Parameters
$archiveId : string : The archive ID.
Tags
throws : ArchiveException
There is no archive with the specified ID.
throws : InvalidArgumentException
The archive ID provided is null or an empty string.
Return values
Archive —
The Archive object.
getBroadcast()
Gets information about an OpenTok broadcast.
public getBroadcast(string $broadcastId) : Broadcast
Parameters
$broadcastId : string : The ID of the broadcast.
Return values
An object with properties defining the broadcast.
getRender()
Fetch an existing render to view status. Status can be one of: <ul> <li><code>starting</code> — The Vonage Video API platform is in the process of connecting to the remote application at the URL provided. This is the initial state.</li> <li><code>started</code> — The Vonage Video API platform has succesfully connected to the remote application server, and is republishing that media into the Vonage Video API platform.</li> <li><code>stopped</code> — The Render has stopped.</li> <li><code>failed</code> — An error occurred and the Render could not proceed. It may occur at startup if the opentok server cannot connect to the remote application server or republish the stream. It may also occur at point during the rendering process due to some error in the Vonage Video API platform.</li> </ul>
public getRender( $renderId) : Render
Parameters
$renderId :
Return values
Render —
getStream()
Gets an Stream object, providing information on a given stream.
public getStream(string $sessionId, string $streamId) : Stream
Parameters
$sessionId : string : The session ID for the OpenTok session containing the stream.
$streamId : string : The stream ID.
Return values
Stream —
The Stream object.
listArchives()
Returns a list of archives for a session.
public listArchives(int $offset[, int $count = null ][, string $sessionId = null ]) : ArchiveList
The items() method of this object returns a list of
archives that are completed and in-progress, for your API key.
Parameters
$offset : int : Optional. The index offset of the first archive. 0 is offset of the most recently started archive. 1 is the offset of the archive that started prior to the most recent archive. If you do not specify an offset, 0 is used.
$count : int = null : Optional. The number of archives to be returned. The maximum number of archives returned is 1000.
$sessionId : string = null : Optional. The OpenTok session Id for which you want to retrieve Archives for. If no session Id is specified, the method will return archives from all sessions created with the API key.
Return values
An ArchiveList object. Call the items() method of the ArchiveList object to return an array of Archive objects.
listRenders()
Returns a list of Experience Composer renderers for an OpenTok project.
public listRenders(int $offset[, int $count = 50 ]) : mixed
Parameters
$offset : int
$count : int = 50
Return values
mixed —
listStreams()
Returns a StreamList Object for the given session ID.
public listStreams(string $sessionId) : StreamList
Parameters
$sessionId : string : The session ID.
Return values
A StreamList object. Call the items() method of the StreamList object to return an array of Stream objects.
playDTMF()
Plays a DTMF string into a session or to a specific connection
public playDTMF(string $sessionId, string $digits[, string $connectionId = null ]) : void
Parameters
$sessionId : string : The ID of the OpenTok session that the participant being called will join.
$digits : string : DTMF digits to play Valid DTMF digits are 0-9, p, #, and * digits. 'p' represents a 500ms pause if a delay is needed during the input process.
$connectionId : string = null : An optional parameter used to send the DTMF tones to a specific connection in a session.
Return values
void —
setArchiveLayout()
Updates the stream layout in an OpenTok Archive.
public setArchiveLayout(string $archiveId, Layout $layoutType) : void
Parameters
$archiveId : string
$layoutType : Layout
Return values
void —
setStreamClassLists()
Sets the layout class list for streams in a session.
public setStreamClassLists(string $sessionId[, array<string|int, mixed> $classListArray = array() ]) : mixed
Layout classes are used in the layout for composed archives and live streaming broadcasts. For more information, see Customizing the video layout for composed archives and Configuring video layout for OpenTok live streaming broadcasts.
Parameters
$sessionId : string : The session ID of the session the streams belong to.
$classListArray : array<string|int, mixed> = array() : The connectionId of the connection in a session.
Return values
mixed —
signal()
Sends a signal to clients (or a specific client) connected to an OpenTok session.
public signal(string $sessionId, array<string|int, mixed> $payload[, string $connectionId = null ]) : mixed
Parameters
$sessionId : string : The OpenTok session ID where the signal will be sent.
$payload : array<string|int, mixed> : This array defines the payload for the signal. This array includes the following keys, of which type is optional:
- `'data'` (string) — The data string for the signal. You can send a maximum of 8kB.
- `'type'` (string) — (Optional) The type string for the signal. You can send a maximum of 128 characters, and only the following characters are allowed: A-Z, a-z, numbers (0-9), '-', '\_', and '~'.
$connectionId : string = null : An optional parameter used to send the signal to a specific connection in a session.
Return values
mixed —
startArchive()
Starts archiving an OpenTok session.
public startArchive(string $sessionId[, array<string|int, mixed> $options = [] ]) : Archive
Clients must be actively connected to the OpenTok session for you to successfully start recording an archive.
You can only record one archive at a time for a given session. You can only record archives of sessions that use the OpenTok Media Router (sessions with the media mode set to routed); you cannot archive sessions with the media mode set to relayed.
For more information on archiving, see the OpenTok archiving programming guide.
Parameters
$sessionId : string : The session ID of the OpenTok session to archive.
$options : array<string|int, mixed> = [] : (Optional) This array defines options for the archive. The array includes the following keys (all of which are optional):
- `'name'` (String) — The name of the archive. You can use this name to
identify the archive. It is a property of the Archive object, and it is a property of
archive-related events in the OpenTok client SDKs.
- `'hasVideo'` (Boolean) — Whether the archive will record video
(true, the default) or not (false). If you set both `hasAudio` and
`hasVideo` to false, the call to the `startArchive()` method results
in an error.
- `'streamMode'` (String) — Whether streams included in the archive are
selected automatically (`StreamMode.AUTO`, the default) or manually
(`StreamMode.MANUAL`). When streams are selected automatically
(`StreamMode.AUTO`), all streams in the session can be included in the archive.
When streams are selected manually (`StreamMode.MANUAL`), you specify streams
to be included based on calls to the `Archive.addStreamToArchive()` and
`Archive.removeStreamFromArchive()`. methods. With manual mode, you can specify
whether a stream's audio, video, or both are included in the archive. In both automatic and
manual modes, the archive composer includes streams based on
[stream
prioritization rules](https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules).
- `'hasAudio'` (Boolean) — Whether the archive will record audio
(true, the default) or not (false). If you set both `hasAudio` and
`hasVideo` to false, the call to the `startArchive()` method results
in an error.
- `'multiArchiveTag'` (String) (Optional) — Set this to support recording multiple archives
for the same session simultaneously. Set this to a unique string for each simultaneous archive of an ongoing
session. You must also set this option when manually starting an archive
that is {https://tokbox.com/developer/guides/archiving/#automatic automatically archived}.
Note that the `multiArchiveTag` value is not included in the response for the methods to
{https://tokbox.com/developer/rest/#listing\_archives list archives} and
{https://tokbox.com/developer/rest/#retrieve\_archive\_info retrieve archive information}.
If you do not specify a unique `multiArchiveTag`, you can only record one archive at a time for a given session.
{https://tokbox.com/developer/guides/archiving/#simultaneous-archives See Simultaneous archives}.
- `'outputMode'` (OutputMode) — Whether all streams in the
archive are recorded to a single file (`OutputMode::COMPOSED`, the default)
or to individual files (`OutputMode::INDIVIDUAL`).
- `'resolution'` (String) — The resolution of the archive, either "640x480" (SD landscape,
the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280"
(HD portrait), or "1080x1920" (FHD portrait). This property only applies to composed archives. If you set
this property and set the outputMode property to "individual", a call to the method
results in an error.
Return values
Archive —
The Archive object, which includes properties defining the archive, including the archive ID.
startBroadcast()
Starts a live streaming broadcast of an OpenTok session.
public startBroadcast(string $sessionId[, array<string|int, mixed> $options = [] ]) : Broadcast
Parameters
$sessionId : string : The session ID of the session to be broadcast.
$options : array<string|int, mixed> = [] : (Optional) An array with options for the broadcast. This array has the following properties:
- `layout` (Layout) — (Optional) An object defining the initial
layout type of the broadcast. If you do not specify an initial layout type,
the broadcast stream uses the Best Fit layout type. For more information, see
[Configuring
Video Layout for the OpenTok live streaming feature](https://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-live-streaming-video-layout).
- `streamMode` (String) — Whether streams included in the broadcast
are selected automatically (`StreamMode.AUTO`, the default) or manually
(`StreamMode.MANUAL`). When streams are selected automatically
(`StreamMode.AUTO`), all streams in the session can be included in the broadcast.
When streams are selected manually (`StreamMode.MANUAL`), you specify streams
to be included based on calls to the `Broadcast.addStreamToBroadcast()` and
`Broadcast.removeStreamFromBroadcast()` methods. With manual mode, you can specify
whether a stream's audio, video, or both are included in the broadcast. In both automatic and
manual modes, the broadcast composer includes streams based on
[stream
prioritization rules](https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules).
- `multiBroadcastTag` (String) (Optional) — Set this to support multiple broadcasts for
the same session simultaneously. Set this to a unique string for each simultaneous broadcast of an ongoing session.
Note that the `multiBroadcastTag` value is \*not\* included in the response for the methods to
{https://tokbox.com/developer/rest/#list\_broadcasts list live streaming broadcasts} and
{https://tokbox.com/developer/rest/#get\_info\_broadcast get information about a live streaming broadcast}.
{https://tokbox.com/developer/guides/broadcast/live-streaming#simultaneous-broadcasts See Simultaneous broadcasts}.
- `resolution` — The resolution of the broadcast: either "640x480" (SD landscape, the default), "1280x720" (HD landscape),
"1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920"
(FHD portrait).
- `maxBitRate` — Max Bitrate allowed for the broadcast composing. Must be between
400000 and 2000000.
- `outputs` (Array) —
Defines the HLS broadcast and RTMP streams. You can provide the following keys:
- `hls` (Array) — available with the following options:
- `'dvr'` (Bool) — Whether to enable
[DVR functionality](https://tokbox.com/developer/guides/broadcast/live-streaming/#dvr)
— rewinding, pausing, and resuming — in players that support it (`true`),
or not (`false`, the default). With DVR enabled, the HLS URL will include
a ?DVR query string appended to the end.
- `'lowLatency'` (Bool) — Whether to enable
[low-latency mode](https://tokbox.com/developer/guides/broadcast/live-streaming/#low-latency)
for the HLS stream. Some HLS players do not support low-latency mode. This feature
is incompatible with DVR mode HLS broadcasts.
- `rtmp` (Array) — An array of arrays defining RTMP streams to broadcast. You
can specify up to five target RTMP streams. Each RTMP stream array has the following keys:
- `id` (String) — The stream ID (optional)
- `serverUrl` (String) — The RTMP server URL
- `streamName` (String) — The stream name, such as
the YouTube Live stream name or the Facebook stream key
Return values
An object with properties defining the broadcast.
startCaptions()
Use this method to start real-time Live Captions for an OpenTok Session.
public startCaptions(string $sessionId, string $token[, string $languageCode = null ][, int $maxDuration = null ][, bool $partialCaptions = null ][, string $statusCallbackUrl = null ]) : array<string|int, mixed>
The maximum allowed duration is 4 hours, after which the audio captioning will stop without any effect on the ongoing OpenTok Session. An event will be posted to your callback URL if provided when starting the captions.
Each OpenTok Session supports only one audio captioning session.
For more information about the Live Captions feature, see the Live Captions developer guide.
Parameters
$sessionId : string : The session ID of the OpenTok session. The audio from Publishers publishing into this session will be used to generate the captions.
$token : string : A valid OpenTok token with role set to Moderator.
$languageCode : string = null : (Optional) The BCP-47 code for a spoken language used on this call. The default value is "en-US". The following language codes are supported: "en-AU" (English, Australia), "en-GB" (English, UK), "en-US" (English, US), "es-US" (Spanish, US), "zh-CN” (Chinese, Simplified), "fr-FR" (French), "fr-CA" (French, Canadian), "de-DE" (German), "hi-IN" (Hindi, Indian), "it-IT" (Italian), "ja-JP" (Japanese), "ko-KR" (Korean), "pt-BR" (Portuguese, Brazilian), "th-TH" (Thai).
$maxDuration : int = null : (Optional) The maximum duration for the audio captioning, in seconds. The default value is 14,400 seconds (4 hours), the maximum duration allowed.
$partialCaptions : bool = null : (Optional) Whether to enable this to faster captioning at the cost of some degree of inaccuracies. The default value is true.
$statusCallbackUrl : string = null : (Optional) A publicly reachable URL controlled by the customer and capable of generating the content to be rendered without user intervention. The minimum length of the URL is 15 characters and the maximum length is 2048 characters. For more information, see Live Caption status updates.
Return values
array<string|int, mixed> —
startRender()
Starts an Experience Composer renderer for an OpenTok session.
public startRender( $sessionId, $token, $url, $maxDuration, $resolution, $properties) : Render
For more information, see the Experience Composer developer guide.
Parameters
$sessionId : : (string) The session ID of the OpenTok session that will include the Experience Composer stream.
$token : : (string) A valid OpenTok token with a Publisher role and (optionally) connection data to be associated with the output stream.
$url : : (string) A publicly reachable URL controlled by the customer and capable of generating the content to be rendered without user intervention. The minimum length of the URL is 15 characters and the maximum length is 2048 characters.
$maxDuration : : (int) (optional) The maximum time allowed for the Experience Composer, in seconds. After this time, it is stopped automatically, if it is still running. The maximum value is 36000 (10 hours), the minimum value is 60 (1 minute), and the default value is 7200 (2 hours). When the Experience Composer ends, its stream is unpublished and an event is posted to the callback URL, if configured in the Account Portal.
$resolution : : (string) (optional) The resolution of the Experience Composer, either "640x480" (SD landscape), "480x640" (SD portrait), "1280x720" (HD landscape), "720x1280" (HD portrait), "1920x1080" (FHD landscape), or "1080x1920" (FHD portrait). By default, this resolution is "1280x720" (HD landscape, the default).
$properties : : (array) (optional) The initial configuration of Publisher properties for the composed output stream.
- `name` (String) (optional) — Serves as the name of the composed output stream which is published to the session. The name must have a minimum length of 1 and
a maximum length of 200.
Return values
Render —
The render object, which includes properties defining the render, including the render ID.
stopArchive()
Stops an OpenTok archive that is being recorded.
public stopArchive(string $archiveId) : Archive
Archives automatically stop recording after 120 minutes or when all clients have disconnected from the session being archived.
Parameters
$archiveId : string : The archive ID of the archive you want to stop recording.
Return values
Archive —
The Archive object corresponding to the archive being stopped.
stopBroadcast()
Stops a broadcast.
public stopBroadcast(string $broadcastId) : Broadcast
Parameters
$broadcastId : string : The ID of the broadcast.
Return values
stopCaptions()
Use this method to stop live captions for a session.
public stopCaptions(string $captionsId) : mixed
Parameters
$captionsId : string
Return values
mixed —
stopRender()
Stops an existing render.
public stopRender( $renderId) : mixed
Parameters
$renderId :
Return values
mixed —
updateBroadcastLayout()
Updates the layout of the broadcast.
public updateBroadcastLayout(string $broadcastId, Layout $layout) : void
See Configuring video layout for OpenTok live streaming broadcasts.
Parameters
$broadcastId : string : The ID of the broadcast.
$layout : Layout : An object defining the layout type for the broadcast.
Return values
void —
updateStream()
Sets the layout class list for a stream.
public updateStream(string $sessionId, string $streamId[, array<string|int, mixed> $properties = array() ]) : mixed
Layout classes are used in the layout for composed archives and live streaming broadcasts.
For more information, see Customizing the video layout for composed archives and Configuring video layout for OpenTok live streaming broadcasts.
You can set the initial layout class list for streams published by a client when you generate the token used by the client to connect to the session. See the OpenTok::generateToken() method.
Parameters
$sessionId : string : The session ID of the session the stream belongs to.
$streamId : string : The stream ID.
$properties : array<string|int, mixed> = array()
: An array containing one property: $layoutClassList.
This property is an array of class names (strings) to apply to the
stream. Set $layoutClassList to an empty array to clear the layout class list for
a stream. For example, this code sets the stream to use two classes:
```
$streamProperties = array(
'$layoutClassList' => array('bottom', 'right')
);
$opentok->updateStream($sessionId, $streamId, $streamProperties);
```
Return values
mixed —
returnLegacyToken()
private returnLegacyToken(string $sessionId[, array<string|int, mixed> $options = [] ]) : string
Parameters
$sessionId : string
$options : array<string|int, mixed> = []
Return values
string —