Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt

Use this file to discover all available pages before exploring further.

This page covers Web SDK code-level issues — problems you hit while wiring the SDK into your app. Click any item below to expand it.
For blurry streams, connection failures, audio problems, mobile disconnects, or stuck builds, see the general Troubleshooting page first. Those issues apply to all Streampixel users, not just SDK developers.

​
Build & setup

Symptom: Build errors like Module not found: Error: Can't resolve 'crypto' or similar.The SDK requires Node.js polyfills for browser use. See the Installation page for the complete config-overrides.js setup.
Symptom: Everything works on localhost but fails when deployed.Solutions:
  • The SDK validates window.location.origin against the project’s allowed URLs list in the dashboard. Add your production domain to the validPathUrl setting.
  • localhost is always allowed for development.
  • Wildcard patterns are supported (e.g., *.example.com).

​
Runtime & integration

Symptom: Console warning and SDK returns empty object {}.StreamPixelApplication is a singleton — it can only be initialized once per page. This commonly happens in React when:
  • The component re-renders and calls StreamPixelApplication again
  • useEffect dependencies change, triggering reinitialization
Fix: Use a ref or flag to ensure single initialization:
const initialized = useRef(false);

useEffect(() => {
  if (initialized.current) return;
  initialized.current = true;

  StreamPixelApplication({ appId }).then(/* ... */);
}, [appId]);
Symptom: You see unfamiliar buttons, panels, or overlays from the default PS UI.Solutions:
  • Add CSS to hide the default UI: 
    #uiFeatures { display: none !important; }
#afkOverlay { display: none !important; }
  • Also hide programmatically after initialization: 
    const uiEl = appStream.rootElement?.querySelector('#uiFeatures');
if (uiEl) uiEl.style.display = 'none';
  • The #uiFeatures element may re-appear after onVideoInitialized, so hide it in that callback too.
Symptom: Stats show something like RTCCodec_1_Inbound_120 instead of H264.Resolve the codec ID from the codecs Map:
pixelStreaming.addEventListener('statsReceived', (e) => {
  const stats = e.data.aggregatedStats;
  const codecId = stats.inboundVideoStats.codecId;
  const codec = stats.codecs.get(codecId);
  console.log('Codec:', codec?.mimeType); // "video/H264"
});
Symptom: After a disconnect, the SDK doesn’t attempt to reconnect.Solutions:
  • Automatic reconnection only triggers for WebSocket close codes 1005 and 1006 (abnormal closures). All other codes (project inactive, max runtime, etc.) are intentional disconnects.
  • The reconnection window is 60 seconds. If the server doesn’t respond within that time, reconnection fails with code 4007.
  • Listen to reconnectStream.on('state', ...) to see the exact state transitions and codes.

​
Next steps

General troubleshooting

Stream quality, connection, audio, and build issues that apply to all users.

reconnectStream API

Inspect reconnection state and disconnect codes.

Stream statistics

Use stats to diagnose codec, bitrate, and packet loss issues.