Getting Started

Start building live video experiences in minutes

What is NativeFrame?

NativeFrame is a powerful platform for adding real-time video streaming to your applications. Whether you're building a live broadcasting platform, video conferencing tool, or interactive streaming experience, NativeFrame provides the infrastructure and SDKs to make it happen.

Key capabilities:

• Broadcast livestreams from cameras, screens, or canvas elements
• View streams with ultra-low latency (< 1 second)
• Group video calls with multiple participants
• Private streaming for one-on-one interactions
• Customizable players to match your brand
• Cross-platform support (Web, mobile browsers)

No complex server setup required. Just add our SDK and start streaming.

---

Choose Your Path

NativeFrame supports both React and Vanilla JavaScript implementations:

Framework	Best For	Key Features
React	React applications (16.8+)	Hooks (usePreviewPlayer, useAuthClient, useCallControls), Context providers, pre-built components, TypeScript support
Vanilla JavaScript	Framework-free projects or integration with Vue, Angular, Svelte	Core SDK loaded from CDN, direct API access, no build step required, maximum flexibility

---

Quick Start

Prerequisites

Before you begin, you'll need:

• Authentication token (JWT) from NativeFrame
• Stream key for your streams
• Backend endpoint (e.g., https://your-subdomain.nativeframe.com)

React

React Implementation

Step 1: Configure .npmrc

Update your .npmrc file to include:

@video:registry=https://npm-packages.nativeframe.com/

Step 2: Installation

Install the React package via npm or yarn:

npm install @video/video-client-react

or

yarn add @video/video-client-react

That's it! The package includes everything you need: hooks, components, and TypeScript types.

Step 3: Your First Broadcaster

Let's create a simple broadcaster that streams your camera to viewers.

import React from 'react';
import {
  usePreviewPlayer,
  useAuthClient,
  useCallControls
} from '@video/video-client-react/hooks';
import {
  MediaStreamControllerAPIProvider,
  PlayerAPIProvider
} from '@video/video-client-react/context';
import { Video } from '@video/video-client-react/components';

function Broadcaster() {
  // Set up camera and preview
  const { mediaStreamController, previewPlayer } = usePreviewPlayer();

  // Set up authentication
  const authClient = useAuthClient({
    authUrl: 'https://your-subdomain.nativeframe.com/api/auth',
    token: 'your-broadcaster-token'
  });

  // Configure call and broadcast
  const callOptions = {
    streamKey: 'your-stream-key',
    backendEndpoints: ['https://your-subdomain.nativeframe.com'],
    auth: authClient,
    user: { userId: 'user-1', displayName: 'Broadcaster' }
  };

  const broadcastOptions = { streamName: 'default' };

  // Get call controls (buttons to start/stop)
  const { callControls } = useCallControls({
    mediaStreamController,
    callOptions,
    broadcastOptions
  });

  return (
    <MediaStreamControllerAPIProvider mediaStreamController={mediaStreamController}>
      <PlayerAPIProvider player={previewPlayer}>
        <div>
          <h1>My First Livestream</h1>
          <Video /> {/* Shows your camera preview */}
          {callControls} {/* Start/Stop buttons */}
        </div>
      </PlayerAPIProvider>
    </MediaStreamControllerAPIProvider>
  );
}

export default Broadcaster;

That's it! You now have a working broadcaster with camera preview and controls.

Step 4: Your First Viewer

Now let's create a viewer that watches the broadcast:

import React, { useState } from 'react';
import { useAuthClient } from '@video/video-client-react/hooks';
import { PlayerAPIProvider } from '@video/video-client-react/context';
import { Video } from '@video/video-client-react/components';
import { createPlayer } from '@video/video-client-react';

function Viewer({ callId }) {
  const [player, setPlayer] = useState(null);

  const authClient = useAuthClient({
    authUrl: 'https://your-subdomain.nativeframe.com/api/auth',
    token: 'your-viewer-token'
  });

  React.useEffect(() => {
    createPlayer({
      callId: callId,
      streamName: 'default',
      backendEndpoints: ['https://your-subdomain.nativeframe.com'],
      auth: authClient
    }).then(setPlayer);

    return () => player?.dispose();
  }, [callId]);

  if (!player) return <div>Loading stream...</div>;

  return (
    <PlayerAPIProvider player={player}>
      <div>
        <h1>Watching Livestream</h1>
        <Video />
      </div>
    </PlayerAPIProvider>
  );
}

export default Viewer;

Success! You now have a basic broadcaster and viewer. The viewer can watch the livestream with ultra-low latency.

Vanilla JavaScript

Vanilla JavaScript Implementation

Step 1: Installation

No installation needed! Load the SDK directly from CDN using an import map:

<!DOCTYPE html>
<html>
<head>
  <script type="importmap">
  {
    "imports": {
      "vdc-cdn": "https://cdn.nativeframe.com/video-client-core/14.0.0/index.js"
    }
  }
  </script>
</head>
<body>
  <script type="module">
    import { createCall } from 'vdc-cdn';
    // Your code here
  </script>
</body>
</html>

The library loads on-demand from our CDN - no build step required.

Step 2: Your First Broadcaster

Let's create a simple broadcaster that streams your camera to viewers.

<!DOCTYPE html>
<html>
<head>
  <script type="importmap">
  {
    "imports": {
      "vdc-cdn": "https://cdn.nativeframe.com/video-client-core/14.0.0/index.js"
    }
  }
  </script>
</head>
<body>
  <div id="preview"></div>
  <button id="startBtn">Start Broadcasting</button>
  <button id="stopBtn" style="display:none">Stop Broadcasting</button>

  <script type="module">
    import {
      createCall,
      BaseAuthClient,
      mediaController,
      requestPlayer
    } from 'vdc-cdn';

    let call, broadcast;

    // Set up authentication
    const authClient = new BaseAuthClient({
      authUrl: 'https://your-subdomain.nativeframe.com/api/auth',
      token: 'your-broadcaster-token'
    });

    // Initialize camera
    await mediaController.initialize();
    const mediaStreamController = mediaController.createMediaStreamController();

    // Create preview
    const previewPlayer = await requestPlayer({
      mediaStreamController,
      muted: true
    });

    const video = document.createElement('video');
    document.getElementById('preview').appendChild(video);
    previewPlayer.attach(video);

    // Start broadcast
    document.getElementById('startBtn').onclick = async () => {
      call = await createCall({
        streamKey: 'your-stream-key',
        backendEndpoints: ['https://your-subdomain.nativeframe.com'],
        auth: authClient,
        user: { userId: 'user-1', displayName: 'Broadcaster' }
      });

      broadcast = await call.broadcast(mediaStreamController, {
        streamName: 'default'
      });

      document.getElementById('startBtn').style.display = 'none';
      document.getElementById('stopBtn').style.display = 'block';
    };

    // Stop broadcast
    document.getElementById('stopBtn').onclick = async () => {
      await broadcast?.dispose();
      await call?.dispose();

      document.getElementById('startBtn').style.display = 'block';
      document.getElementById('stopBtn').style.display = 'none';
    };
  </script>
</body>
</html>

That's it! You now have a working broadcaster with camera preview and controls.

Step 3: Your First Viewer

Now let's create a viewer that watches the broadcast:

<!DOCTYPE html>
<html>
<head>
  <script type="importmap">
  {
    "imports": {
      "vdc-cdn": "https://cdn.nativeframe.com/video-client-core/14.0.0/index.js"
    }
  }
  </script>
</head>
<body>
  <div id="player"></div>

  <script type="module">
    import { createPlayer, BaseAuthClient } from 'vdc-cdn';

    const authClient = new BaseAuthClient({
      authUrl: 'https://your-subdomain.nativeframe.com/api/auth',
      token: 'your-viewer-token'
    });

    const player = await createPlayer({
      callId: 'call-id-from-broadcaster',
      streamName: 'default',
      backendEndpoints: ['https://your-subdomain.nativeframe.com'],
      auth: authClient
    });

    const video = document.createElement('video');
    video.controls = true;
    document.getElementById('player').appendChild(video);
    player.attach(video);
  </script>
</body>
</html>

Success! You now have a basic broadcaster and viewer. The viewer can watch the livestream with ultra-low latency.

---

Next Steps

Now that you have the basics working, explore more features:

📚 Essential Guides

Broadcasting

Learn how to broadcast video streams from cameras, screens, or canvas elements

Viewing Streams

Build video players for your viewers with custom controls and styling

🛠️ Resources

• FAQ - Common questions and answers
• Troubleshooting - Solutions to common issues

---

Understanding the Basics

Before diving deeper, here are some key concepts:

Authentication

All NativeFrame operations require authentication via JWT tokens:

• Broadcaster tokens - Create calls and broadcast streams
• Viewer tokens - View public streams
• Private viewer tokens - View private/invite-only streams

Tokens are provided by your backend and include user permissions.

Calls and Broadcasts

• A Call is a connection to the NativeFrame backend (think of it as a "room")
• A Broadcast is an active stream within a call
• Multiple broadcasts can exist in one call (e.g., multiple participants)
• Viewers join calls to watch broadcasts

Media Stream Controller

Manages camera and microphone access:

• Controls device selection
• Toggles camera/mic on/off
• Switches between multiple devices
• Provides the media stream for broadcasting

Players

Display video content:

• Preview Player - Shows your own camera (for broadcasters)
• Player - Shows remote streams (for viewers)
• Players automatically handle buffering, quality adaptation, and playback

---

Getting Help

Need Support?

❓ FAQ

Common questions and answers about NativeFrame implementation

🔧 Troubleshooting

Solutions to common issues like permissions, connections, and compatibility

---

What's Next?

You're ready to start building! Here are some suggested paths:

For broadcasters:

1. Start with Set up a livestream video
2. Add device controls and UI customization
3. Explore advanced features like canvas streaming or screen sharing

For viewers:

1. Start with View a stream
2. Customize the player to match your brand
3. Add features like quality selection and fullscreen

For interactive apps:

1. Explore Private calls for one-on-one interactions
2. Learn about Group calls for multi-participant video
3. Add waiting rooms and participant management

Happy streaming! 🎥