Odyssey Spatial Communications SDK

Modern spatial audio SDK with Dolby/Voxeet compatibility layer.

Installation

npm install odyssey-spatial-comms

Usage

Native SpatialComms API (Recommended)

import SpatialCommsSDK from 'odyssey-spatial-comms';

// Configure the SDK
SpatialCommsSDK.configure({
  serviceUrl: 'https://your-spatial-audio-service.com'
});

// Initialize with access token
await SpatialCommsSDK.initialize(token, refreshCallback);
const conference = await SpatialCommsSDK.conference.create({ alias: 'my-conference' });
await SpatialCommsSDK.conference.join(conference);

Dolby/Voxeet Compatibility (Drop-in Replacement)

import { VoxeetSDK } from 'odyssey-spatial-comms';

// Only new requirement: configure your service endpoint
VoxeetSDK.configure({
  serviceUrl: 'https://your-spatial-audio-service.com'
});

// All existing Dolby/Voxeet code works unchanged
await VoxeetSDK.initializeToken(token, refreshCallback);
const conference = await VoxeetSDK.conference.create({ alias: 'my-conference' });
await VoxeetSDK.conference.join(conference);

API Comparison

Native SpatialComms API vs Dolby/Voxeet Compatibility

| Feature | SpatialComms Native | Dolby/Voxeet Compat | |---------|-------------------|---------------------| | Initialization | SpatialCommsSDK.initialize() | VoxeetSDK.initializeToken() | | Conference | SpatialCommsSDK.conference | VoxeetSDK.conference | | Session | SpatialCommsSDK.session | VoxeetSDK.session | | Audio | SpatialCommsSDK.audio | VoxeetSDK.audio | | Video | SpatialCommsSDK.video | VoxeetSDK.video | | Notifications | SpatialCommsSDK.notifications | VoxeetSDK.notification | | Media Devices | SpatialCommsSDK.mediaDevice | VoxeetSDK.mediaDevice |

Migration from Dolby/Voxeet

Option 1: Drop-in Replacement (Recommended)

1. Replace the package: npm uninstall @voxeet/voxeet-web-sdk && npm install odyssey-spatial-comms
2. Update import: Change import VoxeetSDK from '@voxeet/voxeet-web-sdk' to import { VoxeetSDK } from 'odyssey-spatial-comms'
3. Add configuration: Point to your spatial audio service endpoint:

   VoxeetSDK.configure({ serviceUrl: 'https://your-spatial-audio-service.com' });

Option 2: Modern API Migration

1. Install package: npm install odyssey-spatial-comms
2. Use modern API: import SpatialCommsSDK from 'odyssey-spatial-comms'
3. Update initialization: VoxeetSDK.initializeToken() → SpatialCommsSDK.initialize()
4. Update notifications: VoxeetSDK.notification → SpatialCommsSDK.notifications

Both approaches provide identical functionality with enhanced spatial audio capabilities.

Service Setup

Getting Your Service URL

1. Deploy Odyssey Spatial Audio Service to your infrastructure
2. Configure your service endpoint in the SDK:

   VoxeetSDK.configure({
     serviceUrl: 'https://your-spatial-audio-service.com'
   });

3. Obtain JWT tokens from your authentication system
4. Initialize the SDK with your access token

Authentication

The SDK requires JWT tokens for authentication:

// Token should include user information and permissions
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

// Initialize with token and refresh callback
VoxeetSDK.initializeToken(token, async () => {
  // Return new token when current expires
  return await fetchNewToken();
});

API Reference

Configuration

interface SDKConfig {
  serviceUrl: string;          // Your spatial audio service endpoint
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
  reconnectAttempts?: number;  // Default: 5
  reconnectDelay?: number;     // Default: 1000ms
}

VoxeetSDK.configure(config);

Session Management

// Open session
await VoxeetSDK.session.open({
  name: 'User Name',
  externalId: 'unique-user-id',
  avatarUrl?: 'https://example.com/avatar.jpg'
});

// Close session
await VoxeetSDK.session.close();

// Get current participant
const participant = VoxeetSDK.session.participant;

Conference Management

// Create conference
const conference = await VoxeetSDK.conference.create({
  alias: 'conference-name',
  params: {
    spatialAudioStyle: 'individual' | 'shared' | 'disabled'
  }
});

// Join conference
await VoxeetSDK.conference.join(conference, {
  participantInfo: { name: 'User', externalId: 'id' },
  constraints: { audio: true, video: false },
  spatialAudio: true
});

// Leave conference
await VoxeetSDK.conference.leave();

// Get current conference
const current = VoxeetSDK.conference.current;

Audio Controls

// Local audio
await VoxeetSDK.audio.local.start();
await VoxeetSDK.audio.local.stop();
VoxeetSDK.audio.local.mute(true);

// Remote audio
VoxeetSDK.audio.remote.setVolume(participant, 0.8);
VoxeetSDK.audio.remote.mute(participant, true);

Video Controls

// Local video
await VoxeetSDK.video.local.start();
await VoxeetSDK.video.local.stop();

// Screen sharing
await VoxeetSDK.conference.startScreenShare();
await VoxeetSDK.conference.stopScreenShare();

Spatial Audio

// Set 3D position
VoxeetSDK.conference.setSpatialPosition(participant, {
  x: 0,   // Left/Right (-1 to 1)
  y: 0,   // Up/Down (-1 to 1) 
  z: 0    // Forward/Back (-1 to 1)
});

// Set spatial direction (where participant is looking)
VoxeetSDK.conference.setSpatialDirection(participant, {
  x: 1, y: 0, z: 0  // Looking forward
});

Events

// Conference events
VoxeetSDK.conference.on('participantJoined', (participant) => {});
VoxeetSDK.conference.on('participantLeft', (participant) => {});
VoxeetSDK.conference.on('streamAdded', (stream) => {});
VoxeetSDK.conference.on('streamRemoved', (stream) => {});

// Audio events
VoxeetSDK.audio.on('deviceChanged', (device) => {});
VoxeetSDK.audio.on('levelChanged', (level) => {});

Error Handling

try {
  await VoxeetSDK.conference.join(conference);
} catch (error) {
  if (error.code === 'CONFERENCE_NOT_FOUND') {
    console.error('Conference does not exist');
  } else if (error.code === 'AUTHENTICATION_FAILED') {
    console.error('Invalid or expired token');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Common Error Codes

• AUTHENTICATION_FAILED: Invalid or expired JWT token
• CONFERENCE_NOT_FOUND: Conference ID/alias not found
• PERMISSION_DENIED: Insufficient permissions
• NETWORK_ERROR: Connection issues
• MEDIA_ERROR: Audio/video device issues

Troubleshooting

Connection Issues

1. Verify service URL is correct and accessible
2. Check JWT token is valid and not expired
3. Enable debug logging:

   VoxeetSDK.configure({ 
     serviceUrl: 'https://your-service.com',
     logLevel: 'debug' 
   });

Audio Issues

1. Check microphone permissions in browser
2. Verify audio device is available:

   const devices = await VoxeetSDK.mediaDevice.enumerateAudioDevices();

3. Test audio levels:

   VoxeetSDK.audio.on('levelChanged', (level) => {
     console.log('Audio level:', level);
   });

Browser Compatibility

• Chrome: 80+
• Firefox: 75+
• Safari: 14+
• Edge: 80+

Note: HTTPS required for microphone/camera access.

Performance Optimization

// Limit video forwarding for better performance
await VoxeetSDK.conference.join(conference, {
  maxVideoForwarding: 4,
  preferRecvMono: true  // Use mono audio for bandwidth savings
});

// Adjust spatial audio quality
VoxeetSDK.configure({
  serviceUrl: 'https://your-service.com',
  spatialQuality: 'medium'  // 'low' | 'medium' | 'high'
});