odyssey-spatial-comms/examples/migration-guide.md

Drop-in replacement for Dolby/Voxeet SDK using Odyssey Spatial Audio Service

# Migration from Dolby/Voxeet SDK

This guide shows how to migrate from the original Dolby/Voxeet SDK to the Odyssey Spatial Audio SDK.

## Before (Original Dolby/Voxeet)

```typescript
import VoxeetSDK from '@voxeet/voxeet-web-sdk';

// Initialize with consumer key/secret
VoxeetSDK.initialize('consumer-key', 'consumer-secret');

// Or with token
VoxeetSDK.initializeToken('access-token', refreshCallback);

// Create and join conference
const conference = await VoxeetSDK.createConference('my-conference');
await VoxeetSDK.joinConference(conference.conferenceId);

// Audio controls
await VoxeetSDK.startAudio();
await VoxeetSDK.stopAudio();

// Video controls
await VoxeetSDK.startVideo();
await VoxeetSDK.stopVideo();

// Spatial positioning (2D)
VoxeetSDK.setUserPosition('user-id', 100, 200);

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

## After (Odyssey Spatial Audio SDK)

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

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

// Initialize with token (same API)
VoxeetSDK.initializeToken('access-token', refreshCallback);

// Create and join conference (enhanced API)
const conference = await VoxeetSDK.conference.create({
  alias: 'my-conference',
  params: { spatialAudioStyle: 'individual' }
});
await VoxeetSDK.conference.join(conference);

// Audio controls (same API)
await VoxeetSDK.audio.local.start();
await VoxeetSDK.audio.local.stop();

// Video controls (same API)
await VoxeetSDK.video.local.start();
await VoxeetSDK.video.local.stop();

// Enhanced 3D spatial positioning
VoxeetSDK.conference.setSpatialPosition(participant, { x: 0, y: 0, z: 0 });
VoxeetSDK.conference.setSpatialDirection(participant, { x: 1, y: 0, z: 0 });

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

## Key Differences

### 1. Configuration Required
Add a configuration step to specify your service endpoint:
```typescript
VoxeetSDK.configure({
  serviceUrl: 'https://your-spatial-audio-service.com'
});
```

### 2. Enhanced Conference API
- `VoxeetSDK.createConference()` → `VoxeetSDK.conference.create()`
- `VoxeetSDK.joinConference()` → `VoxeetSDK.conference.join()`

### 3. Structured Media Controls
- `VoxeetSDK.startAudio()` → `VoxeetSDK.audio.local.start()`
- `VoxeetSDK.startVideo()` → `VoxeetSDK.video.local.start()`

### 4. Advanced Spatial Audio
- 2D positioning → Full 3D positioning with direction
- Enhanced spatial audio styles: individual, shared, disabled
- HRTF processing and distance attenuation

### 5. Session Management
Explicit session management:
```typescript
await VoxeetSDK.session.open({
  name: 'User Name',
  externalId: 'user-123'
});
```

## Migration Steps

1. **Install the new SDK**:
   ```bash
   npm uninstall @voxeet/voxeet-web-sdk
   npm install odyssey-spatial-comms
   ```

2. **Update imports**:
   ```typescript
   // Before
   import VoxeetSDK from '@voxeet/voxeet-web-sdk';
   
   // After
   import { VoxeetSDK } from 'odyssey-spatial-comms';
   ```

3. **Add configuration**:
   ```typescript
   VoxeetSDK.configure({
     serviceUrl: 'https://your-service.com'
   });
   ```

4. **Update API calls** (see examples above)

5. **Test thoroughly** - All existing functionality should work with enhanced features

## Backward Compatibility

The Odyssey SDK maintains backward compatibility for:
- Event names and structures
- Core API methods
- Authentication patterns
- Media control flows

Your existing application logic should work with minimal changes.