usePixelStream

A React hook library for integrating with PixelStream video and audio streaming services.

Installation

npm install usepixelstream
# or
yarn add usepixelstream

Features

• WebRTC-based video and audio streaming
• WebSocket signaling for connection establishment
• React Context Provider for app-wide stream access
• Standalone hook for component-specific usage
• TypeScript support

Usage

Basic Usage

import { usePixelStream } from 'usepixelstream';

function VideoPlayer() {
  const { 
    streams, 
    isConnected, 
    error, 
    connect, 
    disconnect 
  } = usePixelStream({
    connectionUrl: 'wss://your-pixelstream-server.com',
    autoConnect: true
  });

  return (
    <div>
      {isConnected ? (
        <video 
          ref={(el) => {
            if (el && streams.video) {
              el.srcObject = streams.video;
              el.play();
            }
          }}
          width="640"
          height="360"
        />
      ) : (
        <div>Connecting to stream...</div>
      )}
      
      {error && <div className="error">{error}</div>}
      
      <button onClick={connect}>Connect</button>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}

Using the Provider

import { PixelStreamProvider, usePixelStream } from 'usepixelstream';

// In your app root
function App() {
  return (
    <PixelStreamProvider connectionUrl="wss://your-pixelstream-server.com">
      <YourApp />
    </PixelStreamProvider>
  );
}

// In any child component
function VideoComponent() {
  // No need to pass connectionUrl here, it uses the provider
  const { streams, isConnected } = usePixelStream({});
  
  // Use streams.video and streams.audio
  return (
    // Your component JSX
  );
}

Sending Messages

function Controller() {
  const { sendMessage, isConnected } = usePixelStream({
    connectionUrl: 'wss://your-pixelstream-server.com'
  });
  
  const handleAction = () => {
    if (isConnected) {
      sendMessage({
        action: 'performAction',
        parameters: {
          // Your parameters
        }
      });
    }
  };
  
  return (
    <button onClick={handleAction} disabled={!isConnected}>
      Perform Action
    </button>
  );
}

Response Listeners

import { useEffect } from 'react';
import { usePixelStream } from 'usepixelstream';

function ResponseHandler() {
  const { addResponseListener, removeResponseListener, isConnected } = usePixelStream({
    connectionUrl: 'wss://your-pixelstream-server.com'
  });
  
  useEffect(() => {
    const handleResponse = (response) => {
      const data = JSON.parse(response);
      // Handle the response
      console.log('Received response:', data);
    };
    
    if (isConnected) {
      addResponseListener(handleResponse);
    }
    
    return () => {
      removeResponseListener(handleResponse);
    };
  }, [isConnected, addResponseListener, removeResponseListener]);
  
  return null; // This component just handles responses
}

API Reference

usePixelStream Hook

function usePixelStream(args: UsePixelStreamArgs): UsePixelStreamReturn;

interface UsePixelStreamArgs {
  connectionUrl: string;
  autoConnect?: boolean;
}

interface UsePixelStreamReturn {
  isConnected: boolean;
  error: string;
  streams: {
    video: MediaStream | null;
    audio: MediaStream | null;
  };
  connect: () => void;
  disconnect: () => void;
  sendMessage: (descriptor: any) => void;
  addResponseListener: (listener: (response: string) => void) => void;
  removeResponseListener: (listener: (response: string) => void) => void;
  setConnectionUrl: (url: string, reconnect?: boolean) => void;
}

PixelStreamProvider Component

interface PixelStreamProviderProps extends UsePixelStreamArgs {
  children: ReactNode;
}

function PixelStreamProvider(props: PixelStreamProviderProps): JSX.Element;

Browser Compatibility

This library uses WebRTC and WebSockets, which are supported in all modern browsers:

• Chrome 55+
• Firefox 52+
• Safari 11+
• Edge 79+

License

ISC