Session Management

The iOS SDK provides moderator-only methods for managing video sessions — recording, live recording, hard muting, room locking, participant control, RTMP and HLS streaming, pinning, spotlight, and room mode switching. Every method described on this page requires a moderator token; calling them as a participant will result in an authorization error.

EnableX can record the composite video session server-side. Recording can be triggered automatically at room creation time, or started and stopped manually by the moderator during a live session. The resulting file is transcoded after the session ends and made available for download from the EnableX Portal.

Auto Recording

To have the session recorded automatically the moment it starts, set settings.auto_recording: true when creating the room via the server API. Recording begins as soon as the first participant joins. The moderator can still stop it mid-session using stopRecord if needed.

Start Recording

Call startRecord on your EnxRoom instance to begin recording the session. This is a moderator-only action. The SDK responds via two delegate callbacks: one to acknowledge the action to the moderator, and one to notify all participants that recording has started.

Delegate Methods

[room startRecord];

// Moderator acknowledged — recording has started
- (void)startRecordingEvent:(NSArray *)response {
    // Update UI to show recording indicator
}

// All participants notified — recording is on
- (void)roomRecordOn:(NSArray *)data {
    // Show "REC" badge or similar indicator to all users
}

Error Codes

Stop Recording

Call stopRecord on the EnxRoom instance to end an active recording session. Like startRecord, this is moderator-only. The moderator receives an acknowledgment delegate call, and all participants receive a notification that recording has stopped.

Delegate Methods

[room stopRecord];

// Moderator acknowledged — recording has stopped
- (void)stopRecordingEvent:(NSArray *)response {
    // Remove recording indicator from UI
}

// All participants notified — recording is off
- (void)roomRecordOff:(NSArray *)data {
    // Hide "REC" badge or indicator for all users
}

Error Codes

Live Recording creates a real-time transcoded composite file using a custom layout rendered in a Virtual Agent view. Unlike standard recording — which transcodes after the session ends — the live recording output is ready within minutes of the session completing. The layout rendered by the Virtual Agent determines the visual composition of the file. See the Virtual Agent documentation for guidance on building a custom streaming view.

Auto Live Recording

Auto live recording starts the moment the session begins. Configure it in the room creation payload under settings.live_recording. The url field points to your hosted Virtual Agent view — the server appends the session token automatically.

{
  "settings": {
    "live_recording": {
      "auto_recording": true,
      "url": "https://your-custom-view-url/?token="
    }
  }
}

When auto live recording is active, the moderator can still stop it mid-session using stopLiveRecording.

Start Live Recording

Call startLiveRecording: on your EnxRoom instance to begin live recording manually. Pass a streamingConfig dictionary that specifies the Virtual Agent view URL and, optionally, a layout mode and chat overlay preference.

streamingConfig Parameters

Delegate Methods

NSDictionary *streamingConfig = @{
    @"urlDetails": @{
        @"url": @"https://your-domain/streaming-view/?token="
    }
};

[enxRoom startLiveRecording:streamingConfig];

// Moderator acknowledged — live recording started
- (void)room:(EnxRoom *)room didACKStartLiveRecording:(NSArray *)data {
    // Update UI to show live recording is active
}

// All participants notified — live recording started
- (void)room:(EnxRoom *)room didRoomLiveRecordingOn:(NSArray *)data {
    // Show live recording indicator to all users
}

// Live recording failed — notify users
- (void)room:(EnxRoom *)room didRoomliverecordingFailed:(NSArray *)data {
    // Handle failure — show error to moderator
}

// Progress update while initializing
- (void)room:(EnxRoom *)room didRoomliverecordingUpdated:(NSArray *)data {
    // Optional: show a progress state while streaming initializes
}

Error Codes

Stop Live Recording

Stop an active live recording session. Two method signatures are available depending on your SDK version. From iOS SDK 2.1.3 onward, call the no-argument form — there is no longer a need to pass the config dictionary to stop.

Delegate Methods

// iOS SDK 2.1.3+
[enxRoom stopLiveRecording];

// Moderator acknowledged — live recording stopped
- (void)room:(EnxRoom *)room didACKStopLiveRecording:(NSArray *)data {
    // Update UI — live recording is off
}

// All participants notified — live recording stopped
- (void)room:(EnxRoom *)room didRoomliverecordingOff:(NSArray *)data {
    // Hide live recording indicator for all users
}

Error Codes

Live Recording Queue Error Codes

The following informational codes are delivered via delegate when requests are queued or removed from the queue. These are not hard failures — they indicate the state of a queued live recording or streaming request.

Hard muting gives the moderator server-enforced control over audio and video in the room. Unlike a self-mute (which the participant controls), hard muting is applied by the server — participants cannot override it on their own. Hard muting can be applied to the entire room or to individual participants.

Hard Mute a Room

Calling muteAllUser mutes the audio of every participant currently in the room. Any new participants who join after the hard mute is applied are also muted automatically. The moderator receives an acknowledgment; all participants receive a notification.

Delegate Methods

[room muteAllUser];

// Moderator acknowledged — room is hard-muted
- (void)didMutedAllUser:(NSArray *)data {
    // Show "Room Muted" indicator
}

// All participants notified — room is hard-muted
- (void)didHardMutedAll:(NSArray *)data {
    // Disable mic controls in participant UI
}

Error Codes

Hard Unmute a Room

Calling unMuteAllUser lifts the room-wide hard mute. Participants regain control of their own microphone. The moderator receives an acknowledgment and all participants receive a notification.

Delegate Methods

[room unMuteAllUser];

// Moderator acknowledged — room hard mute lifted
- (void)didUnMutedAllUser:(NSArray *)data {
    // Remove "Room Muted" indicator
}

// All participants notified — room hard mute removed
- (void)didHardUnMuteAllUser:(NSArray *)data {
    // Re-enable mic controls in participant UI
}

Error Codes

Hard Mute a Participant

The moderator can hard-mute the audio or video of a specific participant by their client ID. The targeted participant receives a notification and cannot self-unmute while the hard mute is in effect. Two approaches are available depending on the SDK version you are targeting.

Delegate Methods

// Hard-mute a participant's audio
[enxRoom hardMuteUserAudio:@"TARGET_CLIENT_ID"];

// Hard-mute a participant's video
[enxRoom hardMuteUserVideo:@"TARGET_CLIENT_ID"];

// Affected participant — your audio has been hard-muted
- (void)didReceiveHardMutedAudio:(NSArray *)data {
    // Disable mic control in UI and inform user
}

// Moderator acknowledged — participant's audio is hard-muted
- (void)didAckHardMuteUserAudio:(NSArray *)data {
    // Update participant list UI to reflect muted state
}

Error Codes

Hard Unmute a Participant

The moderator can lift a hard mute on a specific participant's audio or video. The affected participant receives a notification and regains control of their own media.

Delegate Methods

// Hard-unmute a participant's audio
[enxRoom hardUnmuteUserAudio:@"TARGET_CLIENT_ID"];

// Affected participant — your audio hard mute has been lifted
- (void)didReceivedHardUnmutedAudio:(NSArray *)data {
    // Re-enable mic control in participant's UI
}

// Moderator acknowledged — participant's audio hard mute lifted
- (void)didHardUnMuteUserAudio:(NSArray *)data {
    // Update participant list to reflect unmuted state
}

Error Codes

The moderator can control who enters the room — locking the room to prevent new joiners, unlocking it to allow entry again, or enabling knock mode so that each participant must be individually approved before they can join.

Lock a Room

Call lockRoom to prevent any new participants from joining. Participants who are already in the room are not affected. The lock remains in effect until the moderator explicitly calls unlockRoom.

Delegate Methods

[room lockRoom];

// Moderator acknowledged — room is locked
- (void)room:(EnxRoom *)room didAckLockRoom:(NSArray *)data {
    // Show "Room Locked" status in moderator UI
}

// All participants notified — room is locked
- (void)room:(EnxRoom *)room didLockRoom:(NSArray *)data {
    // Update UI to reflect that the room cannot accept new joiners
}

Error Codes

Unlock a Room

Call unlockRoom to re-open the room to new participants. Participants with a valid token can join again after the room is unlocked.

Delegate Methods

[room unlockRoom];

// Moderator acknowledged — room is unlocked
- (void)room:(EnxRoom *)room didAckUnlockRoom:(NSArray *)data {
    // Update moderator UI — room accepts new joiners again
}

// All participants notified — room is unlocked
- (void)room:(EnxRoom *)room didUnlockRoom:(NSArray *)data {
    // Update UI to reflect open room state
}

Error Codes

Knock — Moderate Participant Entry

In a knock-enabled room, participants who attempt to join are held in a waiting state instead of entering directly. The moderator sees a notification for each waiting user and must explicitly approve or deny their entry. This gives the moderator full control over who is admitted to the session.

Approve a User's Entry

When a user knocks, the diduserAwaited: delegate fires on the moderator's device with the waiting user's ID and display name. Call approveAwaitedUser: to admit them. The approved user's device receives a didConnect: notification and they enter the room.

Delegate Methods

// Moderator receives a knock notification
- (void)room:(EnxRoom *)room diduserAwaited:(NSArray *)data {
    // data: [{"id": "CLIENT_ID", "name": "Display Name"}]
    NSString *userId = data[0][@"id"];

    // Approve the waiting user
    [room approveAwaitedUser:userId];
}

// Moderator acknowledged — user has been approved
- (void)room:(EnxRoom *)room didAckForApproveAwaitedUser:(NSArray *)data {
    // Update waiting room UI — user admitted
}

Decline a User's Entry

Call denyAwaitedUser: to reject a waiting participant. The user's device receives a didRoomDisconnect: notification with the denial reason, and they are removed from the waiting queue.

Delegate Methods

// Deny a waiting user
- (void)room:(EnxRoom *)room diduserAwaited:(NSArray *)data {
    NSString *userId = data[0][@"id"];
    [room denyAwaitedUser:userId];
}

// Moderator acknowledged — user has been denied
- (void)room:(EnxRoom *)room didAckForDenyAwaitedUser:(NSArray *)data {
    // Remove user from waiting room list in UI
}

Beyond muting and entry control, the moderator has tools to force-disconnect individual participants, extend the session duration, destroy the entire session, and transfer the moderator role to another participant.

Disconnect a User

Call dropUser: to force-disconnect one or more participants from the session. The affected participants receive a didRoomDisconnected: notification with the reason for disconnection. Pass an array of client IDs to drop multiple users at once.

Delegate Methods

// Force-disconnect one or more participants
[room dropUser:@[@"CLIENT_ID_1", @"CLIENT_ID_2"]];

// Moderator acknowledged — user has been dropped
- (void)room:(EnxRoom *)room didAckDropUser:(NSArray *)data {
    // Update participant list in UI
}

Error Codes

Extend Session Duration

Each room has a defined maximum duration configured at creation time. The SDK proactively notifies all participants when the session is approaching its limit so they have an opportunity to extend it. The extension process works in two windows:

• 10 minutes before expiry: The first extension window opens. Any participant can call extendConferenceDuration to extend the session. Once triggered, this window closes.
• 5 minutes before expiry (if not yet extended): A second window opens for a final opportunity to extend.

Delegate Methods

// Call when the extension window notification arrives
[enxRoom extendConferenceDuration];

// Extension window has opened — N minutes remaining
- (void)room:(EnxRoom *)room didConferenceRemainingDuration:(NSArray *)data {
    // Show "Session ending soon — tap to extend" prompt to the user
    // data includes minutes remaining
}

// Session has been extended
- (void)room:(EnxRoom *)room didConferencessExtended:(NSArray *)data {
    // Dismiss the expiry prompt — session continues
}

Destroy a Session

The moderator can end the session for all participants by calling destroy. This terminates the room immediately — all participants receive a didRoomDisconnected: notification and are disconnected. Use this when you need a clean, definitive end to the session rather than waiting for participants to leave on their own.

Delegate Methods

// End the session for all participants
[room destroy];

// Moderator acknowledged — session destroyed
- (void)room:(EnxRoom *)room didAckDestroy:(NSArray *)data {
    // Navigate away from the session view
}

Error Codes

Switch Participant Role

The moderator can transfer the moderator role to any other participant in the room. When the switch happens, the new participant gains moderator access and the previous moderator becomes a regular participant. All participants in the room are notified of the role change.

Delegate Methods

// Transfer moderator role to another participant
[_remoteRoom switchUserRole:@"TARGET_CLIENT_ID"];

// Previous moderator acknowledged — role switch initiated
- (void)room:(EnxRoom *)room didSwitchUserRole:(NSArray *)data {
    // Update your UI — you are now a participant
}

// New moderator and all participants notified
- (void)room:(EnxRoom *)room didUserRoleChanged:(NSArray *)data {
    // New moderator: enable moderator controls in UI
    // All others: update participant list to reflect new moderator
}

Error Codes

RTMP streaming lets the moderator forward the video session as a single live stream to any CDN or platform that accepts an RTMP ingest — YouTube Live, Facebook Live, Twitch, Wowza, or your own media server. The EnableX server composes the session using a custom Virtual Agent view and pushes the resulting stream to your RTMP endpoint. See RTMP Live Streaming for the full setup guide, including how to obtain your streaming key and configure the ingestion URL at your CDN.

Start Streaming

Call startStreaming: on the EnxRoom instance to begin the RTMP broadcast. Pass a streamingConfig dictionary that contains the RTMP ingest URL and, optionally, a custom Virtual Agent view URL for the stream layout. Once streaming is active, both the moderator and all participants receive delegate notifications.

streamingConfig Parameters

Delegate Methods

NSDictionary *streamingConfig = @{
    @"rtmpDetails": @{
        @"rtmpUrl": @"rtmp://a.rtmp.youtube.com/live2/YOUR_STREAMING_KEY",
        @"urlDetails": @{
            @"url": @"https://your-domain/streaming-view/?token="
        }
    }
};

[EnxRoom startStreaming:streamingConfig];

// Moderator acknowledged — you are live
- (void)room:(EnxRoom *)room didAckStartStreaming:(NSArray *)data {
    // Show "LIVE" indicator to the moderator
}

// All participants notified — streaming has started
- (void)room:(EnxRoom *)room didStreamingStarted:(NSArray *)data {
    // Show streaming indicator to all users
}

// All participants notified — streaming failed
- (void)room:(EnxRoom *)room didStreamingFailed:(NSArray *)data {
    // Handle error — inform moderator to retry
}

// Intermediate progress update
- (void)room:(EnxRoom *)room didStreamingUpdated:(NSArray *)data {
    // Optional: show streaming initialization progress
}

Error Codes

Stop Streaming

Call stopStreaming: to end the active RTMP broadcast. Pass the same streamingConfig dictionary used when starting. The moderator receives an acknowledgment and all participants are notified that streaming has ended.

Delegate Methods

[EnxRoom stopStreaming:streamingConfig];

// All participants notified — streaming has stopped
- (void)room:(EnxRoom *)room didStreamingStopped:(NSArray *)data {
    // Remove streaming indicator from all UIs
}

Error Codes

HLS (HTTP Live Streaming) lets you broadcast a video session to a large audience in real time using standard HLS playback — no RTMP key or CDN configuration required. EnableX manages the streaming infrastructure entirely: the HLS stream starts automatically when the first audience member joins and stops when the last audience member disconnects. Publishers (session participants) and audience members connect with different token types. See HLS Streaming for the full overview including room configuration and audience token generation.

HLS Delegate Methods

Implement the following delegate methods on your EnxRoom delegate to handle HLS state transitions. These callbacks fire automatically based on streaming events — you do not need to poll for state.

// HLS stream is live — extract hls_url and pass to your player
- (void)room:(EnxRoom *)room didHlsStarted:(NSArray *)data {
    // data contains hls_url — pass it to AVPlayerViewController to begin playback
    NSString *hlsUrl = data[0][@"hls_url"];
    [self startHlsPlayback:hlsUrl];
}

// HLS stream has stopped
- (void)room:(EnxRoom *)room didHlsStopped:(NSArray *)data {
    // Tear down the player and show post-stream UI
}

// HLS stream is initializing — show a waiting indicator to the audience
- (void)room:(EnxRoom *)room didHlsWaiting:(NSArray *)data {
    // Display "Stream is starting, please wait..." message
}

// HLS stream failed
- (void)room:(EnxRoom *)room didHlsFailed:(NSArray *)data {
    // Notify the user and offer a retry option
}

Playing the HLS Stream with AVPlayerViewController

Use Apple's AVPlayerViewController to play the hls_url you receive in didHlsStarted:. Create an AVPlayerItem from the URL, attach it to an AVPlayer, and present the AVPlayerViewController modally or embed it in your view hierarchy. Call play inside the completion block to guarantee playback begins only after the controller is fully presented.

NSString *hlsUrl = @"HLS_URL_FROM_didHlsStarted";
NSURL *url = [NSURL URLWithString:hlsUrl];

AVPlayerItem *avPlayerItem = [[AVPlayerItem alloc]
    initWithAsset:[AVAsset assetWithURL:url]];

AVPlayer *player = [AVPlayer playerWithPlayerItem:avPlayerItem];

AVPlayerViewController *vc = [[AVPlayerViewController alloc] init];
vc.player = player;

[self presentViewController:vc animated:YES completion:^{
    [player play];
}];

HLS Error Codes

HLS error codes are delivered via the didHlsFailed: delegate and in the response arrays of other HLS delegates. They are grouped by the operation that triggers them.

On HLS Start

On HLS Stop

On HLS Waiting

Generic

Pinning and spotlighting give the moderator control over which participants appear in the Active Talker list. Pinned users are always included regardless of their audio activity level; spotlighted users are pushed to the top of the list to give them visual prominence.

Pin a User

Pinning a user ensures their stream always appears in the Active Talker list regardless of audio activity. This is useful for ensuring that a presenter or panelist is always visible to all participants. The maximum number of pinned users at any time is max_active_talkers - 1 — at least one slot is always reserved for the current active speaker.

Delegate Methods

// Pin one or more participants
[enxRoom pinUsers:@[@"CLIENT_ID_1", @"CLIENT_ID_2"]];

// Moderator acknowledged — users are pinned
- (void)room:(EnxRoom *)room didAckPinUsers:(NSArray *)data {
    // Update moderator UI with pinned state
}

// All participants notified with updated pinned list
- (void)room:(EnxRoom *)room didPinnedUsers:(NSArray *)data {
    // Refresh participant list / video grid to reflect pinned state
}

Error Codes

Unpin a User

Remove the pin from one or more participants. Once unpinned, their stream is subject to the normal Active Talker ranking based on audio activity.

Delegate Methods

• -room:didAckUnpinUsers: — acknowledgment to the moderator when users are unpinned.
• -room:didPinnedUsers: — notification to all participants with the updated pinned user list.

// Unpin a participant
[enxRoom unpinUsers:@[@"CLIENT_ID_1"]];

// Moderator acknowledged — users unpinned
- (void)room:(EnxRoom *)room didAckUnpinUsers:(NSArray *)data {
    // Update moderator UI to reflect unpinned state
}

Error Codes

Spotlight a User

Spotlighting pushes one or more participants to the top of the Active Talker list regardless of their current audio activity. Multiple users can be spotlighted simultaneously — up to max_active_talkers. Spotlighted participants appear at the top of the active talker list with the "spotlight": true flag in the stream metadata, making them easy to identify in the layout.

Delegate Methods

// Spotlight a participant
[enxRoom addSpotlightUsers:@[@"CLIENT_ID_1"]];

// Moderator acknowledged — spotlight applied
- (void)room:(EnxRoom *)room didAckAddSpotlightUsers:(NSArray *)data {
    // data: { "result": 0, "clients": ["CLIENT_ID_1"] }
}

// All participants notified with updated spotlight list
- (void)room:(EnxRoom *)room didUpdatedSpotlightUsers:(NSArray *)data {
    // Reorder video grid to put spotlighted users at the top
}

Remove Spotlight

Remove the spotlight from one or more participants. Once removed, they return to their normal position in the Active Talker list based on current audio activity.

Delegate Methods

• -room:didAckRemoveSpotlightUsers: — acknowledgment to the moderator when spotlight is removed.
• -room:didUpdatedSpotlightUsers: — notification to all participants with the updated spotlight list.

// Remove spotlight from a participant
[enxRoom removeSpotlightUsers:@[@"CLIENT_ID_1"]];

// Moderator acknowledged — spotlight removed
- (void)room:(EnxRoom *)room didAckRemoveSpotlightUsers:(NSArray *)data {
    // Update moderator UI to reflect spotlight removal
}

A room defined with group or lecture mode can be switched at runtime by the moderator. This lets you adapt the session structure dynamically — for example, starting in an open group discussion and then switching to a structured lecture format where only the moderator's stream is active.

Switch Room Mode

Call switchRoomMode: with either @"group" or @"lecture" to change the room's operating mode. The behavior on switch depends on the direction:

• Group → Lecture: All participant streams are dropped. Lecture-mode features activate (floor control, hand raise). Any active breakout rooms are terminated immediately.
• Lecture → Group: Participants are notified to re-publish their streams. The SDK does not auto-publish — participants must call publish themselves, preserving their own privacy choices.

Delegate Methods

// Switch room to lecture mode
[enxRoom switchRoomMode:@"lecture"];

// Moderator acknowledged — mode switch result
- (void)room:(EnxRoom *)room didAckSwitchedRoom:(NSArray *)data {
    // data: { "result": 1715, "moderator": "STRING", "msg": "...", "mode": "lecture" }
    // Update moderator UI to show lecture-mode controls
}

// All participants notified of mode change
- (void)room:(EnxRoom *)room didRoomModeSwitched:(NSArray *)data {
    // Participants: adapt UI to the new room mode
    // If switching from lecture to group, call publish to re-share your stream
}

Error Codes