The Viewer class. Its purpose is to receive media by subscribing to a millicast stream. The stream must already exists and someone must publish media. More...
#include <viewer.h>
Classes | |
| struct | RtsTrackAdded |
| struct | StreamStopped |
| The Stream Stopped event is emitted when the viewer has requested to disconnect from the media server via the "unview" command. More... | |
Public Types | |
| using | Option = ViewerOption |
| using | Credentials = ViewerCredentials |
 Public Types inherited from millicast::Client | |
| enum class | ConnectionState { IDLE , CONNECTING , CONNECTED , RECONNECTING , DISCONNECTING , FAILED } |
| The Connection State enum describes the possible states that a network connecting socket can be in. This enum will be used in the WebsocketState and PeerConnectionState events to describe the state of those network mediums. More... | |
| Public Types inherited from millicast::ClientBase | |
| using | ConnectionOptions = ClientConnectionOptions |
| using | Option = ClientOption |
| using | JsonData = ClientJsonData |
Public Member Functions | |
| virtual Promise< void > | subscribe (std::optional< ViewerOption > &&options=std::nullopt)=0 |
| Subscribe to a Millicast stream. You must be connected first in order to subscribe to a stream. | |
| virtual Promise< void > | unsubscribe ()=0 |
| Stop receiving media from Millicast. | |
| virtual Promise< bool > | is_subscribed () const =0 |
| Tell if the viewer is subscribed. | |
| virtual Promise< void > | set_credentials (ViewerCredentials &&creds)=0 |
| Set the viewer credentials. | |
| virtual Promise< ViewerCredentials > | get_credentials () const =0 |
| Get the current viewer credentials. | |
| virtual EventConnectionPtr | add_event_handler (EventHandler< RtsTrackAdded > &&handler)=0 |
| Attach the event handler for discovery of new RTS tracks. | |
| virtual EventConnectionPtr | add_event_handler (EventHandler< StreamStopped > &&handler)=0 |
| Attach the event handler for the StreamStopped event. | |
| virtual EventConnectionPtr | add_event_handler (EventHandler< StatsEvent > &&handler)=0 |
| Attach the event handler for the StatsEvent containing the StatsReport.. | |
| virtual EventConnectionPtr | add_event_handler (EventHandler< ViewerCount > &&handler)=0 |
| Attach the event handler for the ViewerCount event emitted when the viewer count has changed. | |
| virtual EventConnectionPtr | add_event_handler (EventHandler< SignalingError > &&handler)=0 |
| Attach the event handler for the SignalingError event. | |
| virtual EventConnectionPtr | add_event_handler (EventHandler< HttpConnectionError > &&handler)=0 |
| Attach the event handler for the HttpConnectionError event. | |
| virtual EventConnectionPtr | add_event_handler (EventHandler< WebsocketState > &&handler)=0 |
| Attach the event handler for the WebsocketState change event. | |
| virtual EventConnectionPtr | add_event_handler (EventHandler< PeerConnectionState > &&handler)=0 |
| Attach the event handler for the PeerConnectionState change event. | |
| virtual Promise< std::vector< RtsRemoteAudioTrack * > > | audio_tracks () const =0 |
| virtual Promise< std::vector< RtsRemoteVideoTrack * > > | video_tracks () const =0 |
| virtual Promise< WebrtcRemoteTrack * > | add_webrtc_remote_track (WebrtcRemoteTrack::Kind kind, std::string_view cname)=0 |
| virtual Promise< std::vector< WebrtcRemoteAudioTrack * > > | webrtc_audio_tracks () const =0 |
| virtual Promise< std::vector< WebrtcRemoteVideoTrack * > > | webrtc_video_tracks () const =0 |
| virtual void | enable_seamless_migration (bool enabled=true)=0 |
| Public Member Functions inherited from millicast::Client | |
| virtual Promise< void > | connect (std::optional< ConnectionOptions > &&connection_options)=0 |
| Connect and open a websocket connection with the Millicast platform. | |
| virtual Promise< void > | connect (JsonData &&data, std::optional< ConnectionOptions > &&connection_options)=0 |
| Connect to the media server directly using the websocket url and the JWT. | |
| virtual Promise< bool > | is_connected () const =0 |
| is_connected | |
| virtual Promise< void > | disconnect ()=0 |
| Disconnect from Millicast. The websocket connection to Millicast will no longer be active after disconnect is complete. If the client is currently publishing/subscribing, the SDK will first stop the publishing/subscribing before disconnecting. | |
| virtual Promise< void > | enable_stats (bool enable)=0 |
| Enable the rtc stats collecting. The stats are collected once the client is either publishing or subscribed. | |
| Public Member Functions inherited from millicast::ClientBase | |
| virtual | ~ClientBase ()=default |
Static Public Member Functions | |
| static std::unique_ptr< Viewer > | create () |
| Create a new viewer. | |
| Static Public Member Functions inherited from millicast::ClientBase | |
| static std::list< std::string > | get_supported_video_codecs () |
| get_supported_video_codecs returns the list of the supported video codecs. | |
| static std::list< std::string > | get_supported_audio_codecs () |
| get_supported_audio_codecs returns the list of the supported audio codecs. | |
| static void | cleanup () |
| Clean and free the memory of dynamic objects. | |
Detailed Description
The Viewer class. Its purpose is to receive media by subscribing to a millicast stream. The stream must already exists and someone must publish media.
Member Typedef Documentation
◆ Credentials
◆ Option
Member Function Documentation
◆ add_event_handler() [1/8]
|
pure virtual |
Attach the event handler for the HttpConnectionError event.
- Parameters
-
handler the callback to invoke when an http error has occured..
- Returns
- event connection
◆ add_event_handler() [2/8]
|
pure virtual |
Attach the event handler for the PeerConnectionState change event.
- Parameters
-
handler The callback to invoke when the peer connection state has changed.
- Returns
- event connection
◆ add_event_handler() [3/8]
|
pure virtual |
Attach the event handler for discovery of new RTS tracks.
- Parameters
-
handler the callback to invoke new RTS track is discovered.
- Returns
- event connection
◆ add_event_handler() [4/8]
|
pure virtual |
Attach the event handler for the SignalingError event.
- Parameters
-
handler the callback to invoke when signaling error has occured..
- Returns
- event connection
◆ add_event_handler() [5/8]
|
pure virtual |
Attach the event handler for the StatsEvent containing the StatsReport..
- Parameters
-
handler the callback to invoke when a StatsEvent is ready.
- Returns
- event connection
◆ add_event_handler() [6/8]
|
pure virtual |
Attach the event handler for the StreamStopped event.
- Parameters
-
handler the callback to invoke when publisher has stopped stream.
- Returns
- event connection
◆ add_event_handler() [7/8]
|
pure virtual |
Attach the event handler for the ViewerCount event emitted when the viewer count has changed.
- Parameters
-
handler the callback to invoke publisher has stopped stream.
- Returns
- event connection
◆ add_event_handler() [8/8]
|
pure virtual |
Attach the event handler for the WebsocketState change event.
- Parameters
-
handler The callback to invoke when the websocket state has changed.
- Returns
- event connection
◆ add_webrtc_remote_track()
|
pure virtual |
Add custom webrtc remote track.
The RTS tracks, which are created automatically when the service notifies about the sources becoming active, can be used to enable simple streaming scenarios. They themself do not cover advanced use-cases, like:
- projecting the same RTS source onto multiple webrtc tracks
- enabling lip-sync for audio and video tracks coming from different RTS sources,
- retaining the projection status when the RTS track goes inactive,
- or attaching multiple video renderers to the video track.
The custom webrtc tracks can be used by the application to implement such advanced use-cases.
- Parameters
-
kind audio or video cname the string assigning the webrtc track to a specific sync group. Audio and video tracks with the same cname are lip-synced.
- Returns
- asynchronously produced custom webrtc track, which remains valid for the entire viewer's lifetime.
◆ audio_tracks()
|
pure virtual |
Get all RTS audio tracks.
The RTS track pointers are valid as long as the viewer is not destroyed.
- Returns
- asynchronous collection of all RTS audio tracks.
◆ create()
|
static |
Create a new viewer.
- Returns
- A new Viewer object.
◆ enable_seamless_migration()
|
pure virtual |
Enable or disable the seamless migration and reconnection.
The seamless migration and reconnection is enabled by default. This function can be used to disable it, or to enable it again.
The seamless migration and reconnection is a feature which controls the viewer's behaviour when: 1) the connection is migrated to the new node, and 2) when reconnecting (requires the auto-reconnect option to be enabled, triggered when network problems cause disconnection of the websocket).
When seamless migration and reconnection is disabled, during the migration or reconnection all RtsRemoteTracks will be switched to the inactive state and unprojected. The renderers set on the video tracks will be released. When the reconnection succeeds, the notifications about tracks activity from the service will cause notifying about RtsRemoteTracks becoming active again. The app will need to enable() such tracks again to resume presenting data. The WebrtcRemoteTracks will be disabled and unprojected - the SDK will need to project them again - but the renderers on the video tracks will not be deleted. All pending but not yet finished requests to enable any webrtc track or RTS track will fail when reconnecting.
When seamless migration and reconnection is enabled, that behaviour is changed. The RtsRemoteTracks cease notifying about activity state changes, and the renderers set on the video tracks are not released. The pending enable operations are not aborted. The WebrtcRemoteTracks are not disabled. When the client connects to the service again, it will wait a bit for service notification about tracks activity, and then it will attempt to restore the most recently requested state on all tracks. The RTC tracks which were active prior to disconnection and are active after it will get no notification about activity change. The RTC tracks which were active prior to disconnection, but are not active after it, will get inactive notification (and any projection that was previously established or requested will fail). The custom webrtc tracks which were projected from RTS tracks which are inactive after reconnection will get the Disabled event notification. All RTS tracks which are active after reconnection and were active and projected before disconnection, as well as all webrtc tracks which were projected before disconnection, and their RTS tracks are active after it, will restore their projection state. The application will still receive the disconnected and connected notification, as well as the subscribed notification on the listener, but it will not need to handle any track-related thing, the state will be restored automatically.
Note that if seamless migration is enabled, it does not hide the real (that is, disconnected, unprojected and inactive) state or RTS tracks and webrtc tracks from the application. Attaching the Active event handler to the RTC track exactly while the client is disconnected will not trigger Active event immediately (until the track if confirmed to be active in the new connection). Reading current projection from the webrtc track may return no RTS track. These corner cases might be fixed in the future, but should otherwise be harmless for applications which base their behaviour on event and completion notifications.
Note that if this function is used while the viewer is already connected, there's a possibility that the viewer receives the migrate request or encountered connection problems and started reconnecting at any time, before this function is called. In such a case, this single migration or reconnection operation will use the previously set value controlling the behaviour.
- Parameters
-
enabled true to enable seamless migration, false to disable it.
◆ get_credentials()
|
pure virtual |
Get the current viewer credentials.
- Returns
- Promise object providing asynchronous status.
◆ is_subscribed()
|
pure virtual |
Tell if the viewer is subscribed.
- Returns
- Promise object providing asynchronous status. The completion callback will be invoked with true if subscribed, and with false if not.
◆ set_credentials()
|
pure virtual |
Set the viewer credentials.
- Parameters
-
creds The credentials
- Returns
- Promise object providing asynchronous status.
◆ subscribe()
|
pure virtual |
Subscribe to a Millicast stream. You must be connected first in order to subscribe to a stream.
- Parameters
-
options subscribing options (optional)
- Returns
- Promise object providing asynchronous status.
- Remarks
- when the success callback on the returned promise is invoked, the Viewer is subscribed. There's no need to implement listener's on_subscribed method.
◆ unsubscribe()
|
pure virtual |
Stop receiving media from Millicast.
- Returns
- Promise object providing asynchronous status.
◆ video_tracks()
|
pure virtual |
Get all RTS video tracks.
The RTS track pointers are valid as long as the viewer is not destroyed.
- Returns
- asynchronous collection of all RTS video tracks.
◆ webrtc_audio_tracks()
|
pure virtual |
Get all custom webrtc audio tracks.
Note: the returned collection only contains tracks which were created by the application using add_webrtc_remote_track(). It does not contain interfaces to the default webrtc tracks associated with the RTS tracks.
- Returns
- asynchronous collection of all custom webrtc audio tracks.
◆ webrtc_video_tracks()
|
pure virtual |
Get all custom webrtc video tracks.
Note: the returned collection only contains tracks which were created by the application using add_webrtc_remote_track(). It does not contain interfaces to the default webrtc tracks associated with the RTS tracks.
- Returns
- asynchronous collection of all custom webrtc video tracks.
The documentation for this class was generated from the following file:
- api/millicast-sdk/viewer.h
