Odyssey Spatial Communications SDK

Modern spatial audio SDK with Dolby/Voxeet compatibility layer.

Installation

``bash
npm install odyssey-spatial-comms
`

Usage

$3

`typescript
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);
`

$3

`typescript
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

$3

| 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

$3


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:
`typescript
VoxeetSDK.configure({ serviceUrl: 'https://your-spatial-audio-service.com' });
`

$3

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

$3

1. Deploy Odyssey Spatial Audio Service to your infrastructure
2. Configure your service endpoint in the SDK:
`typescript
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

$3

The SDK requires JWT tokens for authentication:

`typescript
// 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

$3

`typescript
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);
`

$3

`typescript
// 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;
`

$3

`typescript
// 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;
`

$3

`typescript
// 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);
`

$3

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

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

$3

`typescript
// 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
});
`

$3

`typescript
// 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

`typescript
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);
}
}
`

$3

- 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

$3

1. Verify service URL is correct and accessible
2. Check JWT token is valid and not expired
3. Enable debug logging:
`typescript
VoxeetSDK.configure({
serviceUrl: 'https://your-service.com',
logLevel: 'debug'
});
`

$3

1. Check microphone permissions in browser
2. Verify audio device is available:
`typescript
const devices = await VoxeetSDK.mediaDevice.enumerateAudioDevices();
`
3. Test audio levels:
`typescript
VoxeetSDK.audio.on('levelChanged', (level) => {
console.log('Audio level:', level);
});
`

$3

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

Note: HTTPS required for microphone/camera access.

Performance Optimization

`typescript
// 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'
});
``