search

AgoraIO-Community / Angular-Agora-RTC

11 stars 16 forks source link

readme

angular-agora-rtc

Angular 6 wrapper for Agora RTC client from https://www.agora.io/en/

npm version npm license

Installation

Install angular-agora-rtc and from npm:

npm install angular-agora-rtc --save

Examples

Introduction

Setup

In your app's main module, import AngularAgoraRtcModule and AgoraConfig from angular-agora-rtc and add the module to the imports array. Create an instance of AgoraConfig and set AppID equal to the value found in your project list on Agora.io. 

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AngularAgoraRtcModule, AgoraConfig } from 'angular-agora-rtc';

import { AppComponent } from './app.component';

const agoraConfig: AgoraConfig = {
  AppID: '1239021930912039-02193',
};

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    AngularAgoraRtcModule.forRoot(agoraConfig)
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

You can then inject the AngularAgoraRtcService into your components constructor and call createClient() to create the broadcast client object Note: The broadcast client object can only be created once per call session.

import { AngularAgoraRtcService } from 'angular-agora-rtc';
...
  constructor(
    private agoraService: AngularAgoraRtcService,
  ) {
    this.agoraService.createClient();
  }
  ...

Once the client is created and initialization is complete, the user can now join the session by calling client.join(). Pass the channel key, channel name, and user ID to the method parameters:

      this.agoraService.client.join(null, '1000', null, (uid) => {
    });

Note: Users in the same channel can talk to each other, but users with different app IDs cannot call each other even if they join the same channel.

Once this method is called successfully, the SDK triggers the callback with the user id as the parameter.

Create and Manage a Stream

Host a Stream

If a user who has joined the stream will act as the host, the app must create a stream.

Create a Stream

If the user is a host, start the stream using the this.agoraService.createStream() method. The sample app passes in an object with the following properties: this.localStream = this.agoraService.createStream(uid, true, null, null, true, false);

The createStream object is set up for additional optional attributes. See the Agora API documentation for more information.

Set the Stream Video Profile

If the user is a host, the video profile must be set. The sample app sets the video profile to 720p_3, which represents a resolution of 1280x720, frame rate (fps) of 30, and a bitrate (kbps) of 1710. See the Agora API documentation for additional video profile options. localStream.setVideoProfile('720p_3');

Set the Stream Event Listeners for Camera and Microphone Access

Once the stream has been set up and configured, the sample app adds event listeners using the localStream.on() method to check for the user's microphone and camera permissions. These event listeners are used for debugging and to send alerts to request permissions. The sample app uses console logs to check if access to the camera and microphone was allowed or denied by the user.

    // The user has granted access to the camera and mic.
    this.localStream.on("accessAllowed", () => {
      console.log("accessAllowed");
    });
    // The user has denied access to the camera and mic.
    this.localStream.on("accessDenied", () => {
      console.log("accessDenied");
    });

Next, the sample app initializes the stream by calling the localStream.init() method. Once initialized, the stream's host publishes the stream using the client.publish() method.

      this.localStream.init(() => {
      console.log("getUserMedia successfully");
      this.localStream.play('agora_local');
      this.agoraService.client.publish(this.localStream, (err) => console.log("Publish local stream error: " + err));
      this.agoraService.client.on('stream-published', (evt) => console.log("Publish local stream successfully"));
    }, (err) => console.log("getUserMedia failed", err));

Setup Client Error Handling

Passing error into the client.on() method will return the error type err.reason. The sample app uses this error type for debugging and re-invoking methods that failed.

Since the Channel Key has an expiration, the sample app checks for the error DYNAMIC_KET_TIMEOUT in the onFailure callback. It then renews the channel key using the client.renewChannelKey() method.

Note: If the channel key is not renewed, the communication to the SDK will disconnect.

    this.agoraService.client.on('error', (err) => {
      console.log("Got error msg:", err.reason);
      if (err.reason === 'DYNAMIC_KEY_TIMEOUT') {
        this.agoraService.client.renewChannelKey("",() =>{
          console.log("Renew channel key successfully");
        }, (err) =>{
          console.log("Renew channel key failed: ", err);
        });
      }
    });

Add a Stream to the Client

The stream-added event listener detects when a new stream is added to the client. The sample app subscribes the newly added stream to the client after a new stream is added to the client

    this.agoraService.client.on('stream-added', (evt) => {
      const stream = evt.stream;
      this.agoraService.client.subscribe(stream, (err) => {
        console.log("Subscribe stream failed", err);
      });
    });

Subscribe a Stream to the Client and Add to the DOM

The sample app uses the stream-subscribed event listener to detect when a new stream has been subscribed to the client, and to retrieve its stream ID using the stream.getId() method.

    this.agoraService.client.on('stream-subscribed', (evt) => {
      const stream = evt.stream;
      if (!this.remoteCalls.includes(`agora_remote${stream.getId()}`)) this.remoteCalls.push(`agora_remote${stream.getId()}`);
      setTimeout(() => stream.play(`agora_remote${stream.getId()}`), 1000);
    });

Once the stream has been added to the remoteCalls array, the sample app sets a one second timeout to allow the change detection to run and render the new div. Then to play the stream we call the stream.play() method, passing in the string agora_remote followed by the stream ID.

Remove a Stream from the Client

If the stream is removed from the client, the stream-removed event listener is called, the sample app stops the stream from playing by calling the stream.stop() method. We then remove the stream from the remoteCalls array using the filter() method.

    this.agoraService.client.on('stream-removed', (evt) => {
      const stream = evt.stream;
      stream.stop();
      this.remoteCalls = this.remoteCalls.filter(call => call === `#agora_remote${stream.getId()}`);
      console.log(`Remote stream is removed ${stream.getId()}`);
    });

Remove a Peer from the Client

When the sample app detects that a peer leaves the client using the peer-leave event listener, it stops the stream from playing. We then remove the stream from the remoteCalls array using the filter() method.

    this.agoraService.client.on('peer-leave', (evt) => {
      const stream = evt.stream;
      if (stream) {
        stream.stop();
        this.remoteCalls = this.remoteCalls.filter(call => call === `#agora_remote${stream.getId()}`);
        console.log(`${evt.uid} left from this channel`);
      }
    });

Leave a Channel

The client.leave() method removes the user from the current video call (channel). The sample app checks if the action succeeds or fails using the onSuccess and onFailure callbacks.

  leave() {
    this.agoraService.client.leave(() => {
      console.log("Leavel channel successfully");
    }, (err) => {
      console.log("Leave channel failed");
    });
  }