VPSS - Virtual Participant Simulation Service

Mock participants for video call testing. VPSS provides a web interface and API to simulate multiple participants in a video call.

Installation

# Run directly with npx (no installation required)
npx vpss

# Or install globally
npm install -g vpss
vpss

The server starts on http://localhost:4747 by default.

CLI Options

vpss [options]

Options:
  -p, --port <number>  Port to run the server on (default: 4747)
  -d, --dev            Run in development mode
  -h, --help           Show help

Examples:
  vpss                  Start on default port 4747
  vpss --port 3000      Start on port 3000
  vpss -p 8080          Start on port 8080

Features

• Web UI to manage mock participants
• REST API for programmatic control
• WebSocket for real-time updates
• Simulate video, audio, screen share, and hand raised states
• Multiple participant roles (host, co-host, participant, guest)

REST API

List Participants

GET /api/mock-participants

Response:

[
  {
    "id": "abc123",
    "name": "John Doe",
    "role": "participant",
    "isVideoOn": true,
    "isAudioOn": true,
    "isHandRaised": false,
    "isScreensharingOn": false
  }
]

Create Participant

POST /api/mock-participants
Content-Type: application/json

{
  "name": "Jane Smith",
  "role": "participant"
}

Update Participant

PATCH /api/mock-participants/:id
Content-Type: application/json

{
  "isVideoOn": false,
  "isAudioOn": true,
  "isHandRaised": true
}

Valid update fields:

• isVideoOn (boolean)
• isAudioOn (boolean)
• isHandRaised (boolean)
• isScreensharingOn (boolean)
• role (string)

Delete Participant

DELETE /api/mock-participants/:id

WebSocket Integration

Connect to ws://localhost:4747/ws for real-time participant updates.

Message Types

participant_added

{
  "type": "participant_added",
  "participant": { ... },
  "allParticipants": [ ... ]
}

participant_updated

{
  "type": "participant_updated",
  "participant": { ... },
  "allParticipants": [ ... ]
}

participant_removed

{
  "type": "participant_removed",
  "participantId": "abc123"
}

Example Client

const ws = new WebSocket('ws://localhost:4747/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'participant_added':
      console.log('New participant:', data.participant);
      break;
    case 'participant_updated':
      console.log('Updated:', data.participant);
      break;
    case 'participant_removed':
      console.log('Removed:', data.participantId);
      break;
  }
};

Integration Examples

Fetch API (Browser)

// List all participants
const response = await fetch('http://localhost:4747/api/mock-participants');
const participants = await response.json();

// Create a participant
await fetch('http://localhost:4747/api/mock-participants', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Test User', role: 'participant' })
});

// Toggle video for a participant
await fetch(`http://localhost:4747/api/mock-participants/${id}`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ isVideoOn: false })
});

cURL

# List participants
curl http://localhost:4747/api/mock-participants

# Create participant
curl -X POST http://localhost:4747/api/mock-participants \
  -H "Content-Type: application/json" \
  -d '{"name": "Test User", "role": "participant"}'

# Update participant
curl -X PATCH http://localhost:4747/api/mock-participants/abc123 \
  -H "Content-Type: application/json" \
  -d '{"isVideoOn": false}'

# Delete participant
curl -X DELETE http://localhost:4747/api/mock-participants/abc123

React SDK

VPSS ships with React utilities for easy integration. Install the package and import directly.

useParticipants Hook

The simplest way to get participant data. Returns a live-updating array that automatically syncs via WebSocket.

import { useParticipants } from 'vpss';

function ParticipantList() {
  const participants = useParticipants();

  return (
    <ul>
      {participants.map(p => (
        <li key={p.id}>{p.name} ({p.role})</li>
      ))}
    </ul>
  );
}

Optionally pass a custom base URL:

const participants = useParticipants('http://localhost:3000');

useParticipantsState Hook

For full control with loading states, errors, and CRUD operations:

import { useParticipantsState } from 'vpss';

function ParticipantManager() {
  const {
    participants,
    loading,
    error,
    createParticipant,
    updateParticipant,
    deleteParticipant,
  } = useParticipantsState();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {participants.map(p => (
        <li key={p.id}>
          {p.name} ({p.role})
          <button onClick={() => updateParticipant(p.id, { isVideoOn: !p.isVideoOn })}>
            Toggle Video
          </button>
          <button onClick={() => deleteParticipant(p.id)}>Remove</button>
        </li>
      ))}
      <button onClick={() => createParticipant({ name: 'New User', role: 'participant' })}>
        Add Participant
      </button>
    </ul>
  );
}

Options:

useParticipantsState({
  baseUrl: 'http://localhost:4747',  // VPSS server URL (optional)
})

useParticipant Hook

For managing a single participant:

import { useParticipant } from 'vpss';

function ParticipantCard({ id }: { id: string }) {
  const { participant, loading, update, remove } = useParticipant(id);

  if (loading) return <div>Loading...</div>;
  if (!participant) return <div>Not found</div>;

  return (
    <div>
      <h2>{participant.name}</h2>
      <button onClick={() => update({ isVideoOn: !participant.isVideoOn })}>
        Toggle Video
      </button>
      <button onClick={remove}>Remove</button>
    </div>
  );
}

VPSSProvider

Share participant state across components:

import { VPSSProvider, useVPSS } from 'vpss';

function App() {
  return (
    <VPSSProvider baseUrl="http://localhost:4747" realtime>
      <ParticipantCount />
      <ParticipantList />
    </VPSSProvider>
  );
}

function ParticipantCount() {
  const { participants } = useVPSS();
  return <div>Total: {participants.length}</div>;
}

withParticipants HOC

Class component support:

import { withParticipants, WithParticipantsProps } from 'vpss';

class ParticipantList extends React.Component<WithParticipantsProps> {
  render() {
    const { participants, participantsLoading } = this.props;
    if (participantsLoading) return <div>Loading...</div>;
    return <ul>{participants.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
  }
}

export default withParticipants(ParticipantList);

TypeScript Types

import type {
  Participant,
  ParticipantUpdate,
  CreateParticipantInput,
  UseParticipantsOptions,
} from 'vpss';

Development

# Clone and install
git clone https://github.com/ooosome/vpss.git
cd vpss
pnpm install

# Development server
pnpm dev

# Build
pnpm build

# Run tests
pnpm test

License

MIT