Thanks to visit codestin.com
Credit goes to github.com

Skip to content

soulcypherai/sdk

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

29 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

SoulCypher Avatar SDK

JavaScript/TypeScript SDK for integrating streaming AI avatars into your applications.

Installation

npm install @soulcypher/twin-sdk

Quick Start

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:

// 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:

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

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

License

MIT License

Support

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 3

  •  
  •  
  •