Troubleshooting

Solutions to common issues when implementing Native Frame

This guide covers common issues you might encounter when implementing Native Frame and provides solutions to resolve them quickly.

Camera and Microphone Issues

Problem: The preview player shows a black screen or no audio is captured.

Common causes and solutions:

1. Permissions not granted

   • Check browser permissions in the address bar or browser settings
   • The browser should prompt for camera/microphone access on first use
   • On mobile, check device Settings → Safari/Chrome → Camera/Microphone permissions

2. Camera/mic in use by another application

   • Close other applications that might be using the camera (Zoom, Skype, etc.)
   • Refresh the browser page to release any stale media streams

3. Media stream not initialized

      // React: Ensure usePreviewPlayer has completed initialization
      const { mediaStreamController, previewPlayer, isLoading } = usePreviewPlayer();
   
      if (isLoading) {
        return <div>Loading camera...</div>;
      }
   
      // Vanilla JS: Wait for requestEncoder to complete
      const { mediaStreamController, previewPlayer } = await requestEncoder();

4. Video element not properly attached

      // React: Wrap components with PlayerAPIProvider
      <PlayerAPIProvider player={previewPlayer}>
        <Video />
      </PlayerAPIProvider>
   
      // Vanilla JS: Ensure player.attach() is called
      previewPlayer.attach(videoElement);

5. Device not available

   • Check if the device actually has a camera/microphone
   • Try unplugging and replugging external USB cameras
   • Check for hardware switches (some laptops have physical camera disable switches)

Problem: Browser throws permission error when requesting camera/microphone.

Solutions:

1. Reset browser permissions

   • Chrome: Click the lock icon in address bar → Site settings → Reset permissions
   • Safari: Safari menu → Settings → Websites → Camera/Microphone → Remove site
   • Firefox: Click the shield icon → Clear permissions

2. HTTPS requirement

   • Camera/microphone access requires HTTPS (except localhost)
   • Ensure your site is served over HTTPS in production
   • For local development, use https://localhost or http://localhost

3. Check browser compatibility

   • Ensure you're using a supported browser (Chrome, Safari, Firefox, Edge)
   • Update to the latest browser version
   • Some older browsers don't support getUserMedia API

4. Handle permission denial gracefully

      try {
        const { mediaStreamController } = usePreviewPlayer();
      } catch (error) {
        if (error.name === 'NotAllowedError') {
          // Show UI prompting user to grant permissions
          showPermissionDeniedMessage();
        }
      }

Problem: Device selection dropdown doesn't work or switching devices fails.

Solutions:

1. Enumerate devices before selecting

      // Get available devices
      const { audioDevices, videoDevices } = await mediaController.enumerateDevices();
   
      // Select specific device
      await mediaStreamController.setVideoDevice(videoDevices[0].deviceId);
      await mediaStreamController.setAudioDevice(audioDevices[0].deviceId);

2. Wait for device list to populate

   • Device labels may be empty until permissions are granted
   • Request permissions first, then enumerate devices

3. Handle device errors

      try {
        await mediaStreamController.setVideoDevice(deviceId);
      } catch (error) {
        console.error('Failed to switch camera:', error);
        // Fall back to default device or show error to user
      }

4. Check device constraints

   • Some devices may not support requested resolutions
   • Try setting device without additional constraints first

Problem: Preview video appears flipped or inverted.

Solutions:

1. Mirror the preview for better UX

      /* Mirror the video element for preview (like a mirror) */
      video.preview {
        transform: scaleX(-1);
      }

   Note: This only affects the local preview. Viewers will see the correct orientation.

2. Handle device orientation

   • Mobile devices may need orientation handling
   • Use CSS transforms to adjust based on device orientation
   • Consider using the Screen Orientation API

3. Rotation issues

   • Some cameras (especially external USB cameras) may have incorrect rotation metadata
   • This is typically a hardware/driver issue
   • Can be corrected with CSS transforms on the video element

Connection and Network Issues

Problem: Call creation fails with connection error.

Common causes and solutions:

1. Invalid authentication

      // Verify token is valid and not expired
      const authClient = new BaseAuthClient({
        authUrl: 'https://your-subdomain.nativeframe.com/api/auth',
        token: validBroadcasterToken, // Must be valid JWT
      });

2. Incorrect backend endpoint

      // Ensure backend endpoint is correct (include https://)
      const backendEndpoints = [
        'https://your-subdomain.nativeframe.com' // Correct format
      ];
   
      // Common mistakes:
      // ❌ 'your-subdomain.nativeframe.com' (missing https://)
      // ❌ 'https://nativeframe.com' (missing subdomain)

3. Invalid stream key

   • Verify stream key is correct and active
   • Stream keys are case-sensitive
   • Contact Native Frame if you need to regenerate your stream key

4. Network/firewall blocking WebRTC

   • Check if corporate firewall blocks WebRTC traffic
   • Verify ports are open: UDP 16384-32767, TCP 443
   • Try from different network to isolate issue

5. CORS issues

   • Ensure your domain is whitelisted with Native Frame
   • Check browser console for CORS errors
   • Verify clientReferrer matches your domain

Problem: Call connects but disconnects unexpectedly.

Solutions:

1. Handle connection state changes

      call.on('connectionStateChange', (state) => {
        console.log('Connection state:', state);
   
        if (state === 'disconnected') {
          // Attempt reconnection
          attemptReconnect();
        }
      });

2. Network instability

   • Poor WiFi or cellular connection
   • Try wired connection if possible
   • Check network speed (recommend 5+ Mbps upload for HD broadcasting)

3. Token expiration

   • Implement token refresh before expiration

      const authClient = new BaseAuthClient({
        token: currentToken,
        refreshToken: async () => {
          // Fetch new token from your backend
          const newToken = await fetchNewToken();
          return newToken;
        }
      });

4. Browser tab backgrounded (mobile)

   • Mobile browsers may suspend WebRTC when tab is backgrounded
   • Warn users to keep app in foreground
   • Consider implementing reconnection logic

5. Server maintenance

   • Check Native Frame status page for service interruptions
   • Implement retry logic with exponential backoff

Problem: Video is low quality, pixelated, or buffers frequently.

Solutions:

1. Network bandwidth insufficient

   • Check upload speed for broadcaster: speedtest.net
   • Check download speed for viewer: speedtest.net
   • Recommended: 5+ Mbps upload (broadcast), 3+ Mbps download (view)

2. Adjust video constraints

      // Lower resolution for poor connections
      const constraints = {
        video: {
          width: { ideal: 640 },  // Lower from 1280
          height: { ideal: 480 }, // Lower from 720
          frameRate: { ideal: 24 } // Lower from 30
        }
      };

3. Enable adaptive bitrate

   • Native Frame automatically provides adaptive bitrate
   • Ensure viewer player is configured to use ABR
   • Multiple quality levels will be available based on network

4. CPU/GPU limitations

   • Encoding HD video requires significant CPU
   • Close other applications
   • Lower resolution/framerate if device struggles
   • Check CPU usage during broadcast

5. Server selection

   • Ensure using the closest backend endpoint
   • Geographic distance affects latency
   • Configure multiple endpoints for failover

Problem: Significant delay (5+ seconds) between broadcasting and viewing.

Solutions:

1. Use WebRTC for lowest latency

   • Ensure using Video Client SDK (not HLS/manifest)
   • Direct call viewing has lowest latency (< 1 second)
   • Manifest/HLS playback has higher latency (3-30 seconds)

2. Check network conditions

   • Latency increases with poor network conditions
   • Use wired connections when possible
   • Minimize network hops

3. Server geographic distance

   • Choose backend endpoint closest to broadcaster
   • Viewers should connect to same region
   • Cross-region streaming adds latency

4. Browser/device performance

   • Older devices may have processing delays
   • Close unnecessary browser tabs
   • Disable browser extensions that might interfere

5. Expected latency ranges

   • WebRTC direct: 0.5-2 seconds (glass-to-glass)
   • HLS: 6-30 seconds
   • Some latency is normal and expected

Authentication and Authorization Issues

Problem: Requests fail with authentication errors.

Solutions:

1. Verify token format and validity

      // Token should be a valid JWT string
      const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
   
      // Check token hasn't expired
      const payload = JSON.parse(atob(token.split('.')[1]));
      const isExpired = payload.exp * 1000 < Date.now();
      console.log('Token expired:', isExpired);

2. Correct token scope

   • Broadcaster tokens: Required for creating calls and broadcasting
   • Viewer tokens: Required for viewing streams
   • Private viewer tokens: Required for private/direct streams
   • Ensure token has appropriate scope for the operation

3. Token refresh implementation

      const authClient = new BaseAuthClient({
        authUrl: 'https://your-subdomain.nativeframe.com/api/auth',
        token: initialToken,
        refreshToken: async () => {
          // Implement token refresh logic
          const response = await fetch('/api/refresh-token');
          const { token } = await response.json();
          return token;
        }
      });

4. Authorization URL mismatch

   • Ensure authUrl matches your backend endpoint
   • URL should include /api/auth path
   • Verify HTTPS is used

5. Contact Native Frame

   • If issues persist, verify your account is active
   • Check if your domain is whitelisted
   • Confirm your credentials are correct

Problem: Operation fails with permission error.

Solutions:

1. Verify token scope matches operation

      // Creating call requires broadcaster token
      const call = await createCall({
        auth: broadcasterAuthClient, // ✓ Correct
        // auth: viewerAuthClient,   // ✗ Will fail
      });
   
      // Viewing stream requires viewer token
      const player = await createPlayer({
        auth: viewerAuthClient,      // ✓ Correct
      });

2. Check stream key permissions

   • Ensure stream key is associated with your account
   • Verify stream key hasn't been revoked
   • Confirm stream key allows the requested operation

3. Private streaming permissions

   • Private streams require special viewer tokens
   • Ensure private viewer token includes correct permissions
   • Verify viewer is authorized for specific stream

4. Account limitations

   • Check if your account tier supports the feature
   • Verify concurrent stream limits
   • Confirm your account is active and in good standing

Broadcasting Issues

Problem: call.broadcast() fails or throws error.

Solutions:

1. Ensure call is connected first

      // ✓ Correct: Wait for call to be created
      const call = await createCall(options);
      const broadcast = await call.broadcast(mediaStreamController, broadcastOptions);
   
      // ✗ Wrong: Trying to broadcast without call
      const broadcast = await call.broadcast(...); // call is undefined

2. Verify media stream controller

      // Ensure mediaStreamController is initialized
      const { mediaStreamController } = usePreviewPlayer();
   
      if (!mediaStreamController) {
        console.error('Media stream controller not ready');
        return;
      }
   
      // Check that media tracks exist
      const tracks = mediaStreamController.getTracks();
      console.log('Available tracks:', tracks);

3. Check stream name

      // Stream name is required and must be non-empty
      const broadcastOptions = {
        streamName: 'default', // ✓ Valid
        // streamName: '',     // ✗ Invalid
      };

4. Network/firewall blocking

   • Verify WebRTC traffic isn't blocked
   • Check browser console for ICE connection errors
   • Try from different network

5. Call state issues

      // Check call state before broadcasting
      if (call.state === 'connected') {
        const broadcast = await call.broadcast(...);
      }

Problem: Broadcast starts successfully but stops without user action.

Solutions:

1. Handle broadcast lifecycle events

      broadcast.on('stateChange', (state) => {
        console.log('Broadcast state:', state);
   
        if (state === 'stopped') {
          console.log('Broadcast stopped reason:', broadcast.stopReason);
          // Handle reconnection or show error to user
        }
      });

2. Camera/microphone disconnected

   • Check if device was unplugged
   • Handle device change events

      navigator.mediaDevices.addEventListener('devicechange', async () => {
        console.log('Device list changed');
        // Re-enumerate devices and update UI
      });

3. Memory/resource exhaustion

   • Broadcasting for extended periods may cause issues
   • Ensure proper disposal of old streams
   • Monitor browser memory usage

4. Network interruption

   • Poor network caused connection drop
   • Implement automatic reconnection logic
   • Show connection quality indicators to broadcaster

5. Token expiration during broadcast

   • Ensure token refresh is implemented
   • Refresh tokens proactively before expiration
   • Handle auth refresh during active broadcast

Problem: Broadcast appears successful but viewers can't see it.

Solutions:

1. Verify call ID sharing

      // Broadcaster: Get and share call ID
      const call = await createCall(options);
      console.log('Share this call ID with viewers:', call.id);
   
      // Viewer: Use correct call ID
      const player = await createPlayer({
        callId: 'call-id-from-broadcaster', // Must match exactly
      });

2. Check viewer authentication

   • Viewers need valid viewer tokens
   • For private streams, viewers need private viewer tokens
   • Verify viewer token hasn't expired

3. Broadcast state verification

      // Check broadcast is actually active
      console.log('Broadcast state:', broadcast.state);
      console.log('Broadcast stream name:', broadcast.streamName);
   
      // Viewer must request same stream name
      const player = await createPlayer({
        callId: callId,
        streamName: 'default' // Must match broadcaster's streamName
      });

4. Network/firewall on viewer side

   • Viewer's network may block WebRTC
   • Test from different network/device
   • Check viewer's browser console for errors

5. Timing issues

   • Viewer connected before broadcast started
   • Have viewer refresh and reconnect
   • Implement proper player state handling

Problem: Audio doesn't match video timing.

Solutions:

1. Check device/browser compatibility

   • Some devices have audio/video sync issues
   • Try different browser
   • Update browser to latest version

2. Network jitter

   • Unstable network can cause sync issues
   • Check for packet loss
   • Use wired connection if possible

3. Processing delays

   • CPU overload can cause sync issues
   • Close other applications
   • Lower video quality/resolution

4. Browser bugs

   • Some browsers have known sync issues
   • Clear browser cache and restart
   • Try incognito/private mode

5. Hardware acceleration

   • Enable hardware acceleration in browser settings
   • Chrome: Settings → Advanced → System → Hardware acceleration
   • This can improve sync by offloading video processing

Viewing and Playback Issues

Problem: Player shows black screen instead of video.

Solutions:

1. Verify player initialization

      // React: Ensure PlayerAPIProvider wraps Video component
      <PlayerAPIProvider player={player}>
        <Video />
      </PlayerAPIProvider>
   
      // Vanilla JS: Ensure attach is called
      player.attach(videoElement);

2. Check video element dimensions

      /* Video element needs width and height */
      video {
        width: 640px;
        height: 480px;
      }
   
      /* Or use aspect ratio */
      video {
        width: 100%;
        aspect-ratio: 16/9;
      }

3. Verify broadcast is active

   • Ensure broadcaster is actually streaming
   • Check call ID is correct
   • Verify stream name matches

4. Player not loaded

      // Wait for player ready event
      player.on('ready', () => {
        console.log('Player ready to display video');
      });
   
      // Check player state
      console.log('Player state:', player.state);

5. Browser codec support

   • Some browsers don't support all video codecs
   • Try different browser
   • Check for hardware acceleration settings

Problem: Viewer cannot find the stream.

Solutions:

1. Verify call ID

   • Double-check call ID is copied correctly
   • Call IDs are case-sensitive
   • Ensure no extra spaces or characters

2. Broadcast timing

   • Ensure broadcaster has created the call
   • Verify broadcast is active
   • Call must exist before viewer can join

3. Stream name mismatch

      // Broadcaster
      const broadcast = await call.broadcast(msc, { streamName: 'default' });
   
      // Viewer must use same stream name
      const player = await createPlayer({
        callId: callId,
        streamName: 'default' // Must match
      });

4. Call already ended

   • Broadcaster may have ended the call
   • Call IDs are typically session-specific
   • Need new call ID for new session

5. Authorization issues

   • Viewer may not have permission to view stream
   • Check viewer token is valid
   • For private streams, ensure proper authorization

Problem: Playback is choppy with frequent pauses.

Solutions:

1. Network bandwidth

   • Check viewer's internet speed
   • Close bandwidth-heavy applications
   • Reduce video quality if available

2. CPU/GPU overload

   • Close other applications and browser tabs
   • Enable hardware acceleration
   • Try lower quality stream

3. Browser performance

      // Monitor buffer health
      player.on('buffering', (buffering) => {
        if (buffering) {
          console.log('Player is buffering...');
        }
      });
   
      // Check frame drops
      player.getStats((stats) => {
        console.log('Dropped frames:', stats.droppedFrames);
      });

4. Multiple streams

   • Viewing multiple streams simultaneously causes strain
   • Limit number of concurrent streams
   • Prioritize important streams

5. Browser extensions

   • Ad blockers or privacy extensions may interfere
   • Try in incognito/private mode
   • Disable extensions temporarily

Problem: Can hear stream audio but video doesn't show.

Solutions:

1. Video element rendering

   • Ensure video element is visible in DOM
   • Check CSS doesn't hide video element

      /* Check for these issues */
      video {
        display: block; /* Not 'none' */
        visibility: visible; /* Not 'hidden' */
        opacity: 1; /* Not 0 */
      }

2. Video track availability

      // Check if video track exists
      const tracks = player.getTracks();
      const hasVideo = tracks.some(track => track.kind === 'video');
      console.log('Has video track:', hasVideo);

3. Broadcaster camera disabled

   • Broadcaster may have camera turned off
   • Only audio is being broadcast
   • Have broadcaster check camera state

4. Player configuration

      // Ensure player accepts video
      const player = await createPlayer({
        video: true, // Enable video
        audio: true,
      });

5. Codec compatibility

   • Browser may not support video codec
   • Check console for codec errors
   • Try different browser

Group Call Issues

Problem: Participant unable to join group call.

Solutions:

1. Verify call ID from owner

   • Ensure using correct call ID
   • Call must be created by owner first
   • Call ID must be shared exactly as provided

2. Check participant token

      // Participant needs valid token
      const authClient = new BaseAuthClient({
        token: participantToken, // Must be valid
      });

3. Waiting room enabled

   • Owner may need to approve join request
   • Check if waiting in lobby
   • Owner must admit participant

4. Call capacity reached

   • Group calls may have participant limits
   • Check if call is at max capacity
   • Wait for spot to open or contact owner

5. Network/permission issues

   • Same troubleshooting as regular connection issues
   • Verify camera/mic permissions
   • Check network connectivity

Problem: Joined call but don't see other participants' video.

Solutions:

1. Check remote stream rendering

      // Listen for remote streams
      call.on('remoteStreamAdded', (stream) => {
        console.log('Remote stream added:', stream);
        // Render remote stream in video element
        renderRemoteStream(stream);
      });

2. Other participants not broadcasting

   • Verify other participants have cameras enabled
   • Check if participants are actually broadcasting
   • Only broadcasters will be visible

3. Subscription issues

      // Ensure subscribed to remote streams
      await call.subscribe(remoteStream);

4. Network bandwidth

   • Multiple streams require significant bandwidth
   • May need to reduce quality
   • Close other applications

5. Render all remote participants

      // Maintain list of remote streams
      const remoteStreams = new Map();
   
      call.on('remoteStreamAdded', (stream) => {
        remoteStreams.set(stream.id, stream);
        updateParticipantGrid();
      });
   
      call.on('remoteStreamRemoved', (streamId) => {
        remoteStreams.delete(streamId);
        updateParticipantGrid();
      });

Problem: Participants bypass waiting room or approval doesn't work.

Solutions:

1. Verify waiting room configuration

      // Enable waiting room when creating call
      const call = await createCall({
        waitingRoom: {
          enabled: true,
        },
        // ... other options
      });

2. Handle admission events

      // Owner: Listen for join requests
      call.on('participantJoinRequest', (participant) => {
        console.log('Join request from:', participant);
   
        // Admit participant
        await call.admitParticipant(participant.id);
   
        // Or deny
        await call.denyParticipant(participant.id);
      });

3. Participant not waiting

      // Participant: Show waiting UI
      call.on('waitingRoomEntered', () => {
        showWaitingUI();
      });
   
      call.on('waitingRoomExited', () => {
        hideWaitingUI();
        // Admitted to call
      });

4. Permission issues

   • Owner must have permission to admit/deny
   • Verify owner role/permissions
   • Check token scopes

Canvas and Screen Sharing Issues

Problem: Canvas element not broadcasting or shows black.

Solutions:

1. Verify canvas stream capture

      // Ensure canvas is capturing correctly
      const canvas = document.getElementById('myCanvas');
      const stream = canvas.captureStream(30); // 30 FPS
   
      // Check stream has tracks
      console.log('Canvas stream tracks:', stream.getTracks());

2. Canvas dimensions

      // Canvas must have valid dimensions
      canvas.width = 1280;
      canvas.height = 720;
   
      // Or use CSS sizing
      canvas.style.width = '100%';

3. Canvas content rendering

   • Ensure canvas is actually drawn to
   • Canvas must have visible content

      const ctx = canvas.getContext('2d');
      ctx.fillStyle = 'blue';
      ctx.fillRect(0, 0, canvas.width, canvas.height);
      // Now capture will show blue canvas

4. Frame rate

      // Specify frame rate when capturing
      const stream = canvas.captureStream(30); // 30 FPS
      // Don't use 0 or omit (causes variable frame rate)

5. Canvas context

   • Use '2d' context for standard canvas
   • WebGL contexts may have different capture behavior
   • Ensure preserveDrawingBuffer for WebGL

      const gl = canvas.getContext('webgl', {
        preserveDrawingBuffer: true
      });

Problem: getDisplayMedia fails or screen share doesn't start.

Solutions:

1. HTTPS requirement

   • Screen sharing requires HTTPS (except localhost)
   • Ensure using https:// in production
   • For development, use https://localhost

2. User cancelled selection

      // Handle user cancellation
      try {
        const stream = await navigator.mediaDevices.getDisplayMedia({
          video: true,
          audio: true
        });
      } catch (error) {
        if (error.name === 'NotAllowedError') {
          console.log('User cancelled screen share');
          // Show appropriate message
        }
      }

3. Browser support

   • Ensure browser supports getDisplayMedia
   • Chrome, Firefox, Edge support it
   • Safari requires recent version (13+)

4. Check screen share constraints

      const stream = await navigator.mediaDevices.getDisplayMedia({
        video: {
          cursor: 'always', // Include cursor
          displaySurface: 'monitor' // Or 'window', 'browser'
        },
        audio: true // Include system audio if needed
      });

5. Handle screen share stop

      // Detect when user stops screen share via browser UI
      stream.getVideoTracks()[0].addEventListener('ended', () => {
        console.log('Screen share stopped');
        handleScreenShareStop();
      });

Integration and Development Issues

Problem: Cannot find Native Frame packages in the npm registry.

Solution:

1. Ensure proper .npmrc configuration

Make sure your .npmrc file includes the following:

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

Problem: Cannot import Native Frame packages.

Solutions:

1. Verify package installation

      # For React
      npm install @video/video-client-react
   
      # For Vanilla JS (core)
      npm install @video/video-client-core

2. Check import statements

      // React - Correct imports
      import { usePreviewPlayer } from '@video/video-client-react/hooks';
      import { MediaStreamControllerAPIProvider } from '@video/video-client-react/context';
   
      // Vanilla JS - CDN import
      import { createCall, requestPlayer } from 'vdc-cdn';

3. Import map configuration (Vanilla JS)

      <script type="importmap">
      {
        "imports": {
          "vdc-cdn": "https://cdn.nativeframe.com/video-client-core/14.0.0/index.js"
        }
      }
      </script>

4. TypeScript configuration

      // tsconfig.json
      {
        "compilerOptions": {
          "moduleResolution": "node",
          "esModuleInterop": true,
          "allowSyntheticDefaultImports": true
        }
      }

5. Package version compatibility

   • Ensure using compatible versions
   • Check package.json for version conflicts
   • Update to latest stable version

Problem: React hooks throwing errors.

Solutions:

1. Call hooks at top level

      // ✓ Correct
      function MyComponent() {
        const { mediaStreamController } = usePreviewPlayer();
        return <div>...</div>;
      }
   
      // ✗ Wrong - inside callback
      function MyComponent() {
        const handleClick = () => {
          const { mediaStreamController } = usePreviewPlayer(); // Error!
        };
      }

2. Ensure functional component

      // ✓ Correct - functional component
      function MyComponent() {
        const { player } = usePreviewPlayer();
      }
   
      // ✗ Wrong - class component
      class MyComponent extends React.Component {
        // Can't use hooks here
      }

3. React version

   • Hooks require React 16.8+
   • Update React if using older version

      npm install react@latest react-dom@latest

4. Multiple React copies

      # Check for duplicate React installations
      npm ls react
   
      # If duplicates found, dedupe
      npm dedupe

5. Context provider wrapping

      // Ensure components are wrapped in providers
      <MediaStreamControllerAPIProvider mediaStreamController={msc}>
        <MyComponent /> {/* Can now use context hooks */}
      </MediaStreamControllerAPIProvider>

Problem: Application bundle is larger than expected.

Solutions:

1. Exclude optional libraries

      // In webpack config or bundler
      {
        plugins: [
          new webpack.DefinePlugin({
            'process.env.HLSJS_BUNDLED': JSON.stringify('false'),
            'process.env.MPEGTS_BUNDLED': JSON.stringify('false')
          })
        ]
      }

2. Tree shaking

      // Use named imports for better tree shaking
      import { usePreviewPlayer, useAuthClient } from '@video/video-client-react/hooks';
   
      // Instead of
      import * as hooks from '@video/video-client-react/hooks';

3. Code splitting

      // Lazy load video components
      const VideoPlayer = React.lazy(() => import('./VideoPlayer'));
   
      function App() {
        return (
          <Suspense fallback={<Loading />}>
            <VideoPlayer />
          </Suspense>
        );
      }

4. Analyze bundle

      # Use bundle analyzer to see what's large
      npm install --save-dev webpack-bundle-analyzer
   
      # Run analysis
      npx webpack-bundle-analyzer build/stats.json

5. Use CDN for Vanilla JS

   • Core library from CDN doesn't count toward bundle
   • Loads on demand
   • Better for applications with optional video

Problem: TypeScript compilation errors with Native Frame types.

Solutions:

1. Import types correctly

      import { types } from '@video/video-client-react';
   
      // Use types
      const options: types.CreateCallOptions = {
        streamKey: 'my-key',
        // ...
      };

2. Type declarations

      // Create types.d.ts if types are missing
      declare module '@video/video-client-react' {
        export interface MediaStreamController {
          // Add missing type definitions
        }
      }

3. Strict mode issues

      // Handle nullable types
      const { mediaStreamController } = usePreviewPlayer();
   
      if (mediaStreamController) {
        // TypeScript knows it's not null here
        mediaStreamController.setVideoDevice(deviceId);
      }

4. Update type definitions

      # Ensure latest types are installed
      npm update @video/video-client-react

5. Type assertions (use sparingly)

      // Last resort if types are incorrect
      const player = createPlayer(options) as types.Player;

Browser and Device Compatibility

Problem: Features work in Chrome but not Safari.

Solutions:

1. WebRTC vendor prefixes

      // Use adapter.js for cross-browser compatibility
      // It normalizes WebRTC APIs across browsers
      import 'webrtc-adapter';

2. Autoplay policy

      // Safari requires user gesture for autoplay
      video.muted = true; // Muted videos can autoplay
   
      // Or wait for user interaction
      button.onclick = () => {
        video.play();
      };

3. getUserMedia in iframes

      <!-- Safari requires allow attribute -->
      <iframe allow="camera; microphone"></iframe>

4. VP8/VP9 codec support

   • Safari prefers H.264
   • Ensure backend supports H.264
   • Check codec negotiation in logs

5. iOS-specific

   • iOS Safari requires playsinline attribute

      <video playsinline></video>

   • iOS doesn't support background playback
   • Tab must be active for WebRTC

Problem: Features work on desktop but not mobile.

Solutions:

1. Camera orientation

      // Handle device orientation changes
      window.addEventListener('orientationchange', () => {
        // Adjust video layout
        updateVideoLayout();
      });

2. Mobile bandwidth constraints

   • Reduce default video quality on mobile

      const isMobile = /iPhone|iPad|Android/i.test(navigator.userAgent);
   
      const constraints = {
        video: isMobile ? {
          width: { ideal: 640 },
          height: { ideal: 480 }
        } : {
          width: { ideal: 1280 },
          height: { ideal: 720 }
        }
      };

3. Touch vs click events

      // Handle both touch and click
      button.addEventListener('touchstart', handleAction);
      button.addEventListener('click', handleAction);

4. Fullscreen API

      // Use webkit prefix for iOS
      if (video.webkitEnterFullscreen) {
        video.webkitEnterFullscreen();
      } else {
        video.requestFullscreen();
      }

5. Background tab handling

   • Mobile browsers aggressively suspend background tabs
   • Warn users to keep app in foreground
   • Handle visibility change events

      document.addEventListener('visibilitychange', () => {
        if (document.hidden) {
          console.log('App backgrounded');
          // Pause non-critical operations
        }
      });

Problem: Users on older browsers experience issues.

Solutions:

1. Check browser support

      function checkBrowserSupport() {
        if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
          alert('Your browser does not support video streaming. Please update to a modern browser.');
          return false;
        }
        return true;
      }

2. Polyfills

      // Include polyfills for older browsers
      import 'webrtc-adapter'; // WebRTC polyfill
      import 'whatwg-fetch';  // Fetch polyfill

3. Feature detection

      // Detect features before using
      if ('getDisplayMedia' in navigator.mediaDevices) {
        // Screen sharing supported
      } else {
        // Show fallback or disable feature
      }

4. Graceful degradation

   • Provide fallback UI for unsupported features
   • Show clear error messages
   • Link to browser update instructions

5. Minimum browser versions

   • Chrome 74+
   • Firefox 68+
   • Safari 12.1+
   • Edge 79+ (Chromium-based)

Echo Pillarbox Video

Solution:

• Ensure previewPlayer is initialized before rendering
• Verify PlayerAPIProvider wraps the EchoPillarboxWrapper
• Check that the Video component has a ref if needed

Solution:

• Make sure EchoPillarboxVideo is placed inside EchoPillarboxWrapper
• Verify the Video component is also inside the same wrapper
• The components must be siblings within the wrapper

Solution:

• Add explicit sizing to EchoPillarboxWrapper via style or className
• Use minHeight: '100%' or explicit dimensions
• Ensure parent containers have proper height constraints

Solution:

• Dispose the player in useEffect cleanup
• Clean up mediaStreamController
• EchoPillarboxVideo handles its own cleanup automatically

Still Having Issues?

If you've tried the solutions above and are still experiencing problems:

1. Check browser console for error messages and stack traces
2. Enable debug logging in Video Client SDK for detailed diagnostics
3. Test in incognito mode to rule out extensions/cache issues
4. Try different network to isolate network-specific problems
5. Contact Native Frame support with:
   • Detailed problem description
   • Browser and OS version
   • Console error messages
   • Steps to reproduce
   • Network conditions