Metadata

Alongside audio and video, it is possible to send additional metadata with each peer. Metadata is just JSON that can contain arbitrary information. Its most common use is sending a user name associated with a peer. However, it can be also used to send the peer's camera type, application information etc.

info

You can also set metadata on the server side, when adding user to the room. This metadata is persistent throughout its lifetime and is useful for attaching information that can't be overwritten by the peer, like information about real user names or basic permission info.

Setting metadata when joining the room

The joinRoom method from the useConnection hook has a peerMetadata parameter, that can be used for setting object metadata.

React (Web)

import { useConnection } from "@fishjam-cloud/react-client";
import React, { useCallback } from "react";

type PeerMetadata = {
  displayName: string;
};

export function JoinRoomButton() {
  const { joinRoom } = useConnection();

  const onJoinRoomPress = useCallback(async () => {
    await joinRoom<PeerMetadata>({
      peerToken: PEER_TOKEN,
      peerMetadata: { displayName: "John Wick" },
    });
  }, [joinRoom]);

  return <button onClick={onJoinRoomPress}>Join room</button>;
}

React Native (Mobile)

import React, { useCallback } from "react";
import { Button } from "react-native";
import { useConnection } from "@fishjam-cloud/react-native-client";

type PeerMetadata = {
  displayName: string;
};

export function JoinRoomButton() {
  const { joinRoom } = useConnection();

  const onPressJoin = useCallback(async () => {
    // Note: fishjamId is passed to FishjamProvider, not joinRoom
    await joinRoom<PeerMetadata>({
      peerToken: PEER_TOKEN,
      peerMetadata: { displayName: "John Wick" },
    });
  }, [joinRoom]);

  return <Button onPress={onPressJoin} title="Join Room" />;
}

Updating metadata during connection

Once you've joined the room, you can update your peer metadata with the updatePeerMetadata method of the useUpdatePeerMetadata hook:

React (Web)

import { useUpdatePeerMetadata } from "@fishjam-cloud/react-client";
import React, { useCallback } from "react";

type PeerMetadata = {
  displayName: string;
};

export function JoinRoomButton() {
  const { updatePeerMetadata } = useUpdatePeerMetadata<PeerMetadata>();

  const onPressUpdateName = useCallback(async () => {
    await updatePeerMetadata({ displayName: "Thomas A. Anderson" });
  }, [updatePeerMetadata]);

  return <button onClick={onPressUpdateName}>Change name</button>;
}

React Native (Mobile)

import React, { useCallback } from "react";
import { Button } from "react-native";
import { useUpdatePeerMetadata } from "@fishjam-cloud/react-native-client";

type PeerMetadata = {
  displayName: string;
};

export function UpdateNameButton() {
  const { updatePeerMetadata } = useUpdatePeerMetadata<PeerMetadata>();

  const onPressUpdateName = useCallback(async () => {
    await updatePeerMetadata({ displayName: "Thomas A. Anderson" });
  }, [updatePeerMetadata]);

  return <Button onPress={onPressUpdateName} title="Change name" />;
}

Reading metadata

Peer metadata is available as the metadata property for each peer. Therefore, when you list your peers with the usePeers hook, you can read the metadata associated with them. Note that the metadata.peer property contains only the metadata set by the client SDK (as in the examples examples above). The metadata set on the server side is available as metadata.server. Learn more about server metadata here.

React (Web)

import React from "react";
import { usePeers } from "@fishjam-cloud/react-client";

type PeerMetadata = {
  displayName: string;
};

type ServerMetadata = {
  realName: string;
};

export function ListAllNames() {
  const { remotePeers } = usePeers<PeerMetadata, ServerMetadata>();

  return (
    <div>
      {remotePeers.map((peer) => (
        <span>
          Display name: {peer.metadata?.peer.displayName}
          <br />
          Real name: {peer.metadata?.server.realName}
        </span>
      ))}
    </div>
  );
}

React Native (Mobile)

import React from "react";
import { Text, View } from "react-native";
import { usePeers } from "@fishjam-cloud/react-native-client";

type PeerMetadata = {
  displayName: string;
};

type ServerMetadata = {
  realName: string;
};

export function ListAllNames() {
  const { remotePeers } = usePeers<PeerMetadata, ServerMetadata>();

  return (
    <View>
      {remotePeers.map((peer) => (
        <Text key={peer.id}>
          Display name: {peer.metadata?.peer?.displayName || "Unknown"}
          Real name: {peer.metadata?.server?.realName || "Unknown"}
        </Text>
      ))}
    </View>
  );
}

Track metadata

Each track published by a peer also carries a TrackMetadata object. Unlike peer metadata, track metadata is set internally by the SDK and cannot be modified directly by the user.

It contains the following fields:

• type — the kind of media the track carries: camera, microphone, screenShareVideo, screenShareAudio, customVideo, or customAudio
• paused — whether the track is currently muted/disabled
• displayName — the peer's display name, used in recordings

You can read track metadata via the metadata property on a track, for example to check whether a peer's camera is enabled:

React (Web)

import React from "react";
import { usePeers } from "@fishjam-cloud/react-client";

export function CameraStatus() {
  const { remotePeers } = usePeers();

  return (
    <div>
      {remotePeers.map((peer) => {
        const isCameraEnabled = !peer.cameraTrack?.metadata?.paused;
        return (
          <span key={peer.id}>
            {peer.cameraTrack?.metadata?.displayName ?? "Unknown"}: camera is{" "}
            {isCameraEnabled ? "on" : "off"}
          </span>
        );
      })}
    </div>
  );
}

React Native (Mobile)

import React from "react";
import { Text, View } from "react-native";
import { usePeers } from "@fishjam-cloud/react-native-client";

export function CameraStatus() {
  const { remotePeers } = usePeers();

  return (
    <View>
      {remotePeers.map((peer) => {
        const isCameraEnabled = !peer.cameraTrack?.metadata?.paused;
        return (
          <Text key={peer.id}>
            {peer.cameraTrack?.metadata?.displayName ?? "Unknown"}: camera is{" "}
            {isCameraEnabled ? "on" : "off"}
          </Text>
        );
      })}
    </View>
  );
}