Introduction

Injecting an online media stream is the action of adding an external audio or video stream to an ongoing live interactive streaming channel. It enables the hosts and audience in the channel to hear and see the additional stream while interacting with each other.

Applicable scenarios

  • Live sports: The host and audience can watch and simultaneously comment on events.
  • Music concerts, movies, and other entertainments: The hosts and audience can participate in real‑time discussions while watching them.
  • Additional perspectives: The host can inject video streams captured by drones or network cameras into a live streaming channel.

Working principles

The host in a live interactive streaming channel pulls an online media stream and pushes it through the Video Inject Server to the Agora Software‑Defined Real‑time Network (SD‑RTN™) and the channel.

  • The host and audience in the channel can hear and see the media stream.
  • If the host enables Content Delivery Network (CDN) live streaming, the injected media stream is also pushed to the CDN so that the CDN audience can hear and see the media stream.
  • Only one online media stream can be injected into the same channel at the same time.
  • Supported codec type: AAC for audio, H.264 for video.
  • Audio-only streams are also supported.
  • Only the host can inject and remove an injected media stream. Neither the delegated host nor the audience can do that.

Implementation

Before proceeding, ensure that you implement basic live interactive streaming in your project. See Start Live Interactive Streaming for details.

Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.

Refer to the following steps to inject an online media stream:

  1. The host in a channel calls the AddInjectStreamUrl method to inject an online media stream to the live interactive streaming channel. You can modify the parameter values of streamConfig to set the resolution, bitrate and frame rate of the injected stream. See InjectStreamConfig.

    Only one online media stream can be injected into the same channel at the same time.

    If the method call is successful, SDK triggers the OnUserJoinedHandler (uid:666) callback to all the users in the channel, and triggers the OnStreamInjectedStatusHandler callback to the local host.

    The local host can troubleshoot with API Reference when exceptions occur.
  2. The host in a channel calls the RemoveInjectStreamUrl method to remove the injected media stream.
    If the method call is successful, SDK triggers the OnUserOfflineHandler (uid:666) callback to all the users in the channel.

    You do not need to call the RemoveInjectStreamUrl method if the host has left the channel.

Sample code

InjectStreamConfig injectStreamConfig = new InjectStreamConfig();
injectStreamConfig.width = 0;
injectStreamConfig.height = 0;
injectStreamConfig.videoGop = 30;
injectStreamConfig.videoFramerate = 15;
injectStreamConfig.videoBitrate = 400;
injectStreamConfig.audioSampleRate = AUDIO_SAMPLE_RATE_TYPE.AUDIO_SAMPLE_RATE_48000;
injectStreamConfig.audioChannels = 1;
injectStreamConfig.audioBitrate = 48;

// Inject an online media stream.
mRtcEngine.AddInjectStreamUrl(url, injectStreamConfig);
// Remove an online media stream.
mRtcEngine.RemoveInjectStreamUrl(url);

API reference

Considerations

To receive the injected media stream, the audience need to subscribe to the host.