AI Twin Player Integration

npm install @streamoji/aitwin

function TwinDemo() {
  const twinRef = useRef<AiTwinHandle>(null);

  return (
    <AiTwin
      ref={twinRef}
      id="olivia"
      onReady={() => console.log("face ready")}
      onStatusChange={(status) => console.log("status", status)}
      onError={(message) => console.error(message)}
    />
  );
}

<AiTwin
  faceId="64-char-hex-face-id"
  voiceId="eve"
  ttsEngineId="visemetts"
  language="es-MX"
  authToken={authToken}
/>

{/* Premium Cartesia / custom clone */}
<AiTwin
  faceId="64-char-hex-face-id"
  voiceId="2f251ac3-89a9-4a77-a452-704b474ccd01"
  ttsEngineId="eng_c9b1e6d4"
  language="fr"
  authToken={authToken}
/>

<button
  type="button"
  onClick={() => void twinRef.current?.speakText("Hi, how are you?")}
>
  Speak
</button>

<button
  type="button"
  onClick={() =>
    void twinRef.current?.speakText("Bonjour", {
      voiceId: "eve",
      ttsEngineId: "visemetts",
      language: "fr",
      speakingRate: 0.85,
    })
  }
>
  Speak (voice override)
</button>

<button
  type="button"
  onClick={() => twinRef.current?.stop()}
>
  Stop
</button>

import { useEffect, useRef, useState } from "react";
import {
  AiTwin,
  fetchAiTwin,
  type AiTwinHandle,
} from "@streamoji/aitwin";

async function startTwinLead(apiBase: string, seedToken: string, twinSlug: string) {
  const key = `aitwin:lead:${twinSlug}`;
  const existing = sessionStorage.getItem(key);
  const response = await fetch(`${apiBase}/twin-lead/start`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${seedToken}`,
    },
    body: JSON.stringify({
      twin_slug: twinSlug,
      ...(existing ? { lead_id: existing } : {}),
    }),
  });
  const data = await response.json();
  sessionStorage.setItem(key, data.lead_id);
  return data.authToken as string;
}

function VoiceTwin() {
  const twinRef = useRef<AiTwinHandle>(null);
  const [sessionToken, setSessionToken] = useState<string>();

  useEffect(() => {
    const seedToken = "client_…"; // from getAiTwinAuthToken / getAiTwin
    void startTwinLead("https://ai.aitwin.me", seedToken, "modi").then(setSessionToken);
  }, []);

  const handleConnect = async () => {
    if (!sessionToken) return;
    const twin = await fetchAiTwin("modi");
    await twinRef.current?.connect({
      authToken: sessionToken,            // JWT already contains lead_id
      voiceId: twin.voiceId,              // optional
      ttsEngineId: twin.ttsEngineId,      // optional: visemetts or eng_c9b1e6d4
      brainId: twin.brainId ?? twin.knowledgeContextId, // optional hosted brain
      brainUrl: twin.brainUrl, // optional client SSE brain; skips hosted LLM
      speakingRate: 0.85,                 // optional, default 0.85
    });
  };

  const handleDisconnect = async () => {
    await twinRef.current?.disconnect();
  };

  return (
    <>
      <AiTwin
        ref={twinRef}
        id="modi"
        authToken={sessionToken}
        onUserTranscript={(text, final) => {
          if (final) console.log("user:", text);
        }}
        onBotOutput={(text) => console.log("bot:", text)}
        onStatusChange={(status) => console.log("status:", status)}
        onError={(msg) => console.error(msg)}
      />
      <button type="button" onClick={() => void handleConnect()}>
        Connect mic
      </button>
      <button type="button" onClick={() => void handleDisconnect()}>
        Disconnect
      </button>
    </>
  );
}

curl -X POST "https://us-central1-streamoji-265f4.cloudfunctions.net/getAiTwinAuthToken" \
  -H "Content-Type: application/json" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_64_CHAR_API_KEY" \
  -d '{
    "userId": "end-user-123",
    "userName": "Jane Doe"
  }'

// Backend only, never run this in the browser
const CLIENT_ID = process.env.AITWIN_CLIENT_ID;
const CLIENT_SECRET = process.env.AITWIN_CLIENT_SECRET;

async function getAiTwinAuthToken({
  userId,
  userName,
  maxAvatarCreations,
  maxCreditsUtilization,
  expiresIn,
}) {
  const body = { userId, userName };
  if (typeof maxAvatarCreations === "number") {
    body.maxAvatarCreations = maxAvatarCreations;
  }
  if (typeof maxCreditsUtilization === "number") {
    body.maxCreditsUtilization = maxCreditsUtilization;
  }
  if (typeof expiresIn === "number") {
    body.expiresIn = expiresIn; // seconds; -1 = no expiry; omit = 30 min default
  }

  const response = await fetch(
    "https://us-central1-streamoji-265f4.cloudfunctions.net/getAiTwinAuthToken",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Client-Id": CLIENT_ID,
        "Client-Secret": CLIENT_SECRET,
      },
      body: JSON.stringify(body),
    },
  );

  const data = await response.json();
  if (!response.ok || !data.success) {
    throw new Error(data.error ?? "Auth token generation failed");
  }

  return data.authToken; // e.g. "client_eyJ..."
}

// Frontend, pass the token from your backend API
<AiTwin
  ref={twinRef}
  id="olivia"
  authToken={authToken}
/>

<AiTwin
  id="olivia"
  ttsEngineId="visemetts"
  language="es-MX"
/>

<button
  type="button"
  onClick={() =>
    void twinRef.current?.speakText("Bonjour", { language: "fr" })
  }
>
  Speak French
</button>

AiTwinWidget.init("#aitwin", {
  id: "olivia",
  language: "es-MX",
});

twin.speakText("Bonjour", { language: "fr" });

<AiTwin
  id="olivia"
  idleHandoffHoldMs={3000}
/>