Introduction

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

Click the online demo to try this feature out.

Applicable scenarios

  • Live sports: The host and audience can watch and simultaneously commenting 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 broadcast.

Working principles

The host in a live-broadcast 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.
Note:
  • 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 (broadcaster) 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 the 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 Client.addInjectStreamUrl method to inject an online media stream to the live interactive streaming channel. You can modify the parameter values of config 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 Client.on("stream-added" and Client.on("peer-online") callbacks to all the users in the channel, and triggers the Client.on("streamInjectedStatus") callback to the local host.

    The local host can troubleshoot with API documentation when exceptions occur.

  2. The host in a channel calls the Client.removeInjectStreamUrl method to remove the injected media stream.
    If the method call is successful, SDK triggers the Client.on("peer-leave") and Client.on("stream-removed")callbacks to all the users in the channel.

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

Sample code

// Javascript
// Inject an online media stream.
var InjectStreamConfig = {
   width: 0,
   height: 0,
   videoGop: 30,
   videoFramerate: 15,
   videoBitrate: 400,
   audioSampleRate: 44100,
   audioChannels: 1,
   };

Client.addInjectStreamUrl(url, config);

// Remove an online media stream.
Client.removeInjectStreamUrl(url);

We also provide an open-source Live-Streaming-Injection demo project on GitHub.

API reference

Considerations

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

Reference

See also: When injecting online streams to the CDN, what should I do when a disconnection happens?