@tanstack/ai-byteplus 0.3.5 → 0.4.1

package/dist/esm/adapters/tts.d.ts

@@ -1,5 +1,5 @@
 import { BaseTTSAdapter } from '@tanstack/ai/adapters';
-import { TTSOptions } from '@tanstack/ai';
+import { TTSCapabilities, TTSOptions, TTSTurn } from '@tanstack/ai';
 import { InternalLogger } from '@tanstack/ai/adapter-internals';
 import { BytePlusVoiceConfig } from '../utils/client.js';
 import { BytePlusTTSModel } from '../model-meta.js';
@@ -19,6 +19,12 @@ export declare const BYTEPLUS_DEFAULT_TTS_SPEAKER = "en_female_stokie_uranus_big
  * when `speech_rate` slows it down.
  */
 export declare const BYTEPLUS_TTS_MAX_OUTPUT_SECONDS = 120;
+/**
+ * Hard cap on the `references` array, and therefore on the number of distinct
+ * voices one dialogue request can use. The markers that cite them in
+ * `text_prompt` run `@Audio1`..`@Audio3`.
+ */
+export declare const BYTEPLUS_TTS_MAX_REFERENCES = 3;
 /**
  * BytePlus Seed Speech text-to-speech adapter.
  *
@@ -52,6 +58,12 @@ export declare const BYTEPLUS_TTS_MAX_OUTPUT_SECONDS = 120;
  */
 export declare class BytePlusTTSAdapter<TModel extends BytePlusTTSModel = BytePlusTTSModel> extends BaseTTSAdapter<TModel, BytePlusTTSProviderOptions> {
     readonly name: "byteplus";
+    /**
+     * Seed Audio 1.0 does multi-role dialogue in one pass, addressed through
+     * `references` (capped at 3 entries), and returns word/sentence timings
+     * when `audio_config.enable_subtitle` is set.
+     */
+    readonly capabilities: TTSCapabilities;
     private readonly apiKey;
     private readonly baseURL;
     private readonly defaultHeaders;
@@ -70,10 +82,14 @@ export declare class BytePlusTTSAdapter<TModel extends BytePlusTTSModel = BytePl
 export declare function buildTTSRequestBody(options: {
     model: string;
     text: string;
+    /** Dialogue turns, when the caller asked for multi-role synthesis. */
+    turns?: Array<TTSTurn>;
     voice: string | undefined;
     format: TTSOptions['format'] | undefined;
     speed: number | undefined;
     modelOptions: BytePlusTTSProviderOptions | undefined;
+    /** Core `timestamps: true` — turns on `audio_config.enable_subtitle`. */
+    timestamps?: boolean;
     logger: InternalLogger;
 }): {
     body: BytePlusTTSCreateRequest;

package/dist/esm/adapters/tts.js

@@ -51,6 +51,12 @@ var BYTEPLUS_DEFAULT_TTS_SPEAKER = "en_female_stokie_uranus_bigtts";
 */
 var BYTEPLUS_TTS_MAX_OUTPUT_SECONDS = 120;
 /**
+* Hard cap on the `references` array, and therefore on the number of distinct
+* voices one dialogue request can use. The markers that cite them in
+* `text_prompt` run `@Audio1`..`@Audio3`.
+*/
+var BYTEPLUS_TTS_MAX_REFERENCES = 3;
+/**
 * BytePlus Seed Speech text-to-speech adapter.
 *
 * Talks to `POST {baseURL}/api/v3/tts/create` on the Seed Speech voice host.
@@ -83,6 +89,15 @@ var BYTEPLUS_TTS_MAX_OUTPUT_SECONDS = 120;
 */
 var BytePlusTTSAdapter = class extends BaseTTSAdapter {
 	name = "byteplus";
+	/**
+	* Seed Audio 1.0 does multi-role dialogue in one pass, addressed through
+	* `references` (capped at 3 entries), and returns word/sentence timings
+	* when `audio_config.enable_subtitle` is set.
+	*/
+	capabilities = {
+		maxSpeakers: 3,
+		timestamps: true
+	};
 	apiKey;
 	baseURL;
 	defaultHeaders;
@@ -96,7 +111,7 @@ var BytePlusTTSAdapter = class extends BaseTTSAdapter {
 		this.fetchImpl = resolved.fetch ?? globalThis.fetch.bind(globalThis);
 	}
 	async generateSpeech(options) {
-		const { logger, model, text, voice, format, speed, modelOptions } = options;
+		const { logger, model, text, voice, format, speed, modelOptions, turns } = options;
 		logger.request(`activity=generateSpeech provider=byteplus model=${model}`, {
 			provider: "byteplus",
 			model
@@ -104,10 +119,12 @@ var BytePlusTTSAdapter = class extends BaseTTSAdapter {
 		const { body, audioFormat, sampleRate } = buildTTSRequestBody({
 			model,
 			text,
+			turns,
 			voice,
 			format,
 			speed,
 			modelOptions,
+			timestamps: options.timestamps,
 			logger
 		});
 		try {
@@ -135,6 +152,7 @@ var BytePlusTTSAdapter = class extends BaseTTSAdapter {
 				...duration !== void 0 && { duration },
 				...originalDuration !== void 0 && { originalDuration },
 				...data.subtitle !== void 0 && { subtitle: data.subtitle },
+				...toAlignmentFields(data.subtitle),
 				...data.url !== void 0 && { url: data.url }
 			};
 		} catch (error) {
@@ -155,7 +173,7 @@ var BytePlusTTSAdapter = class extends BaseTTSAdapter {
 * `contentType`.
 */
 function buildTTSRequestBody(options) {
-	const { model, text, voice, format, speed, modelOptions, logger } = options;
+	const { model, text, turns, voice, format, speed, modelOptions, logger } = options;
 	const audioFormat = pickAudioFormat(modelOptions?.format, format, logger);
 	const sampleRate = modelOptions?.sample_rate ?? DEFAULT_SAMPLE_RATE;
 	const audioConfig = {
@@ -164,16 +182,18 @@ function buildTTSRequestBody(options) {
 	};
 	if (modelOptions?.pitch_rate !== void 0) audioConfig.pitch_rate = modelOptions.pitch_rate;
 	if (modelOptions?.loudness_rate !== void 0) audioConfig.loudness_rate = modelOptions.loudness_rate;
-	if (modelOptions?.enable_subtitle !== void 0) audioConfig.enable_subtitle = modelOptions.enable_subtitle;
+	const enableSubtitle = modelOptions?.enable_subtitle ?? (options.timestamps || void 0);
+	if (enableSubtitle !== void 0) audioConfig.enable_subtitle = enableSubtitle;
 	const speechRate = modelOptions?.speech_rate ?? (speed !== void 0 ? toSpeechRate(speed, logger) : void 0);
 	if (speechRate !== void 0) audioConfig.speech_rate = speechRate;
+	const dialogue = turns ? buildDialoguePrompt(turns) : void 0;
 	const body = {
 		model,
-		[TTS_TEXT_FIELD]: text,
-		references: modelOptions?.references ?? [{ speaker: modelOptions?.speaker ?? voice ?? "en_female_stokie_uranus_bigtts" }],
+		[TTS_TEXT_FIELD]: dialogue?.textPrompt ?? text,
+		references: modelOptions?.references ?? dialogue?.references ?? [{ speaker: modelOptions?.speaker ?? voice ?? "en_female_stokie_uranus_bigtts" }],
 		audio_config: audioConfig
 	};
-	if (modelOptions?.watermark !== void 0) body.watermark = modelOptions.watermark;
+	if (modelOptions?.watermark !== void 0) body.watermark = typeof modelOptions.watermark === "boolean" ? { aigc_watermark: modelOptions.watermark } : modelOptions.watermark;
 	return {
 		body,
 		audioFormat,
@@ -256,6 +276,59 @@ function getContentType(format, sampleRate) {
 	}
 }
 /**
+* Turn dialogue turns into the one-prompt form Seed Audio 1.0 takes: each
+* distinct voice becomes a `references` entry, and every line of the script
+* cites its voice by the reference's 1-based position (`@Audio1`..`@Audio3`),
+* which is the marker convention the reference array already uses.
+*
+* **The prompt form is unprobed.** The flat `references[]` member shape is
+* confirmed (see `BytePlusTTSReference`), and the model card documents
+* multi-role dialogue and positional reference markers, but no worked
+* multi-speaker example was available and no Seed Speech key existed to
+* confirm how lines should cite their voice.
+*/
+function buildDialoguePrompt(turns) {
+	const voices = [...new Set(turns.map((turn) => turn.voice))];
+	return {
+		textPrompt: turns.map((turn) => `@Audio${voices.indexOf(turn.voice) + 1}: ${turn.text}`).join("\n"),
+		references: voices.map((speaker) => ({ speaker }))
+	};
+}
+/**
+* Map the BytePlus `subtitle` block onto the cross-provider `alignment` /
+* `segments` fields.
+*
+* `words` is the finest granularity Seed Speech reports, so it becomes
+* `alignment`; `sentences` is utterance segmentation, so it becomes
+* `segments`. **Subtitle times are milliseconds** while the rest of the
+* response is seconds — the conversion happens here, once.
+*
+* The raw block stays on {@link BytePlusTTSResult.subtitle} for callers
+* already reading it.
+*/
+function toAlignmentFields(subtitle) {
+	if (!subtitle) return {};
+	const fields = {};
+	const words = subtitle.words?.filter(isTimedEntry);
+	if (words && words.length > 0) fields.alignment = {
+		unit: "word",
+		texts: words.map((word) => word.text ?? ""),
+		startSeconds: words.map((word) => word.start_time / 1e3),
+		endSeconds: words.map((word) => word.end_time / 1e3)
+	};
+	const sentences = subtitle.sentences?.filter(isTimedEntry);
+	if (sentences && sentences.length > 0) fields.segments = sentences.map((sentence) => ({
+		startSeconds: sentence.start_time / 1e3,
+		endSeconds: sentence.end_time / 1e3,
+		...sentence.text !== void 0 && { text: sentence.text }
+	}));
+	return fields;
+}
+/** Both times present, so the entry can be placed on the timeline. */
+function isTimedEntry(entry) {
+	return typeof entry.start_time === "number" && typeof entry.end_time === "number";
+}
+/**
 * Coerce a `duration` / `original_duration` field to a usable number of
 * seconds.
 *
@@ -302,6 +375,6 @@ function byteplusSpeech(model, config) {
 	return createBytePlusSpeech(model, getBytePlusVoiceApiKeyFromEnv(), config);
 }
 //#endregion
-export { BYTEPLUS_DEFAULT_TTS_SPEAKER, BYTEPLUS_TTS_MAX_OUTPUT_SECONDS, BytePlusTTSAdapter, buildTTSRequestBody, byteplusSpeech, createBytePlusSpeech, getContentType, toDurationSeconds, toSpeechRate };
+export { BYTEPLUS_DEFAULT_TTS_SPEAKER, BYTEPLUS_TTS_MAX_OUTPUT_SECONDS, BYTEPLUS_TTS_MAX_REFERENCES, BytePlusTTSAdapter, buildTTSRequestBody, byteplusSpeech, createBytePlusSpeech, getContentType, toDurationSeconds, toSpeechRate };
 
 //# sourceMappingURL=tts.js.map

package/dist/esm/adapters/tts.js.map

@@ -1 +1 @@
-{"version":3,"file":"tts.js","names":[],"sources":["../../../src/adapters/tts.ts"],"sourcesContent":["import { BaseTTSAdapter } from '@tanstack/ai/adapters'\nimport { generateId } from '@tanstack/ai-utils'\nimport { toRunErrorPayload } from '@tanstack/ai/adapter-internals'\nimport {\n  BYTEPLUS_VOICE_BASE_URL,\n  bytePlusVoiceError,\n  bytePlusVoiceHeaders,\n  getBytePlusVoiceApiKeyFromEnv,\n  readJsonBody,\n  withBytePlusVoiceDefaults,\n} from '../utils/client'\nimport type { TTSOptions } from '@tanstack/ai'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\nimport type { BytePlusVoiceConfig } from '../utils/client'\nimport type { BytePlusTTSModel } from '../model-meta'\nimport type {\n  BytePlusTTSAudioConfig,\n  BytePlusTTSAudioFormat,\n  BytePlusTTSCreateRequest,\n  BytePlusTTSCreateResponse,\n} from '../audio/wire-types'\nimport type {\n  BytePlusTTSProviderOptions,\n  BytePlusTTSResult,\n} from '../audio/tts-provider-options'\n\n/** Path of the synchronous Seed Speech synthesis endpoint. */\nconst TTS_CREATE_PATH = '/api/v3/tts/create'\n\n/**\n * Name of the request field carrying the text to speak.\n *\n * **`text_prompt` is correct — do not \"fix\" this to `text`.** The endpoint\n * schema (docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01) lists this\n * body as exactly `model`, `text_prompt`, `references`, `audio_config`,\n * `watermark`; there is no request-side `text`. The `text` spelling belongs\n * to the *other* endpoint, `/tts/unidirectional` (TTS 2.0), where it sits\n * under `req_params.text`. The name stays isolated here so the two spellings\n * never get conflated.\n */\nconst TTS_TEXT_FIELD = 'text_prompt' satisfies keyof BytePlusTTSCreateRequest\n\n/**\n * Sample rate used when the caller doesn't pick one. The endpoint documents a\n * default of 40000, which is not among the rates it accepts — so the adapter\n * never relies on the server default and always sends this instead.\n */\nconst DEFAULT_SAMPLE_RATE = 24000\n\n/**\n * True when a Seed Speech envelope's `code` means success.\n *\n * Seed Speech uses `0` for success and a flat numeric code otherwise\n * (`45000010 Invalid X-Api-Key`). The success envelope has not been confirmed\n * against a live key, so `code` is accepted as a number, its string form, or\n * absent — an envelope that omits `code` entirely is treated as success, which\n * is what the HTTP status already told us.\n */\nfunction isZeroCode(code: number | string | undefined): boolean {\n  if (code === undefined) return true\n  return Number(code) === 0\n}\n\n/**\n * Voice used when neither `TTSOptions.voice` nor `modelOptions.speaker` is\n * set — the English female \"Stokie\" voice from the TTS 2.0 generation.\n */\nexport const BYTEPLUS_DEFAULT_TTS_SPEAKER = 'en_female_stokie_uranus_bigtts'\n\n/**\n * Hard cap on a single Seed Speech synthesis, in seconds. Longer scripts must\n * be split across calls and stitched client-side.\n *\n * The cap applies to the *pre-rate* length the service bills on — the\n * `original_duration` it returns. The delivered clip can run longer than this\n * when `speech_rate` slows it down.\n */\nexport const BYTEPLUS_TTS_MAX_OUTPUT_SECONDS = 120\n\n/**\n * BytePlus Seed Speech text-to-speech adapter.\n *\n * Talks to `POST {baseURL}/api/v3/tts/create` on the Seed Speech voice host.\n * Two things differ from the Ark-hosted adapters in this package:\n *\n * - **Separate API key.** Seed Speech authenticates with `X-Api-Key` and its\n *   own key (`BYTEPLUS_VOICE_API_KEY`). An `ARK_API_KEY` sent here is\n *   rejected with `45000010 Invalid X-Api-Key`.\n * - **120 s output cap.** A single call synthesises at most\n *   {@link BYTEPLUS_TTS_MAX_OUTPUT_SECONDS} seconds of audio; longer scripts\n *   have to be split and stitched client-side. The cap is measured before\n *   `speech_rate` is applied, so a slowed clip can play for longer than that\n *   — `result.duration` is the delivered length and `result.originalDuration`\n *   is the metered one.\n *\n * Streaming synthesis (`tts/unidirectional` and the WebSocket API) is not\n * covered by this adapter — note that endpoint spells the text field `text`,\n * while this one uses `text_prompt`.\n *\n * @example\n * ```ts\n * const adapter = byteplusSpeech('seed-audio-1.0')\n * const result = await generateSpeech({\n *   adapter,\n *   text: 'welcome to the guitar store',\n *   voice: 'en_female_stokie_uranus_bigtts',\n *   format: 'mp3',\n * })\n * ```\n */\nexport class BytePlusTTSAdapter<\n  TModel extends BytePlusTTSModel = BytePlusTTSModel,\n> extends BaseTTSAdapter<TModel, BytePlusTTSProviderOptions> {\n  readonly name = 'byteplus' as const\n\n  private readonly apiKey: string\n  private readonly baseURL: string\n  private readonly defaultHeaders: Record<string, string>\n  private readonly fetchImpl: typeof fetch\n\n  constructor(model: TModel, config: BytePlusVoiceConfig) {\n    super(model, config)\n    const resolved = withBytePlusVoiceDefaults(config)\n    this.apiKey = resolved.apiKey\n    this.baseURL = resolved.baseURL ?? BYTEPLUS_VOICE_BASE_URL\n    this.defaultHeaders = resolved.defaultHeaders ?? {}\n    this.fetchImpl = resolved.fetch ?? globalThis.fetch.bind(globalThis)\n  }\n\n  async generateSpeech(\n    options: TTSOptions<BytePlusTTSProviderOptions>,\n  ): Promise<BytePlusTTSResult> {\n    const { logger, model, text, voice, format, speed, modelOptions } = options\n\n    logger.request(`activity=generateSpeech provider=byteplus model=${model}`, {\n      provider: 'byteplus',\n      model,\n    })\n\n    const { body, audioFormat, sampleRate } = buildTTSRequestBody({\n      model,\n      text,\n      voice,\n      format,\n      speed,\n      modelOptions,\n      logger,\n    })\n\n    try {\n      const response = await this.fetchImpl(\n        `${this.baseURL}${TTS_CREATE_PATH}`,\n        {\n          method: 'POST',\n          headers: bytePlusVoiceHeaders(this.apiKey, {\n            ...this.defaultHeaders,\n            // Client-generated per-request id. BytePlus echoes it in their\n            // request logs, which is what support asks for when diagnosing a\n            // synthesis failure.\n            'X-Api-Request-Id': newRequestId(),\n          }),\n          body: JSON.stringify(body),\n        },\n      )\n\n      const payload = await readJsonBody(response)\n\n      if (!response.ok) {\n        throw bytePlusVoiceError(response.status, payload, 'text-to-speech')\n      }\n\n      const data = payload as BytePlusTTSCreateResponse\n\n      // Seed Speech reports status in the body, not only in the HTTP status:\n      // a 200 can carry a non-zero `code`. Check it before looking at `audio`,\n      // because a failed call may still return a partial or placeholder\n      // payload that would otherwise be handed back as if it were valid.\n      //\n      // `code` is accepted as a number *or* a string. The success envelope was\n      // never confirmed against a live key (no voice key yet — see\n      // `audio/wire-types.ts`), and `readStringField` already tolerates both\n      // forms when rendering the error, so requiring a number here would let\n      // `{\"code\": \"45000010\"}` through both this gate and the one below.\n      if (!isZeroCode(data.code)) {\n        throw bytePlusVoiceError(response.status, payload, 'text-to-speech')\n      }\n\n      // Belt and braces for a 200 that reports success but carries nothing to\n      // play. Say that the adapter rejected it, rather than reusing the\n      // envelope-error phrasing — a bare \"failed (200)\" gives no hint that the\n      // response was well-formed and simply empty.\n      if (typeof data.audio !== 'string' || data.audio.length === 0) {\n        throw new Error(\n          `BytePlus Seed Speech text-to-speech returned a success response ` +\n            `with no audio (model ${model}).`,\n        )\n      }\n\n      const duration = toDurationSeconds(data.duration)\n      const originalDuration = toDurationSeconds(data.original_duration)\n\n      return {\n        id: generateId(this.name),\n        model,\n        audio: data.audio,\n        format: audioFormat,\n        contentType: getContentType(audioFormat, sampleRate),\n        ...(duration !== undefined && { duration }),\n        ...(originalDuration !== undefined && { originalDuration }),\n        ...(data.subtitle !== undefined && { subtitle: data.subtitle }),\n        ...(data.url !== undefined && { url: data.url }),\n      }\n    } catch (error) {\n      logger.errors('byteplus.generateSpeech fatal', {\n        error: toRunErrorPayload(error, 'byteplus.generateSpeech failed'),\n        source: 'byteplus.generateSpeech',\n      })\n      throw error\n    }\n  }\n}\n\n/**\n * Build the JSON body for `POST /api/v3/tts/create`, resolving the voice,\n * output format and rate fields in one place.\n *\n * Returns the request `body`, the resolved `audioFormat` and the\n * `sampleRate`, which the caller reports on the result and turns into a\n * `contentType`.\n */\nexport function buildTTSRequestBody(options: {\n  model: string\n  text: string\n  voice: string | undefined\n  format: TTSOptions['format'] | undefined\n  speed: number | undefined\n  modelOptions: BytePlusTTSProviderOptions | undefined\n  logger: InternalLogger\n}): {\n  body: BytePlusTTSCreateRequest\n  audioFormat: BytePlusTTSAudioFormat\n  sampleRate: number\n} {\n  const { model, text, voice, format, speed, modelOptions, logger } = options\n\n  const audioFormat = pickAudioFormat(modelOptions?.format, format, logger)\n  // Always explicit: the documented server default (40000) is not one of the\n  // rates the endpoint accepts, so relying on it is a coin flip.\n  const sampleRate = modelOptions?.sample_rate ?? DEFAULT_SAMPLE_RATE\n\n  const audioConfig: BytePlusTTSAudioConfig = {\n    format: audioFormat,\n    sample_rate: sampleRate,\n  }\n  if (modelOptions?.pitch_rate !== undefined) {\n    audioConfig.pitch_rate = modelOptions.pitch_rate\n  }\n  if (modelOptions?.loudness_rate !== undefined) {\n    audioConfig.loudness_rate = modelOptions.loudness_rate\n  }\n  if (modelOptions?.enable_subtitle !== undefined) {\n    audioConfig.enable_subtitle = modelOptions.enable_subtitle\n  }\n\n  // An explicit `speech_rate` always wins over the derived one — it is the\n  // native unit and the only way to reach the extremes precisely.\n  const speechRate =\n    modelOptions?.speech_rate ??\n    (speed !== undefined ? toSpeechRate(speed, logger) : undefined)\n  if (speechRate !== undefined) {\n    audioConfig.speech_rate = speechRate\n  }\n\n  const body: BytePlusTTSCreateRequest = {\n    model,\n    [TTS_TEXT_FIELD]: text,\n    // The voice belongs inside `references`, not at the top level — a\n    // top-level `speaker` is silently ignored by the server. The flat member\n    // shape here is the best-supported reading of the docs; see\n    // `BytePlusTTSReference` for the unresolved part and the live-probe flag.\n    references: modelOptions?.references ?? [\n      {\n        speaker: modelOptions?.speaker ?? voice ?? BYTEPLUS_DEFAULT_TTS_SPEAKER,\n      },\n    ],\n    audio_config: audioConfig,\n  }\n  if (modelOptions?.watermark !== undefined) {\n    body.watermark = modelOptions.watermark\n  }\n\n  return { body, audioFormat, sampleRate }\n}\n\n/**\n * Convert the cross-provider `TTSOptions.speed` multiplier into Seed Speech's\n * `speech_rate` percentage.\n *\n * ```\n * speech_rate = clamp(round((speed - 1) * 100), -50, 100)\n * ```\n *\n * so `0.5 → -50`, `1.0 → 0`, `1.5 → 50`, `2.0 → 100`.\n *\n * The range `-50`..`100` and both multiplier anchors (`-50` = 0.5×,\n * `100` = 2×) are documented, and hold on both the `/tts/create` and\n * `/tts/unidirectional` endpoints.\n *\n * `TTSOptions.speed` spans a wider 0.25×–4× than the endpoint supports, so\n * anything outside 0.5×–2× clamps (and warns) rather than erroring.\n */\nexport function toSpeechRate(speed: number, logger?: InternalLogger): number {\n  const rate = Math.round((speed - 1) * 100)\n  const clamped = Math.min(100, Math.max(-50, rate))\n  if (clamped !== rate) {\n    logger?.warn(\n      `Speed ${speed}× is outside the range BytePlus Seed Speech documents (0.5×–2×) — clamping speech_rate from ${rate} to ${clamped}.`,\n      { provider: 'byteplus', requestedSpeed: speed, speechRate: clamped },\n    )\n  }\n  return clamped\n}\n\n/**\n * Map the cross-provider `TTSOptions.format` onto a Seed Speech output\n * format. An explicit `modelOptions.format` always wins.\n *\n * Seed Speech produces `wav`, `mp3`, `pcm` and `ogg_opus`. The generic\n * `opus` maps onto `ogg_opus`; `aac` and `flac` have no equivalent and fall\n * back to `mp3` (matching how the other non-OpenAI TTS adapters in this repo\n * handle unsupported codecs). The fallback is logged so it isn't silent.\n */\nfunction pickAudioFormat(\n  override: BytePlusTTSAudioFormat | undefined,\n  format: TTSOptions['format'] | undefined,\n  logger: InternalLogger,\n): BytePlusTTSAudioFormat {\n  if (override) return override\n  if (!format) return 'mp3'\n  switch (format) {\n    case 'mp3':\n    case 'wav':\n    case 'pcm':\n      return format\n    case 'opus':\n      return 'ogg_opus'\n    case 'aac':\n    case 'flac':\n      logger.warn(\n        `BytePlus Seed Speech does not support ${format} output — falling back to mp3. Set modelOptions.format to choose between wav, mp3, pcm and ogg_opus.`,\n        { provider: 'byteplus', requestedFormat: format },\n      )\n      return 'mp3'\n  }\n}\n\n/**\n * Build a per-request id for the `X-Api-Request-Id` header. Falls back to the\n * package's own id generator on runtimes without `crypto.randomUUID`.\n */\nfunction newRequestId(): string {\n  return globalThis.crypto?.randomUUID?.() ?? generateId('byteplus-tts')\n}\n\n/**\n * MIME type for a Seed Speech output format.\n *\n * `pcm` is raw little-endian 16-bit samples, so its media type has to carry\n * the sample rate (RFC 3551/3555). The adapter always resolves a rate, so one\n * is always available here.\n */\nexport function getContentType(\n  format: BytePlusTTSAudioFormat,\n  sampleRate?: number,\n): string {\n  switch (format) {\n    case 'mp3':\n      return 'audio/mpeg'\n    case 'wav':\n      return 'audio/wav'\n    case 'ogg_opus':\n      return 'audio/ogg;codecs=opus'\n    case 'pcm':\n      return `audio/L16;rate=${sampleRate ?? 24000}`\n  }\n}\n\n/**\n * Coerce a `duration` / `original_duration` field to a usable number of\n * seconds.\n *\n * Both are documented as float **seconds**, so this only parses the string\n * form and drops values that can't be a length (zero, negative, non-numeric).\n * Note that `duration` may legitimately exceed\n * {@link BYTEPLUS_TTS_MAX_OUTPUT_SECONDS} — a clip synthesised at\n * `speech_rate: -50` runs at half speed, so up to 120 s of billed audio can\n * be delivered as up to 240 s of playback. Do not \"correct\" a large value\n * here; the cap applies to `original_duration`.\n *\n * The subtitle timings are the mixed-unit exception: those are milliseconds\n * and are passed through untouched on {@link BytePlusTTSResult.subtitle}.\n */\nexport function toDurationSeconds(\n  raw: number | string | undefined,\n): number | undefined {\n  const value = typeof raw === 'string' ? Number(raw) : raw\n  if (value === undefined || !Number.isFinite(value) || value <= 0) {\n    return undefined\n  }\n  return value\n}\n\n/**\n * Creates a BytePlus Seed Speech TTS adapter with an explicit API key.\n *\n * The key is the **Seed Speech** key, not the Ark key used by the chat, image\n * and video adapters.\n *\n * @example\n * ```ts\n * const adapter = createBytePlusSpeech('seed-audio-1.0', process.env.BYTEPLUS_VOICE_API_KEY!)\n * ```\n */\nexport function createBytePlusSpeech<\n  TModel extends BytePlusTTSModel = BytePlusTTSModel,\n>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<BytePlusVoiceConfig, 'apiKey'>,\n): BytePlusTTSAdapter<TModel> {\n  return new BytePlusTTSAdapter(model, { ...config, apiKey })\n}\n\n/**\n * Creates a BytePlus Seed Speech TTS adapter, reading the API key from\n * `BYTEPLUS_VOICE_API_KEY`.\n *\n * @throws Error if `BYTEPLUS_VOICE_API_KEY` is not set.\n */\nexport function byteplusSpeech<\n  TModel extends BytePlusTTSModel = BytePlusTTSModel,\n>(\n  model: TModel,\n  config?: Omit<BytePlusVoiceConfig, 'apiKey'>,\n): BytePlusTTSAdapter<TModel> {\n  return createBytePlusSpeech(model, getBytePlusVoiceApiKeyFromEnv(), config)\n}\n"],"mappings":"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"}
+{"version":3,"file":"tts.js","names":[],"sources":["../../../src/adapters/tts.ts"],"sourcesContent":["import { BaseTTSAdapter } from '@tanstack/ai/adapters'\nimport { generateId } from '@tanstack/ai-utils'\nimport { toRunErrorPayload } from '@tanstack/ai/adapter-internals'\nimport {\n  BYTEPLUS_VOICE_BASE_URL,\n  bytePlusVoiceError,\n  bytePlusVoiceHeaders,\n  getBytePlusVoiceApiKeyFromEnv,\n  readJsonBody,\n  withBytePlusVoiceDefaults,\n} from '../utils/client'\nimport type {\n  TTSAlignment,\n  TTSCapabilities,\n  TTSOptions,\n  TTSSegment,\n  TTSTurn,\n} from '@tanstack/ai'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\nimport type { BytePlusVoiceConfig } from '../utils/client'\nimport type { BytePlusTTSModel } from '../model-meta'\nimport type {\n  BytePlusTTSAudioConfig,\n  BytePlusTTSAudioFormat,\n  BytePlusTTSCreateRequest,\n  BytePlusTTSCreateResponse,\n  BytePlusTTSReference,\n  BytePlusTTSSubtitle,\n  BytePlusTTSSubtitleEntry,\n} from '../audio/wire-types'\nimport type {\n  BytePlusTTSProviderOptions,\n  BytePlusTTSResult,\n} from '../audio/tts-provider-options'\n\n/** Path of the synchronous Seed Speech synthesis endpoint. */\nconst TTS_CREATE_PATH = '/api/v3/tts/create'\n\n/**\n * Name of the request field carrying the text to speak.\n *\n * **`text_prompt` is correct — do not \"fix\" this to `text`.** The endpoint\n * schema (docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01) lists this\n * body as exactly `model`, `text_prompt`, `references`, `audio_config`,\n * `watermark`; there is no request-side `text`. The `text` spelling belongs\n * to the *other* endpoint, `/tts/unidirectional` (TTS 2.0), where it sits\n * under `req_params.text`. The name stays isolated here so the two spellings\n * never get conflated.\n */\nconst TTS_TEXT_FIELD = 'text_prompt' satisfies keyof BytePlusTTSCreateRequest\n\n/**\n * Sample rate used when the caller doesn't pick one. The endpoint documents a\n * default of 40000, which is not among the rates it accepts — so the adapter\n * never relies on the server default and always sends this instead.\n */\nconst DEFAULT_SAMPLE_RATE = 24000\n\n/**\n * True when a Seed Speech envelope's `code` means success.\n *\n * Seed Speech uses `0` for success and a flat numeric code otherwise\n * (`45000010 Invalid X-Api-Key`). The success envelope has not been confirmed\n * against a live key, so `code` is accepted as a number, its string form, or\n * absent — an envelope that omits `code` entirely is treated as success, which\n * is what the HTTP status already told us.\n */\nfunction isZeroCode(code: number | string | undefined): boolean {\n  if (code === undefined) return true\n  return Number(code) === 0\n}\n\n/**\n * Voice used when neither `TTSOptions.voice` nor `modelOptions.speaker` is\n * set — the English female \"Stokie\" voice from the TTS 2.0 generation.\n */\nexport const BYTEPLUS_DEFAULT_TTS_SPEAKER = 'en_female_stokie_uranus_bigtts'\n\n/**\n * Hard cap on a single Seed Speech synthesis, in seconds. Longer scripts must\n * be split across calls and stitched client-side.\n *\n * The cap applies to the *pre-rate* length the service bills on — the\n * `original_duration` it returns. The delivered clip can run longer than this\n * when `speech_rate` slows it down.\n */\nexport const BYTEPLUS_TTS_MAX_OUTPUT_SECONDS = 120\n\n/**\n * Hard cap on the `references` array, and therefore on the number of distinct\n * voices one dialogue request can use. The markers that cite them in\n * `text_prompt` run `@Audio1`..`@Audio3`.\n */\nexport const BYTEPLUS_TTS_MAX_REFERENCES = 3\n\n/**\n * BytePlus Seed Speech text-to-speech adapter.\n *\n * Talks to `POST {baseURL}/api/v3/tts/create` on the Seed Speech voice host.\n * Two things differ from the Ark-hosted adapters in this package:\n *\n * - **Separate API key.** Seed Speech authenticates with `X-Api-Key` and its\n *   own key (`BYTEPLUS_VOICE_API_KEY`). An `ARK_API_KEY` sent here is\n *   rejected with `45000010 Invalid X-Api-Key`.\n * - **120 s output cap.** A single call synthesises at most\n *   {@link BYTEPLUS_TTS_MAX_OUTPUT_SECONDS} seconds of audio; longer scripts\n *   have to be split and stitched client-side. The cap is measured before\n *   `speech_rate` is applied, so a slowed clip can play for longer than that\n *   — `result.duration` is the delivered length and `result.originalDuration`\n *   is the metered one.\n *\n * Streaming synthesis (`tts/unidirectional` and the WebSocket API) is not\n * covered by this adapter — note that endpoint spells the text field `text`,\n * while this one uses `text_prompt`.\n *\n * @example\n * ```ts\n * const adapter = byteplusSpeech('seed-audio-1.0')\n * const result = await generateSpeech({\n *   adapter,\n *   text: 'welcome to the guitar store',\n *   voice: 'en_female_stokie_uranus_bigtts',\n *   format: 'mp3',\n * })\n * ```\n */\nexport class BytePlusTTSAdapter<\n  TModel extends BytePlusTTSModel = BytePlusTTSModel,\n> extends BaseTTSAdapter<TModel, BytePlusTTSProviderOptions> {\n  readonly name = 'byteplus' as const\n\n  /**\n   * Seed Audio 1.0 does multi-role dialogue in one pass, addressed through\n   * `references` (capped at 3 entries), and returns word/sentence timings\n   * when `audio_config.enable_subtitle` is set.\n   */\n  override readonly capabilities: TTSCapabilities = {\n    maxSpeakers: BYTEPLUS_TTS_MAX_REFERENCES,\n    timestamps: true,\n  }\n\n  private readonly apiKey: string\n  private readonly baseURL: string\n  private readonly defaultHeaders: Record<string, string>\n  private readonly fetchImpl: typeof fetch\n\n  constructor(model: TModel, config: BytePlusVoiceConfig) {\n    super(model, config)\n    const resolved = withBytePlusVoiceDefaults(config)\n    this.apiKey = resolved.apiKey\n    this.baseURL = resolved.baseURL ?? BYTEPLUS_VOICE_BASE_URL\n    this.defaultHeaders = resolved.defaultHeaders ?? {}\n    this.fetchImpl = resolved.fetch ?? globalThis.fetch.bind(globalThis)\n  }\n\n  async generateSpeech(\n    options: TTSOptions<BytePlusTTSProviderOptions>,\n  ): Promise<BytePlusTTSResult> {\n    const { logger, model, text, voice, format, speed, modelOptions, turns } =\n      options\n\n    logger.request(`activity=generateSpeech provider=byteplus model=${model}`, {\n      provider: 'byteplus',\n      model,\n    })\n\n    const { body, audioFormat, sampleRate } = buildTTSRequestBody({\n      model,\n      text,\n      turns,\n      voice,\n      format,\n      speed,\n      modelOptions,\n      timestamps: options.timestamps,\n      logger,\n    })\n\n    try {\n      const response = await this.fetchImpl(\n        `${this.baseURL}${TTS_CREATE_PATH}`,\n        {\n          method: 'POST',\n          headers: bytePlusVoiceHeaders(this.apiKey, {\n            ...this.defaultHeaders,\n            // Client-generated per-request id. BytePlus echoes it in their\n            // request logs, which is what support asks for when diagnosing a\n            // synthesis failure.\n            'X-Api-Request-Id': newRequestId(),\n          }),\n          body: JSON.stringify(body),\n        },\n      )\n\n      const payload = await readJsonBody(response)\n\n      if (!response.ok) {\n        throw bytePlusVoiceError(response.status, payload, 'text-to-speech')\n      }\n\n      const data = payload as BytePlusTTSCreateResponse\n\n      // Seed Speech reports status in the body, not only in the HTTP status:\n      // a 200 can carry a non-zero `code`. Check it before looking at `audio`,\n      // because a failed call may still return a partial or placeholder\n      // payload that would otherwise be handed back as if it were valid.\n      //\n      // `code` is accepted as a number *or* a string. The success envelope was\n      // never confirmed against a live key (no voice key yet — see\n      // `audio/wire-types.ts`), and `readStringField` already tolerates both\n      // forms when rendering the error, so requiring a number here would let\n      // `{\"code\": \"45000010\"}` through both this gate and the one below.\n      if (!isZeroCode(data.code)) {\n        throw bytePlusVoiceError(response.status, payload, 'text-to-speech')\n      }\n\n      // Belt and braces for a 200 that reports success but carries nothing to\n      // play. Say that the adapter rejected it, rather than reusing the\n      // envelope-error phrasing — a bare \"failed (200)\" gives no hint that the\n      // response was well-formed and simply empty.\n      if (typeof data.audio !== 'string' || data.audio.length === 0) {\n        throw new Error(\n          `BytePlus Seed Speech text-to-speech returned a success response ` +\n            `with no audio (model ${model}).`,\n        )\n      }\n\n      const duration = toDurationSeconds(data.duration)\n      const originalDuration = toDurationSeconds(data.original_duration)\n\n      return {\n        id: generateId(this.name),\n        model,\n        audio: data.audio,\n        format: audioFormat,\n        contentType: getContentType(audioFormat, sampleRate),\n        ...(duration !== undefined && { duration }),\n        ...(originalDuration !== undefined && { originalDuration }),\n        ...(data.subtitle !== undefined && { subtitle: data.subtitle }),\n        ...toAlignmentFields(data.subtitle),\n        ...(data.url !== undefined && { url: data.url }),\n      }\n    } catch (error) {\n      logger.errors('byteplus.generateSpeech fatal', {\n        error: toRunErrorPayload(error, 'byteplus.generateSpeech failed'),\n        source: 'byteplus.generateSpeech',\n      })\n      throw error\n    }\n  }\n}\n\n/**\n * Build the JSON body for `POST /api/v3/tts/create`, resolving the voice,\n * output format and rate fields in one place.\n *\n * Returns the request `body`, the resolved `audioFormat` and the\n * `sampleRate`, which the caller reports on the result and turns into a\n * `contentType`.\n */\nexport function buildTTSRequestBody(options: {\n  model: string\n  text: string\n  /** Dialogue turns, when the caller asked for multi-role synthesis. */\n  turns?: Array<TTSTurn>\n  voice: string | undefined\n  format: TTSOptions['format'] | undefined\n  speed: number | undefined\n  modelOptions: BytePlusTTSProviderOptions | undefined\n  /** Core `timestamps: true` — turns on `audio_config.enable_subtitle`. */\n  timestamps?: boolean\n  logger: InternalLogger\n}): {\n  body: BytePlusTTSCreateRequest\n  audioFormat: BytePlusTTSAudioFormat\n  sampleRate: number\n} {\n  const { model, text, turns, voice, format, speed, modelOptions, logger } =\n    options\n\n  const audioFormat = pickAudioFormat(modelOptions?.format, format, logger)\n  // Always explicit: the documented server default (40000) is not one of the\n  // rates the endpoint accepts, so relying on it is a coin flip.\n  const sampleRate = modelOptions?.sample_rate ?? DEFAULT_SAMPLE_RATE\n\n  const audioConfig: BytePlusTTSAudioConfig = {\n    format: audioFormat,\n    sample_rate: sampleRate,\n  }\n  if (modelOptions?.pitch_rate !== undefined) {\n    audioConfig.pitch_rate = modelOptions.pitch_rate\n  }\n  if (modelOptions?.loudness_rate !== undefined) {\n    audioConfig.loudness_rate = modelOptions.loudness_rate\n  }\n  // `modelOptions.enable_subtitle` still wins, so an explicit `false` can\n  // opt out of the flag even when core asked for timestamps. A `timestamps`\n  // the caller never set stays off the body entirely.\n  const enableSubtitle =\n    modelOptions?.enable_subtitle ?? (options.timestamps || undefined)\n  if (enableSubtitle !== undefined) {\n    audioConfig.enable_subtitle = enableSubtitle\n  }\n\n  // An explicit `speech_rate` always wins over the derived one — it is the\n  // native unit and the only way to reach the extremes precisely.\n  const speechRate =\n    modelOptions?.speech_rate ??\n    (speed !== undefined ? toSpeechRate(speed, logger) : undefined)\n  if (speechRate !== undefined) {\n    audioConfig.speech_rate = speechRate\n  }\n\n  const dialogue = turns ? buildDialoguePrompt(turns) : undefined\n\n  const body: BytePlusTTSCreateRequest = {\n    model,\n    [TTS_TEXT_FIELD]: dialogue?.textPrompt ?? text,\n    // The voice belongs inside `references`, not at the top level — a\n    // top-level `speaker` is silently ignored by the server.\n    references: modelOptions?.references ??\n      dialogue?.references ?? [\n        {\n          speaker:\n            modelOptions?.speaker ?? voice ?? BYTEPLUS_DEFAULT_TTS_SPEAKER,\n        },\n      ],\n    audio_config: audioConfig,\n  }\n  if (modelOptions?.watermark !== undefined) {\n    // The endpoint wants an object. `true` means the audible marker, which is\n    // what a caller passing a boolean is asking for.\n    body.watermark =\n      typeof modelOptions.watermark === 'boolean'\n        ? { aigc_watermark: modelOptions.watermark }\n        : modelOptions.watermark\n  }\n\n  return { body, audioFormat, sampleRate }\n}\n\n/**\n * Convert the cross-provider `TTSOptions.speed` multiplier into Seed Speech's\n * `speech_rate` percentage.\n *\n * ```\n * speech_rate = clamp(round((speed - 1) * 100), -50, 100)\n * ```\n *\n * so `0.5 → -50`, `1.0 → 0`, `1.5 → 50`, `2.0 → 100`.\n *\n * The range `-50`..`100` and both multiplier anchors (`-50` = 0.5×,\n * `100` = 2×) are documented, and hold on both the `/tts/create` and\n * `/tts/unidirectional` endpoints.\n *\n * `TTSOptions.speed` spans a wider 0.25×–4× than the endpoint supports, so\n * anything outside 0.5×–2× clamps (and warns) rather than erroring.\n */\nexport function toSpeechRate(speed: number, logger?: InternalLogger): number {\n  const rate = Math.round((speed - 1) * 100)\n  const clamped = Math.min(100, Math.max(-50, rate))\n  if (clamped !== rate) {\n    logger?.warn(\n      `Speed ${speed}× is outside the range BytePlus Seed Speech documents (0.5×–2×) — clamping speech_rate from ${rate} to ${clamped}.`,\n      { provider: 'byteplus', requestedSpeed: speed, speechRate: clamped },\n    )\n  }\n  return clamped\n}\n\n/**\n * Map the cross-provider `TTSOptions.format` onto a Seed Speech output\n * format. An explicit `modelOptions.format` always wins.\n *\n * Seed Speech produces `wav`, `mp3`, `pcm` and `ogg_opus`. The generic\n * `opus` maps onto `ogg_opus`; `aac` and `flac` have no equivalent and fall\n * back to `mp3` (matching how the other non-OpenAI TTS adapters in this repo\n * handle unsupported codecs). The fallback is logged so it isn't silent.\n */\nfunction pickAudioFormat(\n  override: BytePlusTTSAudioFormat | undefined,\n  format: TTSOptions['format'] | undefined,\n  logger: InternalLogger,\n): BytePlusTTSAudioFormat {\n  if (override) return override\n  if (!format) return 'mp3'\n  switch (format) {\n    case 'mp3':\n    case 'wav':\n    case 'pcm':\n      return format\n    case 'opus':\n      return 'ogg_opus'\n    case 'aac':\n    case 'flac':\n      logger.warn(\n        `BytePlus Seed Speech does not support ${format} output — falling back to mp3. Set modelOptions.format to choose between wav, mp3, pcm and ogg_opus.`,\n        { provider: 'byteplus', requestedFormat: format },\n      )\n      return 'mp3'\n  }\n}\n\n/**\n * Build a per-request id for the `X-Api-Request-Id` header. Falls back to the\n * package's own id generator on runtimes without `crypto.randomUUID`.\n */\nfunction newRequestId(): string {\n  return globalThis.crypto?.randomUUID?.() ?? generateId('byteplus-tts')\n}\n\n/**\n * MIME type for a Seed Speech output format.\n *\n * `pcm` is raw little-endian 16-bit samples, so its media type has to carry\n * the sample rate (RFC 3551/3555). The adapter always resolves a rate, so one\n * is always available here.\n */\nexport function getContentType(\n  format: BytePlusTTSAudioFormat,\n  sampleRate?: number,\n): string {\n  switch (format) {\n    case 'mp3':\n      return 'audio/mpeg'\n    case 'wav':\n      return 'audio/wav'\n    case 'ogg_opus':\n      return 'audio/ogg;codecs=opus'\n    case 'pcm':\n      return `audio/L16;rate=${sampleRate ?? 24000}`\n  }\n}\n\n/**\n * Turn dialogue turns into the one-prompt form Seed Audio 1.0 takes: each\n * distinct voice becomes a `references` entry, and every line of the script\n * cites its voice by the reference's 1-based position (`@Audio1`..`@Audio3`),\n * which is the marker convention the reference array already uses.\n *\n * **The prompt form is unprobed.** The flat `references[]` member shape is\n * confirmed (see `BytePlusTTSReference`), and the model card documents\n * multi-role dialogue and positional reference markers, but no worked\n * multi-speaker example was available and no Seed Speech key existed to\n * confirm how lines should cite their voice.\n */\nfunction buildDialoguePrompt(turns: Array<TTSTurn>): {\n  textPrompt: string\n  references: Array<BytePlusTTSReference>\n} {\n  const voices = [...new Set(turns.map((turn) => turn.voice))]\n  return {\n    textPrompt: turns\n      .map((turn) => `@Audio${voices.indexOf(turn.voice) + 1}: ${turn.text}`)\n      .join('\\n'),\n    references: voices.map((speaker) => ({ speaker })),\n  }\n}\n\n/**\n * Map the BytePlus `subtitle` block onto the cross-provider `alignment` /\n * `segments` fields.\n *\n * `words` is the finest granularity Seed Speech reports, so it becomes\n * `alignment`; `sentences` is utterance segmentation, so it becomes\n * `segments`. **Subtitle times are milliseconds** while the rest of the\n * response is seconds — the conversion happens here, once.\n *\n * The raw block stays on {@link BytePlusTTSResult.subtitle} for callers\n * already reading it.\n */\nfunction toAlignmentFields(subtitle: BytePlusTTSSubtitle | undefined): {\n  alignment?: TTSAlignment\n  segments?: Array<TTSSegment>\n} {\n  if (!subtitle) return {}\n  const fields: { alignment?: TTSAlignment; segments?: Array<TTSSegment> } = {}\n  const words = subtitle.words?.filter(isTimedEntry)\n  if (words && words.length > 0) {\n    fields.alignment = {\n      unit: 'word',\n      texts: words.map((word) => word.text ?? ''),\n      startSeconds: words.map((word) => word.start_time / 1000),\n      endSeconds: words.map((word) => word.end_time / 1000),\n    }\n  }\n  const sentences = subtitle.sentences?.filter(isTimedEntry)\n  if (sentences && sentences.length > 0) {\n    fields.segments = sentences.map((sentence) => ({\n      startSeconds: sentence.start_time / 1000,\n      endSeconds: sentence.end_time / 1000,\n      ...(sentence.text !== undefined && { text: sentence.text }),\n    }))\n  }\n  return fields\n}\n\n/** Both times present, so the entry can be placed on the timeline. */\nfunction isTimedEntry(\n  entry: BytePlusTTSSubtitleEntry,\n): entry is BytePlusTTSSubtitleEntry & {\n  start_time: number\n  end_time: number\n} {\n  return (\n    typeof entry.start_time === 'number' && typeof entry.end_time === 'number'\n  )\n}\n\n/**\n * Coerce a `duration` / `original_duration` field to a usable number of\n * seconds.\n *\n * Both are documented as float **seconds**, so this only parses the string\n * form and drops values that can't be a length (zero, negative, non-numeric).\n * Note that `duration` may legitimately exceed\n * {@link BYTEPLUS_TTS_MAX_OUTPUT_SECONDS} — a clip synthesised at\n * `speech_rate: -50` runs at half speed, so up to 120 s of billed audio can\n * be delivered as up to 240 s of playback. Do not \"correct\" a large value\n * here; the cap applies to `original_duration`.\n *\n * The subtitle timings are the mixed-unit exception: those are milliseconds\n * and are passed through untouched on {@link BytePlusTTSResult.subtitle}.\n */\nexport function toDurationSeconds(\n  raw: number | string | undefined,\n): number | undefined {\n  const value = typeof raw === 'string' ? Number(raw) : raw\n  if (value === undefined || !Number.isFinite(value) || value <= 0) {\n    return undefined\n  }\n  return value\n}\n\n/**\n * Creates a BytePlus Seed Speech TTS adapter with an explicit API key.\n *\n * The key is the **Seed Speech** key, not the Ark key used by the chat, image\n * and video adapters.\n *\n * @example\n * ```ts\n * const adapter = createBytePlusSpeech('seed-audio-1.0', process.env.BYTEPLUS_VOICE_API_KEY!)\n * ```\n */\nexport function createBytePlusSpeech<\n  TModel extends BytePlusTTSModel = BytePlusTTSModel,\n>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<BytePlusVoiceConfig, 'apiKey'>,\n): BytePlusTTSAdapter<TModel> {\n  return new BytePlusTTSAdapter(model, { ...config, apiKey })\n}\n\n/**\n * Creates a BytePlus Seed Speech TTS adapter, reading the API key from\n * `BYTEPLUS_VOICE_API_KEY`.\n *\n * @throws Error if `BYTEPLUS_VOICE_API_KEY` is not set.\n */\nexport function byteplusSpeech<\n  TModel extends BytePlusTTSModel = BytePlusTTSModel,\n>(\n  model: TModel,\n  config?: Omit<BytePlusVoiceConfig, 'apiKey'>,\n): BytePlusTTSAdapter<TModel> {\n  return createBytePlusSpeech(model, getBytePlusVoiceApiKeyFromEnv(), config)\n}\n"],"mappings":"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"}

package/dist/esm/audio/tts-provider-options.d.ts

@@ -1,4 +1,4 @@
-import { BytePlusTTSAudioFormat, BytePlusTTSReference, BytePlusTTSSampleRate, BytePlusTTSSubtitle } from './wire-types.js';
+import { BytePlusTTSAudioFormat, BytePlusTTSReference, BytePlusTTSSampleRate, BytePlusTTSSubtitle, BytePlusTTSWatermark } from './wire-types.js';
 import { TTSResult } from '@tanstack/ai';
 /**
  * Seed Speech voice identifier (`speaker` on the wire).
@@ -72,10 +72,13 @@ export interface BytePlusTTSProviderOptions {
      */
     enable_subtitle?: boolean;
     /**
-     * Watermark the generated audio. The field name is confirmed against the
-     * endpoint schema; the boolean type is assumed and unprobed.
+     * Watermark the generated audio.
+     *
+     * Seed Audio takes an object with two independent markers — an audible
+     * `aigc_watermark` appended to the clip and an `aigc_metadata` block written
+     * into the audio header. `true` is shorthand for `{ aigc_watermark: true }`.
      */
-    watermark?: boolean;
+    watermark?: boolean | BytePlusTTSWatermark;
 }
 /**
  * BytePlus-specific extension of `TTSResult`.

package/dist/esm/audio/wire-types.d.ts

@@ -46,15 +46,16 @@ export type BytePlusTTSSampleRate = (typeof BYTEPLUS_TTS_SAMPLE_RATES)[number];
  * audio references (30 s / 10 MB each) and 1 image reference (10 MB), and
  * image references are mutually exclusive with audio ones.
  *
- * **Member object shape is unresolved — must live-probe when the Seed Speech
- * key lands.** The docs list the member fields flat (`speaker | audio_data |
- * audio_url | image_data | image_url`) without a worked example, so whether
- * the server wants a flat `{ speaker }` or a discriminated `{ type, ... }`
- * could not be settled. The adapter sends the flat reading — see
- * `buildTTSRequestBody` in `../adapters/tts`.
+ * The member fields are flat (`speaker | audio_data | audio_url | image_data |
+ * image_url`), confirmed against
+ * docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01.
  */
 export interface BytePlusTTSReference {
-    /** Stock voice id, e.g. `en_female_stokie_uranus_bigtts`. */
+    /**
+     * Voice id, e.g. `en_female_stokie_uranus_bigtts`. Either a stock TTS 2.0
+     * voice or the id of a voice you cloned through Voice Replication — this
+     * field is the join between replication and synthesis.
+     */
     speaker?: string;
     /** URL of a reference clip to clone (≤30 s, ≤10 MB). */
     audio_url?: string;
@@ -88,6 +89,36 @@ export interface BytePlusTTSAudioConfig {
     /** Emit sentence and word timings in the response. Defaults to `false`. */
     enable_subtitle?: boolean;
 }
+/**
+ * `watermark` block of a TTS request.
+ *
+ * Two independent markers, both off by default:
+ *
+ * - `aigc_watermark` — **explicit**: appends an audible rhythm marker to the
+ *   end of the clip.
+ * - `aigc_metadata` — **implicit**: writes provenance metadata into the audio
+ *   header. Nothing is written unless `enable` is `true`.
+ *
+ * This is an object, not a boolean — unlike Seedream images and Seedance
+ * video, where `watermark` genuinely is a boolean.
+ */
+export interface BytePlusTTSWatermark {
+    /** Append an audible rhythm marker to the end of the audio. Default `false`. */
+    aigc_watermark?: boolean;
+    /** Provenance metadata written into the audio header. */
+    aigc_metadata?: {
+        /** Write the metadata. Default `false` — the rest is ignored without it. */
+        enable?: boolean;
+        /** Name or code of the synthesis provider. */
+        content_producer?: string;
+        /** Content production id. */
+        produce_id?: string;
+        /** Name or code of the distribution provider. */
+        content_propagator?: string;
+        /** Content distribution id. */
+        propagate_id?: string;
+    };
+}
 /** Request body for `POST /api/v3/tts/create` — exactly five fields. */
 export interface BytePlusTTSCreateRequest {
     /** Seed Speech synthesis model, e.g. `seed-audio-1.0`. */
@@ -109,11 +140,8 @@ export interface BytePlusTTSCreateRequest {
     /** Voice selection and cloning references. See {@link BytePlusTTSReference}. */
     references?: Array<BytePlusTTSReference>;
     audio_config?: BytePlusTTSAudioConfig;
-    /**
-     * Watermark the generated audio. The field name is confirmed; the boolean
-     * type is assumed by analogy with Seedream's `watermark` and unprobed.
-     */
-    watermark?: boolean;
+    /** Watermark the generated audio. See {@link BytePlusTTSWatermark}. */
+    watermark?: BytePlusTTSWatermark;
 }
 /**
  * One timed entry of a TTS subtitle track.

package/dist/esm/audio/wire-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"wire-types.js","names":[],"sources":["../../../src/audio/wire-types.ts"],"sourcesContent":["/**\n * Minimal wire types for the BytePlus **Seed Speech** HTTP API (TTS + ASR).\n *\n * Seed Speech is a separate product from Ark: it lives on\n * `voice.ap-southeast-1.bytepluses.com`, authenticates with `X-Api-Key`\n * (a different key from `ARK_API_KEY`), and returns a flat numeric error\n * envelope instead of Ark's OpenAI-shaped one.\n *\n * Only the fields the adapters read or write are modelled here — this is a\n * hand-written subset, not a generated schema.\n *\n * Provenance:\n * - Endpoints, auth header, format/rate ranges and the 120 s TTS output cap:\n *   BytePlus Seed Speech docs (`docs.byteplus.com/en/docs/byteplusvoice`),\n *   captured in the Phase 0 research notes.\n * - Error envelope `{code, message}`: verified live — an Ark key sent as\n *   `X-Api-Key` returns HTTP 401 `{\"code\":45000010,\"message\":\"Invalid X-Api-Key\"}`.\n * - ASR request/response shape (`user`/`audio`/`request` in, `audio_info` +\n *   `result.utterances` out, all timings in **milliseconds**): the Volcengine\n *   flash-recognition reference the BytePlus endpoint is derived from\n *   (`docs.volcengine.com/docs/6561/1631584`).\n *\n * No Seed Speech API key was available when these were written, so the TTS\n * response fields are documented-but-unverified; the adapters parse them\n * defensively rather than assuming they are always present.\n */\n\n// ============================================================================\n// TTS — POST /api/v3/tts/create\n// ============================================================================\n\n/** Output container/codec accepted by `audio_config.format`. */\nexport type BytePlusTTSAudioFormat = 'wav' | 'mp3' | 'pcm' | 'ogg_opus'\n\n/**\n * Sample rates `audio_config.sample_rate` accepts.\n *\n * The docs also state a *default* of 40000, which is not one of the valid\n * values — a documentation bug. The adapter therefore always sends an\n * explicit rate rather than relying on the server default.\n */\nexport const BYTEPLUS_TTS_SAMPLE_RATES = [\n  8000, 16000, 24000, 32000, 44100, 48000,\n] as const\n\n/** A sample rate `audio_config.sample_rate` accepts. */\nexport type BytePlusTTSSampleRate = (typeof BYTEPLUS_TTS_SAMPLE_RATES)[number]\n\n/**\n * One entry of the request's `references` array.\n *\n * This is where the voice lives: `speaker` names a stock voice, while\n * `audio_url` / `audio_data` supply reference clips to clone (the `@Audio1`..\n * `@Audio3` markers in `text_prompt` address them positionally). Exactly one\n * of `speaker`, `audio_url` or `audio_data` may be set per entry; at most 3\n * audio references (30 s / 10 MB each) and 1 image reference (10 MB), and\n * image references are mutually exclusive with audio ones.\n *\n * **Member object shape is unresolved — must live-probe when the Seed Speech\n * key lands.** The docs list the member fields flat (`speaker | audio_data |\n * audio_url | image_data | image_url`) without a worked example, so whether\n * the server wants a flat `{ speaker }` or a discriminated `{ type, ... }`\n * could not be settled. The adapter sends the flat reading — see\n * `buildTTSRequestBody` in `../adapters/tts`.\n */\nexport interface BytePlusTTSReference {\n  /** Stock voice id, e.g. `en_female_stokie_uranus_bigtts`. */\n  speaker?: string\n  /** URL of a reference clip to clone (≤30 s, ≤10 MB). */\n  audio_url?: string\n  /** Base64 reference clip to clone (≤30 s, ≤10 MB). */\n  audio_data?: string\n  /** URL of a reference image (≤10 MB). Mutually exclusive with audio refs. */\n  image_url?: string\n  /** Base64 reference image (≤10 MB). Mutually exclusive with audio refs. */\n  image_data?: string\n}\n\n/**\n * `audio_config` block of a TTS request — exactly six fields.\n *\n * The three `*_rate` fields are integer percentages relative to the voice's\n * neutral delivery, not multipliers.\n */\nexport interface BytePlusTTSAudioConfig {\n  /** Output format. Defaults to `wav` server-side. */\n  format?: BytePlusTTSAudioFormat\n  /**\n   * Output sample rate in Hz. See {@link BYTEPLUS_TTS_SAMPLE_RATES} for the\n   * valid values and for why the adapter always sends one.\n   */\n  sample_rate?: number\n  /** Speaking rate, `-50`..`100`. `-50` = 0.5×, `0` = 1×, `100` = 2×. */\n  speech_rate?: number\n  /** Loudness adjustment, `-50`..`100`. `0` is the voice's natural level. */\n  loudness_rate?: number\n  /** Pitch adjustment, `-12`..`12`. `0` is the voice's natural pitch. */\n  pitch_rate?: number\n  /** Emit sentence and word timings in the response. Defaults to `false`. */\n  enable_subtitle?: boolean\n}\n\n/** Request body for `POST /api/v3/tts/create` — exactly five fields. */\nexport interface BytePlusTTSCreateRequest {\n  /** Seed Speech synthesis model, e.g. `seed-audio-1.0`. */\n  model: string\n  /**\n   * The text to speak (≤3000 chars). Dual-purpose: either literal text or a\n   * natural-language description of the delivery, and the place the\n   * `@Audio1`..`@Audio3` reference markers go.\n   *\n   * **`text_prompt` is correct — do not \"fix\" this to `text`.** This endpoint\n   * has no request-side `text` field. The `text` spelling belongs to the\n   * *other* endpoint, `/tts/unidirectional` (TTS 2.0), where it sits under\n   * `req_params.text`. Confirmed against\n   * docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01, which lists this\n   * body as exactly `model`, `text_prompt`, `references`, `audio_config`,\n   * `watermark`.\n   */\n  text_prompt: string\n  /** Voice selection and cloning references. See {@link BytePlusTTSReference}. */\n  references?: Array<BytePlusTTSReference>\n  audio_config?: BytePlusTTSAudioConfig\n  /**\n   * Watermark the generated audio. The field name is confirmed; the boolean\n   * type is assumed by analogy with Seedream's `watermark` and unprobed.\n   */\n  watermark?: boolean\n}\n\n/**\n * One timed entry of a TTS subtitle track.\n *\n * **Times are milliseconds** — unlike the response's `duration` fields, which\n * are seconds. The endpoint genuinely mixes units.\n */\nexport interface BytePlusTTSSubtitleEntry {\n  text?: string\n  start_time?: number\n  end_time?: number\n}\n\n/** Sentence- and word-level timings returned when `enable_subtitle` is set. */\nexport interface BytePlusTTSSubtitle {\n  sentences?: Array<BytePlusTTSSubtitleEntry>\n  words?: Array<BytePlusTTSSubtitleEntry>\n}\n\n/** Response body for `POST /api/v3/tts/create`. */\nexport interface BytePlusTTSCreateResponse {\n  /**\n   * Status code — `0` on success, a flat error code otherwise.\n   *\n   * Typed as `number | string` because only the *error* envelope was verified\n   * live (HTTP 401 `{\"code\":45000010,…}`); the success envelope's shape is\n   * docs-derived and no voice key was available to confirm it. Treating a\n   * string code as \"not a failure\" would return a failed 200 as success, so\n   * the adapter coerces before comparing — see `isZeroCode` in\n   * `adapters/tts.ts`.\n   */\n  code?: number | string\n  message?: string\n  /** Base64-encoded audio in the requested `audio_config.format`. */\n  audio?: string\n  /**\n   * Length of the delivered audio in **seconds** (float), after `speech_rate`\n   * is applied. This can legitimately exceed 120 when the clip is slowed\n   * down — the 120 s cap applies to {@link BytePlusTTSCreateResponse.original_duration}.\n   */\n  duration?: number | string\n  /**\n   * Length in **seconds** (float) before rate adjustment. This is the billing\n   * basis and is capped at 120.\n   */\n  original_duration?: number | string\n  /** Temporary download URL for the same audio. Expires after ~2 hours. */\n  url?: string\n  /** Sentence and word timings, present when `enable_subtitle` was set. */\n  subtitle?: BytePlusTTSSubtitle\n}\n\n// ============================================================================\n// ASR — POST /api/v3/auc/bigmodel/recognize/flash\n// ============================================================================\n\n/**\n * Value of the `X-Api-Resource-Id` header that selects the Seed ASR turbo\n * model. The flash endpoint takes no `model` field in its body — the model is\n * chosen entirely by this header.\n */\nexport const BYTEPLUS_ASR_RESOURCE_ID = 'volc.seedasr.auc_turbo'\n\n/** Header name carrying {@link BYTEPLUS_ASR_RESOURCE_ID}. */\nexport const BYTEPLUS_ASR_RESOURCE_HEADER = 'X-Api-Resource-Id'\n\n/**\n * Audio input. Exactly one of `url` or `data` is sent — the endpoint accepts\n * files up to 2 hours long / 100 MB.\n */\nexport interface BytePlusASRAudio {\n  /** Publicly reachable URL of the audio file. */\n  url?: string\n  /** Base64-encoded audio bytes. */\n  data?: string\n  /** Container hint, e.g. `mp3`, `wav`, `ogg`. */\n  format?: string\n}\n\n/** `request` block of a recognition call. */\nexport interface BytePlusASRRequestOptions {\n  /** Recognition model family. Defaults to `bigmodel`. */\n  model_name?: string\n  /** Inverse text normalisation (spoken numbers → digits). */\n  enable_itn?: boolean\n  /** Insert punctuation. */\n  enable_punc?: boolean\n  /** Disfluency removal (\"um\", repeated words). */\n  enable_ddc?: boolean\n  /** Attach per-utterance speaker labels. */\n  enable_speaker_info?: boolean\n  /** Return the `utterances` breakdown as well as the flat transcript. */\n  show_utterances?: boolean\n  /** Spoken language hint, e.g. `en-US`. */\n  language?: string\n}\n\n/** Request body for `POST /api/v3/auc/bigmodel/recognize/flash`. */\nexport interface BytePlusASRRecognizeRequest {\n  user?: { uid?: string }\n  audio: BytePlusASRAudio\n  request?: BytePlusASRRequestOptions\n}\n\n/** One recognised word. `start_time` / `end_time` are milliseconds. */\nexport interface BytePlusASRWord {\n  text?: string\n  start_time?: number\n  end_time?: number\n  confidence?: number\n}\n\n/** One recognised utterance. `start_time` / `end_time` are milliseconds. */\nexport interface BytePlusASRUtterance {\n  text?: string\n  start_time?: number\n  end_time?: number\n  words?: Array<BytePlusASRWord>\n  /**\n   * Extra per-utterance annotations. Speaker labels arrive here when\n   * `enable_speaker_info` is set; the exact key is read defensively because it\n   * could not be confirmed against a live response.\n   */\n  additions?: Record<string, string>\n}\n\nexport interface BytePlusASRResult {\n  text?: string\n  utterances?: Array<BytePlusASRUtterance>\n}\n\n/**\n * Response body for `POST /api/v3/auc/bigmodel/recognize/flash`.\n *\n * The Volcengine-lineage wire shape nests everything under `result`; BytePlus'\n * prose docs describe the same payload as \"transcript + utterances\", so the\n * flat spelling is tolerated as a fallback.\n */\nexport interface BytePlusASRRecognizeResponse {\n  /** `duration` is the audio length in **milliseconds**. */\n  audio_info?: { duration?: number }\n  result?: BytePlusASRResult\n  /** Flat alias for `result.text`. */\n  transcript?: string\n  /** Flat alias for `result.utterances`. */\n  utterances?: Array<BytePlusASRUtterance>\n}\n\n// ============================================================================\n// Errors\n// ============================================================================\n\n/**\n * Seed Speech error envelope: a flat numeric `code` plus a `message`, e.g.\n * `{\"code\": 45000010, \"message\": \"Invalid X-Api-Key\"}` (verified live on a\n * 401). Format it with `bytePlusVoiceError` from `../utils/client`.\n */\nexport interface BytePlusVoiceErrorBody {\n  code?: number\n  message?: string\n}\n"],"mappings":";;;;;;;;AAyCA,IAAa,4BAA4B;CACvC;CAAM;CAAO;CAAO;CAAO;CAAO;AACpC;;;;;;AAmJA,IAAa,2BAA2B;;AAGxC,IAAa,+BAA+B"}
+{"version":3,"file":"wire-types.js","names":[],"sources":["../../../src/audio/wire-types.ts"],"sourcesContent":["/**\n * Minimal wire types for the BytePlus **Seed Speech** HTTP API (TTS + ASR).\n *\n * Seed Speech is a separate product from Ark: it lives on\n * `voice.ap-southeast-1.bytepluses.com`, authenticates with `X-Api-Key`\n * (a different key from `ARK_API_KEY`), and returns a flat numeric error\n * envelope instead of Ark's OpenAI-shaped one.\n *\n * Only the fields the adapters read or write are modelled here — this is a\n * hand-written subset, not a generated schema.\n *\n * Provenance:\n * - Endpoints, auth header, format/rate ranges and the 120 s TTS output cap:\n *   BytePlus Seed Speech docs (`docs.byteplus.com/en/docs/byteplusvoice`),\n *   captured in the Phase 0 research notes.\n * - Error envelope `{code, message}`: verified live — an Ark key sent as\n *   `X-Api-Key` returns HTTP 401 `{\"code\":45000010,\"message\":\"Invalid X-Api-Key\"}`.\n * - ASR request/response shape (`user`/`audio`/`request` in, `audio_info` +\n *   `result.utterances` out, all timings in **milliseconds**): the Volcengine\n *   flash-recognition reference the BytePlus endpoint is derived from\n *   (`docs.volcengine.com/docs/6561/1631584`).\n *\n * No Seed Speech API key was available when these were written, so the TTS\n * response fields are documented-but-unverified; the adapters parse them\n * defensively rather than assuming they are always present.\n */\n\n// ============================================================================\n// TTS — POST /api/v3/tts/create\n// ============================================================================\n\n/** Output container/codec accepted by `audio_config.format`. */\nexport type BytePlusTTSAudioFormat = 'wav' | 'mp3' | 'pcm' | 'ogg_opus'\n\n/**\n * Sample rates `audio_config.sample_rate` accepts.\n *\n * The docs also state a *default* of 40000, which is not one of the valid\n * values — a documentation bug. The adapter therefore always sends an\n * explicit rate rather than relying on the server default.\n */\nexport const BYTEPLUS_TTS_SAMPLE_RATES = [\n  8000, 16000, 24000, 32000, 44100, 48000,\n] as const\n\n/** A sample rate `audio_config.sample_rate` accepts. */\nexport type BytePlusTTSSampleRate = (typeof BYTEPLUS_TTS_SAMPLE_RATES)[number]\n\n/**\n * One entry of the request's `references` array.\n *\n * This is where the voice lives: `speaker` names a stock voice, while\n * `audio_url` / `audio_data` supply reference clips to clone (the `@Audio1`..\n * `@Audio3` markers in `text_prompt` address them positionally). Exactly one\n * of `speaker`, `audio_url` or `audio_data` may be set per entry; at most 3\n * audio references (30 s / 10 MB each) and 1 image reference (10 MB), and\n * image references are mutually exclusive with audio ones.\n *\n * The member fields are flat (`speaker | audio_data | audio_url | image_data |\n * image_url`), confirmed against\n * docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01.\n */\nexport interface BytePlusTTSReference {\n  /**\n   * Voice id, e.g. `en_female_stokie_uranus_bigtts`. Either a stock TTS 2.0\n   * voice or the id of a voice you cloned through Voice Replication — this\n   * field is the join between replication and synthesis.\n   */\n  speaker?: string\n  /** URL of a reference clip to clone (≤30 s, ≤10 MB). */\n  audio_url?: string\n  /** Base64 reference clip to clone (≤30 s, ≤10 MB). */\n  audio_data?: string\n  /** URL of a reference image (≤10 MB). Mutually exclusive with audio refs. */\n  image_url?: string\n  /** Base64 reference image (≤10 MB). Mutually exclusive with audio refs. */\n  image_data?: string\n}\n\n/**\n * `audio_config` block of a TTS request — exactly six fields.\n *\n * The three `*_rate` fields are integer percentages relative to the voice's\n * neutral delivery, not multipliers.\n */\nexport interface BytePlusTTSAudioConfig {\n  /** Output format. Defaults to `wav` server-side. */\n  format?: BytePlusTTSAudioFormat\n  /**\n   * Output sample rate in Hz. See {@link BYTEPLUS_TTS_SAMPLE_RATES} for the\n   * valid values and for why the adapter always sends one.\n   */\n  sample_rate?: number\n  /** Speaking rate, `-50`..`100`. `-50` = 0.5×, `0` = 1×, `100` = 2×. */\n  speech_rate?: number\n  /** Loudness adjustment, `-50`..`100`. `0` is the voice's natural level. */\n  loudness_rate?: number\n  /** Pitch adjustment, `-12`..`12`. `0` is the voice's natural pitch. */\n  pitch_rate?: number\n  /** Emit sentence and word timings in the response. Defaults to `false`. */\n  enable_subtitle?: boolean\n}\n\n/**\n * `watermark` block of a TTS request.\n *\n * Two independent markers, both off by default:\n *\n * - `aigc_watermark` — **explicit**: appends an audible rhythm marker to the\n *   end of the clip.\n * - `aigc_metadata` — **implicit**: writes provenance metadata into the audio\n *   header. Nothing is written unless `enable` is `true`.\n *\n * This is an object, not a boolean — unlike Seedream images and Seedance\n * video, where `watermark` genuinely is a boolean.\n */\nexport interface BytePlusTTSWatermark {\n  /** Append an audible rhythm marker to the end of the audio. Default `false`. */\n  aigc_watermark?: boolean\n  /** Provenance metadata written into the audio header. */\n  aigc_metadata?: {\n    /** Write the metadata. Default `false` — the rest is ignored without it. */\n    enable?: boolean\n    /** Name or code of the synthesis provider. */\n    content_producer?: string\n    /** Content production id. */\n    produce_id?: string\n    /** Name or code of the distribution provider. */\n    content_propagator?: string\n    /** Content distribution id. */\n    propagate_id?: string\n  }\n}\n\n/** Request body for `POST /api/v3/tts/create` — exactly five fields. */\nexport interface BytePlusTTSCreateRequest {\n  /** Seed Speech synthesis model, e.g. `seed-audio-1.0`. */\n  model: string\n  /**\n   * The text to speak (≤3000 chars). Dual-purpose: either literal text or a\n   * natural-language description of the delivery, and the place the\n   * `@Audio1`..`@Audio3` reference markers go.\n   *\n   * **`text_prompt` is correct — do not \"fix\" this to `text`.** This endpoint\n   * has no request-side `text` field. The `text` spelling belongs to the\n   * *other* endpoint, `/tts/unidirectional` (TTS 2.0), where it sits under\n   * `req_params.text`. Confirmed against\n   * docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01, which lists this\n   * body as exactly `model`, `text_prompt`, `references`, `audio_config`,\n   * `watermark`.\n   */\n  text_prompt: string\n  /** Voice selection and cloning references. See {@link BytePlusTTSReference}. */\n  references?: Array<BytePlusTTSReference>\n  audio_config?: BytePlusTTSAudioConfig\n  /** Watermark the generated audio. See {@link BytePlusTTSWatermark}. */\n  watermark?: BytePlusTTSWatermark\n}\n\n/**\n * One timed entry of a TTS subtitle track.\n *\n * **Times are milliseconds** — unlike the response's `duration` fields, which\n * are seconds. The endpoint genuinely mixes units.\n */\nexport interface BytePlusTTSSubtitleEntry {\n  text?: string\n  start_time?: number\n  end_time?: number\n}\n\n/** Sentence- and word-level timings returned when `enable_subtitle` is set. */\nexport interface BytePlusTTSSubtitle {\n  sentences?: Array<BytePlusTTSSubtitleEntry>\n  words?: Array<BytePlusTTSSubtitleEntry>\n}\n\n/** Response body for `POST /api/v3/tts/create`. */\nexport interface BytePlusTTSCreateResponse {\n  /**\n   * Status code — `0` on success, a flat error code otherwise.\n   *\n   * Typed as `number | string` because only the *error* envelope was verified\n   * live (HTTP 401 `{\"code\":45000010,…}`); the success envelope's shape is\n   * docs-derived and no voice key was available to confirm it. Treating a\n   * string code as \"not a failure\" would return a failed 200 as success, so\n   * the adapter coerces before comparing — see `isZeroCode` in\n   * `adapters/tts.ts`.\n   */\n  code?: number | string\n  message?: string\n  /** Base64-encoded audio in the requested `audio_config.format`. */\n  audio?: string\n  /**\n   * Length of the delivered audio in **seconds** (float), after `speech_rate`\n   * is applied. This can legitimately exceed 120 when the clip is slowed\n   * down — the 120 s cap applies to {@link BytePlusTTSCreateResponse.original_duration}.\n   */\n  duration?: number | string\n  /**\n   * Length in **seconds** (float) before rate adjustment. This is the billing\n   * basis and is capped at 120.\n   */\n  original_duration?: number | string\n  /** Temporary download URL for the same audio. Expires after ~2 hours. */\n  url?: string\n  /** Sentence and word timings, present when `enable_subtitle` was set. */\n  subtitle?: BytePlusTTSSubtitle\n}\n\n// ============================================================================\n// ASR — POST /api/v3/auc/bigmodel/recognize/flash\n// ============================================================================\n\n/**\n * Value of the `X-Api-Resource-Id` header that selects the Seed ASR turbo\n * model. The flash endpoint takes no `model` field in its body — the model is\n * chosen entirely by this header.\n */\nexport const BYTEPLUS_ASR_RESOURCE_ID = 'volc.seedasr.auc_turbo'\n\n/** Header name carrying {@link BYTEPLUS_ASR_RESOURCE_ID}. */\nexport const BYTEPLUS_ASR_RESOURCE_HEADER = 'X-Api-Resource-Id'\n\n/**\n * Audio input. Exactly one of `url` or `data` is sent — the endpoint accepts\n * files up to 2 hours long / 100 MB.\n */\nexport interface BytePlusASRAudio {\n  /** Publicly reachable URL of the audio file. */\n  url?: string\n  /** Base64-encoded audio bytes. */\n  data?: string\n  /** Container hint, e.g. `mp3`, `wav`, `ogg`. */\n  format?: string\n}\n\n/** `request` block of a recognition call. */\nexport interface BytePlusASRRequestOptions {\n  /** Recognition model family. Defaults to `bigmodel`. */\n  model_name?: string\n  /** Inverse text normalisation (spoken numbers → digits). */\n  enable_itn?: boolean\n  /** Insert punctuation. */\n  enable_punc?: boolean\n  /** Disfluency removal (\"um\", repeated words). */\n  enable_ddc?: boolean\n  /** Attach per-utterance speaker labels. */\n  enable_speaker_info?: boolean\n  /** Return the `utterances` breakdown as well as the flat transcript. */\n  show_utterances?: boolean\n  /** Spoken language hint, e.g. `en-US`. */\n  language?: string\n}\n\n/** Request body for `POST /api/v3/auc/bigmodel/recognize/flash`. */\nexport interface BytePlusASRRecognizeRequest {\n  user?: { uid?: string }\n  audio: BytePlusASRAudio\n  request?: BytePlusASRRequestOptions\n}\n\n/** One recognised word. `start_time` / `end_time` are milliseconds. */\nexport interface BytePlusASRWord {\n  text?: string\n  start_time?: number\n  end_time?: number\n  confidence?: number\n}\n\n/** One recognised utterance. `start_time` / `end_time` are milliseconds. */\nexport interface BytePlusASRUtterance {\n  text?: string\n  start_time?: number\n  end_time?: number\n  words?: Array<BytePlusASRWord>\n  /**\n   * Extra per-utterance annotations. Speaker labels arrive here when\n   * `enable_speaker_info` is set; the exact key is read defensively because it\n   * could not be confirmed against a live response.\n   */\n  additions?: Record<string, string>\n}\n\nexport interface BytePlusASRResult {\n  text?: string\n  utterances?: Array<BytePlusASRUtterance>\n}\n\n/**\n * Response body for `POST /api/v3/auc/bigmodel/recognize/flash`.\n *\n * The Volcengine-lineage wire shape nests everything under `result`; BytePlus'\n * prose docs describe the same payload as \"transcript + utterances\", so the\n * flat spelling is tolerated as a fallback.\n */\nexport interface BytePlusASRRecognizeResponse {\n  /** `duration` is the audio length in **milliseconds**. */\n  audio_info?: { duration?: number }\n  result?: BytePlusASRResult\n  /** Flat alias for `result.text`. */\n  transcript?: string\n  /** Flat alias for `result.utterances`. */\n  utterances?: Array<BytePlusASRUtterance>\n}\n\n// ============================================================================\n// Errors\n// ============================================================================\n\n/**\n * Seed Speech error envelope: a flat numeric `code` plus a `message`, e.g.\n * `{\"code\": 45000010, \"message\": \"Invalid X-Api-Key\"}` (verified live on a\n * 401). Format it with `bytePlusVoiceError` from `../utils/client`.\n */\nexport interface BytePlusVoiceErrorBody {\n  code?: number\n  message?: string\n}\n"],"mappings":";;;;;;;;AAyCA,IAAa,4BAA4B;CACvC;CAAM;CAAO;CAAO;CAAO;CAAO;AACpC;;;;;;AAgLA,IAAa,2BAA2B;;AAGxC,IAAa,+BAA+B"}

package/dist/esm/index.d.ts

@@ -3,13 +3,13 @@ export type { BytePlusVideoConfig } from './adapters/video.js';
 export { parseBytePlusVideoSize, resolveBytePlusVideoResolution, resolveBytePlusVideoSize, supportsAudioOnlyReference, supportsLastFrame, supportsReferenceMedia, } from './video/video-provider-options.js';
 export type { BytePlusVideoModelProviderOptionsByName, BytePlusVideoOutputFormat, BytePlusVideoProviderOptions, BytePlusVideoServiceTier, } from './video/video-provider-options.js';
 export type { BytePlusVideoContentPart, BytePlusVideoContentRole, BytePlusVideoCreateRequest, BytePlusVideoCreateResponse, BytePlusVideoTask, BytePlusVideoTaskContent, BytePlusVideoTaskError, BytePlusVideoTaskListItem, BytePlusVideoTaskListResponse, BytePlusVideoTaskStatus, BytePlusVideoTaskUsage, } from './video/wire-types.js';
-export { BYTEPLUS_DEFAULT_TTS_SPEAKER, BYTEPLUS_TTS_MAX_OUTPUT_SECONDS, BytePlusTTSAdapter, byteplusSpeech, createBytePlusSpeech, toSpeechRate, } from './adapters/tts.js';
+export { BYTEPLUS_DEFAULT_TTS_SPEAKER, BYTEPLUS_TTS_MAX_OUTPUT_SECONDS, BYTEPLUS_TTS_MAX_REFERENCES, BytePlusTTSAdapter, byteplusSpeech, createBytePlusSpeech, toSpeechRate, } from './adapters/tts.js';
 export type { BytePlusTTSProviderOptions, BytePlusTTSResult, BytePlusTTSVoice, } from './audio/tts-provider-options.js';
 export { BytePlusTranscriptionAdapter, byteplusTranscription, createBytePlusTranscription, } from './adapters/transcription.js';
 export type { BytePlusTranscriptionWord } from './adapters/transcription.js';
 export type { BytePlusTranscriptionProviderOptions } from './audio/transcription-provider-options.js';
 export { BYTEPLUS_ASR_RESOURCE_HEADER, BYTEPLUS_ASR_RESOURCE_ID, BYTEPLUS_TTS_SAMPLE_RATES, } from './audio/wire-types.js';
-export type { BytePlusASRAudio, BytePlusASRRecognizeRequest, BytePlusASRRecognizeResponse, BytePlusASRResult, BytePlusASRUtterance, BytePlusASRWord, BytePlusTTSAudioConfig, BytePlusTTSAudioFormat, BytePlusTTSCreateRequest, BytePlusTTSCreateResponse, BytePlusTTSReference, BytePlusTTSSampleRate, BytePlusTTSSubtitle, BytePlusTTSSubtitleEntry, BytePlusVoiceErrorBody, } from './audio/wire-types.js';
+export type { BytePlusASRAudio, BytePlusASRRecognizeRequest, BytePlusASRRecognizeResponse, BytePlusASRResult, BytePlusASRUtterance, BytePlusASRWord, BytePlusTTSAudioConfig, BytePlusTTSAudioFormat, BytePlusTTSCreateRequest, BytePlusTTSCreateResponse, BytePlusTTSReference, BytePlusTTSSampleRate, BytePlusTTSSubtitle, BytePlusTTSSubtitleEntry, BytePlusTTSWatermark, BytePlusVoiceErrorBody, } from './audio/wire-types.js';
 export { BytePlusImageAdapter, byteplusImage, createBytePlusImage, } from './adapters/image.js';
 export type { BytePlusImageConfig } from './adapters/image.js';
 export { BYTEPLUS_IMAGE_MAX_PROMPT_WORDS, BYTEPLUS_IMAGE_MAX_SEQUENTIAL_IMAGES, BYTEPLUS_OUTPUT_FORMAT_IMAGE_MODELS, parseBytePlusImageSize, } from './image/image-provider-options.js';

package/dist/esm/index.js

@@ -2,10 +2,10 @@ import { BYTEPLUS_ARK_BASE_URL, BYTEPLUS_VOICE_BASE_URL, bytePlusArkError, byteP
 import { BYTEPLUS_CHAT_MODELS, BYTEPLUS_IMAGE_MAX_REFERENCE_IMAGES, BYTEPLUS_IMAGE_MODELS, BYTEPLUS_STRUCTURED_OUTPUT_CHAT_MODELS, BYTEPLUS_THINKING_SUMMARY_MODELS, BYTEPLUS_TRANSCRIPTION_MODELS, BYTEPLUS_TTS_MODELS, BYTEPLUS_VIDEO_DURATIONS, BYTEPLUS_VIDEO_FALLBACK_DURATIONS, BYTEPLUS_VIDEO_MODELS, emitsEncryptedContent, getBytePlusVideoDurationOptions, isKnownBytePlusVideoModel, supportsStructuredOutput } from "./model-meta.js";
 import { parseBytePlusVideoSize, resolveBytePlusVideoResolution, resolveBytePlusVideoSize, supportsAudioOnlyReference, supportsLastFrame, supportsReferenceMedia } from "./video/video-provider-options.js";
 import { BytePlusVideoAdapter, byteplusVideo, createBytePlusVideo } from "./adapters/video.js";
-import { BYTEPLUS_DEFAULT_TTS_SPEAKER, BYTEPLUS_TTS_MAX_OUTPUT_SECONDS, BytePlusTTSAdapter, byteplusSpeech, createBytePlusSpeech, toSpeechRate } from "./adapters/tts.js";
+import { BYTEPLUS_DEFAULT_TTS_SPEAKER, BYTEPLUS_TTS_MAX_OUTPUT_SECONDS, BYTEPLUS_TTS_MAX_REFERENCES, BytePlusTTSAdapter, byteplusSpeech, createBytePlusSpeech, toSpeechRate } from "./adapters/tts.js";
 import { BYTEPLUS_ASR_RESOURCE_HEADER, BYTEPLUS_ASR_RESOURCE_ID, BYTEPLUS_TTS_SAMPLE_RATES } from "./audio/wire-types.js";
 import { BytePlusTranscriptionAdapter, byteplusTranscription, createBytePlusTranscription } from "./adapters/transcription.js";
 import { BYTEPLUS_IMAGE_MAX_PROMPT_WORDS, BYTEPLUS_IMAGE_MAX_SEQUENTIAL_IMAGES, BYTEPLUS_OUTPUT_FORMAT_IMAGE_MODELS, parseBytePlusImageSize } from "./image/image-provider-options.js";
 import { BytePlusImageAdapter, byteplusImage, createBytePlusImage } from "./adapters/image.js";
 import { BytePlusTextAdapter, byteplusText, createBytePlusText } from "./adapters/text.js";
-export { BYTEPLUS_ARK_BASE_URL, BYTEPLUS_ASR_RESOURCE_HEADER, BYTEPLUS_ASR_RESOURCE_ID, BYTEPLUS_CHAT_MODELS, BYTEPLUS_DEFAULT_TTS_SPEAKER, BYTEPLUS_IMAGE_MAX_PROMPT_WORDS, BYTEPLUS_IMAGE_MAX_REFERENCE_IMAGES, BYTEPLUS_IMAGE_MAX_SEQUENTIAL_IMAGES, BYTEPLUS_IMAGE_MODELS, BYTEPLUS_OUTPUT_FORMAT_IMAGE_MODELS, BYTEPLUS_STRUCTURED_OUTPUT_CHAT_MODELS, BYTEPLUS_THINKING_SUMMARY_MODELS, BYTEPLUS_TRANSCRIPTION_MODELS, BYTEPLUS_TTS_MAX_OUTPUT_SECONDS, BYTEPLUS_TTS_MODELS, BYTEPLUS_TTS_SAMPLE_RATES, BYTEPLUS_VIDEO_DURATIONS, BYTEPLUS_VIDEO_FALLBACK_DURATIONS, BYTEPLUS_VIDEO_MODELS, BYTEPLUS_VOICE_BASE_URL, BytePlusImageAdapter, BytePlusTTSAdapter, BytePlusTextAdapter, BytePlusTranscriptionAdapter, BytePlusVideoAdapter, bytePlusArkError, bytePlusArkHeaders, bytePlusVoiceError, bytePlusVoiceHeaders, byteplusImage, byteplusSpeech, byteplusText, byteplusTranscription, byteplusVideo, createBytePlusImage, createBytePlusSpeech, createBytePlusText, createBytePlusTranscription, createBytePlusVideo, emitsEncryptedContent, getBytePlusArkApiKeyFromEnv, getBytePlusVideoDurationOptions, getBytePlusVoiceApiKeyFromEnv, isKnownBytePlusVideoModel, parseBytePlusImageSize, parseBytePlusVideoSize, resolveBytePlusVideoResolution, resolveBytePlusVideoSize, supportsAudioOnlyReference, supportsLastFrame, supportsReferenceMedia, supportsStructuredOutput, toSpeechRate, withBytePlusArkDefaults, withBytePlusVoiceDefaults };
+export { BYTEPLUS_ARK_BASE_URL, BYTEPLUS_ASR_RESOURCE_HEADER, BYTEPLUS_ASR_RESOURCE_ID, BYTEPLUS_CHAT_MODELS, BYTEPLUS_DEFAULT_TTS_SPEAKER, BYTEPLUS_IMAGE_MAX_PROMPT_WORDS, BYTEPLUS_IMAGE_MAX_REFERENCE_IMAGES, BYTEPLUS_IMAGE_MAX_SEQUENTIAL_IMAGES, BYTEPLUS_IMAGE_MODELS, BYTEPLUS_OUTPUT_FORMAT_IMAGE_MODELS, BYTEPLUS_STRUCTURED_OUTPUT_CHAT_MODELS, BYTEPLUS_THINKING_SUMMARY_MODELS, BYTEPLUS_TRANSCRIPTION_MODELS, BYTEPLUS_TTS_MAX_OUTPUT_SECONDS, BYTEPLUS_TTS_MAX_REFERENCES, BYTEPLUS_TTS_MODELS, BYTEPLUS_TTS_SAMPLE_RATES, BYTEPLUS_VIDEO_DURATIONS, BYTEPLUS_VIDEO_FALLBACK_DURATIONS, BYTEPLUS_VIDEO_MODELS, BYTEPLUS_VOICE_BASE_URL, BytePlusImageAdapter, BytePlusTTSAdapter, BytePlusTextAdapter, BytePlusTranscriptionAdapter, BytePlusVideoAdapter, bytePlusArkError, bytePlusArkHeaders, bytePlusVoiceError, bytePlusVoiceHeaders, byteplusImage, byteplusSpeech, byteplusText, byteplusTranscription, byteplusVideo, createBytePlusImage, createBytePlusSpeech, createBytePlusText, createBytePlusTranscription, createBytePlusVideo, emitsEncryptedContent, getBytePlusArkApiKeyFromEnv, getBytePlusVideoDurationOptions, getBytePlusVoiceApiKeyFromEnv, isKnownBytePlusVideoModel, parseBytePlusImageSize, parseBytePlusVideoSize, resolveBytePlusVideoResolution, resolveBytePlusVideoSize, supportsAudioOnlyReference, supportsLastFrame, supportsReferenceMedia, supportsStructuredOutput, toSpeechRate, withBytePlusArkDefaults, withBytePlusVoiceDefaults };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-byteplus",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "BytePlus ModelArk adapter for TanStack AI: Seed LLM chat, Seedance video, Seedream image, and Seed Speech TTS/ASR.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -54,15 +54,15 @@
   "devDependencies": {
     "@vitest/coverage-v8": "4.1.10",
     "vite": "^8.2.1",
-    "@tanstack/ai": "0.54.0"
+    "@tanstack/ai": "0.57.0"
   },
   "peerDependencies": {
-    "@tanstack/ai": "^0.54.0"
+    "@tanstack/ai": "^0.57.0"
   },
   "dependencies": {
     "openai": "^6.41.0",
     "@tanstack/ai-utils": "^0.4.0",
-    "@tanstack/openai-base": "^0.10.11"
+    "@tanstack/openai-base": "^0.10.14"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/tts.ts

@@ -9,7 +9,13 @@ import {
   readJsonBody,
   withBytePlusVoiceDefaults,
 } from '../utils/client'
-import type { TTSOptions } from '@tanstack/ai'
+import type {
+  TTSAlignment,
+  TTSCapabilities,
+  TTSOptions,
+  TTSSegment,
+  TTSTurn,
+} from '@tanstack/ai'
 import type { InternalLogger } from '@tanstack/ai/adapter-internals'
 import type { BytePlusVoiceConfig } from '../utils/client'
 import type { BytePlusTTSModel } from '../model-meta'
@@ -18,6 +24,9 @@ import type {
   BytePlusTTSAudioFormat,
   BytePlusTTSCreateRequest,
   BytePlusTTSCreateResponse,
+  BytePlusTTSReference,
+  BytePlusTTSSubtitle,
+  BytePlusTTSSubtitleEntry,
 } from '../audio/wire-types'
 import type {
   BytePlusTTSProviderOptions,
@@ -77,6 +86,13 @@ export const BYTEPLUS_DEFAULT_TTS_SPEAKER = 'en_female_stokie_uranus_bigtts'
  */
 export const BYTEPLUS_TTS_MAX_OUTPUT_SECONDS = 120
 
+/**
+ * Hard cap on the `references` array, and therefore on the number of distinct
+ * voices one dialogue request can use. The markers that cite them in
+ * `text_prompt` run `@Audio1`..`@Audio3`.
+ */
+export const BYTEPLUS_TTS_MAX_REFERENCES = 3
+
 /**
  * BytePlus Seed Speech text-to-speech adapter.
  *
@@ -113,6 +129,16 @@ export class BytePlusTTSAdapter<
 > extends BaseTTSAdapter<TModel, BytePlusTTSProviderOptions> {
   readonly name = 'byteplus' as const
 
+  /**
+   * Seed Audio 1.0 does multi-role dialogue in one pass, addressed through
+   * `references` (capped at 3 entries), and returns word/sentence timings
+   * when `audio_config.enable_subtitle` is set.
+   */
+  override readonly capabilities: TTSCapabilities = {
+    maxSpeakers: BYTEPLUS_TTS_MAX_REFERENCES,
+    timestamps: true,
+  }
+
   private readonly apiKey: string
   private readonly baseURL: string
   private readonly defaultHeaders: Record<string, string>
@@ -130,7 +156,8 @@ export class BytePlusTTSAdapter<
   async generateSpeech(
     options: TTSOptions<BytePlusTTSProviderOptions>,
   ): Promise<BytePlusTTSResult> {
-    const { logger, model, text, voice, format, speed, modelOptions } = options
+    const { logger, model, text, voice, format, speed, modelOptions, turns } =
+      options
 
     logger.request(`activity=generateSpeech provider=byteplus model=${model}`, {
       provider: 'byteplus',
@@ -140,10 +167,12 @@ export class BytePlusTTSAdapter<
     const { body, audioFormat, sampleRate } = buildTTSRequestBody({
       model,
       text,
+      turns,
       voice,
       format,
       speed,
       modelOptions,
+      timestamps: options.timestamps,
       logger,
     })
 
@@ -208,6 +237,7 @@ export class BytePlusTTSAdapter<
         ...(duration !== undefined && { duration }),
         ...(originalDuration !== undefined && { originalDuration }),
         ...(data.subtitle !== undefined && { subtitle: data.subtitle }),
+        ...toAlignmentFields(data.subtitle),
         ...(data.url !== undefined && { url: data.url }),
       }
     } catch (error) {
@@ -231,17 +261,22 @@ export class BytePlusTTSAdapter<
 export function buildTTSRequestBody(options: {
   model: string
   text: string
+  /** Dialogue turns, when the caller asked for multi-role synthesis. */
+  turns?: Array<TTSTurn>
   voice: string | undefined
   format: TTSOptions['format'] | undefined
   speed: number | undefined
   modelOptions: BytePlusTTSProviderOptions | undefined
+  /** Core `timestamps: true` — turns on `audio_config.enable_subtitle`. */
+  timestamps?: boolean
   logger: InternalLogger
 }): {
   body: BytePlusTTSCreateRequest
   audioFormat: BytePlusTTSAudioFormat
   sampleRate: number
 } {
-  const { model, text, voice, format, speed, modelOptions, logger } = options
+  const { model, text, turns, voice, format, speed, modelOptions, logger } =
+    options
 
   const audioFormat = pickAudioFormat(modelOptions?.format, format, logger)
   // Always explicit: the documented server default (40000) is not one of the
@@ -258,8 +293,13 @@ export function buildTTSRequestBody(options: {
   if (modelOptions?.loudness_rate !== undefined) {
     audioConfig.loudness_rate = modelOptions.loudness_rate
   }
-  if (modelOptions?.enable_subtitle !== undefined) {
-    audioConfig.enable_subtitle = modelOptions.enable_subtitle
+  // `modelOptions.enable_subtitle` still wins, so an explicit `false` can
+  // opt out of the flag even when core asked for timestamps. A `timestamps`
+  // the caller never set stays off the body entirely.
+  const enableSubtitle =
+    modelOptions?.enable_subtitle ?? (options.timestamps || undefined)
+  if (enableSubtitle !== undefined) {
+    audioConfig.enable_subtitle = enableSubtitle
   }
 
   // An explicit `speech_rate` always wins over the derived one — it is the
@@ -271,22 +311,29 @@ export function buildTTSRequestBody(options: {
     audioConfig.speech_rate = speechRate
   }
 
+  const dialogue = turns ? buildDialoguePrompt(turns) : undefined
+
   const body: BytePlusTTSCreateRequest = {
     model,
-    [TTS_TEXT_FIELD]: text,
+    [TTS_TEXT_FIELD]: dialogue?.textPrompt ?? text,
     // The voice belongs inside `references`, not at the top level — a
-    // top-level `speaker` is silently ignored by the server. The flat member
-    // shape here is the best-supported reading of the docs; see
-    // `BytePlusTTSReference` for the unresolved part and the live-probe flag.
-    references: modelOptions?.references ?? [
-      {
-        speaker: modelOptions?.speaker ?? voice ?? BYTEPLUS_DEFAULT_TTS_SPEAKER,
-      },
-    ],
+    // top-level `speaker` is silently ignored by the server.
+    references: modelOptions?.references ??
+      dialogue?.references ?? [
+        {
+          speaker:
+            modelOptions?.speaker ?? voice ?? BYTEPLUS_DEFAULT_TTS_SPEAKER,
+        },
+      ],
     audio_config: audioConfig,
   }
   if (modelOptions?.watermark !== undefined) {
-    body.watermark = modelOptions.watermark
+    // The endpoint wants an object. `true` means the audible marker, which is
+    // what a caller passing a boolean is asking for.
+    body.watermark =
+      typeof modelOptions.watermark === 'boolean'
+        ? { aigc_watermark: modelOptions.watermark }
+        : modelOptions.watermark
   }
 
   return { body, audioFormat, sampleRate }
@@ -385,6 +432,81 @@ export function getContentType(
   }
 }
 
+/**
+ * Turn dialogue turns into the one-prompt form Seed Audio 1.0 takes: each
+ * distinct voice becomes a `references` entry, and every line of the script
+ * cites its voice by the reference's 1-based position (`@Audio1`..`@Audio3`),
+ * which is the marker convention the reference array already uses.
+ *
+ * **The prompt form is unprobed.** The flat `references[]` member shape is
+ * confirmed (see `BytePlusTTSReference`), and the model card documents
+ * multi-role dialogue and positional reference markers, but no worked
+ * multi-speaker example was available and no Seed Speech key existed to
+ * confirm how lines should cite their voice.
+ */
+function buildDialoguePrompt(turns: Array<TTSTurn>): {
+  textPrompt: string
+  references: Array<BytePlusTTSReference>
+} {
+  const voices = [...new Set(turns.map((turn) => turn.voice))]
+  return {
+    textPrompt: turns
+      .map((turn) => `@Audio${voices.indexOf(turn.voice) + 1}: ${turn.text}`)
+      .join('\n'),
+    references: voices.map((speaker) => ({ speaker })),
+  }
+}
+
+/**
+ * Map the BytePlus `subtitle` block onto the cross-provider `alignment` /
+ * `segments` fields.
+ *
+ * `words` is the finest granularity Seed Speech reports, so it becomes
+ * `alignment`; `sentences` is utterance segmentation, so it becomes
+ * `segments`. **Subtitle times are milliseconds** while the rest of the
+ * response is seconds — the conversion happens here, once.
+ *
+ * The raw block stays on {@link BytePlusTTSResult.subtitle} for callers
+ * already reading it.
+ */
+function toAlignmentFields(subtitle: BytePlusTTSSubtitle | undefined): {
+  alignment?: TTSAlignment
+  segments?: Array<TTSSegment>
+} {
+  if (!subtitle) return {}
+  const fields: { alignment?: TTSAlignment; segments?: Array<TTSSegment> } = {}
+  const words = subtitle.words?.filter(isTimedEntry)
+  if (words && words.length > 0) {
+    fields.alignment = {
+      unit: 'word',
+      texts: words.map((word) => word.text ?? ''),
+      startSeconds: words.map((word) => word.start_time / 1000),
+      endSeconds: words.map((word) => word.end_time / 1000),
+    }
+  }
+  const sentences = subtitle.sentences?.filter(isTimedEntry)
+  if (sentences && sentences.length > 0) {
+    fields.segments = sentences.map((sentence) => ({
+      startSeconds: sentence.start_time / 1000,
+      endSeconds: sentence.end_time / 1000,
+      ...(sentence.text !== undefined && { text: sentence.text }),
+    }))
+  }
+  return fields
+}
+
+/** Both times present, so the entry can be placed on the timeline. */
+function isTimedEntry(
+  entry: BytePlusTTSSubtitleEntry,
+): entry is BytePlusTTSSubtitleEntry & {
+  start_time: number
+  end_time: number
+} {
+  return (
+    typeof entry.start_time === 'number' && typeof entry.end_time === 'number'
+  )
+}
+
 /**
  * Coerce a `duration` / `original_duration` field to a usable number of
  * seconds.

package/src/audio/tts-provider-options.ts

@@ -3,6 +3,7 @@ import type {
   BytePlusTTSReference,
   BytePlusTTSSampleRate,
   BytePlusTTSSubtitle,
+  BytePlusTTSWatermark,
 } from './wire-types'
 import type { TTSResult } from '@tanstack/ai'
 
@@ -79,10 +80,13 @@ export interface BytePlusTTSProviderOptions {
    */
   enable_subtitle?: boolean
   /**
-   * Watermark the generated audio. The field name is confirmed against the
-   * endpoint schema; the boolean type is assumed and unprobed.
+   * Watermark the generated audio.
+   *
+   * Seed Audio takes an object with two independent markers — an audible
+   * `aigc_watermark` appended to the clip and an `aigc_metadata` block written
+   * into the audio header. `true` is shorthand for `{ aigc_watermark: true }`.
    */
-  watermark?: boolean
+  watermark?: boolean | BytePlusTTSWatermark
 }
 
 /**

package/src/audio/wire-types.ts

@@ -56,15 +56,16 @@ export type BytePlusTTSSampleRate = (typeof BYTEPLUS_TTS_SAMPLE_RATES)[number]
  * audio references (30 s / 10 MB each) and 1 image reference (10 MB), and
  * image references are mutually exclusive with audio ones.
  *
- * **Member object shape is unresolved — must live-probe when the Seed Speech
- * key lands.** The docs list the member fields flat (`speaker | audio_data |
- * audio_url | image_data | image_url`) without a worked example, so whether
- * the server wants a flat `{ speaker }` or a discriminated `{ type, ... }`
- * could not be settled. The adapter sends the flat reading — see
- * `buildTTSRequestBody` in `../adapters/tts`.
+ * The member fields are flat (`speaker | audio_data | audio_url | image_data |
+ * image_url`), confirmed against
+ * docs.byteplus.com/en/docs/byteplusvoice/seedaudio-01.
  */
 export interface BytePlusTTSReference {
-  /** Stock voice id, e.g. `en_female_stokie_uranus_bigtts`. */
+  /**
+   * Voice id, e.g. `en_female_stokie_uranus_bigtts`. Either a stock TTS 2.0
+   * voice or the id of a voice you cloned through Voice Replication — this
+   * field is the join between replication and synthesis.
+   */
   speaker?: string
   /** URL of a reference clip to clone (≤30 s, ≤10 MB). */
   audio_url?: string
@@ -100,6 +101,37 @@ export interface BytePlusTTSAudioConfig {
   enable_subtitle?: boolean
 }
 
+/**
+ * `watermark` block of a TTS request.
+ *
+ * Two independent markers, both off by default:
+ *
+ * - `aigc_watermark` — **explicit**: appends an audible rhythm marker to the
+ *   end of the clip.
+ * - `aigc_metadata` — **implicit**: writes provenance metadata into the audio
+ *   header. Nothing is written unless `enable` is `true`.
+ *
+ * This is an object, not a boolean — unlike Seedream images and Seedance
+ * video, where `watermark` genuinely is a boolean.
+ */
+export interface BytePlusTTSWatermark {
+  /** Append an audible rhythm marker to the end of the audio. Default `false`. */
+  aigc_watermark?: boolean
+  /** Provenance metadata written into the audio header. */
+  aigc_metadata?: {
+    /** Write the metadata. Default `false` — the rest is ignored without it. */
+    enable?: boolean
+    /** Name or code of the synthesis provider. */
+    content_producer?: string
+    /** Content production id. */
+    produce_id?: string
+    /** Name or code of the distribution provider. */
+    content_propagator?: string
+    /** Content distribution id. */
+    propagate_id?: string
+  }
+}
+
 /** Request body for `POST /api/v3/tts/create` — exactly five fields. */
 export interface BytePlusTTSCreateRequest {
   /** Seed Speech synthesis model, e.g. `seed-audio-1.0`. */
@@ -121,11 +153,8 @@ export interface BytePlusTTSCreateRequest {
   /** Voice selection and cloning references. See {@link BytePlusTTSReference}. */
   references?: Array<BytePlusTTSReference>
   audio_config?: BytePlusTTSAudioConfig
-  /**
-   * Watermark the generated audio. The field name is confirmed; the boolean
-   * type is assumed by analogy with Seedream's `watermark` and unprobed.
-   */
-  watermark?: boolean
+  /** Watermark the generated audio. See {@link BytePlusTTSWatermark}. */
+  watermark?: BytePlusTTSWatermark
 }
 
 /**

package/src/index.ts

@@ -47,6 +47,7 @@ export type {
 export {
   BYTEPLUS_DEFAULT_TTS_SPEAKER,
   BYTEPLUS_TTS_MAX_OUTPUT_SECONDS,
+  BYTEPLUS_TTS_MAX_REFERENCES,
   BytePlusTTSAdapter,
   byteplusSpeech,
   createBytePlusSpeech,
@@ -84,6 +85,7 @@ export type {
   BytePlusTTSSampleRate,
   BytePlusTTSSubtitle,
   BytePlusTTSSubtitleEntry,
+  BytePlusTTSWatermark,
   BytePlusVoiceErrorBody,
 } from './audio/wire-types'
 export {