AbsoluteJS

@absolutejs/voice-cartesia

@absolutejs/voice-cartesiav0.0.1-beta.6betaVoice & Media

Cartesia text-to-speech adapter for @absolutejs/voice

#Installation

BASH
bun add @absolutejs/voice-cartesia

#Capabilities

Overview

Cartesia text-to-speech adapter for @absolutejs/voice.

Wraps Cartesia's /tts/sse (default) and /tts/bytes HTTP endpoints behind the TTSAdapter seam exposed by @absolutejs/voice. Streams audio chunks straight from the response body so the voice runtime can start playback as soon as Cartesia returns the first frame.

Use

For telephony (8 kHz μ-law):

Options

Option — Required — Default — Notes

apiKey — yes — — — Cartesia API key.

voice — yes — — — Either a voice id string (shorthand for { id, mode: "id" }) or { embedding, mode: "embedding" } for live cloning.

Show 10 more

model — no — "sonic-2" — Cartesia model id.

outputFormat.container — no — "raw" — Must be "raw" for streaming.

outputFormat.encoding — no — "pcm_s16le" — pcm_s16le, pcm_f32le, pcm_mulaw (telephony), or pcm_alaw.

outputFormat.sampleRate — no — 24_000 — 8 / 16 / 22_050 / 24 / 44.1 / 48 kHz.

language — no — — — Forwarded to Cartesia.

speed — no — — — slow / normal / fast or a numeric multiplier.

transport — no — "sse" — "sse" (server-sent events with base64 frames) or "http" (raw chunked bytes).

version — no — "2024-11-13" — Cartesia-Version header.

baseUrl — no — "https://api.cartesia.ai" — Override for self-hosted or staging environments.

fetch — no — globalThis.fetch — Inject for tests; opportunistic HTTP/2 multiplexing is enabled for HTTPS targets.

Notes

Only the raw container is supported because the voice runtime needs framed PCM/μ-law/α-law to feed transports. If you need mp3 or wav for offline files, use the Cartesia SDK directly.

The adapter aborts the in-flight HTTP request on session.close(reason) and refuses further send() calls. No reconnect/keep-alive is needed for HTTP transports.

Whitespace-only send() is a no-op (no network call, matching the ElevenLabs adapter).

Outcomes

What you can build

Build on the supported package contract

Use @absolutejs/voice-cartesia through its supported public entry points.

Hardening checklist

Production guidance

Make every external boundary explicitPin the deployed @absolutejs/voice-cartesia version, replace example or memory-backed dependencies with durable implementations, bound external calls, protect credentials, and emit enough evidence to retry or recover safely.

Follow in order

Troubleshooting path

1
Trace from the first failed boundary
Reproduce the smallest canonical @absolutejs/voice-cartesia example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.

#Use

Partial snippet

Working example for Use.

TS
import { voice } from "@absolutejs/voice";
import { cartesia } from "@absolutejs/voice-cartesia";

const app = voice({
  // ... stt + other voice options ...
  tts: cartesia({
    apiKey: process.env.CARTESIA_API_KEY!,
    model: "sonic-2",
    outputFormat: {
      container: "raw",
      encoding: "pcm_s16le",
      sampleRate: 24_000,
    },
    voice: "a0e99841-438c-4a64-b679-ae501e7d6091",
  }),
});

#Use 2

Partial snippet

For telephony (8 kHz μ-law):

TS
cartesia({
  apiKey,
  voice: voiceId,
  outputFormat: {
    container: "raw",
    encoding: "pcm_mulaw",
    sampleRate: 8_000,
  },
});

#Public entry points

Supported entry points declared by this package manifest.

Package entry point declared in package.json.

@absolutejs/voice-cartesia@absolutejs/voice-cartesia/manifest@absolutejs/voice-cartesia/manifest.json

#Package commands

Scripts declared by this package manifest.

bun run buildrm -rf dist && bun build ./src/index.ts ./src/manifest.ts --outdir dist --target bun --external @absolutejs/manifest --external '@absolutejs/manifest/*' --external @absolutejs/voice --external '@absolutejs/voice/*' --external @sinclair/typebox --external '@sinclair/typebox/*' && tsc --emitDeclarationOnly --project tsconfig.json && absolute-manifest emit
bun run check:packagebun run format && bun run typecheck && bun run test && bun run verify-package && bun run build && bun run verify-package --artifacts
bun run formatprettier --write "./**/*.{js,ts,json,md}"
bun run testbun test
bun run typecheckbun run tsc --noEmit