Vanilla JS SDK

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

Installation

NPM

npm install @tts2go/vanilla

View @tts2go/vanilla on npm →

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

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

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

Full example

<button id="play">Play</button>
<button id="stop" disabled>Stop</button>
<span id="status">idle</span>

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

  const playBtn = document.getElementById("play");
  const stopBtn = document.getElementById("stop");
  const statusEl = document.getElementById("status");

  const instance = tts.create(
    "Welcome to our website. This text is being read aloud by TTS2Go.",
    "voice-id"
  );

  instance.onStatusChange = (status) => {
    statusEl.textContent = status;
    stopBtn.disabled = status !== "playing";
    playBtn.disabled = status === "loading";
    playBtn.textContent = status === "loading" ? "Loading..." : "Play";
  };

  playBtn.addEventListener("click", () => instance.play());
  stopBtn.addEventListener("click", () => instance.stop());
</script>

TTSInstance methods

Method / Property	Type	Description
`play()`	`Promise<void>`	Start playback (tries CDN, falls back to browser TTS, queues generation)
`stop()`	`void`	Stop playback and reset position
`pause()`	`void`	Pause playback
`resume()`	`void`	Resume paused playback
`getStatus()`	`TTSStatus`	Current status synchronously
`getUrl()`	`string \| null`	CDN URL after successful playback
`getError()`	`string \| null`	Error message if failed
`destroy()`	`void`	Clean up all resources
`onStatusChange`	`((status: TTSStatus) => void) \| null`	Callback fired when status changes

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.com",  // Optional, defaults to production CDN
  apiBase: "https://backend.tts2go.com/api/v1", // Optional
});

Status flow

idle → loading → playing → idle
                ↘ error
                ↘ fallback → idle

If the CDN audio hasn't been generated yet, the SDK falls back to the browser's built-in TTS engine and queues a generation request in the background. Next time the same content is played, it loads from the CDN in high quality.

TypeScript

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