Skip to content

API

Jump to bottom
pdcarroll edited this page Jul 22, 2022 · 5 revisions

useMaster

Establishes a master connection using an existing signaling channel, manages peer connections and returns local media stream and media streams for remote peers.

Example

import React, { useEffect, useRef } from "react";
import { useMaster } from "react-kinesis-webrtc";

function Peer({ media }) {
  const ref = useRef();

  useEffect(() => {
    if (ref.current) {
      ref.current.srcObject = media;
    }
  }, [ref, media]);

  return <video autoPlay ref={ref} />;
}

function Master() {
  const localMediaRef = useRef();
  const config = {
    credentials: {
      accessKeyId: "YOUR_AWS_ACCESS_KEY_ID",
      secretAccessKey: "YOUR_AWS_SECRET_ACCESS_KEY",
    },
    channelARN: "MASTER_SIGNALING_CHANNEL_ARN",
    region: "AWS_REGION",
    media: {
      audio: true,
      video: true,
    },
  };

  const { error, localMedia, peers } = useMaster(config);

  // Assign the local media stream to a video source
  useEffect(() => {
    if (localMediaRef.current) {
      localMediaRef.current.srcObject = localMedia;
    }
  }, [localMedia, localMediaRef]);

  // Display an error
  if (error) {
    return <p>An error occurred: {error.message}</p>;
  }

  return (
    <>
      {/* Display the local media stream. */}
      <video autoPlay ref={localMediaRef} />
      {/* Display a Peer component for each remote peer stream */}
      {peers.map(({ id, media }) => <Peer key={id} media={media} />)}
    </>
  );
}

If your application renders a master and viewer(s) simultaneously, the isOpen property can be used to avoid race conditions:

const { isOpen } = useMaster(masterConfig);

if (!isOpen) {
  return null;
}

// In this example, the `Viewer` component implements the `useViewer` hook.
// Only render the viewer when `isOpen` is `true` to ensure that the master is open before any viewers attempt to connect.
return <Viewer />;

Reference

Configuration

Accepts an object with the following properties:

credentials - object (see: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)

  • accessKeyId - string - AWS Access Key ID
  • secretAccessKey - string - AWS Secret Access Key

channelARN - string - The Amazon Resource Name of the master signaling channel (see: https://docs.aws.amazon.com/kinesisvideostreams-webrtc-dg/latest/devguide/kvswebrtc-how-it-works.html)

debug - boolean (optional) - Set to true to view debug logs in the console

media - object (optional) - Options used for accessing the viewer's media devices (see: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia). Omit this property to establish a one-way viewer connection.

  • audio - boolean
  • video - boolean | MediaTrackConstraints

region - string - AWS region where the channel exists

Return value

Returns an object containing the following properties:

error - Error | undefined - Any error that occurred

isOpen - boolean - Whether or not the master signaling client is open (see: https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-js#class-signalingclient)

localMedia - MediaStream - The user's local media stream (see: https://developer.mozilla.org/en-US/docs/Web/API/MediaStream)

peers - array - Peer viewer connections

useViewer

Establishes a viewer connection to an existing, active signaling channel. The default is a two-way connection between the client and peer.

To create a one-way connection with a remote peer, omit the media argument from the config object. In this case, the client's local media devices are not accessed.

Example

import React, { useEffect, useRef } from "react";
import { useViewer } from "react-kinesis-webrtc";

function Viewer() {
  const config = {
    credentials: {
      accessKeyId: "YOUR_AWS_ACCESS_KEY_ID",
      secretAccessKey: "YOUR_AWS_SECRET_ACCESS_KEY",
    },
    channelARN: "MASTER_SIGNALING_CHANNEL_ARN",
    region: "AWS_REGION",
    media: {
      audio: true,
      video: true,
    },
  };

  const {
    error,
    peer: { media } = {},
  } = useViewer(config);

  const videoRef = useRef();

  // Assign the peer media stream to a video source
  useEffect(() => {
    if (videoRef.current) {
      videoRef.current.srcObject = media;
    }
  }, [media, videoRef]);

  // Display an error
  if (error) {
    return <p>An error occurred: {error.message}</p>;
  }

  // Display the peer media stream
  return <video autoPlay ref={videoRef} />;
}

Reference

Configuration

Accepts an object with the following properties:

credentials - object (see: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)

  • accessKeyId - string - AWS Access Key ID
  • secretAccessKey - string - AWS Secret Access Key

channelARN - string - The Amazon Resource Name of the master signaling channel (see: https://docs.aws.amazon.com/kinesisvideostreams-webrtc-dg/latest/devguide/kvswebrtc-how-it-works.html)

debug - boolean (optional) - Set to true to view debug logs in the console

media - object (optional) - Options used for accessing the viewer's media devices (see: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia). Omit this property to establish a one-way viewer connection.

  • audio - boolean
  • video - boolean | MediaTrackConstraints

region - string - AWS region where the channel exists

Return value

Returns an object containing the following properties:

error - Error | undefined - Any error that occurred

localMedia - MediaStream - The user's local media stream (see: https://developer.mozilla.org/en-US/docs/Web/API/MediaStream)

peer - object

Clone this wiki locally