Package com.vonage.client.video

Class VideoClient

java.lang.Object
com.vonage.client.video.VideoClient
public class VideoClient extends Object
A client for using the Vonage Video API. The standard way to obtain an instance of this class is to use VonageClient.getVideoClient().
Since:
8.0.0-beta1

  • Constructor Details

    • VideoClient

      public VideoClient(HttpWrapper wrapper)
      Constructor.
      Parameters:
      wrapper - (REQUIRED) shared HTTP wrapper object used for making REST calls.

  • Method Details

    • generateToken

      public String generateToken(String sessionId, TokenOptions options)
      Generates a signed JSON Web Token which can be passed to the client.
      Parameters:
      sessionId - The session ID.
      options - Configuration parameters (claims) of the token, e.g. role, expiry time etc.
      Returns:
      The JWT with the specified properties, as a raw string.
      Since:
      8.0.0-beta2

    • generateToken

      public String generateToken(String sessionId)
      Generates a signed JSON Web Token which can be passed to the client, using the default token options.
      Parameters:
      sessionId - The session ID.
      Returns:
      The JWT with the default properties, as a raw string.
      Since:
      8.0.0-beta2
      See Also:

    • createSession

      public CreateSessionResponse createSession()
      Generate a new session, using default properties.
      Returns:
      Details of the created session.
      See Also:

    • createSession

      public CreateSessionResponse createSession(CreateSessionRequest request)
      Generate a new session.
      Parameters:
      request - (OPTIONAL) The session properties.
      Returns:
      Details of the created session.

    • listStreams

      public List<GetStreamResponse> listStreams(String sessionId)
      Use this method to get information on all Vonage Video streams in a session.
      Parameters:
      sessionId - The session ID.
      Returns:
      Details for each stream, as a List.
      See Also:

    • getStream

      public GetStreamResponse getStream(String sessionId, String streamId)
      Use this method to get information on a Vonage Video stream. For example, you can call this method to get information about layout classes used by a Vonage Video stream. The layout classes define how the stream is displayed in the layout of a broadcast stream.
      Parameters:
      sessionId - The session ID.
      streamId - ID of the stream to retrieve.
      Returns:
      Details of the requested stream.

    • setStreamLayout

      public void setStreamLayout(String sessionId, List<SessionStream> streams)
      Use this method to change layout classes for a Vonage Video stream. The layout classes define how the stream is displayed in the layout of a composed Vonage Video archive.
      Parameters:
      sessionId - The session ID.
      streams - The stream layouts to change.

    • setStreamLayout

      public void setStreamLayout(String sessionId, SessionStream... streams)
      Use this method to change layout classes for a Vonage Video stream. The layout classes define how the stream is displayed in the layout of a composed Vonage Video archive.
      Parameters:
      sessionId - The session ID.
      streams - The stream layouts to change.
      Since:
      8.0.0-beta2
      See Also:

    • signalAll

      public void signalAll(String sessionId, SignalRequest request)
      Sends signals to all participants in an active Vonage Video session.
      Parameters:
      sessionId - The session ID.
      request - Signal payload.

    • signal

      public void signal(String sessionId, String connectionId, SignalRequest request)
      Sends signal to a specific participant in an active Vonage Video session.
      Parameters:
      sessionId - The session ID.
      connectionId - Specific publisher connection ID.
      request - Signal payload.

    • forceDisconnect

      public void forceDisconnect(String sessionId, String connectionId)
      Force a client to disconnect from a session.
      Parameters:
      sessionId - The session ID.
      connectionId - Specific publisher connection ID.

    • muteStream

      public void muteStream(String sessionId, String streamId)
      Force mute a specific publisher stream.
      Parameters:
      sessionId - The session ID.
      streamId - ID of the stream to mute.

    • muteSession

      public ProjectDetails muteSession(String sessionId, boolean active, Collection<String> excludedStreamIds)
      Force all streams (except for an optional list of streams) in a session to mute published audio. You can also use this method to disable the force mute state of a session.
      Parameters:
      sessionId - The session ID.
      active - Whether to mute streams in the session (true) and enable the mute state of the session, or to disable the mute state of the session (false). With the mute state enabled (true), all current and future streams published to the session (except streams in "excludedStreamIds") are muted. If this is set to false, future streams published to the session are not muted (but any existing muted streams will remain muted).
      excludedStreamIds - (OPTIONAL) The stream IDs for streams that should not be muted. If you omit this, all streams in the session will be muted. This only applies when the "active" property is set true. When the "active" property is set to false, it is ignored.
      Returns:
      Details about the Vonage Video project.

    • muteSession

      public void muteSession(String sessionId, boolean active, String... excludedStreamIds)
      Force all streams (except for an optional list of streams) in a session to mute published audio. You can also use this method to disable the force mute state of a session.
      Parameters:
      sessionId - The session ID.
      active - Whether to mute streams in the session (true) and enable the mute state of the session, or to disable the mute state of the session (false). With the mute state enabled (true), all current and future streams published to the session (except streams in "excludedStreamIds") are muted. If this is set to false, future streams published to the session are not muted (but any existing muted streams will remain muted).
      excludedStreamIds - (OPTIONAL) The stream IDs for streams that should not be muted. If you omit this, all streams in the session will be muted. This only applies when the "active" property is set true. When the "active" property is set to false, it is ignored.
      See Also:

    • sipDial

      public SipDialResponse sipDial(SipDialRequest request)
      Use this method to connect your SIP platform to a Vonage video session. The audio from your end of the SIP call is added to the video session as an audio-only stream. The Vonage Media Router mixes audio from other streams in the session and sends the mixed audio to your SIP endpoint.

      The call ends when your SIP server sends a BYE message (to terminate the call). You can also end a call using forceDisconnect(String, String). The Vonage Video SIP gateway automatically ends a call after 5 minutes of inactivity (5 minutes without media received). Also, as a security measure, the Vonage Video SIP gateway closes any SIP call that lasts longer than 6 hours.

      The SIP interconnect feature requires that you use video session that uses the Vonage Media Router (a session with the media mode set to MediaMode.ROUTED).

      For more information, including technical details and security considerations, see the Vonage SIP interconnect developer guide.

      Parameters:
      request - The outbound SIP call's properties.
      Returns:
      Details of the SIP connection.
      Since:
      8.0.0-beta4

    • sendDtmf

      public void sendDtmf(String sessionId, String connectionId, String digits)
      Play DMTF tones into a specific connection. Telephony events are negotiated over SDP and transmitted as RFC4733/RFC2833 digits to the remote endpoint.
      Parameters:
      sessionId - The session ID.
      connectionId - Specific publisher connection ID.
      digits - The string of DTMF digits to send. This can include 0-9, '*', '#', and 'p'. A 'p' indicates a pause of 500ms (if you need to add a delay in sending the digits).
      Since:
      8.0.0-beta4

    • sendDtmf

      public void sendDtmf(String sessionId, String digits)
      Play DTMF tones into a SIP call. Telephony events are negotiated over SDP and transmitted as RFC4733/RFC2833 digits to the remote endpoint.
      Parameters:
      sessionId - The session ID.
      digits - The string of DTMF digits to send. This can include 0-9, '*', '#', and 'p'. A 'p' indicates a pause of 500ms (if you need to add a delay in sending the digits).
      Since:
      8.0.0-beta4

    • listArchives

      public List<Archive> listArchives()
      List all archives in the application. Deleted archives are not included in the results.
      Returns:
      The list of archives up to the first 1000, in order from newest to oldest.
      See Also:

    • listArchives

      public List<Archive> listArchives(ListStreamCompositionsRequest request)
      List all archives in the application. Deleted archives are not included in the results.
      Parameters:
      request - (OPTIONAL) Filter properties of the request.
      Returns:
      The list of archives matching the filter criteria, in order from newest to oldest.

    • getArchive

      public Archive getArchive(String archiveId)
      Retrieve information about a specific archive.
      Parameters:
      archiveId - ID of the archive to retrieve.
      Returns:
      The Archive corresponding to the archiveId.

    • createArchive

      public Archive createArchive(Archive request)
      Create a new archive.
      Parameters:
      request - Properties of the archive.
      Returns:
      The created Archive.

    • updateArchiveLayout

      public void updateArchiveLayout(String archiveId, StreamCompositionLayout layout)
      Dynamically change the layout type of a composed archive while it is being recorded.
      Parameters:
      archiveId - ID of the archive to change.
      layout - Properties of the layout change request.

    • addArchiveStream

      public void addArchiveStream(String archiveId, String streamId)
      Adds a stream to a composed archive that was started with the streamMode set to StreamMode.MANUAL.
      Parameters:
      archiveId - ID of the archive.
      streamId - ID of the stream to add.
      See Also:

    • addArchiveStream

      public void addArchiveStream(String archiveId, String streamId, Boolean audio, Boolean video)
      Adds a stream to a composed archive.
      Parameters:
      archiveId - ID of the archive.
      streamId - ID of the stream to add.
      audio - (OPTIONAL) Whether the composed archive should include the stream's audio (true by default).
      video - (OPTIONAL) Whether the composed archive should include the stream's video (true by default).

    • removeArchiveStream

      public void removeArchiveStream(String archiveId, String streamId)
      Removes a stream from a composed archive that was started with the streamMode set to StreamMode.MANUAL.
      Parameters:
      archiveId - ID of the archive.
      streamId - ID of the stream to remove.

    • stopArchive

      public Archive stopArchive(String archiveId)
      Archives stop recording after 4 hours (14,400 seconds), or 60 seconds after the last client disconnects from the session, or 60 minutes after the last client stops publishing. However, automatic archives continue recording to multiple consecutive files of up to 4 hours in length each.

      Calling this method for automatic archives has no effect. Automatic archives continue recording to multiple consecutive files of up to 4 hours (14,400 seconds) in length each, until 60 seconds after the last client disconnects from the session, or 60 minutes after the last client stops publishing a stream to the session.

      Parameters:
      archiveId - ID of the archive to stop.
      Returns:
      The Archive corresponding to the archiveId.

    • deleteArchive

      public void deleteArchive(String archiveId)
      Deletes an archive. You can only delete an archive which has a status of ArchiveStatus.AVAILABLE or ArchiveStatus.UPLOADED. Deleting an archive removes its record from the list of archives (see listArchives()). For an "available" archive, it also removes the archive file, making it unavailable for download.
      Parameters:
      archiveId - ID of the archive to delete.

    • listBroadcasts

      public List<Broadcast> listBroadcasts()
      List all broadcasts that are in progress and started in the application. Completed broadcasts are not included in the listing.
      Returns:
      The list of broadcasts up to the first 1000, in order from newest to oldest.
      Since:
      8.0.0-beta4
      See Also:

    • listBroadcasts

      public List<Broadcast> listBroadcasts(ListStreamCompositionsRequest request)
      List all broadcasts that are in progress and started in the application. Completed broadcasts are not included in the listing.
      Parameters:
      request - (OPTIONAL) Filter properties of the request.
      Returns:
      The list of broadcasts matching the filter criteria, in order from newest to oldest.
      Since:
      8.0.0-beta4

    • getBroadcast

      public Broadcast getBroadcast(String broadcastId)
      Get Information about a Broadcast that is in progress.
      Parameters:
      broadcastId - ID of the broadcast to retrieve.
      Returns:
      The Broadcast corresponding to the broadcastId.
      Since:
      8.0.0-beta4

    • createBroadcast

      public Broadcast createBroadcast(Broadcast request)
      Start a new live streaming broadcast. This broadcasts the session to an HLS (HTTP live streaming) or to RTMP streams. To successfully start broadcasting a session, at least one client must be connected to the session.

      The live streaming broadcast can target one HLS endpoint and up to five RTMP servers simultaneously for a session. You can only start live streaming for sessions that use the Vonage Media Router (with the media mode set to MediaMode.ROUTED); you cannot use live streaming with sessions that have the media mode set to MediaMode.RELAYED.

      Parameters:
      request - Broadcast object with initial properties.
      Returns:
      The same Broadcast object that was passed in with additional fields populated from the server's response.
      Since:
      8.0.0-beta4

    • updateBroadcastLayout

      public void updateBroadcastLayout(String broadcastId, StreamCompositionLayout layout)
      Dynamically change the layout type of a live streaming broadcast.
      Parameters:
      broadcastId - ID of the broadcast to change.
      layout - Properties of the layout change request.
      Since:
      8.0.0-beta4

    • addBroadcastStream

      public void addBroadcastStream(String broadcastId, String streamId)
      Adds a stream to a live broadcast that was started with the streamMode set to StreamMode.MANUAL.
      Parameters:
      broadcastId - ID of the broadcast.
      streamId - ID of the stream to add.
      Since:
      8.0.0-beta4
      See Also:

    • addBroadcastStream

      public void addBroadcastStream(String broadcastId, String streamId, Boolean audio, Boolean video)
      Adds a stream to a live broadcast that was started with the streamMode set to StreamMode.MANUAL.
      Parameters:
      broadcastId - ID of the broadcast.
      streamId - ID of the stream to add.
      audio - (OPTIONAL) Whether the broadcast should include the stream's audio (true by default).
      video - (OPTIONAL) Whether the broadcast should include the stream's video (true by default).
      Since:
      8.0.0-beta4

    • removeBroadcastStream

      public void removeBroadcastStream(String broadcastId, String streamId)
      Removes a stream from a live broadcast that was started with the streamMode set to StreamMode.MANUAL.
      Parameters:
      broadcastId - ID of the broadcastId.
      streamId - ID of the stream to remove.
      Since:
      8.0.0-beta4

    • stopBroadcast

      public Broadcast stopBroadcast(String broadcastId)
      Stop a live broadcast. Note that a broadcast stops automatically 60 seconds after the last client disconnects from the session. There is a default maximum duration of 4 hours (14400 seconds) for each HLS and RTMP stream (the live stream broadcast automatically stops when this duration is reached). You can change the maximum duration for the broadcast by setting the Broadcast.Builder.maxDuration(int) property when you start the broadcast using the createBroadcast(Broadcast) method.
      Parameters:
      broadcastId - ID of the broadcast to stop.
      Returns:
      Details of the Broadcast.
      Since:
      8.0.0-beta4

    • startCaptions

      public CaptionsResponse startCaptions(CaptionsRequest request)
      Start real-time Live Captions for a Vonage Video Session.

      The maximum allowed duration is 4 hours, after which the audio captioning will stop without any effect on the ongoing Vonage Video Session. An event will be posted to your callback URL if provided when starting the captions. Each Vonage Video Session supports only one audio captioning session.

      Parameters:
      request - Properties of the live captioning.
      Returns:
      Live captioning metadata.
      Since:
      8.5.0

    • stopCaptions

      public void stopCaptions(String captionsId)
      Stop live captions for a session.
      Parameters:
      captionsId - ID of the live captions to stop.
      Since:
      8.5.0

    • connectToWebsocket

      public ConnectResponse connectToWebsocket(ConnectRequest request)
      Send audio from a Vonage Video API session to a WebSocket.
      Parameters:
      request - Properties of the WebSocket connection.
      Returns:
      The connection metadata.
      Since:
      8.5.0

    • listRenders

      public List<RenderResponse> listRenders()
      List all Experience Composers in the application.
      Returns:
      The list of Experience Composers up to the first 1000, in order from newest to oldest.
      Since:
      8.6.0
      See Also:

    • listRenders

      public List<RenderResponse> listRenders(ListStreamCompositionsRequest request)
      List Experience Composers in the application, with the specified offset and number of results.
      Parameters:
      request - (OPTIONAL) Filter properties of the request. Note that only offset and count are applicable here.
      Returns:
      The list of broadcasts matching the filter criteria, in order from newest to oldest.
      Since:
      8.6.0
      See Also:

    • getRender

      public RenderResponse getRender(String renderId)
      Retrieve details on an Experience Composer.
      Parameters:
      renderId - ID of the Experience Composer instance.
      Returns:
      The Experience Composer corresponding to the specified renderId.
      Since:
      8.6.0

    • startRender

      public RenderResponse startRender(RenderRequest request)
      Create an Experience Composer for a Vonage Video session.
      Parameters:
      request - Properties of the Experience Composer.
      Returns:
      Details of the created Experience Composer.
      Since:
      8.6.0

    • stopRender

      public void stopRender(String renderId)
      Stop an active Experience Composer.
      Parameters:
      renderId - ID of the Experience Composer instance.
      Since:
      8.6.0