Boop-Share

Boop-Share

A JavaScript library for sending and receiving data using high-frequency audio tones, similar to dial-up modems. It supports redundancy for reliable transmission, real-time communication, and automatic exclusion of own transmitted data for multi-device scenarios.

Features

• High-Frequency Audio Transmission: Uses FSK (Frequency Shift Keying) with configurable frequencies for older and newer devices
• Redundant Transmission: Sends data multiple times for improved reliability
• Real-Time Communication: Continuous sending and receiving with automatic filtering
• Multi-Device Support: Unique device IDs prevent echo and enable group communication
• Error Detection: Parity checksum for basic error validation
• Browser-Compatible: Uses Web Audio API and getUserMedia
• Simple API: Easy-to-use methods for various communication patterns

Installation

npm install boop-share

Or include directly in HTML:

<script src="https://unpkg.com/boop-share@latest/dist/boop-share.js"></script>

Quick Start

import BoopShare from 'boop-share';

// Create instance with unique ID
const boopShare = new BoopShare({ deviceId: 1 });

// Send a message
await boopShare.send('Hello, World!');

// Receive messages
boopShare.startReceiving((data, senderId) => {
  console.log(`Received from device ${senderId}:`, new TextDecoder().decode(data));
});

Technical Overview

How It Works

Boop-Share uses Frequency Shift Keying (FSK) to encode binary data into audio tones:

• Bit 0: Represented by one frequency (e.g., 18kHz)
• Bit 1: Represented by another frequency (e.g., 19kHz)

Data transmission includes:

1. Preamble: Sync sequence for receiver alignment
2. Device ID: 1-byte sender identifier
3. Payload: The actual data
4. Checksum: Parity bit for error detection

Frequency Ranges

• Older Devices: 18-19kHz (audible high-frequency)
• Newer Devices: 20-21kHz (ultrasonic)

Transmission Protocol

[Preamble] [DeviceID] [Data] [Checksum]
   6 bits    8 bits   Variable   1 bit

API Reference

Constructor

const boopShare = new BoopShare(options);

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | freq0 | number | 18000 | Frequency for bit 0 (Hz) | | freq1 | number | 19000 | Frequency for bit 1 (Hz) | | highFreq0 | number | 20000 | High frequency for bit 0 (Hz) | | highFreq1 | number | 21000 | High frequency for bit 1 (Hz) | | useHighFreq | boolean | false | Use ultrasonic frequencies | | redundancy | number | 3 | Number of transmission repetitions | | bitDuration | number | 0.1 | Duration per bit (seconds) | | preamble | array | [1,0,1,0,1,0] | Sync sequence | | deviceId | number | 0 | Unique device identifier (0-255) |

Methods

send(data)

Sends data asynchronously.

await boopShare.send('Hello'); // String
await boopShare.send(new Uint8Array([72, 101, 108, 108, 111])); // Binary

startReceiving(callback)

Starts continuous reception mode.

boopShare.startReceiving((data, senderId) => {
  // data: Uint8Array
  // senderId: number (0-255)
  console.log(`From device ${senderId}:`, data);
});

stopReceiving()

Stops continuous reception.

boopShare.stopReceiving();

receive(callback) (Legacy)

Single-message reception (for backward compatibility).

await boopShare.receive((data) => {
  console.log('Received:', data);
});

Usage Examples

Basic Communication

const device1 = new BoopShare({ deviceId: 1 });
const device2 = new BoopShare({ deviceId: 2 });

// Device 1 sends
await device1.send('Ping');

// Device 2 receives
device2.startReceiving((data, senderId) => {
  console.log(`Device ${senderId} says:`, new TextDecoder().decode(data));
  // Output: "Device 1 says: Ping"
});

Real-Time Chat

const chat = new BoopShare({ deviceId: 1 });

// Start listening
chat.startReceiving((data, senderId) => {
  const message = new TextDecoder().decode(data);
  console.log(`[${senderId}] ${message}`);
});

// Send messages
setInterval(() => {
  chat.send(`Hello from device 1 at ${Date.now()}`);
}, 2000);

High-Frequency Mode

const ultrasonic = new BoopShare({
  useHighFreq: true,    // Use 20-21kHz
  bitDuration: 0.05,    // Faster transmission
  redundancy: 5         // More reliable
});

Limitations

• Range: Limited to audio proximity (speaker to microphone)
• Speed: ~80-200 bits/second depending on configuration
• Reliability: Audio quality affects transmission success
• Browser Support: Requires Web Audio API and microphone permissions
• Echo Cancellation: May need physical separation or headphones
• Data Size: No hard limit, but larger data increases error probability

Browser Support

| Browser | Version | Notes | |---------|---------|-------| | Chrome | 14+ | Full support | | Firefox | 25+ | Full support | | Safari | 6+ | Full support | | Edge | 12+ | Full support |

Requires:

• AudioContext or webkitAudioContext
• getUserMedia or webkitGetUserMedia

Troubleshooting

No Audio Output

• Check speaker volume
• Ensure microphone permissions granted
• Try different frequency settings

Reception Issues

• Reduce background noise
• Increase bitDuration for slower, more reliable transmission
• Use headphones to prevent echo
• Check device frequency capabilities

Permission Errors

// Handle microphone permission
try {
  await boopShare.startReceiving(callback);
} catch (err) {
  console.error('Microphone access denied:', err);
}

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Development with watch
npm run dev

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

Apache License 2.0 - see LICENSE file for details.

Changelog

v1.0.0

• Initial release
• Basic send/receive functionality
• Real-time communication support
• Multi-device capabilities
• Configurable frequencies and redundancy

Features

• High-frequency audio data transmission (ultrasonic for newer devices, high audible for older)
• Redundant transmission to improve reliability
• Real-time continuous sending and receiving
• Automatic exclusion of own transmitted data
• Multi-device communication support
• Simple API for sending and receiving data
• Browser-compatible using Web Audio API
• Configurable frequencies and parameters

Installation

npm install boop-share

Usage

Basic Example

import BoopShare from 'boop-share';

// Create instance
const boopShare = new BoopShare();

// Send data
await boopShare.send('Hello, World!');

// Receive data
boopShare.receive((data) => {
  console.log('Received:', new TextDecoder().decode(data));
});

Advanced Configuration

const boopShare = new BoopShare({
  useHighFreq: true, // Use ultrasonic frequencies for newer devices
  redundancy: 5,     // Send data 5 times for better reliability
  bitDuration: 0.05, // Faster transmission (50ms per bit)
  deviceId: 1        // Unique ID for this device
});

// Send data
await boopShare.send(new Uint8Array([72, 101, 108, 108, 111])); // "Hello"

Real-Time Communication

const boopShare = new BoopShare({ deviceId: 1 });

// Start continuous receiving
boopShare.startReceiving((data, senderId) => {
  console.log(`Received from device ${senderId}:`, new TextDecoder().decode(data));
});

// Send messages in real-time
setInterval(() => {
  boopShare.send('Ping from device 1');
}, 2000);

// Stop when done
// boopShare.stopReceiving();

API

Constructor Options

• freq0: Frequency for bit 0 (default: 18000 Hz)
• freq1: Frequency for bit 1 (default: 19000 Hz)
• highFreq0: High frequency for bit 0 (default: 20000 Hz)
• highFreq1: High frequency for bit 1 (default: 21000 Hz)
• useHighFreq: Use high frequencies if true (default: false)
• redundancy: Number of times to send data (default: 3)
• bitDuration: Duration per bit in seconds (default: 0.1)
• preamble: Sync sequence array (default: [1,0,1,0,1,0])
• deviceId: Unique device identifier (0-255, default: 0)

Methods

• send(data): Send string or Uint8Array data
• startReceiving(callback(data, deviceId)): Start continuous receiving, callback receives data and sender deviceId
• stopReceiving(): Stop continuous receiving
• receive(callback): Legacy method for single message reception (backward compatibility)

How It Works

Boop-Share uses Frequency Shift Keying (FSK) to encode binary data into audio tones. Each bit is represented by a different frequency, and data is transmitted with a preamble for synchronization. Redundancy is achieved by sending the data multiple times, allowing the receiver to use error correction.

For older devices, it uses frequencies around 18-19kHz. For newer devices with better audio hardware, it can use ultrasonic frequencies above 20kHz.

Browser Support

Requires Web Audio API and getUserMedia for microphone access. Works in modern browsers that support these APIs.

License

MIT