Features

Features are built-in behaviors controlled through the features config object. Each feature has an enabled flag and, in some cases, tuning options — several are on by default, so the table below is also the list of what to turn off. You can also toggle features at runtime — see feature control methods.

Inactivity timeout

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

await NapsterCompanionApiSdk.init(token, {
  features: {
    inactiveTimeout: {
      enabled: true,
      duration: 60000, // idle time before the countdown, in ms
      countdown: 10,   // countdown length before disconnect, in seconds
    },
  },
});

Use onInactivityStatusChange to react when the inactivity status flips.

Loading screen

Display a loading overlay while the avatar assets load. It is enabled by default. Customize the background color, loader color, and animation type, or supply your own CSS class.

await NapsterCompanionApiSdk.init(token, {
  features: {
    showSDKLoader: {
      enabled: true,
      bgColor: "#ffffff",         // overlay background color
      color: "#000000",           // loader animation color
      type: "spinner",            // "spinner" | "pulse"
      className: "custom-loader", // optional custom class
    },
  },
});

With className you can override the loader's appearance entirely:

.my-brand-loader {
  width: 60px !important;
  height: 60px !important;
  border-width: 5px !important;
  border-style: solid !important;
  border-color: rgba(99, 102, 241, 0.2) !important;
  border-top-color: #6366f1 !important;
  border-radius: 50% !important;
  animation: spin 0.8s linear infinite !important;
}

@keyframes spin {
  to { transform: rotate(360deg); }
}

Built-in controls

The controls block is the mute / volume / screen-share / end buttons rendered over the avatar. It is enabled by default. The volume control toggles the sound on and off; to set a specific volume level, use setAudioVolume from your own UI. Disable the block entirely when your application provides its own controls using the instance methods (muteMic, setAudioVolume, stopAvatarTalking, destroy, and so on).

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

You can toggle it at runtime:

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

Picture-in-picture

Pop the avatar into a Document Picture-in-Picture window when the user switches browser tabs, so the conversation stays visible while they work elsewhere. The PiP window mirrors the live avatar video and renders the built-in controls. Closing the PiP window or returning to the original tab restores the in-page avatar.

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

The auto-PiP trigger requires Chrome or Edge 116+ and:

• A secure context (HTTPS).
• Active media playback with audio.
• The site has met the browser's Media Engagement Index threshold.

If the requirements aren't met, the avatar stays in-page when the tab loses focus — no errors are thrown. To check support programmatically, use the exported checkPiPSupport helper.

PiP support helpers

The SDK exports two helpers for detecting Document Picture-in-Picture support:

import { checkPiPSupport, resetPiPSupportCache } from "@touchcastllc/napster-companion-api";

if (checkPiPSupport()) {
  // the browser supports Document Picture-in-Picture
}

checkPiPSupport() returns whether the browser supports the API; the result is cached. resetPiPSupportCache() clears that cache, which is mainly useful in tests.

Screen sharing

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

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

Start and stop sharing from your own UI with the screen-sharing methods:

await instance.startScreenShare(); // opens the browser's screen picker
instance.stopScreenShare();
await instance.toggleScreenShare();

The SDK sends start_video / stop_video commands to the avatar automatically. Screen sharing stops automatically when the user calls destroy(), when the WebRTC connection closes, or when the user clicks the browser's native "Stop sharing" button. Listen for onScreenShareStateChange to keep your UI in sync.

Background removal

Remove the avatar's background so it composites over your page. Enabled by default.

await NapsterCompanionApiSdk.init(token, {
  features: {
    backgroundRemoval: {
      enabled: true,
    },
  },
});

For chroma-keying a green-screen stream, see avatarStyle.view: "silhouette" and the green screen background channel option.

Disclaimer

A small disclaimer shown over the widget — legal text or usage hints. It is enabled by default with the default text; set enabled: false to remove it, or provide your own text.

await NapsterCompanionApiSdk.init(token, {
  features: {
    disclaimer: {
      enabled: true,
      text: "AI-generated responses. May contain errors.",
      color: "#666666", // optional
    },
  },
});

You can change it at runtime:

instance.updateFeatureConfig("disclaimer", { text: "New disclaimer text" });

Next steps