iOS and macOS

Last updated: 2021-08-27 15:57:25

    Use Cases

    TRTC supports four room entry modes. Video call (VideoCall) and audio call (VoiceCall) are the call modes, and interactive video live streaming (Live) and interactive audio live streaming (VoiceChatRoom) are the live streaming modes.
    The live streaming modes allow a maximum of 100,000 concurrent users in each room with smooth mic connection/disconnection. Co-anchoring latency is kept below 300 ms and watch latency below 1,000 ms. The live streaming modes are suitable for use cases such as low-latency interactive live streaming, interactive classrooms for up to 100,000 participants, video dating, online education, remote training, and super conferences.

    How It Works

    TRTC services use two types of server nodes: access servers and proxy servers.

    • Access server
      This type of nodes use high-quality lines and high-performance servers and are better suited to drive low-latency end-to-end calls, but the unit cost is relatively high.
    • Proxy server
      This type of servers use mediocre lines and average-performance servers and are better suited to power high-concurrency stream pulling and playback. The unit cost is relatively low.

    In the live streaming modes, TRTC has introduced the concept of "role". Users are either in the role of "anchor" or "audience". Anchors are assigned to access servers, and audience to proxy servers. Each room allows up to 100,000 users in the role of audience.
    For audience to speak, they must switch the role (switchRole) to “anchor”. The switching process involves users being migrated from proxy servers to access servers. TRTC’s low-latency streaming and smooth mic on/off technologies help keep this process short.

    Sample Code

    You can visit GitHub to obtain the sample code used in this document.

    Note:

    If your access to GitHub is slow, download the ZIP file here.

    Directions

    Step 1. Integrate the SDK

    You can integrate the TRTC SDK into your project in the following ways:

    Method 1: integrating through CocoaPods

    1. Install CocoaPods. For detailed directions, please see Getting Started.
    2. Open the Podfile file in the root directory of your project and add the following code:
      Note:

      If you cannot find a Podfile file in the directory, run the pod init command to create one and add the code below.

      target 'Your Project' do
          pod 'TXLiteAVSDK_TRTC'
      end
      
    3. Run the command below to install the TRTC SDK.
      pod install
      
      After successful installation, a xcworkspace file will be generated in the root directory of your project.
    4. Open the xcworkspace file.

    Method 2: manual integration

    If you do not want to install CocoaPods, or your access to CocoaPods repositories is slow, you can download the ZIP file of the SDK and integrate it into your project as instructed in SDK Quick Integration > iOS.

    Step 2. Add device permission requests

    Add camera and mic permission requests in the Info.plist file.

    Key Value
    Privacy - Camera Usage Description States the reason for requesting camera permission, for example, “camera access is required to capture your video”.
    Privacy - Microphone Usage Description States the reason for requesting mic permission, for example, “mic access is required to capture your audio”.

    Step 3. Initialize an SDK instance and configure event callbacks

    1. Call the sharedInstance() API to create a TRTCCloud instance.
      // Create a TRTCCloud instance
      _trtcCloud = [TRTCCloud sharedInstance];
      _trtcCloud.delegate = self;
    2. Set the attributes of delegate to subscribe to event callbacks and listen for event and error notifications.
      // Error events must be listened for and captured, and error messages should be sent to users
      - (void)onError:(TXLiteAVError)errCode errMsg:(NSString *)errMsg extInfo:(NSDictionary *)extInfo {
      if (ERR_ROOM_ENTER_FAIL == errCode) {
      [self toastTip:@"Failed to enter room"];
      [self.trtcCloud exitRoom];
      }
      }

    Step 4. Assemble the room entry parameter TRTCParams

    When calling the enterRoom() API, you need to pass in a key parameter TRTCParams, which includes the following required fields:

    Parameter Field Type Description Example
    sdkAppId Number Application ID, which you can view in the TRTC console. 1400000123
    userId String Only letters (a-z and A-Z), digits (0-9), underscores, and hyphens are allowed. test_user_001
    userSig String userSig is calculated based on userId. For the calculation method, see UserSig. eJyrVareCeYrSy1SslI...
    roomId Number String-type room IDs tend to slow down the room entry process and are therefore not supported by the SDK by default. If you need to use string-type room IDs, please submit a ticket. 29834
    Note:

    • In TRTC, users with the same userId cannot be in the same room at the same time as it will cause a conflict.
    • The value of appScene must be the same on each client. Inconsistent appScene may cause unexpected problems.

    Step 5. Enable camera preview and mic capturing

    1. Call startLocalPreview() to enable preview of the local camera. The SDK will ask for camera permission.
    2. Call setLocalViewFillMode() to set the display mode of the local video image:
      • Fill: aspect fill. The image may be scaled up and cropped, but there are no black bars.
      • Fit: aspect fit. The image may be scaled down to ensure that it’s displayed in its entirety, and there may be black bars.
    3. Call setVideoEncoderParam() to set the encoding parameters for the local video, which determine the quality of your video seen by other users in the room.
    4. Call startLocalAudio() to turn on the mic. The SDK will ask for mic permission.
    // Sample code: publish local audio/video streams
    [self.trtcCloud startLocalPreview:_isFrontCamera view:self.view];

    // Set local video encoding parameters
    TRTCVideoEncParam *encParams = [TRTCVideoEncParam new];
    encParams.videoResolution = TRTCVideoResolution_640_360;
    encParams.videoBitrate = 550;
    encParams.videoFps = 15;

    [self.trtcCloud setVideoEncoderParam:encParams];

    Step 6. Sets beauty filters

    1. Call getBeautyManager() to get the beauty filter setting API TXBeautyManager.
    2. Call setBeautyStyle() to set the beauty filter style.
      • Smooth: smooth. This style features more obvious skin smoothing effect and is typically used by influencers.
      • Nature: natural. This style retains more facial details and is more natural.
      • Pitu: this style is supported only by the Enterprise Edition.
    3. Call setBeautyLevel() to set the skin smoothing strength (5 is recommended).
    4. Call setWhitenessLevel() to set the skin brightening strength (5 is recommended).
    5. Given the yellow tint of the iPhone camera, we recommended that you call setFilter() to apply the skin brightening filter to your video. You can download the file for the filter here.

    Step 7. Create a room and push streams

    1. Set the role field in TRTCParams to TRTCRoleType.anchor to take the role of “anchor”.
    2. Call enterRoom(), specifying appScene, and a room whose ID is the value of the roomId field in TRTCParams will be created.
      • TRTCAppScene.LIVE: the interactive live video streaming mode, which is used in the example of this document.
      • TRTCAppScene.voiceChatRoom: the interactive live audio streaming mode
    3. After the room is created, start encoding and transferring audio/video data. The SDK will return the onEnterRoom(result) callback. If result is greater than 0, room entry succeeds, and the value indicates the time (ms) room entry takes; if result is less than 0, room entry fails, and the value is the error code for the failure.
    - (void)enterRoom() {
    TRTCParams *params = [TRTCParams new];
    params.sdkAppId = SDKAppID;
    params.roomId = _roomId;
    params.userId = _userId;
    params.role = TRTCRoleAnchor;
    params.userSig = [GenerateTestUserSig genTestUserSig:params.userId];
    [self.trtcCloud enterRoom:params appScene:TRTCAppSceneLIVE];
    }

    - (void)onEnterRoom:(NSInteger)result {
    if (result > 0)
    {
    [self toastTip:@"Entered room"];
    } else {
    [self toastTip:@"Failed to enter room"];
    }
    }

    Step 8. Enter the room as audience

    1. Set the role field in TRTCParams to TRTCRoleType.audience to take the role of “audience”.
    2. Call enterRoom() to enter the room whose ID is the value of the roomId field in TRTCParams, specifying appScene.
      • TRTCAppScene.LIVE: the interactive live video streaming mode, which is used in the example of this document.
      • TRTCAppScene.voiceChatRoom: interactive live audio streaming mode.
    3. Watch the anchor’s video:

    Step 9. Co-anchor

    1. Call switch(TRTCRoleType.anchor) to switch the role to “anchor” (TRTCRoleType.anchor).
    2. Call startLocalPreview() to enable preview of the local image.
    3. Call startLocalAudio() to enable mic capturing.
    // Sample code: audience becomes an anchor
    [self.trtcCloud switchRole:TRTCRoleAnchor];
    [self.trtcCloud startLocalAudio:TRTCAudioQualityMusic];
    [self.trtcCloud startLocalPreview:_isFrontCamera view:self.view];

    // Sample code: an anchor becomes audience
    [self.trtcCloud switchRole:TRTCRoleAudience];
    [self.trtcCloud stopLocalAudio];
    [self.trtcCloud stopLocalPreview]

    Step 10. Co-anchor across rooms

    Anchors from two rooms can compete with each other without exiting their current rooms.

    1. Anchor A calls the connectOtherRoom() API. The API uses parameters in JSON strings, so anchor A needs to pass the roomId and userId of anchor B in the format of {"roomId": 978,"userId": "userB"} to the API.
    2. After co-anchoring succeeds, anchor A will receive the onConnectOtherRoom() callback, and all users in both rooms will receive the onUserVideoAvailable() and onUserAudioAvailable() callbacks.
      For example, after anchor A in room "001" uses connectOtherRoom() to call anchor B in room “002” successfully all users in room "001" will receive the onUserVideoAvailable(B, available: true) and onUserAudioAvailable(B, available: true) callbacks, and all users in room "002" will receive the onUserVideoAvailable(A, available: true) and onUserAudioAvailable(A, available: true) callbacks.
    3. Users in both rooms can call startRemoteView(userId, view: view) to display the video image of the anchor in the other room, and audio will be played back automatically.
    // Sample code: cross-room anchor competition
    NSMutableDictionary * jsonDict = [[NSMutableDictionary alloc] init];
    [jsonDict setObject:@([_otherRoomIdTextField.text intValue]) forKey:@"roomId"];
    [jsonDict setObject:_otherUserIdTextField.text forKey:@"userId"];
    NSData* jsonData = [NSJSONSerialization dataWithJSONObject:jsonDict options:NSJSONWritingPrettyPrinted error:nil];
    NSString* jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
    [self.trtcCloud connectOtherRoom:jsonString];

    Step 11. Exit the room

    Call exitRoom() to exit the room. The SDK disables and releases devices such as cameras and mics during room exit. Therefore, room exit is not an instant process. It completes only after the onExitRoom() callback is received.

    // Please wait for the `onExitRoom` callback after calling the room exit API
    [self.trtcCloud exitRoom];

    - (void)onExitRoom:(NSInteger)reason {
    NSLog(@"Exited room: reason: %ld", reason)
    }
    Note:

    If your application integrates multiple audio/video SDKs, please wait after you receive the onExitRoom callback to enable other SDKs; otherwise the device busy error may occur.