Vanilla JS SDK

@tts2go/vanillais a framework-agnostic SDK that works anywhere JavaScript runs — including plain <script> tags.

Installation

NPM

npm install @tts2go/vanilla

CDN (script tag)

<script src="https://unpkg.com/@tts2go/vanilla/dist/index.global.js"></script>
<script>
  const tts = new TTS2Go.TTS2Go({
    apiKey: "tts_your_api_key",
    projectId: "your-project-id",
  });
</script>

Basic usage

import { TTS2Go } from "@tts2go/vanilla";

const tts = new TTS2Go({
  apiKey: "tts_your_api_key",
  projectId: "your-project-id",
});

// Create a TTS instance for specific content
const instance = tts.create("Hello, world!", "voice_abc123");

// Play it
document.getElementById("play-btn").addEventListener("click", () => {
  instance.play();
});

document.getElementById("stop-btn").addEventListener("click", () => {
  instance.stop();
});

One-shot generation

Use generate() to create an instance and immediately start playback:

const instance = await tts.generate("Read this text aloud", "voice_abc123");
// Audio is already playing

Event handling

Subscribe to events on a TTS instance:

const instance = tts.create("Hello!", "voice_abc123");

instance.on("statusChange", (status) => {
  console.log("Status:", status);
  // "idle" | "loading" | "playing" | "paused" | "error" | "fallback"
});

instance.on("urlReady", (url) => {
  console.log("Audio URL:", url);
});

instance.on("error", (message) => {
  console.error("TTS error:", message);
});

instance.on("timeUpdate", ({ currentTime, duration }) => {
  const progress = (currentTime / duration) * 100;
  progressBar.style.width = progress + "%";
});

// Remove a listener
instance.off("statusChange", myCallback);

Events

Event	Payload	Description
`statusChange`	`TTSStatus`	Fired when playback status changes
`urlReady`	`string`	Fired when CDN URL becomes available
`error`	`string`	Fired on generation or playback error
`play`	`void`	Fired when playback starts
`pause`	`void`	Fired when playback pauses
`stop`	`void`	Fired when playback stops
`timeUpdate`	`{ currentTime, duration }`	Fired during playback with progress

TTSInstance methods

Method	Description
`play()`	Start playback (generates audio if needed)
`stop()`	Stop playback and reset position
`pause()`	Pause playback
`resume()`	Resume paused playback
`getStatus()`	Get current status synchronously
`getUrl()`	Get CDN URL (null if not yet generated)
`getError()`	Get error message (null if no error)
`destroy()`	Clean up all resources and listeners

Fetching voices

const voices = await tts.getVoices();
voices.forEach((voice) => {
  console.log(voice.id, voice.name, voice.description);
});

Configuration

const tts = new TTS2Go({
  apiKey: "tts_your_api_key",   // Required
  projectId: "your-project-id",  // Required
  cdnBase: "https://cdn.tts2go.dev",  // Optional, defaults to production CDN
  apiBase: "https://api.tts2go.dev/api/v1", // Optional
});

TypeScript

import type {
  TTSInstance,
  TTSEventMap,
  TTSEventCallback,
  TTS2GoConfig,
  TTSStatus,
  Voice,
  PollOptions,
} from "@tts2go/vanilla";