Skip to main content
Version: 0.x.x

Relay Media (PK Host) - JavaScript

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.

This feature allows audiences in one live stream to view and hear hosts from another live stream without changing rooms, creating powerful interactive experiences.

Key Concepts​

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

Sequence Diagram​

sequenceDiagram participant HostA as Host A participant HostB as Host B participant AudienceB as Audience B HostA->>HostB: requestMediaRelay(meetingB_Id, token, kinds) HostB-->>HostB: media-relay-request-received event alt Accept HostB->>HostA: accept() HostA-->>HostA: media-relay-request-response("accepted") HostA-->>HostA: media-relay-started(meetingB_Id) HostA->>AudienceB: Media streaming else Reject HostB->>HostA: reject() HostA-->>HostA: media-relay-request-response("rejected") end HostA->>HostB: stopMediaRelay(meetingB_Id) HostA-->>HostA: media-relay-stopped(meetingB_Id, reason);

Implementation Guide​

1. Requesting Media Relay​

requestMediaRelay()​

Parameters:

  • destinationMeetingId (string): ID of the target liveStream
  • token (string, optional): Authentication token for the destination liveStream
  • kinds (array, optional): Array of media types to relay. Options:
    • "video": Camera video
    • "audio": Microphone audio
    • "share": Screen share video
    • "share_audio": Screen share audio
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

liveStream.requestMediaRelay({
  destinationMeetingId: "liveStream-B",
  token: "VIDEOSDK_AUTHENTICATION_TOKEN",
  kinds: ["video", "audio"],
});

2. Handling Relay Requests (Destination liveStream)​

In the destination liveStream, hosts (participants with SEND_AND_RECV mode) will receive relay requests:

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

liveStream.on(
  "media-relay-request-received",
  ({ participantId, liveStreamId, displayName, accept, reject }) => {
    console.log(
      `Relay request from ${displayName} (${participantId}) in liveStream ${liveStreamId}`
    );

    // You can show UI to accept/reject the request
    showRelayRequestDialog(displayName, liveStreamId, accept, reject);
  }
);

// Example dialog handler
function showRelayRequestDialog(displayName, liveStreamId, accept, reject) {
  // Show custom UI dialog
  const confirmed = confirm(
    `${displayName} wants to relay their media to this live stream. Accept?`
  );

  if (confirmed) {
    accept(); // Accept the relay request
  } else {
    reject(); // Reject the relay request
  }
}

3. Handling Request Responses (Source Meeting)​

In the source liveStream, track the response to your relay requests:

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

liveStream.on(
  "media-relay-request-response",
  ({ decision, decidedBy, meetingId }) => {
    if (decision === "accepted") {
      console.log(`Relay request accepted by ${decidedBy}`);
      // Update UI to show relay is active
      updateRelayStatus(decidedBy, true);
    } else {
      console.log(`Relay request rejected by ${decidedBy}`);
      // Update UI to show relay was rejected
      showRelayRejectedMessage(decidedBy);
    }
  }
);

4. Tracking Active Relays​

When a relay successfully starts:

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});
liveStream.on("media-relay-started", ({ liveStreamId }) => {
  console.log(`Media relay started to ${liveStreamId}`);
  // Update UI to show active relay
  addActiveRelayToUI(liveStreamId);
});

5. Stopping Media Relay​

To stop an ongoing relay:

stopMediaRelay()​

Parameters:

  • liveStreamId (string): ID of the liveStream where the relay should stop
let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});
liveStream.stopMediaRelay("liveStream-B");

6. Handling Relay Stop Events​

When a relay stops for any reason:

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});
liveStream.on("media-relay-stopped", ({ meetingId, reason }) => {
  console.log(`Relay to ${meetingId} stopped. Reason: ${reason}`);

  // Update UI based on stop reason
  switch (reason) {
    case "user_stopped":
      showMessage(`You stopped relaying to ${meetingId}`);
      break;
    case "connection_lost":
      showMessage(`Relay to ${meetingId} ended due to connection issues`);
      break;
    default:
      showMessage(`Relay to ${meetingId} ended: ${reason}`);
  }

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

7. Handling Relay Errors​

To handle errors that may occur during relay:

let liveStream;

// Initialize liveStream
liveStream = VideoSDK.initMeeting({
  // ...
});
liveStream.on("media-relay-error", ({ meetingId, error }) => {
  console.error(`Relay error to ${meetingId}: ${error}`);
  // Show error in UI
  showErrorNotification(`Couldn't relay to ${meetingId}: ${error}`);
});

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 meetings 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 meetings remain active
    • Look for error events with specific reasons

API Reference​

Got a Question? Ask us on discord

Last updated on by ahmed bhesaniya

Was this helpful?