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

Built-in Controls Block

Toggle the built-in controls UI (mute / volume / screen-share / end buttons) rendered over the avatar. Disable this when your application provides its own UI using the public methods (muteMic, unmuteMic, setAudioVolume, stopAvatarTalking, destroy, etc.). Defaults to enabled: true — existing integrations see no change.

const instance = await NapsterCompanionApiSdk.init(token, {
  features: {
    controls: {
      enabled: false, // hide built-in buttons, render your own
    },
  },
});

You can also toggle it at runtime via updateFeatureConfig (or enableFeature / disableFeature):

instance.updateFeatureConfig("controls", { enabled: false });
// later
instance.enableFeature("controls");

3.2 Picture-in-Picture (PiP)

Automatically pop the avatar into a Document Picture-in-Picture window when the user switches browser tabs, so the conversation stays visible while they work in another tab. The PiP window mirrors the live avatar video and renders the built-in controls (mute / volume / screen-share / end). Closing the PiP window or returning to the original tab restores the in-page avatar. Chrome / Edge 116+ on HTTPS.

const instance = await NapsterCompanionApiSdk.init(token, {
  features: {
    pictureInPicture: {
      enabled: true,
      width: 400, // optional, default 400
      height: 300, // optional, default 300
    },
  },
});

Browser requirements for the auto-PiP trigger to fire:

• Secure context (HTTPS)
• Active media playback with audio
• The site has met the browser's Media Engagement Index threshold (user frequently consumes media on the site)

If the requirements aren't met, the avatar simply stays in-page when the tab loses focus — no errors are thrown.

3.3 Screen Sharing

Share the user's screen with the avatar in real time. The SDK captures the display at 1 FPS, renders each frame onto an internal canvas, and streams the canvas track over WebRTC so the avatar can "see" what the user sees. Fully browser-based — no plugins or extensions required.

Enable & Configure

const instance = await NapsterCompanionApiSdk.init(token, {
  features: {
    screenShare: {
      enabled: true,
    },
  },
});

Note: features.screenShare.enabled must be true for the screen share controls to appear and for isScreenShareSupported to return true.

Start & Stop

// Start sharing (opens browser's screen picker)
await instance.startScreenShare();

// Stop sharing
instance.stopScreenShare();

// Or toggle on/off
await instance.toggleScreenShare();

The SDK sends start_video / stop_video commands to the avatar server automatically. If the user stops sharing via the browser's native "Stop sharing" button, the SDK detects this and cleans up.

Checking State

// Whether screen sharing is currently active
instance.isScreenSharing; // boolean

// Whether the browser supports screen sharing AND the feature is enabled
instance.isScreenShareSupported; // boolean

Cleanup

Screen sharing is automatically stopped when:

• The user calls instance.destroy()
• The WebRTC connection closes (network failure, session end)
• The user clicks the browser's native "Stop sharing" button

3.4 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 Screen Sharing Methods

startScreenShare(): Promise<void>

Start screen sharing. Opens the browser's screen picker and begins streaming frames to the avatar.

await instance.startScreenShare();

Note: Requires features.screenShare.enabled = true in the init config. Does nothing if already sharing.

stopScreenShare(): void

Stop screen sharing. Releases the display stream and notifies the server.

instance.stopScreenShare();

toggleScreenShare(): Promise<void>

Toggle screen sharing on or off.

await instance.toggleScreenShare();

isScreenSharing: boolean (read-only)

Whether screen sharing is currently active.

if (instance.isScreenSharing) {
  console.log("User is sharing their screen");
}

isScreenShareSupported: boolean (read-only)

Whether screen sharing is supported by the browser and enabled in the feature config.

if (instance.isScreenShareSupported) {
  showScreenShareButton();
}

5.5 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" });

5.6 Audio Control Methods

Control the avatar's incoming WebRTC audio output (the avatar's voice the user hears). These methods operate on the underlying <audio> element and do not affect the user's microphone.

muteAudio(): void

Mute the avatar's audio output.

instance.muteAudio();

unmuteAudio(): void

Unmute the avatar's audio output.

instance.unmuteAudio();

isAudioMuted: boolean (readonly)

Whether the avatar's audio output is currently muted.

if (instance.isAudioMuted) {
  instance.unmuteAudio();
}

setAudioVolume(volume: number): void

Set the avatar's audio output volume. Accepts a value in the range 0..1; values outside the range are clamped.

instance.setAudioVolume(0.5); // 50% volume

getAudioVolume(): number

Get the current avatar audio output volume in the range 0..1.

const volume = instance.getAudioVolume();

5.7 Microphone Control Methods

Control the user's microphone input that is sent to the avatar.

muteMic(): void

Mute the user's microphone input.

instance.muteMic();

unmuteMic(): void

Unmute the user's microphone input.

instance.unmuteMic();

isMicMuted: boolean (readonly)

Whether the user's microphone is currently muted.

if (instance.isMicMuted) {
  instance.unmuteMic();
}

5.8 Avatar Speech Control Methods

Interrupt the avatar's response and inspect speaking state for both sides of the conversation.

stopAvatarTalking(): void

Interrupt the avatar's current response so it stops talking. Sends a cancel command over the data channel.

instance.stopAvatarTalking();

isAvatarSpeaking: boolean (readonly)

Whether the avatar is currently speaking.

if (instance.isAvatarSpeaking) {
  instance.stopAvatarTalking();
}

isUserTalking: boolean (readonly)

Whether the user is currently talking (detected from the microphone input).

if (instance.isUserTalking) {
  // e.g. dim a "push to talk" indicator
}

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 };
    pictureInPicture?: {
      enabled: boolean;
      width?: number; // default 400
      height?: number; // default 300
    };
    screenShare?: { enabled: boolean };
    controls?: { enabled: boolean };
  };

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