Customize Your Streaming Application

Build custom controls using the MediaStreamController API.

While Native Frame provides pre-built components for common use cases, you may need to create custom controls that match your design system or implement specialized functionality. This guide demonstrates how to build custom components that interact directly with the MediaStreamController API, giving you full control over camera, microphone, and broadcasting behavior.

React

Prerequisites

This guide assumes you have a basic understanding of setting up an <PreviewPlayer/> with @video/video-client-react. We will be focusing on the key differences for customizing components, specifically:

How to create your own components
Interacting with the MediaStreamController context
React to MediaStreamController events

For foundational concepts, please review:

The usePreviewPlayer and useAuthClient hooks.
The useCallControls custom hook.
The PreviewPlayer component for device controls.

Custom Button Component

Next, you'll likely want to interact with the Encoder API to handle custom functionality.

In this example, we'll create a custom button that will disable the microphone of the encoder, and allow for custom callback logic.

Imports

import React, { memo, useCallback } from "react";
import { context, hooks } from "@video/video-client-react";

/**
 * IMPORT EXPLANATIONS:
 *
 * 1. React imports:
 *    - memo: Prevents unnecessary re-renders for performance
 *    - useCallback: Memoizes callback functions to prevent recreation
 *
 * 2. @video/video-client-react imports:
 *    - context: Provides hooks to access video client Context
 *    - hooks: Provides custom hooks for video client functionality
 */

// Extract the hook to access media stream controller from Context
const { useMediaStreamControllerAPI } = context;

// Extract the hook to listen for video client events
const { useEvent } = hooks;

Hooks

Use the useMediaStreamControllerAPI hook to access the MediaStreamControllerAPIContext and the useEvent hook to listen for the audioDisabled event

  /**
   * STEP 1: Access the Media Stream Controller
   *
   * The `useMediaStreamControllerAPI` hook retrieves the media stream
   * controller instance from React Context. This controller manages:
   * - Camera on/off state
   * - Microphone on/off state
   * - Device selection (which camera/mic to use)
   * - Media permissions
   *
   * IMPORTANT: This hook must be used inside a MediaStreamControllerAPIProvider.
   * The parent component (CustomizeYourStreamingApplication) provides this context.
   */
  const msc = useMediaStreamControllerAPI();

  /**
   * STEP 2: Listen for Audio State Changes
   *
   * The `useEvent` hook subscribes to events from the media stream controller.
   * When you call this hook with "audioDisabled", the component will re-render
   * whenever the audio enabled/disabled state changes.
   *
   * Why is this useful?
   * - Your UI can update to reflect the current audio state
   * - The button can show different states (muted/unmuted)
   * - You can react to audio changes from other components
   *
   * The event name "audioDisabled" matches the property on the controller.
   * Other available events: "videoDisabled", "deviceError", etc.
   */
  useEvent(msc, "audioDisabled");

Click Hanlder

  /**
   * STEP 3: Handle Button Click
   *
   * This function runs when the user clicks the button.
   * It demonstrates how to control the microphone programmatically.
   *
   * What happens:
   * 1. Set audioDisabled to true (mutes the microphone)
   * 2. You can add custom logic here (analytics, notifications, etc.)
   *
   * useCallback optimization:
   * - Prevents the function from being recreated on every render
   * - Only recreates if 'msc' changes
   * - Improves performance, especially important for frequently rendered components
   *
   * CUSTOMIZATION IDEAS:
   * - Toggle instead of just disabling: msc.audioDisabled = !msc.audioDisabled
   * - Show a toast notification when muting
   * - Log analytics events
   * - Trigger other UI changes
   * - Control video: msc.videoDisabled = true
   * - Change devices: msc.audioDeviceId = "device-id"
   */
  const handleClick = useCallback(() => {
    // Disable audio (mute the microphone)
    msc.audioDisabled = true;

    // Add your custom logic here!
    // Examples:
    // - console.log('Audio muted');
    // - showNotification('Microphone muted');
    // - trackAnalyticsEvent('audio_muted');
  }, [msc]);

Full Component Code

// CustomButton.tsx

/**
 * CustomButton Component
 *
 * OVERVIEW:
 * This component demonstrates how to create custom UI controls that
 * interact with the video client's media stream controller.
 *
 * WHAT YOU'LL LEARN:
 * - How to access video client state from context
 * - How to listen for and react to video client events
 * - How to control camera and microphone programmatically
 * - How to create custom UI components that integrate with the video client
 *
 * KEY CONCEPTS:
 * 1. CONTEXT: Accessing shared video client instances from React Context
 * 2. EVENTS: Listening for state changes in the video client
 * 3. MEDIA CONTROL: Programmatically controlling camera/microphone
 *
 * USE CASES:
 * - Creating custom styled buttons
 * - Adding additional functionality beyond built-in components
 * - Integrating video controls with your existing UI design system
 * - Implementing complex control logic (e.g., toggle multiple devices)
 *
 * @example
 * ```tsx
 * // Must be used inside MediaStreamControllerAPIProvider
 * <MediaStreamControllerAPIProvider mediaStreamControllerAPI={msc}>
 *   <CustomButton />
 * </MediaStreamControllerAPIProvider>
 * ```
 */

import React, { memo, useCallback } from "react";
import { context, hooks } from "@video/video-client-react";

/**
 * IMPORT EXPLANATIONS:
 *
 * 1. React imports:
 *    - memo: Prevents unnecessary re-renders for performance
 *    - useCallback: Memoizes callback functions to prevent recreation
 *
 * 2. @video/video-client-react imports:
 *    - context: Provides hooks to access video client Context
 *    - hooks: Provides custom hooks for video client functionality
 */

// Extract the hook to access media stream controller from Context
const { useMediaStreamControllerAPI } = context;

// Extract the hook to listen for video client events
const { useEvent } = hooks;


function CustomButton(): JSX.Element | null {

  /**
   * STEP 1: Access the Media Stream Controller
   *
   * The `useMediaStreamControllerAPI` hook retrieves the media stream
   * controller instance from React Context. This controller manages:
   * - Camera on/off state
   * - Microphone on/off state
   * - Device selection (which camera/mic to use)
   * - Media permissions
   *
   * IMPORTANT: This hook must be used inside a MediaStreamControllerAPIProvider.
   * The parent component (CustomizeYourStreamingApplication) provides this context.
   */
  const msc = useMediaStreamControllerAPI();

  /**
   * STEP 2: Listen for Audio State Changes
   *
   * The `useEvent` hook subscribes to events from the media stream controller.
   * When you call this hook with "audioDisabled", the component will re-render
   * whenever the audio enabled/disabled state changes.
   *
   * Why is this useful?
   * - Your UI can update to reflect the current audio state
   * - The button can show different states (muted/unmuted)
   * - You can react to audio changes from other components
   *
   * The event name "audioDisabled" matches the property on the controller.
   * Other available events: "videoDisabled", "deviceError", etc.
   */
  useEvent(msc, "audioDisabled");

  /**
   * STEP 3: Handle Button Click
   *
   * This function runs when the user clicks the button.
   * It demonstrates how to control the microphone programmatically.
   *
   * What happens:
   * 1. Set audioDisabled to true (mutes the microphone)
   * 2. You can add custom logic here (analytics, notifications, etc.)
   *
   * useCallback optimization:
   * - Prevents the function from being recreated on every render
   * - Only recreates if 'msc' changes
   * - Improves performance, especially important for frequently rendered components
   *
   * CUSTOMIZATION IDEAS:
   * - Toggle instead of just disabling: msc.audioDisabled = !msc.audioDisabled
   * - Show a toast notification when muting
   * - Log analytics events
   * - Trigger other UI changes
   * - Control video: msc.videoDisabled = true
   * - Change devices: msc.audioDeviceId = "device-id"
   */
  const handleClick = useCallback(() => {
    // Disable audio (mute the microphone)
    msc.audioDisabled = true;

    // Add your custom logic here!
    // Examples:
    // - console.log('Audio muted');
    // - showNotification('Microphone muted');
    // - trackAnalyticsEvent('audio_muted');
  }, [msc]);

  /**
   * STEP 4: Render the Button
   *
   * This is a simple button with inline styles. In a real application,
   * you would likely use CSS classes or a component library.
   *
   * CUSTOMIZATION IDEAS:
   * - Change button text based on audio state:
   *   {msc.audioDisabled ? "Unmute" : "Mute"}
   * - Add icons (mic icon, muted mic icon)
   * - Apply different styling based on state
   * - Add hover/active states
   * - Use your design system's button component
   * - Add accessibility attributes (aria-label, aria-pressed)
   *
   * @example Advanced Button:
   * ```tsx
   * <button
   *   onClick={handleClick}
   *   aria-label={msc.audioDisabled ? "Unmute microphone" : "Mute microphone"}
   *   aria-pressed={msc.audioDisabled}
   *   className={msc.audioDisabled ? "btn-muted" : "btn-active"}
   * >
   *   {msc.audioDisabled ? <MicOffIcon /> : <MicOnIcon />}
   * </button>
   * ```
   */
  return (
    <button
      type="button"
      onClick={handleClick}
      style={{
        color: "white",
        background: "green",
        padding: ".5rem",
        borderRadius: "5px",
      }}
    >
      Custom Button
    </button>
  );
}

/**
 * EXPORT WITH MEMOIZATION
 *
 * We wrap the component in React.memo() to prevent unnecessary re-renders.
 * The component only re-renders when its props change or when events it
 * listens to (via useEvent) are triggered.
 *
 * This is a performance optimization that's especially valuable for
 * UI controls that might be rendered frequently.
 */
export default memo(CustomButton);

Broadcast Component

As mentioned above, this is almost identical to this Broadcasting Component. The only difference is the <CustomButton/> included in the return.

  // #14
  /**
   * MAIN UI RENDERING
   */
  return (
    <MediaStreamControllerAPIProvider mediaStreamControllerAPI={mediaStreamController}>
      <PlayerAPIProvider playerAPI={previewPlayer}>
        <div className="w-full flex flex-col overflow-hidden mb-4">
          {/* Video preview showing what your camera sees */}
          <Encoder />

          {/* Control buttons for managing call and broadcast */}
          <div className="flex flex-row my-2 gap-2 ">
            {/* Example custom button - you can add your own controls here */}
            <CustomButton />
            {/* Built-in controls from useCallControls hook */}
            {renderControls()}
          </div>
        </div>
      </PlayerAPIProvider>
    </MediaStreamControllerAPIProvider>

  );

Full Code