Napster Companion API SDK

Real-time conversational video AI for web applications. Embed AI companions that users can talk to face-to-face via WebRTC. Attaches to any DOM element, handles video streaming and avatar rendering, connects to Azure OpenAI for conversation.

Supported Environments:

• Modern browsers (Chrome, Firefox, Safari, Edge)
• React 16.x through 19.x
• Vue 2.x and 3.x
• Angular 12+
• Vanilla JavaScript (no build tools required)

Key Capabilities:

• WebRTC Video Streaming: Real-time video with AI avatars
• Framework Agnostic: React, Vue, Angular, or vanilla JS
• Zero External Dependencies: Drop in a script tag and go
• TypeScript Support: Fully typed APIs
• Tree-Shakeable: Import only what you need
• Production Ready: Minified builds with type definitions

1. Quick Start

Get up and running in minutes. Follow these four steps to integrate the SDK into your project.

1.1 Choose Your Setup

Pick the integration method that matches your project:

| Build Type | Best For | Import Path | Dependencies | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -------------------- | | ESM | ✅ Recommended for most projects✅ You use a bundler (Vite, Webpack, Rollup, etc.)✅ You want optimal bundle size (dependencies not bundled)✅ You're using TypeScript or modern JavaScript | @touchcastllc/napster-companion-api | Redux Toolkit (peer) | | Standalone | ✅ You want a <script> tag (no bundler, no external dependencies)✅ You want zero external dependencies✅ You don't want to manage dependencies separately✅ You're okay with a slightly larger file (all dependencies included) | lib/index.standalone.js | All bundled |

1.2 Installation & Setup

1.2.1 For ESM Build Type (Recommended)

Step 1: Install the SDK

Install the package:

npm install @touchcastllc/napster-companion-api
# or
yarn add @touchcastllc/napster-companion-api

Install peer dependencies:

npm install @reduxjs/toolkit

Step 2: Import the SDK

import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";

Also, import CSS Stylesheet (required):

The SDK comes with a complete stylesheet for all components. Import it in your application:

ESM/TypeScript:

import "@touchcastllc/napster-companion-api/styles";

CommonJS:

require("@touchcastllc/napster-companion-api/styles");

HTML <link> Tag:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css"
/>

CSS @import:

@import url("https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css");

The CSS file (index.css) is minified and contains all styles needed for the avatar widget, controls, tooltips, and more.

1.2.2 For Standalone Build Type

Step 1: Import the SDK

<!-- All dependencies bundled (easier, larger file) -->
<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.js"></script>

1.3 Initialization

1.3.1 For ESM Build Type

Initialize the SDK by calling NapsterCompanionApiSdk.init() with your auth token and configuration options.

See the 1.4 Authentication section for details on generating auth tokens.

Basic Example:

const widget = await NapsterCompanionApiSdk.init("YOUR_AUTH_TOKEN", {
  mountContainer: "#avatar-container",
});

1.3.2 For Standalone Build Type

Initialize the SDK by calling window.napsterCompanionApiSDK.init() with your auth token and configuration options.

See the 1.4 Authentication section for details on generating auth tokens.

Step 1: Add container to your HTML

<div id="sdk-container"></div>

Step 2: Initialize globally

<script>
  window.napsterCompanionApiSDK.init("AUTH_TOKEN", {
    mountContainer: "#sdk-container",
  });
</script>

1.4 Authentication

The SDK requires an auth token to connect to the Napster Companion API.

Important: Do not generate tokens in client-side code — use a backend service to keep your API key secure.

Step 1: Generate Napster Companion API Key

1. Visit the Napster Companion API Keys page
2. Click Generate API key and enter your details
3. Store your API key securely on your backend server

Step 2: Create Connection & Get Token (Backend)

Create a backend API call to the Napster Companion API to generate auth tokens:

Request URL:

POST https://companion-api.napster.com/public/connections

Request Headers:

| Header | Value | | -------------- | ------------------- | | content-type | application/json | | x-api-key | YOUR_API_KEY_HERE |

Request Body:

| Field | Type | Description | | ----------------------------------------------------------- | ------- | ------------------------------------ | | companionId | string | Your Napster Companion ID | | providerConfig.type | string | Provider type (e.g., azureOpenAI) | | providerConfig.voiceId | string | Voice identifier (e.g., alloy) | | providerConfig.settings.instructions | string | Custom instructions for the avatar | | providerConfig.settings.turnDetection.threshold | number | Voice detection threshold | | providerConfig.settings.turnDetection.prefix_padding_ms | number | Padding before speech detection (ms) | | providerConfig.settings.turnDetection.silence_duration_ms | number | Silence duration threshold (ms) | | providerConfig.settings.temperature | number | Response temperature (0-1) | | providerConfig.useGreenVideo | boolean | Enable green screen background | | disableIdleTimeout | boolean | Disable idle timeout |

Example Request:

curl 'https://companion-api.napster.com/public/connections' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  --data-raw '{
    "companionId": "YOUR_COMPANION_ID",
    "providerConfig": {
      "type": "azureOpenAI",
      "voiceId": "alloy",
      "settings": {
        "instructions": "Your custom instructions here...",
        "turnDetection": {
          "threshold": 0,
          "prefix_padding_ms": 0,
          "silence_duration_ms": 0
        },
        "temperature": 0
      },
      "useGreenVideo": true
    },
    "disableIdleTimeout": false
  }'

Step 3: Use Token in Client

Fetch the token from your backend and pass it to the SDK:

// Possible client-side code for token retrieval
async function initializeAvatar() {
  // Fetch token from your backend
  const response = await fetch("/your-backend-endpoint", { method: "POST" });
  const { token } = await response.json();
}

2. Examples

We provide example implementations for popular frameworks and vanilla JavaScript:

2.1 React

import React, { useEffect, useRef, useState } from "react";
import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
import type { NapsterCompanionApiInstance } from "@touchcastllc/napster-companion-api";

export function CompanionWidget() {
  const containerRef = useRef<HTMLDivElement>(null);
  const [instance, setInstance] = useState<NapsterCompanionApiInstance | null>(
    null
  );

  useEffect(() => {
    const initSDK = async () => {
      if (!containerRef.current) return;

      const result = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
        mountContainer: containerRef.current,
        position: "bottom-right",
      });
      setInstance(result);
    };

    initSDK();

    return () => {
      instance?.destroy();
    };
  }, []);

  return <div ref={containerRef} style={{ width: "100%", height: "100%" }} />;
}

2.2 Vue 3

<template>
  <div ref="containerRef"></div>
</template>

<script setup lang="ts">
  import { onMounted, onUnmounted, ref } from "vue";
  import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
  import type { NapsterCompanionApiInstance } from "@touchcastllc/napster-companion-api";

  const containerRef = ref<HTMLElement>();
  let instance: NapsterCompanionApiInstance | null = null;

  onMounted(async () => {
    if (!containerRef.value) return;

    instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
      mountContainer: containerRef.value,
      position: "bottom-right",
    });
  });

  onUnmounted(() => {
    instance?.destroy();
  });
</script>

2.3 Angular

import {
  Component,
  OnInit,
  OnDestroy,
  ElementRef,
  ViewChild,
} from "@angular/core";
import {
  NapsterCompanionApiSdk,
  NapsterCompanionApiInstance,
} from "@touchcastllc/napster-companion-api";

@Component({
  selector: "app-companion",
  template: "<div #containerRef></div>",
})
export class CompanionComponent implements OnInit, OnDestroy {
  @ViewChild("containerRef") containerRef!: ElementRef<HTMLDivElement>;
  private instance: NapsterCompanionApiInstance | null = null;

  async ngOnInit() {
    this.instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
      mountContainer: this.containerRef.nativeElement,
      position: "bottom-right",
    });
  }

  ngOnDestroy() {
    this.instance?.destroy();
  }
}

2.4 Vanilla JavaScript/TypeScript

<div id="sdk-container"></div>
<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.js"></script>
<script>
  const sdk = window.napsterCompanionApiSDK;

  sdk
    .init("YOUR_TOKEN", {
      mountContainer: "#sdk-container",
      position: "bottom-right",
    })
    .then(instance => {
      // Control the avatar
      instance.showAvatar();

      // Hide after 10 seconds
      setTimeout(() => instance.hideAvatar(), 10000);
    });
</script>

2.5 Advanced Configuration

async function initAdvancedAvatar() {
  const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
    mountContainer: "#avatar-container",
    position: "bottom-right",

    avatarStyle: {
      view: "round", // Options: "round" | "rectangle" | "silhouette"
    },

    features: {
      inactiveTimeout: { enabled: true, duration: 120000, countdown: 15 },
      showSDKLoader: { enabled: true, bgColor: "#f0f0f0" },
    },

    style: {
      borderRadius: "12px",
      boxShadow: "0 4px 20px rgba(0,0,0,0.3)",
    },

    onReady: () => console.log("Avatar ready!"),
    onError: error => console.error("Error:", error),
    onAvatarReady: ready => console.log("Avatar loaded:", ready),
  });

  return instance;
}

2.6 Dynamic Feature Control

async function controlFeatures() {
  const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
    mountContainer: "#avatar-container",
  });

  // Change position dynamically
  document.getElementById("move-avatar")?.addEventListener("click", () => {
    instance.setPosition("top-left");
  });

  return instance;
}

2.7 Custom Styling

Inline Styles

const instance = await NapsterCompanionApiSdk.init(token, {
  style: {
    border: "2px solid #00ff00",
    borderRadius: "8px",
    boxShadow: "0 2px 10px rgba(0,0,0,0.2)",
    background: "rgba(255,255,255,0.95)",
  },
});

CSS Classes

const instance = await NapsterCompanionApiSdk.init(token, {
  className: "my-custom-avatar",
});

.my-custom-avatar {
  border: 2px solid #007acc;
  border-radius: 12px;
  backdrop-filter: blur(10px);
}

Dynamic Style Updates

// Update styles after initialization
instance.updateStyles({
  opacity: "0.9",
  transform: "scale(1.1)",
  transition: "all 0.3s ease",
});

2.8 Avatar Style Configuration

Customize the avatar's visual appearance using the avatarStyle configuration. Control the avatar's view mode, and other visual properties.

Avatar View Modes

const instance = await NapsterCompanionApiSdk.init(token, {
  avatarStyle: {
    view: "round", // Options: "round" | "rectangle" | "silhouette"
  },
});

Available View Modes:

• "round" (default) - Circular avatar with rounded appearance
• "rectangle" - Rectangular container, ideal for custom styling
• "silhouette" - Full view without background styling. (Note: works only with green screen feature enabled in Create Connection API)

Avatar Style Example

const instance = await NapsterCompanionApiSdk.init(token, {
  avatarStyle: {
    view: "rectangle",
  },
  style: {
    borderRadius: "16px", // Works well with rectangle
    boxShadow: "0 8px 32px rgba(0,0,0,0.2)",
  },
});

3. Feature Configuration

3.1 Core Features

Inactivity Timeout

Automatically disconnect the avatar after a period of user inactivity. Users receive a countdown notification before disconnection.

const instance = await NapsterCompanionApiSdk.init(token, {
  features: {
    inactiveTimeout: {
      enabled: true,
      duration: 60000, // 60 seconds (max: 180000ms)
      countdown: 10, // 10 second countdown (max: 60s)
    },
  },
});

SDK Loading Screen

Display a loading screen while the avatar assets are being loaded. Customize the background color to match your application's design.

const instance = await NapsterCompanionApiSdk.init(token, {
  features: {
    showSDKLoader: {
      enabled: true,
      bgColor: "#ffffff", // Optional background color
    },
  },
});

3.2 Position & Layout

Customize the avatar's position on the screen using predefined positions or custom styles. Also you can override the position using style properties.

const instance = await NapsterCompanionApiSdk.init(token, {
  mountContainer: "#my-container", // CSS selector or HTMLElement
  position: "bottom-right", // Predefined positions
  // Apply custom inline styles to override default SDK styles, will be added to root container
  style: {
    top: "20px",
    left: "20px",
    zIndex: "1000",
  },
  // Apply CSS class name to override default SDK styles, will be added to root container
  className: "my-custom-class",
});

Available Positions:

• "bottom-right" (default)
• "bottom-left"
• "bottom-center"
• "top-right"
• "top-left"
• "top-center"
• "center"

4. Event Handling

The SDK provides several event callbacks for monitoring status and handling errors.

const instance = await NapsterCompanionApiSdk.init(token, {
  // Fires when the SDK is initialized and ready to use
  onReady: () => console.log("SDK ready!"),
  // Fires on any SDK error
  onError: error => console.error("SDK error:", error),
  // Fires when the avatar is fully loaded and ready
  onAvatarReady: isReady => console.log("Avatar ready:", isReady),
  // Fires when user inactivity status changes
  onInactivityStatusChange: isInactive => console.log("Inactive:", isInactive),
  // Fires when the SDK is destroyed
  onDestroy: () => console.log("SDK destroyed"),
  // Fires when data is received from the WEBRTC data channel
  onData: data => console.log("Data received:", data),
});

5. API Reference

5.1 Core Methods

init(token: string, config?: NapsterCompanionApiConfig): Promise<NapsterCompanionApiInstance>

Initialize the SDK with authentication token and configuration.

const instance = await NapsterCompanionApiSdk.init("YOUR_TOKEN", {
  mountContainer: "#avatar-container",
  position: "bottom-right",
});

showAvatar(): void

Make the avatar visible on screen.

instance.showAvatar();

hideAvatar(): void

Hide the avatar from screen.

instance.hideAvatar();

avatarIsVisible(): boolean

Check if the avatar is currently visible.

if (instance.avatarIsVisible()) {
  console.log("Avatar is visible");
}

destroy(): void

Cleanup and remove the SDK completely.

instance.destroy();

5.2 Styling & Position Methods

updateStyles(styles: StyleObject): void

Update container styles dynamically.

instance.updateStyles({
  top: "50px",
  left: "50px",
  opacity: "0.8",
});

setPosition(position: Position): void

Change avatar position on screen.

instance.setPosition("top-left");
// or using enum
import { Position } from "@touchcastllc/napster-companion-api";
instance.setPosition(Position.TOP_LEFT);

clearPosition(): void

Reset position to default/configured value.

instance.clearPosition();

5.3 Feature Control Methods

enableFeature(feature: string): void

Enable a specific feature.

instance.enableFeature("disclaimer");

disableFeature(feature: string): void

Disable a specific feature.

instance.disableFeature("disclaimer");

isFeatureEnabled(feature: string): boolean

Check if a feature is currently enabled.

if (instance.isFeatureEnabled("disclaimer")) {
  console.log("Disclaimer is enabled");
}

5.4 Communication Methods

sendCommand(command: { type: string; data?: object }): void

Send a command to the avatar via the data channel.

// Send a message to the avatar
instance.sendCommand({ type: "send_message", data: { text: "Hello, how are you?" } });

// Cancel the current response
instance.sendCommand({ type: "cancel" });

6. Configuration Interface

interface NapsterCompanionApiConfig {
  // Container mounting
  mountContainer?: HTMLElement | string | null;

  // Positioning
  position?:
    | "bottom-right"
    | "bottom-left"
    | "bottom-center"
    | "top-right"
    | "top-left"
    | "top-center"
    | "center";

  // Styling
  style?: StyleObject;
  className?: string;
  avatarStyle?: {
    view: "round" | "rectangle" | "silhouette";
    borderWidth?: string;
    borderColor?: string;
    borderStyle?: string;
  };

  // Features
  features?: {
    backgroundRemoval?: { enabled: boolean };
    inactiveTimeout?: {
      enabled: boolean;
      duration?: number; // max: 180000ms
      countdown?: number; // max: 60s
    };
    disclaimer?: { enabled: boolean; text?: string };
    showSDKLoader?: { enabled: boolean; bgColor?: string };
  };

  // Configuration
  debug?: boolean;

  // Event callbacks
  onReady?: () => void;
  onError?: (error: Error) => void;
  onData?: (data: EventMessage) => void;
  onAvatarReady?: (isReady?: boolean) => void;
  onInactivityStatusChange?: (isInactive: boolean) => void;
  onDestroy?: () => void;
  onFeaturesUpdate?: (features: FeatureConfig) => void;
}

7. Troubleshooting

7.1 Common Issues

Problem: "Module not found" Error
Solution:

# Ensure package is installed
npm install @touchcastllc/napster-companion-api

# Install peer dependencies
npm install @reduxjs/toolkit

Problem: Invalid or expired token
Solution:

• Generate new token from backend API
• Ensure token is passed correctly to init()

Problem: Avatar appears unstyled
Solution:

See the style import guide from 1.2.1 Installation & Setup

Problem: mountContainer element doesn't exist
Solution:

// Wait for DOM to load
document.addEventListener("DOMContentLoaded", async () => {
  const instance = await NapsterCompanionApiSdk.init(token, {
    mountContainer: "#avatar-container", // Ensure element exists
  });
});

7.2 Debug Mode

Enable debug logging:

const instance = await NapsterCompanionApiSdk.init(token, {
  debug: true, // Enable debug logs
  onError: error => console.error("SDK Error:", error),
  onData: data => console.log("SDK Data:", data),
});

7.3 Performance Issues

Large Bundle Size

• Use ESM build instead of standalone
• Import only needed features
• Enable tree-shaking in bundler

Memory Leaks

// Always cleanup when done
useEffect(() => {
  return () => {
    instance?.destroy();
  };
}, [instance]);

License

This project is licensed under the MIT License - see the LICENSE file for details.