Choosing Configuration

To choose a configuration for video streams, you should carefully consider the below use cases, the intended layout, and how the app will be used. Different configurations will have different effects on bandwidth consumption, performance, and battery life.

One-to-one call (TeleHealth use case)

Telehealth provides a platform for communication between doctors and patients regarding healthcare services through technology rather than physically visiting a doctor’s office or hospital. Using this platform patients can remotely access medical services and manage medical care.

The BlueJeans SDK provides you to customize the video layout to your requirements. There may be several types of scenarios like one-one appointments, two doctors, and one patient, group therapies, virtual consultations, and more.

Here is an example of how your remote video must fill the entire screen with a high-quality stream.

  let configuration = [VideoStreamConfiguration(
     requestedStreamQuality: .r720p_30fps,
     streamPriority: .high
  )]

You can alter the stream quality with the high, medium, and low quality of your choice.

Note
The BlueJeans SDK will downgrade the video stream if it exceeds the available bandwidth. We recommend that you only request video quality when you need it. Otherwise, the user's bandwidth will be consumed more than necessary.

Remote Education

A remote education use case is given below, where you may have a virtual classroom in which the teachers’ video should be a bigger share (higher resolution) of the view space compared to other student video tiles with lower resolution.

There may be another use case where a couple of teachers/trainers are shown in screen view high-resolution and the rest of the students are shown in low resolution.

In your use case, there may be a couple of trainers, for simplicity the below use case is taken as one Teacher/moderator using participantID. Use participantID as moderator from the ParticipantsServiceProtocol.

  func getModeratorId() -> String? {
      let participantsService = BlueJeansSDK.meetingService.participantsService
      let moderator = participantsService.participants.value?.first(where: { participant in
         participant.isModerator == true
      })
      return moderator?.id
  }

This function assumes there is only one moderator (there may be many) but we will just take the first for simplicity.

func getModeratorConfiguration() -> VideoStreamConfiguration? {
    guard let moderatorId = getModeratorId() else {
      print("No moderator?!?")
      return nil
    }
    return VideoStreamConfiguration(requestedStreamQuality: .r360p_30fps, participantId: moderatorId, 
                                    streamPriority: .high)
   }

For the other participants/students, you can request a grid of small tiles. In this use case, the moderator/teacher will be displayed with the highest priority, and the rest participants/students will be displayed with lower resolution.

 func getStudentsConfiguration(numberOfVideos: Int = 24) -> [VideoStreamConfiguration] {
   let oneVideo = VideoStreamConfiguration(requestedStreamQuality: .r90p_7fps, streamPriority: .medium)
   let allVideos = [VideoStreamConfiguration](repeating: oneVideo, count: numberOfVideos)
   return allVideos
 }

To get the total configuration of videos that is requested by combining the two for one total configuration.

    func getTotalConfiguration() -> [VideoStreamConfiguration]? {
        guard let moderatorConfiguration = getModeratorConfiguration() else {
            print("No moderator :(")
            return nil
        }
        return [moderatorConfiguration] + getStudentsConfiguration()
    }

Video Stream Priority enumeration

Stream prioritization provides you to have more control over the playback video by allowing you to specify priority order for the streams. The video streams are prioritized is as follows:

The high-priority video stream receives the video of the most recent speaking participant.
Higher priority streams are allocated bandwidth before lower priority streams.
The overall configuration is ordered from highest to lowest priority.

The stream priority is classified as follows

High (Participants with higher priority will be displayed in high resolution)
Medium (Participants with medium priority will be displayed in medium resolution)
Low (Participants with low priority will be displayed in lower resolution)

In order to guarantee a particular stream will receive a higher resolution than other streams, the stream should have a distinct, and higher priority than the other streams.

The below use case explains the scenario where stream priority will be chosen according to the active speakers. An active speaker will be shown on the screen with 720p, the preceding speaker will be shown 360p with 30fps, the earlier preceding speaker will be shown 360p with 15 fps, and 6 more participants shown 180p 15 fps with low stream priority.

 let configuration = [
     VideoStreamConfiguration(requestedStreamQuality: .r720p_30fps, streamPriority: .high),
     VideoStreamConfiguration(requestedStreamQuality: .r360p_30fps, streamPriority: .medium),
     VideoStreamConfiguration(requestedStreamQuality: .r360p_15fps, streamPriority: .medium),
     VideoStreamConfiguration(requestedStreamQuality: .r180p_15fps, streamPriority: .low),
     VideoStreamConfiguration(requestedStreamQuality: .r180p_15fps, streamPriority: .low),
     VideoStreamConfiguration(requestedStreamQuality: .r180p_15fps, streamPriority: .low),
     VideoStreamConfiguration(requestedStreamQuality: .r180p_15fps, streamPriority: .low),
     VideoStreamConfiguration(requestedStreamQuality: .r180p_15fps, streamPriority: .low),
     VideoStreamConfiguration(requestedStreamQuality: .r180p_15fps, streamPriority: .low)
 ]

Note

invalidStreamPriorityCombination is a videoStreamConfiguration error that occurs when you tried to mix a configuration with "high, medium, low" priority and a configuration with a priority of "none" (e.g., streamPriority is not given or set to nil). The configuration must specify all priorities or no priorities.

User Experience Recommendation

You can only have one video view per stream of video, i.e., you cannot render the same video in two different views on screen.
You can request a specific video quality, but it may not be provided depending on the network or other factors.

Note

You should only request the quality you require (e.g. The 720p video should not be requested for a small thumbnail because it is not necessary, consumes more bandwidth, and consumes more power).

Known Limitations

The "Video share and upload feature" found on some BlueJeans Clients is not supported when using custom layouts.