@knock-knock/server

v0.0.1

Published

6 months ago

Serverside library for knock-knock

0High
0Medium
0Low

anuragrao04

users viscinity close proximity

@knock-knock/server

Ultrasonic proximity detection library for real-time clustering of nearby users.

What it does

This server-side library detects which users are physically close to each other using ultrasonic frequencies (17-20 kHz). It manages WebSocket connections, assigns unique frequencies to users, processes proximity data, and clusters users based on mutual frequency detection.

Key features:

Assigns unique ultrasonic frequencies to users within sessions
Processes frequency detection data from clients
Clusters users based on mutual proximity detection
Real-time WebSocket communication and updates
Session isolation (different sessions can reuse frequencies)

Use Cases

Meeting & Collaboration

Automatically group meeting participants by location
Create breakout rooms based on physical proximity
Detect when remote participants are actually in the same room

Events & Networking

Connect nearby attendees at conferences or events
Facilitate spontaneous networking opportunities
Group people for activities or discussions

Gaming & Social

Proximity-based multiplayer games
Social apps that connect people in the same space
Location-aware features without GPS

Workplace & Education

Team formation based on physical proximity
Classroom interaction and group activities
Office space utilization and collaboration tracking

How it works

Session Creation: Users join sessions via WebSocket connections
Frequency Assignment: Each user receives a unique ultrasonic frequency (17-20 kHz)
Audio Processing: Client devices emit assigned frequencies and listen for others
Detection Reporting: Clients send frequency detection data to the server
Mutual Verification: Server verifies bidirectional detection between users
Clustering: Graph-based algorithm groups users who mutually detect each other
Real-time Updates: Proximity changes are broadcast to all session participants

Installation

npm install @knock-knock/server

Basic Usage

import { KnockKnockServer } from '@knock-knock/server';

// Initialize server with frequency range (Hz) and spacing
const server = new KnockKnockServer(17800, 19200, 100); // 15 users max

// Handle WebSocket connections
server.handleConnection(websocket, 'user123', 'session-abc');

// Get proximity clusters
const allUsers = server.getUsers('session-abc');          // [['user1'], ['user2', 'user3']]
const nearby = server.getUsersTogetherOnly('session-abc'); // [['user2', 'user3']]

Frontend Integration

Note: A companion frontend library @knock-knock/browser is in development to handle audio processing, microphone/speaker operations, and WebSocket communication. This server library is designed to work with that client library.

Your client needs to:

// Send frequency detections to server
websocket.send(JSON.stringify({
  type: 'frequency_heard',
  data: {
    frequency: 17900,
    amplitude: 0.8,
    confidence: 0.95
  }
}));

// Receive proximity updates
websocket.on('message', (data) => {
  const message = JSON.parse(data);
  if (message.type === 'proximity_update') {
    console.log('Nearby users:', message.data.nearbyUsers);
  }
});

API Reference