Frequently Asked Questions

Common questions and answers about NativeFrame implementation

Getting Started

If you're building a broadcaster application, start with Set up a livestream video. This demo shows you how to set up a preview player, access camera and microphone, and start broadcasting.

If you're building a viewer application, start with View a stream. This demo shows you how to set up a video player to consume and display livestreams.

Both demos are available in React and Vanilla JavaScript versions, so choose based on your framework preference.

React demos use the @video/video-client-react package and provide:

• React hooks (usePreviewPlayer, useAuthClient, useCallControls)
• React Context Providers for state management
• Pre-built React components
• Modern React patterns with functional components

Vanilla JavaScript demos use the @video/video-client-core package loaded from CDN and provide:

• No framework dependencies
• Direct API access to core functionality
• ES modules with import maps
• Manual state management

Both implementations offer the same underlying functionality. Choose React if you're building a React application, or Vanilla JS if you prefer framework-free development or need to integrate with other frameworks.

To run any NativeFrame demo, you'll need:

Required:

• Authentication Token: A JWT token for broadcaster or viewer authentication (provided by NativeFrame)
• Stream Key: A unique identifier for your stream (provided by NativeFrame)
• Backend Endpoint: Your NativeFrame backend URL (e.g., https://your-subdomain.nativeframe.com)

For React demos:

• Node.js and npm/yarn
• React 16.8+ (for hooks support)
• @video/video-client-react package

For Vanilla JS demos:

• A web server to serve HTML files (due to ES modules and CORS)
• Modern browser with ES modules support

Contact NativeFrame to obtain your authentication credentials and backend endpoint.

Broadcasting

Use the Set up a livestream video demo. This demonstrates:

• Requesting camera and microphone permissions
• Creating a preview player to see what you're broadcasting
• Setting up device controls (camera toggle, mic mute, device selection)
• Authenticating with NativeFrame backend
• Creating a call and starting a broadcast
• Managing broadcast lifecycle (start/stop)

This is the foundation for all broadcasting scenarios. Once you understand this basic setup, you can extend it with additional features like screen sharing, canvas streaming, or custom UI.

Use the Livestream a canvas element demo. This shows you how to:

• Create and manipulate HTML canvas elements
• Capture canvas output as a MediaStream
• Broadcast canvas content instead of camera feed
• Combine canvas with audio from microphone

This is useful for:

• Broadcasting games or interactive graphics
• Creating custom visualizations
• Adding overlays and effects to video
• Building drawing or whiteboard applications

Use the Screenshare Broadcaster demo. This demonstrates:

• Requesting screen capture permissions
• Broadcasting your entire screen or specific windows
• Switching between camera and screen sharing
• Combining screen sharing with audio

Screen sharing is commonly used for:

• Remote presentations and demos
• Educational content and tutorials
• Collaborative work sessions
• Technical support scenarios

Direct streaming enables private, one-to-one or small group broadcasts where only specific authorized viewers can access the stream. Use the Direct Streaming Broadcaster demo.

Use direct streaming for:

• Private consultations or meetings
• Customer support video calls
• One-on-one coaching or tutoring
• Exclusive content delivery

Key differences from public broadcasting:

• Restricted viewer access (invite-only)
• Enhanced privacy and security
• Lower viewer capacity (optimized for small groups)
• Private viewer authentication required

Public broadcasting is better for large audiences, while direct streaming is ideal for private interactions.

Use the Customize your streaming application demo. This shows advanced customization techniques:

• Building custom UI components
• Creating branded video players
• Adding custom controls and interactions
• Implementing advanced features (pip, resolution selection, effects)
• Styling to match your application design

Start with the basic setup demo, then apply these customization patterns to create a unique experience for your users.

Viewing Streams

Use the View a stream demo. This demonstrates:

• Creating a video player for viewing streams
• Connecting to a broadcast using a call ID
• Handling stream playback and buffering
• Managing player lifecycle
• Implementing basic player controls

Viewers need:

• Valid viewer authentication token
• Call ID of the active broadcast
• Backend endpoint configuration

The player automatically handles adaptive bitrate streaming to optimize quality based on network conditions.

View a Stream (standard method):

• Connects directly to a call using call ID
• Uses Video Client SDK for playback
• Provides low-latency streaming
• Offers fine-grained control and events
• Best for interactive applications

Play a Stream Using a Manifest (manifest method):

• Uses HLS or other manifest formats
• Compatible with standard video players
• Works with CDN delivery
• Better for wide browser compatibility
• Suitable for traditional video-on-demand workflows

Use View a Stream for real-time, interactive livestreaming. Use manifest playback when you need compatibility with standard video infrastructure or CDN delivery.

Use the Direct Streaming Viewer demo. Private stream viewing requires:

• Private viewer token: Special authentication for private access
• Stream key or call ID: From the broadcaster
• Authorization: Permission from the broadcaster

Unlike public stream viewing, private streaming enforces access control at the authentication level. Viewers without proper authorization cannot access the stream.

Use the Customize your player demo. This shows how to:

• Add custom playback controls (play, pause, volume, fullscreen)
• Implement quality selection UI
• Add branding and styling
• Display stream metadata and stats
• Handle player events for custom behavior

The player provides a flexible API for building completely custom video experiences while maintaining performance and reliability.

Group Calls

NativeFrame supports multi-participant group calls with distinct roles:

Group Call Owner (use Create a Group Call Owner demo):

• Initiates and controls the group call
• Broadcasts their video/audio to all participants
• Can manage participant permissions
• Controls call lifecycle

Group Call Participant (use Create a Group Call Participant demo):

• Joins existing group calls
• Views owner and other participants
• Can broadcast their own video/audio (if permitted)
• Receives real-time updates

Group calls are ideal for:

• Video conferencing and meetings
• Virtual classrooms
• Collaborative sessions
• Panel discussions

Owner:

• Creates the call and receives a call ID
• Has full control over call settings
• Can admit/remove participants (with waiting room)
• Automatically broadcasts to all participants
• Responsible for call lifecycle management

Participant:

• Joins using the owner's call ID
• Limited control (can leave, toggle own devices)
• May need owner approval to join (waiting room)
• Can view owner and other participants

Think of the owner as the "host" and participants as "guests" in the call.

Use the Waiting Room demo. This implements a lobby where:

• Participants request to join the call
• Owner sees pending join requests
• Owner can approve or deny participants
• Approved participants enter the call automatically

Benefits of a waiting room:

• Control over who joins your calls
• Prevents unauthorized access
• Allows host to prepare before admitting participants
• Professional meeting experience

The waiting room pattern is commonly used for:

• Professional meetings and webinars
• Private group sessions
• Moderated discussions
• Educational settings

Advanced Features

Echo Pillarbox is a technique for handling vertical video in horizontal layouts (or vice versa). When video aspect ratios don't match the player dimensions, Echo Pillarbox fills the empty space with a blurred, mirrored version of the video.

Use the Echo Pillarbox demo to see this effect in action.

Use cases:

• Mobile-first applications with vertical video
• Responsive layouts that adapt to different aspect ratios
• Aesthetic enhancement of letterboxed content
• Maintaining viewer engagement in empty space

Traditional approaches:

• Black bars (letterbox/pillarbox) - less visually appealing
• Cropping - loses content
• Stretching - distorts video

Echo Pillarbox provides a modern, visually pleasing alternative that maintains the original video while filling empty space creatively.

NativeFrame uses JWT (JSON Web Token) authentication. Your application needs:

For Broadcasters:

const authClient = new BaseAuthClient({
  authUrl: 'your-auth-endpoint',
  token: 'broadcaster-jwt-token',
  refreshToken: optionalRefreshFunction
});

For Viewers:

const authClient = new BaseAuthClient({
  authUrl: 'your-auth-endpoint',
  token: 'viewer-jwt-token',
  refreshToken: optionalRefreshFunction
});

Token types:

• Broadcaster tokens: Allow creating calls and broadcasting
• Viewer tokens: Allow viewing public streams
• Private viewer tokens: Allow viewing private/direct streams

Tokens are provided by your backend and should include appropriate scopes/permissions. See Authentication documentation for details on token generation and refresh.

By default, the player includes hls.js and mpegts.js libraries in the bundle for immediate playback capability. You can exclude these packages to reduce bundle size, though this adds a small delay when these players are first needed.

To exclude these libraries:

Use a JavaScript minifier/bundler that can replace process.env variables and remove dead code, then pass these environment variables:

• HLSJS_BUNDLED=false - Excludes hls.js (loads on demand)
• MPEGTS_BUNDLED=false - Excludes mpegts.js (loads on demand)

Trade-offs:

• Smaller bundle size: Faster initial page load
• Lazy loading: Small delay when starting playback
• Network request: Additional HTTP request for library download

Recommended approach:

• For applications where most users will play video: include in bundle
• For applications where video is optional/rare: lazy load on demand
• Measure your specific use case to determine the best approach

Framework and API

Yes! NativeFrame supports multiple integration approaches:

Vanilla JavaScript (Framework-agnostic):

• Use @video/video-client-core from CDN
• Direct API access works with any framework
• See Vanilla JS demos for examples

React:

• Use @video/video-client-react package
• Includes hooks and components
• Idiomatic React patterns

Other frameworks (Vue, Angular, Svelte, etc.):

• Use the core @video/video-client-core library
• Create framework-specific wrappers as needed
• Follow patterns similar to Vanilla JS demos
• Adapt to your framework's state management

The core library is framework-agnostic, making it easy to integrate with any JavaScript framework or no framework at all.

Complete API documentation is available in the VideoClientAPI reference, which includes:

• Core Classes: Call, Broadcast, MediaStreamController, Player
• Methods: Full method signatures and parameters
• Events: Available events and event data
• Types: TypeScript type definitions
• Configuration Options: All available configuration parameters

For React-specific APIs:

• Hook documentation (usePreviewPlayer, useAuthClient, etc.)
• Component APIs (Context Providers, props)
• React-specific patterns and best practices

For implementation examples, refer to the demo source code which demonstrates real-world usage of all major APIs.