In-Session Communication

The iOS SDK provides the following methods for obtaining information about the in-session communication:

• sendMessage(): To exchange messages among session participants.
• sendUserData(): To send customized data
• sendFiles() - to initiate a file transfer to the EnableX server.
• getAvailableFiles(): To return a JSON object with all the files available for download.
• downloadFile(): To initiate a file download.
• cancelUpload(): To cancel an ongoing file upload job.
• cancelAllUploads(): To cancel all ongoing file uploads.
• cancelDownload(): To cancel an ongoing file download job.
• cancelAllDownloads(): To cancel all ongoing file downloads.
• startScreenShare(): To create a screen sharing stream.
• stopScreenShare(): To stop an ongoing screen sharing.
• exitScreenShare(): To notify the Screen Share Broadcast Extension to exit from an ongoing session.
• stopAllSharing(): To force stop an ongoing screen sharing.
• startCanvas(): To start canvas streaming.
• stopCanvas(): To stop sanvas streaming.
• stopAllSharing(): To force stop an ongoing canvas streaming.
• startAnnotation(): To start annotation on a specific stream object.
• stopAnnotation(): To stop annotations.
• startLiveTranscription: To start self transcription.
• startLiveTranscriptionForRoom: To start room-level transcription.
• stopLiveTranscription(): To stop the transcription.

Chat

The EnxRoom.sendMessage() exchanges messages among session participants. It allows to exchange the following types of messages:

• Public Messaging: To send messages to all the connected users.
• Private Messaging: To send messages to a specific user.
• Group Messaging: To send messages to multiple users.

The Messaging feature does not require the sender to publish local streams or the receiver to subscribe to remote streams.

Class: EnxRoom

Method: -(void)sendMessage:(NSString *)message isBroadCast:(BOOL)broadcast recipientIDs:(NSArray *)clientIds;

Parameters

Delegate Method: - room:didMessageReceived- Receives message in a JSON object.

Sample Code

NSArray *clientArray = [NSArray arrayWithObjects:@"xxx",@"xxx", nil]

// Private message to one or selected Recipients
[room sendMessage:[NSString stringWithFormat:@"%@",text] isBroadCast:true recipientIDs:clientArray]; 

// Users Receive Message through Callback 
// Available from v1.5.3.
- (void)room:(EnxRoom *)room didMessageReceived:(NSArray *)data {
    // data contains incoming message
}

Custom Signalling

The EnxRoom.sendUserData() method allows you to send customized data adhering to a structure not bound by the EnableX message structure to one or more users connected in a session. It allows your application to send messages and structured instructions, polls, or any data that requires a customized data structure per your business requirement.

Class: EnxRoom

Method: -(void)sendUserData:(NSDictionary *)Message isBroadCast:(BOOL)broadcast recipientIDs:(NSArray *)clientIds;

Parameters

Delegate Method: - room:didUserDataReceived: Receives signaling in JSONObject. Available from iOS SDk v1.5.3 and later.

Sample Code - Message Dictionary Sample

// Example: You can put important information with custom keys
// You may define the JSONObject as per your business needs

NSDictionary* message = @{
    "sender": "Sender's Name",
    "message": "Message body",
    "custom_key": "Data"
}

Sample Code - To send and receive Custom Signaling

NSArray *clientArray = [NSArray arrayWithObjects:@"xxx",@"xxx", nil]

// Signaling to one or selected Recipients
[room sendUserData: message broadCast:false recipientIDs:clientArray]; 

// Users receive Signal through Callback 
// Available till v1.5.2. Deprecated in v1.5.3
- (void)room:(EnxRoom *)room didReceiveChatDataAtRoom:(NSArray *)data {
    // data contains incoming message
}

// Users receive Signal through Callback 
// Available from v1.5.3.
- (void)room:(EnxRoom *)room didUserDataReceived:(NSArray *)data {
    // data contains incoming message
}

Error Codes and Exceptions

File Sharing

This functionality is available in iOS SDK 1.5.3 and later versions. It is compatible with iOS 13 and later versions.

The following APIs allow users in an RTC session to send and receive files with each other. Using these APIs, you can initiate a file transfer, cancel a file transfer, be notified of the availability of a file for download, and receive/download a shared file.

Upload a File for Sharing

The EnxRoom.sendFiles() method initiates a file transfer to the EnableX server.

Class: EnxRoom

Method: -(void) shareFiles:(EnxFilePosition)position isBroadcast:(BOOL)isBroadcast clientIds:(NSArray *_Nullable)clientIds

Parameters

Delegate Methods at Sender's End

Delegate Methods at Receiver's End

Sample Code

[room shareFiles:Top isBroadcast:true clientIds:nil];

// To intended receiver - A new file upload started
- (void)room:(EnxRoom *_Nonnull)room didFileUploadStarted:(NSArray *_Nullable)data {
    // data contains incoming file information
}

// To intended receiver - A file is available for download 
-(void)room:(EnxRoom *_Nonnull)room didFileAvailable:(NSArray *_Nullable)data {
    // data contains incoming file information
}

// To sender - File upload process started
- (void)room:(EnxRoom *_Nonnull)room didInitFileUpload:(NSArray *_Nullable)data {
    // data contains file information
}

// To sender - File upload is complete
- (void)room:(EnxRoom *_Nonnull)room didFileUploaded:(NSArray *_Nullable)data {
	// data contains file information
}

// To sender - File upload has failed
- (void)room:(EnxRoom *_Nonnull)room didFileUploadFailed:(NSArray *_Nullable)data {
	// data contains error information
}

Download a Shared File

The process of downloading shared files comprises of two steps:

1. Know the file available for download.
2. Initiate a download of the available file.

Know Files Available for Download

Room Lookup: The EnxRoom.getAvailableFiles() method returns a JSON object with all the files available for download.

Class: EnxRoom

Method: -(NSArray*)getAvailableFiles

Sample Code 1

[room getAvailableFiles];

Delegate method: -room:didFileAvailable: The intended receiver is notified when a file is available for download.

Sample Code 2

// To intended receiver - A file is available for download 
-(void)room:(EnxRoom *_Nonnull)room didFileAvailable:(NSArray *_Nullable)data {
    // data contains incoming file information
}

Initiate a File Download

The EnxRoom.downloadFile() method initiates the file download using the information received about the file to download.

Class: EnxRoom

Method: -(void)downloadFile:(NSDictionary *_Nonnull)file autoSave:(BOOL)flag

Parameters

Note: The Auto Saving option is applicable for image and video files only. The other file types must be manually saved using the Base64 encoded RAW data.

Callbacks at Receiver's End

Sample Code

[room downloadFile:fileObject autoSave:true];

// To receiver - File has been downloaded
- (void)room:(EnxRoom *_Nonnull)room didFileDownloaded:(NSString *_Nullable)data {
	// Handle FileObject with download information
}

// To receiver - File download has failed
- (void)room:(EnxRoom *_Nonnull)room didFileDownloadFailed:(NSArray *_Nullable)data {
 // Handle download error
}

Cancel a File Upload

The EnxRoom.cancelUpload() method allows you to cancel an ongoing file upload job initiated by you.

Class: EnxRoom

Method: -(void)cancelUpload:(int)jobID

Parameter: jobId: Numeric. The Id of the file upload job.

Sample Code

[EnxRoom cancelUpload jobId];

Callback: didFileUploadCancelled: Acknowledgment to the user when the file upload is canceled.

Sample Code

- (void)room:(EnxRoom *_Nonnull)room
didFileUploadCancelled:(NSArray *_Nullable)data

Error Codes and Exceptions

Cancel All Uploaded Files

The EnxRoom.cancelAllUploads() method allows you to cancel all the ongoing file uploads initiated by you.

Class: EnxRoom

Method: -(void)cancelAllUploads

Parameter: jobId: Numeric. The Id of the file upload job.

Sample Code

[EnxRoom cancelAllUploads];

Callback: didFileUploadCancelled: Acknowledgment to the user when the file upload is canceled.

Sample Code

- (void)room:(EnxRoom *_Nonnull)room
didFileUploadCancelled:(NSArray *_Nullable)data

Error Codes and Exceptions

Cancel a File Download

The EnxRoom.cancelDownload() allows you to cancel the ongoing file download job at your endpoint.

Class: EnxRoom

Method: -(void)cancelDownload:(int)jobID;

Parameter: jobId: Numeric. The ID of the file download job.

Callback: didFileDownloadCancelled: Acknowledgment to the user when the file download is canceled.

Sample Code

- (void)room:(EnxRoom *_Nonnull)room
didFileDownloadCancelled:(NSArray *_Nullable)data;

Error Codes or Exceptions

Cancel all Ongoing File Downloads

The EnxRoom.cancelAllDownloads() method allows you to cancel all ongoing file downloads at your endpoint.

Method: -(void)cancelAllDownloads

Sample Code

[EnxRoom cancelAllDownloads];

Callback: didFileDownloadCancelled: Acknowledgment to the user when the file download is canceled.

Sample Code

- (void)room:(EnxRoom *_Nonnull)room
didFileDownloadCancelled:(NSArray *_Nullable)data;

Error Codes and Exceptions

Screen Sharing

To support screen sharing in a room, enable screen sharing during Room Creation by setting: { "screen_share": true; } in the JSON payload. To receive a shared screen, subscribe to the screen sharing Stream ID# 101 and play it on the video player.

Start Screen Sharing

The EnxRoom.startScreenShare() method creates a screen sharing stream @ 6fps to publish in the room. Screen sharing continues even when the application runs in the background.

Class: EnxRoom

Method: - (void) startScreenShare

Delegate Methods

Sample Code

[enxRoom startScreenShare];

// Broadcast extension class receives this callback 
// method when publishing the Screen Stream

-(void)didStartBroadCast:(NSArray *)data {

}

// Acknowledgement to the endpoint when screen stream starts.

-(void)room:(EnxRoom *)room didStartScreenShareACK:(NSArray *)Data {

}

For more information, click here.

Stop Screen Sharing

The EnxRoom.stopScreenShare() method stops the ongoing Screen-Sharing.

Class: EnxRoom

Method: -(void) stopScreenShare

Delegate Methods

Sample Code

[enxRoom stopScreenShare ];

// Broadcast extension class receives this callback 
// method when unpublishing the Screen Stream

-(void) didStoppedBroadCast:(NSArray *)data {

}

// Acknowledgement to the endpoint whern screen stream stops

-(void)room:(EnxRoom *)room didStopScreenShareACK:(NSArray *)Data {

}

For more information, click here.

Exit Screen Sharing

The EnxRoom.exitScreenShare() method is used to notify the Screen Share Broadcast Extension to exit from an ongoing session. It must be called Broadcast Extension, which differs from the primary target.

Class: EnxRoom

Method: -(void)exitScreenShare

Delegate Methods

Sample Code

[enxRoom exitScreenShare];

// Notification received by the child client (screen share client)

-(void)didRequestedExitRoom:(NSArray *_Nullable)Data {

}

// Acknowledgment callback for the parent client

-(void)room:(EnxRoom *_Nullable)room didExitScreenShareACK:(NSArray *_Nullable)Data {

}

Error Codes and Exceptions

For more information, click here.

Force Stop Other's Screen Sharing

This functionality is available in iOS SDK 2.1.2 and later versions.

If the moderator wishes to force stop an ongoing screen sharing by another user in the room, the moderator can do so by using the EnxRoom.stopAllSharing() method.

Note: This is moderator exclusive feature and can't be executed from participant endpoints.

This method also forces stopping of ongoing canvas streaming.

Class: EnxRoom

Observer: ACK CallBack

Method: -(void)stopAllSharing

Callbacks: –didACKStopAllSharing: Notification to everyone in a room when screen sharing stops.

Sample Code

[enxRoom stopAllSharing];

-(void)room:(EnxRoom *_Nullable)room didStopAllSharingACK:(NSArray *_Nullable)data {

};

Canvas Streaming

Canvas streaming allows you to publish any view into the room. To support canvas streaming in the room, enable canvas during Room Creation by setting: { canvas: true; } in the JSON payload.

Start Canvas Streaming

The EnxRoom.startCanvas() method is used to start canvas streaming.

Method: (void) startCanvas:(UIView*_Nonnull)view

Parameter: UI View: JSON Object. The UI view to use for canvas streaming.

Delegate Methods

Sample Code

[room startCanvas: UIView];

// Callback method for Publisher to
// acknowledge that Canvas Streaming has started
-(void)room:(EnxRoom *_Nullable)room didStartCanvasACK:(NSArray *_Nullable)Data; 

// Callback method for all participants in 
// the room to notify that canvas streaming has started
-(void)room:(EnxRoom*)room didCanvasStarted:(EnxStream *_Nullable)stream{
	stream.enxPlayer.frame = yourFrame;
	[yourView addSubview:stream.enxPlayer];
}

-(void)room:(EnxRoom *)room didStartCanvasACK:(NSArray *)Data{
	// Acknowledge to the Publisher that Canvas Stream started.
	
}

Error Codes and Exceptions

Stop Canvas Streaming

The EnxRoom.stopCanvas() method is used to stop canvas streaming.

Class: EnxRoom

Method: -(void)stopCanvas;

Delegate Methods

Sample Code

[room stopCanvas];

// Callback method for Publisher to
// acknowledge that Canvas Streaming has stopped
-(void)room:(EnxRoom *_Nullable)room didStoppedCanvasACK:(NSArray *_Nullable)Data; 

// Everyone notified that Canvas Streaming has stopped
-(void)room:(EnxRoom *)room didCanvasStopped:(EnxStream *_Nullable)stream{
	[stream.enxPlayer removeFromSuperview];
}

Receive and Play Canvas Streaming

To receive canvas streaming, subscribe to the Canvas Stream ID# 102. Once subscribed, you can play it like any other video stream using a video player.

Sample Code

// You are notified when Canvas Streaming started
-(void)room:(EnxRoom *)room canvasStarted:(NSArray *)Data{
	/*Data is 
	[	{ 
			"clientId" : "XXXX", 
			"name" : "Canvas Streaming from Web",
			"result" : 0, 
			"streamId" : 102
		},
		"<null>"
	]
	*/


	NSDictionary *responseDict = Data[0];
	
	// Get remote stream using streamId
	NSString *streamId = *responseDict[@"streamId"];
	EnxStream *stream = room.streamsByStreamId[streamId]; 
	  
	// init player view
	EnxPlayerView *playerView = [[EnxPlayerView alloc] initWithFrame:frame];
	[stream attachRenderer:playerView];
	[playerView setDelegate:self];
}


// You are notified when Canvas Streaming stopped
-(void)room:(EnxRoom *)room canvasStopped:(NSArray *)Data{
	/* Data is 
	[	{ 
			"clientId" : "XXXX", 
			"name" : "Canvas Streaming from Web",
			"result" : 0, 
			"streamId" : 102
		},
		"<null>"
	]
	*/

	// Update your UI here.

}

Note: In case of an error, <null> is received at the first index and error info at the second index.

Force Stop Canvas Streaming

This functionality is available in iOS SDK 2.1.2 and later versions.

If the moderator wishes to force stop any ongoing canvas streaming by another user in the room, the moderator can do so by using the EnxRoom.stopAllSharing() method.

This is moderator exclusive feature and cannot be executed from participant endpoints. This method also forces stops ongoing screen sharing.

Class: EnxRoom

Observer: ACK CallBack

Method: -(void)stopAllSharing

Callback: didACKStopAllSharing: Notification to everyone in a room when canvas streaming stops.

Sample Code

[EnxRoom stopAllSharing];     // Force Stop the Canvas Streaming

 
// Notification to all when share stops
- (void)signalingChannel:(EnxSignalingChannel *_Nullable)channel didACKStopAllSharing:(NSArray *_Nonnull)data

Annotation

This functionality is available in iOS SDK 1.5.6 and later versions.

The Annotation feature allows you to annotate on a remote stream. To support this feature, you need to enable canvas streaming during Room Creation by setting: { canvas: true; } in the JSON payload. To implement Annotation, you need to add Annotation Toolbar before you can start Annotations.

Add Annotation Toolbar

Initiate the Annotation toolbar using the following code in XML:

EnxToolBar *toolBar = [[EnxToolBar alloc] initWithFrame:CGRectMake(X, Y, width, height)];

Start Annotation

The EnxRoom.startAnnotation() is used to start annotation on a specific stream object.

Class: EnxRoom

Method: -(void)startAnnotation:(EnxStream *_Nonnull)stream

Parameter: EnxStream: JSON Object. Stream object to annotate.

Delegate Methods

Sample Code

// Start Annotation
-(void)startAnnotation:(EnxStream*_Nonnull)stream;

// Stop Annotation
-(void)stopAnnotation;  

// Notification to all - Annotation started
-(void)room: (EnxRoom *_Nullable) room didAnnotationStarted: (NSArray *_Nullable) Data; 

// Acknowlegement to Annotator - Annotation started
-(void)room: (EnxRoom *_Nullable) room didStartAnnotationACK: (NSArray *_Nullable) Data; 

// Notification to all - Annotation stopped
-(void)room: (EnxRoom *_Nullable) room didAnnotationStopped: (NSArray *_Nullable) Data; 

// Acknowlegement to Annotator - Annotation stopped
-(void)room: (EnxRoom *_Nullable) room didStoppedAnnotationACK: (NSArray *_Nullable) Data;

Stop Annotation

The EnxRoom.stopAnnotation() method is used to stop annotations.

Method: -(void)stopAnnotation

Delegate Methods

Error Codes and Exceptions

Live Transcription

EnableX supports live transcription of video sessions. All endpoints requesting live transcription start receiving Speech-to-Text contents of all the actively talking users in a video room through a notification event. Live transcription is helpful when participants have limited language proficiency or difficulty hearing because of a noisy background.

Live transcription converts the speech of all active talkers in a video room to text, and the converted text can be shared with each user who has subscribed to receive it. The transcription process starts when the first user requests it and continues until the last user opts out. The text content is generated through a single transcription process and broadcasted to each user who has requested for it.

Service Subscription

Live transcription is a subscription-based service. For subscription details, contact the Sales or Account Manager.

Live Transcription Settings in a Room

Live transcription is automatically enabled in all rooms if live transcription subscription is enabled. However, you can disable it for certain rooms or configure its settings to meet your requirements using the room-level settings.

For more information, see Create a Video Room. For more information about obtaining the session transcription file, click here.

Sample Code: Room definition JSON payload to live transcription settings

{
  "name": "HLS Trial",
  "owner_ref": "XOXO",
  "settings": {
    "description": "HLS Trial",
    "mode": "group",
    "scheduled": false,
    "adhoc": false,
    "duration": 30,
    "moderators": "1",
    "participants": "2",
    "audiences": 6,
    "auto_recording": false,
    "quality": "SD",
    "live_transcription": {
        "language": "english_us",
        "auto_transcribe": true,
        "enable": true
    } 

  }
}

Note: If live transcription is not subscribed, then room definition with related settings is prohibited.

Methods and Notifications

In addition to the auto-start settings of live transcription, it can be started or stopped using SDK method calls.

When the SDK method is called to start live transcription, the method initiates it and subscribes for the feed to receive. If the transcription process is already started in the room, it subscribes to it. So, any new user can subsequently execute the command to start it and only subscribe to it.

On the other hand, when the stop command is executed, the user unsubscribes from the feed and does not receive the transcribed content after that point. When the last subscribed user stops the subscription, the transcription process stops in the room.

Note: If the transcription is automatically started at the room level, it is not stopped when the last user stops. It is only stopped at the end of the session.

Start a Live Transcription

To start live transcription, call the following SDK method from an endpoint. When the method executes first, it starts the live transcription process in the video room. It also subscribes to the endpoint to receive the text-to-speech content. Subsequently, the same method call from other endpoints only subscribes to receive the text-to-speech content.

When only one endpoint starts the process and receives the transcription, it is called the self-transcription process. On subsequent requests, it gets promoted to room-level transcription.

Methods

Parameter language: Optional. The default language is english_us. Use one of the strings from the list of languages. It is the language that you want the Speech Recognition engine to recognize for you.

Delegate Methods

Sample Code

// Start Transcription
[enxRoom startLiveTranscriptionForRoom:@"english_us"];
 

- (void)room:(EnxRoom* _Nullable)room didRoomTranscriptionOn:(NSArray *_Nonnull)data {
	// Room-Level  transcription is on
}
    
- (void)room:(EnxRoom* _Nullable)room didSelfTranscriptionOn:(NSArray *_Nonnull)data {
	// Self transcription is on    
}

- (void)room:(EnxRoom* _Nullable)room didTranscriptionEvents:(NSArray *_Nonnull)data {
	// Speech Recognising or Recognized events with transcribed data   
}

Error Codes

Stop Live Transcription

The following method call unsubscribes an endpoint from receiving the live transcription content. The transcription process ends when all the endpoints request to stop receiving the content. However, the transcription process does not stop if the auto-transcribe option is enabled at the room-level and it continues till the end of the session.

Method: -(void)stopLiveTranscription;

Delegate Methods

Sample Code

// Stop Transcription
[enxRoom stopLiveTranscription];
 

- (void)room:(EnxRoom* _Nullable)room didRoomTranscriptionOff:(NSArray *_Nonnull)data {
	// Room-Level transcription is turned off
}
    
- (void)room:(EnxRoom* _Nullable)room didSelfTranscriptionOff:(NSArray *_Nonnull)data {
	// Self transcription is turned off    
}

Error Codes