odyssey-spatial-comms/README.md

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

# Odyssey Spatial Communications SDK

Modern spatial audio SDK with Dolby/Voxeet compatibility layer.

## Installation

```bash
npm install odyssey-spatial-comms
```

## Usage

### Native SpatialComms API (Recommended)

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

### Dolby/Voxeet Compatibility (Drop-in Replacement)

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

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

### Authentication

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

### Configuration

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

### Session Management

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

### Conference Management

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

### Audio Controls

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

### Video Controls

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

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

### Spatial Audio

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

### Events

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

### 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**:
   ```typescript
   VoxeetSDK.configure({ 
     serviceUrl: 'https://your-service.com',
     logLevel: 'debug' 
   });
   ```

### Audio Issues

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

### Browser Compatibility

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