Relay Media(PK Host) - React Native

note

This page uses the following asynchronous methods. Refer to their API reference for the errors each Promise may reject with, and handle these rejections appropriately based on your use case.

• requestMediaRelay()
• stopMediaRelay()

Overview

The Relay Media feature enables hosts to relay their media (audio, video, screen share) to one or multiple other live streams. This creates cross-stream interactions similar to "PK battles" or collaborative broadcasts.

Audiences in one live stream can see and hear hosts from another live stream without changing rooms.

Key Concepts

• Media Relay: The process of transmitting a host's audio/video from one live stream to another
• Source Room: The original live stream where the host is broadcasting
• Destination Room: The target live stream(s) where the host's media will be relayed
• Relay Kinds: The types of media that can be relayed: audio, video and screen share

Sequence Diagram

Implementation Guide

1. Requesting Media Relay

requestMediaRelay()

Parameters:

It takes one object with these fields:

• destinationRoomId (string): ID of the target liveStream
• token (string, optional): Authentication token for the destination liveStream
• kinds (array, optional): Array of media types to relay. Leave it out to relay every kind; an empty array relays none. Options:
  • "video": Camera video
  • "audio": Microphone audio
  • "share": Screen share

import { useRoom } from "@videosdk.live/react-native-sdk";
import { TouchableOpacity, Text, StyleSheet } from "react-native";

const LiveStreamView = () => {
  //Getting the requestMediaRelay method from hook
  const { requestMediaRelay } = useRoom();

  const handleRequestMediaRelay = async () => {
    try {
      await requestMediaRelay({
        destinationRoomId: "liveStream-B",
        token: "VIDEOSDK_AUTHENTICATION_TOKEN",
        kinds: ["video", "audio"],
      });
    } catch (err) {
      console.error("requestMediaRelay failed:", err);
    }
  };

  return (
    <TouchableOpacity style={styles.button} onPress={handleRequestMediaRelay}>
      <Text style={styles.buttonText}>Request Media Relay</Text>
    </TouchableOpacity>
  );
};

const styles = StyleSheet.create({
  button: {
    backgroundColor: "#007AFF",
    padding: 12,
    borderRadius: 8,
    alignItems: "center",
  },
  buttonText: {
    color: "white",
    fontSize: 16,
    fontWeight: "600",
  },
});

2. Handling Relay Requests (Destination Room)

In the destination liveStream, hosts (participants with SEND_AND_RECV mode) receive your relay request in onMediaRelayRequestReceived, and one of them calls accept() or reject() on it. Their answer reaches you in the source liveStream, as the next step shows.

import { useRoom } from "@videosdk.live/react-native-sdk";

const LiveStreamView = () => {
  function onMediaRelayRequestReceived({ participantId, roomId, displayName, accept, reject }) {
    console.log(`${displayName} (${participantId}) in ${roomId} wants to relay media`);
    // Answer from your own UI; here the request is always accepted
    accept();
  }

  useRoom({
    onMediaRelayRequestReceived,
  });

  return null;
};

3. Handling Request Responses (Source Room)

In the source liveStream, track the response to your relay requests. The callback receives one object: decision is "ACCEPTED" or "REJECTED" (Constants.RelayDecision), decidedBy is the ID of the participant who gave it, and roomId is the destination liveStream.

import { Constants, useRoom } from "@videosdk.live/react-native-sdk";
import { ToastAndroid, Platform, Alert } from "react-native";

const LiveStreamView = () => {
  function onMediaRelayRequestResponse({ decision, decidedBy }) {
    if (decision === Constants.RelayDecision.ACCEPTED) {
      console.log(`Relay request accepted by ${decidedBy}`);
      // Show notification for both platforms
      showNotification(`Relay request accepted by ${decidedBy}`);
      // Update UI to show relay is active
      updateRelayStatus(decidedBy, true);
    } else {
      console.log(`Relay request rejected by ${decidedBy}`);
      // Show notification for both platforms
      showNotification(`Relay request rejected by ${decidedBy}`);
      // Update UI to show relay was rejected
      showRelayRejectedMessage(decidedBy);
    }
  }

  // Helper function to show notifications across platforms
  const showNotification = (message) => {
    if (Platform.OS === "android") {
      ToastAndroid.show(message, ToastAndroid.SHORT);
    } else {
      Alert.alert("Notification", message, [{ text: "OK" }]);
    }
  };

  useRoom({
    onMediaRelayRequestResponse,
  });

  return null;
};

4. Tracking Active Relays

When a relay successfully starts:

import { useRoom } from "@videosdk.live/react-native-sdk";
import { ToastAndroid, Platform, Alert } from "react-native";

const LiveStreamView = () => {
  function onMediaRelayStarted({ roomId }) {
    console.log(`Media relay started to ${roomId}`);
    // Show notification for both platforms
    showNotification(`Media relay started to ${roomId}`);
    // Update UI to show active relay
    addActiveRelayToUI(roomId);
  }

  // Helper function to show notifications across platforms
  const showNotification = (message) => {
    if (Platform.OS === "android") {
      ToastAndroid.show(message, ToastAndroid.SHORT);
    } else {
      Alert.alert("Notification", message, [{ text: "OK" }]);
    }
  };

  useRoom({
    onMediaRelayStarted,
  });

  return null;
};

5. Stopping Media Relay

To stop an ongoing relay:

stopMediaRelay()

Parameters:

• destinationRoomId (string): ID of the liveStream where the relay should stop

import { useRoom } from "@videosdk.live/react-native-sdk";
import { TouchableOpacity, Text, StyleSheet } from "react-native";

const LiveStreamView = () => {
  //Getting the stopMediaRelay method from hook
  const { stopMediaRelay } = useRoom();

  const handleStopMediaRelay = async () => {
    try {
      await stopMediaRelay("liveStream-B");
    } catch (err) {
      console.error("stopMediaRelay failed:", err);
    }
  };

  return (
    <TouchableOpacity style={styles.button} onPress={handleStopMediaRelay}>
      <Text style={styles.buttonText}>Stop Media Relay</Text>
    </TouchableOpacity>
  );
};

const styles = StyleSheet.create({
  button: {
    backgroundColor: "#FF3B30",
    padding: 12,
    borderRadius: 8,
    alignItems: "center",
  },
  buttonText: {
    color: "white",
    fontSize: 16,
    fontWeight: "600",
  },
});

6. Handling Relay Stop Events

When a relay stops for any reason:

import { useRoom } from "@videosdk.live/react-native-sdk";
import { ToastAndroid, Platform, Alert } from "react-native";

const LiveStreamView = () => {
  function onMediaRelayStopped({ roomId, reason }) {
    console.log(`Relay to ${roomId} stopped. Reason: ${reason}`);

    // Show notification for both platforms
    showNotification(`Relay to ${roomId} ended: ${reason}`);

    // Remove from active relays in UI
    removeActiveRelayFromUI(roomId);
  }

  // Helper function to show notifications across platforms
  const showNotification = (message) => {
    if (Platform.OS === "android") {
      ToastAndroid.show(message, ToastAndroid.SHORT);
    } else {
      Alert.alert("Notification", message, [{ text: "OK" }]);
    }
  };

  useRoom({
    onMediaRelayStopped,
  });

  return null;
};

7. Handling Relay Errors

To handle errors that may occur during relay:

import { useRoom } from "@videosdk.live/react-native-sdk";
import { ToastAndroid, Platform, Alert } from "react-native";

const LiveStreamView = () => {
  function onMediaRelayError({ roomId, error }) {
    console.error(`Relay error to ${roomId}: ${error}`);
    // Show error notification for both platforms
    showNotification(`Couldn't relay to ${roomId}: ${error}`);
  }

  // Helper function to show notifications across platforms
  const showNotification = (message) => {
    if (Platform.OS === "android") {
      ToastAndroid.show(message, ToastAndroid.LONG);
    } else {
      Alert.alert("Error", message, [{ text: "OK" }]);
    }
  };

  useRoom({
    onMediaRelayError,
  });

  return null;
};

Use Cases

1. Guest Appearances: Allow popular hosts to make guest appearances in other streams without leaving their audience
2. Cross-Stream Competitions: Create "battles" or competitions between hosts in different streams
3. Multi-Location Broadcasting: Connect hosts from different physical locations into a shared experience
4. Expert Commentary: Bring in subject matter experts to comment on events in another stream

Troubleshooting

Common Issues

1. Relay Request Not Received

   • Verify both rooms are active
   • Check that destination liveStream ID is correct
   • Ensure the token has proper permissions

2. Media Not Visible After Acceptance

   • Verify network connectivity
   • Check that appropriate media kinds were specified
   • Ensure the host has enabled their camera/microphone

3. Unexpected Relay Termination

   • Check for network connectivity issues
   • Verify that both rooms remain active
   • Look for error events with specific reasons

API Reference

• requestMediaRelay
• stopMediaRelay
• onMediaRelayRequestReceived
• onMediaRelayRequestResponse
• onMediaRelayStarted
• onMediaRelayStopped
• onMediaRelayError