npm package: @soulcypher/twin-sdk
Description: Official SDK for SoulCypher Twin OS
Author: SoulCypher
Latest version: 0.5.0

# SoulCypher Twin SDK

JavaScript/TypeScript SDK for integrating streaming AI avatars into your applications. Create and interact with digital twins powered by SoulCypher Platform.

## Installation

```bash
npm install @soulcypher/twin-sdk
```

## Quick Start

```typescript

import { SoulCypherSDK, AvatarSessionManager, AVATAR_PROVIDERS } from '@soulcypher/twin-sdk';

const sdk = new SoulCypherSDK({
  apiKey: "your-api-key",
});

// Get avatars
const avatars = await sdk.getAvatars();

// Create session
const sessionManager = await sdk.createSession({
  avatarId: avatars[0].id,
  userId: "user-123",
});

// Connect (video for Hedra, audio-only for RPM)
const videoEl = document.getElementById("video");
const audioEl = document.getElementById("audio");

if (avatars[0].provider === AVATAR_PROVIDERS.HEDRA) {
  await sessionManager.connect(videoEl, audioEl);
} else {
  await sessionManager.connect(undefined, audioEl);
}

// Listen for responses
sessionManager.on("avatar.response", (event) => {
  console.log("Avatar said:", event.data.text);
});

// Send message
await sessionManager.sendMessage("Hello!");
```

## Provider Types

- **Hedra**: Video + audio avatars
- **RPM**: Audio-only avatars

## Creating Avatars

You can create custom avatars with voice and image files:

```typescript
// For Hedra avatars (requires image + audio)
const imageFile = document.getElementById("imageInput").files[0];
const audioFiles = Array.from(document.getElementById("audioInput").files);

const hedraAvatar = await sdk.createAvatar({
  name: "My Hedra Avatar",
  description: "Custom avatar with video",
  provider: "hedra",
  image: imageFile, // Required for Hedra
  audioFiles: audioFiles, // Required for voice creation
  systemPrompt: "You are a helpful assistant.",
});

// For RPM avatars (audio files only)
const rpmAvatar = await sdk.createAvatar({
  name: "My RPM Avatar",
  description: "Custom voice-only avatar",
  provider: "rpm",
  audioFiles: audioFiles, // Required for voice creation
  systemPrompt: "You are a knowledgeable expert.",
});

console.log("Avatar created with voice ID:", avatar.voiceId);
```

### File Requirements

- **Audio files**: Required for ALL avatars (voice creation via ElevenLabs)
  - Supported formats: MP3, WAV, M4A, AAC, OGG, FLAC
  - Up to 5 files, 25MB total limit
- **Image file**: Required only for Hedra avatars
  - Supported formats: JPEG, PNG, GIF, WebP
  - Used for avatar appearance

## Events

- `session.started` - Session connected
- `session.ended` - Session disconnected
- `avatar.response` - Text response from avatar
- `avatar.video` - Video track available (Hedra only)
- `avatar.audio` - Audio track available

## Manual Session Creation

If using your own API routes:

```typescript
// Create via your API
const sessionData = await fetch("/api/sessions", {
  method: "POST",
  body: JSON.stringify({ avatarId, userId }),
}).then((r) => r.json());

// Use session data directly
const sessionManager = new AvatarSessionManager(sessionData);
```

## API Reference

### SDK Methods

- `getAvatars()` → `Avatar[]`
- `getAvatar(id)` → `Avatar`
- `createSession(request)` → `AvatarSessionManager`
- `endSession(sessionId)` → `void`

### Session Manager

- `connect(videoEl?, audioEl?)` → Connect to LiveKit
- `sendMessage(text)` → Send message to avatar
- `disconnect()` → End session
- `on(event, handler)` → Listen for events

### Types

```typescript
interface Avatar {
  id: string;
  slug: string;
  name: string;
  provider: "rpm" | "hedra";
  // ... other fields
}
```

## License

MIT License

## Support

- [Website](https://soulcypher.ai)
- [Documentation](https://docs.soulcypher.ai)