Multi-streaming
Some special scenarios require live streaming over two or more separate channels. For example, consider the case of a real-time monitoring system, where camera feed is shared over two channels for two types of users. There are also certain applications where you want to send multiple streams over the same channel. Consider the case of a monitoring system where feeds from multiple cameras are shared on the same channel.
Agora IoT SDK multi-streaming allows you to join multiple channels at the same time or send multiple streams over a single channel. This page shows you how to implement two different multi-streaming methods into your app using IoT SDK. Choose the method that best fits your particular scenario.
Understand the tech
Agora IoT SDK provides the following approaches to implementing multi-streaming:
-
Push multiple streams to a single channel
To push multiple streams to a single channel, you create multiple connections using Agora engine. You call the join channel method multiple times with the same channel name but different connection Ids and distinct user Ids to set up multiple streams. To send audio or video data, you use the connection Id of the intended stream.
-
Stream to multiple channels
To stream over multiple channels, you create multiple connections using Agora engine. To join each channel, you use a distinct channel name and a dedicated connection Id. You use the connection Id to specify the intended channel when sending audio or video data, when leaving a particular channel, or when closing a connection.
The following figure shows the workflow you need to implement to add multi-streaming to your app:
Prerequisites
To follow this procedure you must have implemented the SDK quickstart for IoT SDK.
Project setup
In order to create the environment necessary to implement Agora multi-streaming feature into your app, open the IoT SDK SDK quickstart project you created previously.
Implement multi-streaming
This section shows you how to implement the following multi-streaming methods:
Add pthread
library to your project
The pthread library enables you to control multiple different flows of work that overlap in time. To integrate pthread into your app:
-
Add the library into your project
In the project you implemented for the SDK quickstart for IoT SDK, open
<project-root>/agora_rtsa_sdk/example/hello_rtsa/CMakeLists.txt
and add the following line aftertarget_link_libraries(hello_rtsa_multi agora-rtc-sdk file_parser ${LIBS})
: -
Include the header in your code
Open
<project-root>/agora_rtsa_sdk/example/hello_rtsa/hello_rtsa_multi.c
and add the following to the list of#include
statements:
Push multiple streams to a single channel
Pushing multiple audio and video streams to a single channel is implemented in
<project-root>/agora_rtsa_sdk/example/hello_rtsa/hello_rtsa_multi.c
in the sample project. The following
section shows and explains code snippets that you can reuse in your own app to integrate this functionality.
-
Initialize the SDK, verify license, and set connection count
The following code initializes the Agora Engine event handler, configures options, and sets the connection count. That is, the number of streams you push to a single channel:
-
Create multiple connections
When the app starts, you create the multiple connections that you use to send audio or video data to a channel:
-
Handle Agora Engine events
IoT SDK uses callbacks in the event handler to notify you of important events. For example, users joining or leaving a channel, and receipt of audio or video data. The following code adds some important methods to handle IoT SDK events and initializes the event handler.
-
Join the same channel multiple times
You configure
rtc_channel_options_t
and join the same channel multiple times with different user Ids and connection Ids. -
Stream audio and video data
You create tasks, that is, asynchronous threads, to send video and audio frames.
-
Send an audio frame to through muliple connections
To send audio, you read data from an audio file and call
agora_rtc_send_audio_data
. The following code sends an audio frame each time it is called: -
Send a video frame to through muliple connections
To send video, you read frame data from a video file, create a
video_frame_info_t
, and callagora_rtc_send_video_data
. The following code sends a video frame each time it is called: -
Leave a channel and clean up all connections
To leave a channel and destroy all connections you call
agora_rtc_leave_channel
andagora_rtc_destroy_connection
with their connection Ids.
Stream to multiple channels
To send audio and video streams to multiple channels, open the same sample project you implemented for Push multiple streams to a single channel and make the following changes:
-
Declare the variables you need
To manage other connections and join additional channels, add the following variable declarations to the
main()
in<project-root>/agora_rtsa_sdk/example/hello_rtsa/hello_rtsa_multi.c
: -
Set channel name & token for each connection
Using the sample project, your user can join 10 additional channels. In this page you set channel names and tokens for three connections. To do this, add the following code before the join channel loop,
agora_rtc_join_channel
: -
Join multiple channels
To send audio and video streams to multiple channels, join these different channels with different tokens, user and connection Ids. Replace
agora_rtc_join_channel
in the join channel loop with:
Test your implementation
To ensure that you have implemented multi-streaming into your app, follow the relevant testing procedure:
Test pushing multiple streams to a single channel
-
Generate a temporary token in Agora Console.
-
In your browser, navigate to the Agora web demo and update App ID, Channel, and Token with the values for your temporary token, then click Join.
-
Compile the sample project
In the terminal, execute the following commands:
-
Run the sample app:
-
In the terminal, navigate to the output folder:
-
Launch the compiled app with your app ID, channel ID, and token from Agora Console
-
You see 3 video streams with audio are playing in the browser. The terminal output shows all the connections sending streams to same channel:
Test streaming to multiple channels
-
Generate the following temporary tokens in Agora Console.
-
token1
- using theappId
andchannelName1
. -
token2
- using theappId
andchannelName2
. -
token3
- using theappId
andchannelName3
.
-
-
In your browser, navigate to the Agora web demo and join a channel using
appId
,channelName1
andtoken1
. -
In another browser tab, join the Agora web demo using
appId
,channelName2
andtoken2
. -
In another browser tab, join the Agora web demo using
appId
,channelName3
andtoken3
. -
Compile the sample project
In the terminal, execute the following commands:
-
Run the sample app:
-
In the terminal, navigate to the output folder:
-
Launch the compiled app using your app ID:
-
You see that your app joins all 3 Agora web demo channels. The video and audio streams are playing individually. The terminal output shows the behavior:
Reference
This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.