@tanstack/ai-byteplus 0.0.0

package/dist/esm/adapters/transcription.js

@@ -0,0 +1,274 @@
+import { bytePlusVoiceError, bytePlusVoiceHeaders, getBytePlusVoiceApiKeyFromEnv, readJsonBody, withBytePlusVoiceDefaults } from "../utils/client.js";
+import { BYTEPLUS_ASR_RESOURCE_HEADER, BYTEPLUS_ASR_RESOURCE_ID } from "../audio/wire-types.js";
+import { BaseTranscriptionAdapter } from "@tanstack/ai/adapters";
+import { toRunErrorPayload } from "@tanstack/ai/adapter-internals";
+import { arrayBufferToBase64, generateId } from "@tanstack/ai-utils";
+//#region src/adapters/transcription.ts
+/** Path of the synchronous ("flash") Seed ASR endpoint. */
+var RECOGNIZE_FLASH_PATH = "/api/v3/auc/bigmodel/recognize/flash";
+/** Default `user.uid` echoed into BytePlus' request logs. */
+var DEFAULT_UID = "tanstack-ai";
+/**
+* BytePlus Seed Speech transcription (ASR) adapter.
+*
+* Talks to `POST {baseURL}/api/v3/auc/bigmodel/recognize/flash` — the
+* synchronous "flash" endpoint, which returns the whole transcript in one
+* response rather than requiring a submit/poll cycle. It accepts audio up to
+* 2 hours long or 100 MB, either as a publicly reachable URL or as base64
+* bytes.
+*
+* Two BytePlus-specific details:
+*
+* - The model is selected by the `X-Api-Resource-Id` header
+*   (`volc.seedasr.auc_turbo`), not by a `model` field in the body. The
+*   package's `seed-asr` model id exists to satisfy the SDK contract and to
+*   give logs a stable value.
+* - Authentication uses `X-Api-Key` with the **Seed Speech** key, which is a
+*   different key from `ARK_API_KEY`.
+*
+* All timings on the wire are milliseconds; they are converted to seconds to
+* match the cross-provider `TranscriptionResult`.
+*
+* @example
+* ```ts
+* const adapter = byteplusTranscription('seed-asr')
+* const result = await generateTranscription({
+*   adapter,
+*   audio: 'https://example.com/interview.mp3',
+*   language: 'en-US',
+* })
+* ```
+*/
+var BytePlusTranscriptionAdapter = class extends BaseTranscriptionAdapter {
+	name = "byteplus";
+	apiKey;
+	baseURL;
+	defaultHeaders;
+	fetchImpl;
+	constructor(model, config) {
+		super(model, config);
+		const resolved = withBytePlusVoiceDefaults(config);
+		this.apiKey = resolved.apiKey;
+		this.baseURL = resolved.baseURL ?? "https://voice.ap-southeast-1.bytepluses.com";
+		this.defaultHeaders = resolved.defaultHeaders ?? {};
+		this.fetchImpl = resolved.fetch ?? globalThis.fetch.bind(globalThis);
+	}
+	async transcribe(options) {
+		const { logger, model, audio, language, prompt, responseFormat, modelOptions } = options;
+		logger.request(`activity=generateTranscription provider=byteplus model=${model}`, {
+			provider: "byteplus",
+			model
+		});
+		if (prompt) logger.warn("BytePlus Seed ASR has no prompt-biasing field on the flash endpoint — the `prompt` option is ignored.", {
+			provider: "byteplus",
+			model
+		});
+		if (responseFormat !== void 0 && responseFormat !== "json") logger.warn(`BytePlus Seed ASR always returns JSON — the requested responseFormat "${responseFormat}" is ignored. Build srt/vtt from result.segments if you need them.`, {
+			provider: "byteplus",
+			model,
+			responseFormat
+		});
+		try {
+			const body = buildRecognizeRequestBody({
+				audio: await normalizeAudioInput(audio, modelOptions?.audio_format),
+				language,
+				modelOptions
+			});
+			const response = await this.fetchImpl(`${this.baseURL}${RECOGNIZE_FLASH_PATH}`, {
+				method: "POST",
+				headers: bytePlusVoiceHeaders(this.apiKey, {
+					...this.defaultHeaders,
+					[BYTEPLUS_ASR_RESOURCE_HEADER]: BYTEPLUS_ASR_RESOURCE_ID
+				}),
+				body: JSON.stringify(body)
+			});
+			const payload = await readJsonBody(response);
+			if (!response.ok) throw bytePlusVoiceError(response.status, payload, "transcription");
+			const data = payload;
+			const text = data.result?.text ?? data.transcript;
+			if (typeof text !== "string") throw bytePlusVoiceError(response.status, payload, "transcription");
+			if (text === "" && !hasUtterances(data)) logger.warn("byteplus: transcription returned an empty transcript with no utterances. This is a valid result for silent audio, and is also what a 200-wrapped failure looks like.", {
+				provider: this.name,
+				model
+			});
+			const requestedLanguage = modelOptions?.language ?? language;
+			return {
+				id: generateId(this.name),
+				model,
+				...mapRecognizeResponse(data, text, logger),
+				...requestedLanguage !== void 0 && { language: requestedLanguage }
+			};
+		} catch (error) {
+			logger.errors("byteplus.transcribe fatal", {
+				error: toRunErrorPayload(error, "byteplus.transcribe failed"),
+				source: "byteplus.transcribe"
+			});
+			throw error;
+		}
+	}
+};
+/**
+* Build the JSON body for `POST /api/v3/auc/bigmodel/recognize/flash`.
+*
+* `show_utterances` defaults to `true` so the response carries the
+* per-utterance breakdown that populates `segments` and `words`.
+*/
+function buildRecognizeRequestBody(options) {
+	const { audio, language, modelOptions } = options;
+	const resolvedLanguage = modelOptions?.language ?? language;
+	return {
+		user: { uid: modelOptions?.uid ?? DEFAULT_UID },
+		audio,
+		request: {
+			model_name: modelOptions?.model_name ?? "bigmodel",
+			show_utterances: modelOptions?.show_utterances ?? true,
+			...modelOptions?.enable_itn !== void 0 && { enable_itn: modelOptions.enable_itn },
+			...modelOptions?.enable_punc !== void 0 && { enable_punc: modelOptions.enable_punc },
+			...modelOptions?.enable_ddc !== void 0 && { enable_ddc: modelOptions.enable_ddc },
+			...modelOptions?.enable_speaker_info !== void 0 && { enable_speaker_info: modelOptions.enable_speaker_info },
+			...resolvedLanguage !== void 0 && { language: resolvedLanguage }
+		}
+	};
+}
+/**
+* Turn a recognition response into the transcript-shaped half of a
+* `TranscriptionResult`. Wire timings are milliseconds; everything returned
+* here is seconds.
+*/
+function mapRecognizeResponse(data, text, logger) {
+	const utterances = data.result?.utterances ?? data.utterances ?? [];
+	const segments = utterances.flatMap((utterance) => toSegment(utterance)).map((segment, index) => ({
+		...segment,
+		id: index
+	}));
+	const rawWords = utterances.flatMap((utterance) => utterance.words ?? []);
+	const words = rawWords.flatMap((word) => {
+		if (typeof word.text !== "string" || typeof word.start_time !== "number" || typeof word.end_time !== "number") return [];
+		const mapped = {
+			word: word.text,
+			start: msToSeconds(word.start_time),
+			end: msToSeconds(word.end_time)
+		};
+		if (word.confidence !== void 0) mapped.confidence = word.confidence;
+		return [mapped];
+	});
+	const droppedWords = rawWords.length - words.length;
+	if (droppedWords > 0) logger?.warn(`byteplus: dropped ${droppedWords} of ${rawWords.length} word(s) with missing or non-numeric timings.`, { provider: "byteplus" });
+	const droppedSegments = utterances.length - segments.length;
+	if (droppedSegments > 0) logger?.warn(`byteplus: dropped ${droppedSegments} of ${utterances.length} utterance(s) with missing or non-numeric timings.`, { provider: "byteplus" });
+	const durationMs = data.audio_info?.duration;
+	const duration = typeof durationMs === "number" && durationMs > 0 ? msToSeconds(durationMs) : void 0;
+	const usage = duration !== void 0 ? {
+		promptTokens: 0,
+		completionTokens: 0,
+		totalTokens: 0,
+		durationSeconds: duration
+	} : void 0;
+	return {
+		text,
+		...duration !== void 0 && { duration },
+		...segments.length > 0 && { segments },
+		...words.length > 0 && { words },
+		...usage !== void 0 && { usage }
+	};
+}
+/**
+* Convert one utterance into a segment, or nothing when it carries no
+* timings. The `id` is a placeholder — the caller renumbers after filtering.
+*/
+/**
+* True when the response carries at least one utterance, in either envelope
+* form. Used to tell "silent audio" from a 200-wrapped failure: a genuinely
+* empty transcript usually still arrives with no utterances, so the pairing is
+* a hint rather than proof — hence a warning rather than a throw.
+*/
+function hasUtterances(data) {
+	return (data.result?.utterances ?? data.utterances ?? []).length > 0;
+}
+function toSegment(utterance) {
+	if (typeof utterance.start_time !== "number" || typeof utterance.end_time !== "number") return [];
+	const speaker = utterance.additions?.speaker;
+	return [{
+		id: 0,
+		start: msToSeconds(utterance.start_time),
+		end: msToSeconds(utterance.end_time),
+		text: utterance.text ?? "",
+		...speaker !== void 0 && { speaker }
+	}];
+}
+/**
+* **Must verify when the Seed Speech key lands.** Every timing this adapter
+* reads — `audio_info.duration`, and each utterance's and word's
+* `start_time` / `end_time` — is assumed to be milliseconds. That comes from
+* the Volcengine flash-recognition reference this endpoint derives from
+* (a 2.499 s clip reports `duration: 2499`), not from a BytePlus response we
+* have seen. If BytePlus reports seconds instead, every duration, segment and
+* word timing here is 1000× too small, and this is the only place to fix.
+*/
+function msToSeconds(milliseconds) {
+	return milliseconds / 1e3;
+}
+/**
+* Turn the cross-provider `audio` input into the endpoint's `audio` block.
+*
+* URLs are passed through untouched — Seed ASR fetches them itself, which
+* avoids pulling large media through this process. Everything else is sent as
+* base64 `data`, with the container inferred from the input's MIME type or
+* filename when the caller didn't pin `audio_format`.
+*/
+async function normalizeAudioInput(audio, formatHint) {
+	const withFormat = (payload, inferred) => {
+		const format = formatHint ?? inferred;
+		return format ? {
+			...payload,
+			format
+		} : payload;
+	};
+	if (typeof audio === "string") {
+		if (/^https?:\/\//i.test(audio)) return withFormat({ url: audio }, extensionOf(audio));
+		const dataUrl = /^data:([^;,]+)?(?:;[^,]*)*,(.*)$/s.exec(audio);
+		if (dataUrl) return withFormat({ data: dataUrl[2] ?? "" }, formatFromMime(dataUrl[1]));
+		return withFormat({ data: audio });
+	}
+	if (audio instanceof ArrayBuffer) return withFormat({ data: arrayBufferToBase64(audio) });
+	const data = arrayBufferToBase64(await audio.arrayBuffer());
+	const inferred = ("name" in audio && typeof audio.name === "string" ? extensionOf(audio.name) : void 0) ?? formatFromMime(audio.type);
+	return withFormat({ data }, inferred);
+}
+function extensionOf(pathOrName) {
+	const withoutQuery = pathOrName.split(/[?#]/)[0] ?? "";
+	return /\.([a-z0-9]+)$/i.exec(withoutQuery)?.[1]?.toLowerCase();
+}
+function formatFromMime(mime) {
+	if (!mime || !mime.startsWith("audio/")) return void 0;
+	const subtype = mime.slice(6).toLowerCase();
+	if (subtype === "mpeg") return "mp3";
+	if (subtype === "x-wav" || subtype === "wave") return "wav";
+	return subtype.replace(/^x-/, "");
+}
+/**
+* Creates a BytePlus Seed Speech transcription adapter with an explicit API
+* key.
+*
+* The key is the **Seed Speech** key, not the Ark key used by the chat, image
+* and video adapters.
+*/
+function createBytePlusTranscription(model, apiKey, config) {
+	return new BytePlusTranscriptionAdapter(model, {
+		...config,
+		apiKey
+	});
+}
+/**
+* Creates a BytePlus Seed Speech transcription adapter, reading the API key
+* from `BYTEPLUS_VOICE_API_KEY`.
+*
+* @throws Error if `BYTEPLUS_VOICE_API_KEY` is not set.
+*/
+function byteplusTranscription(model, config) {
+	return createBytePlusTranscription(model, getBytePlusVoiceApiKeyFromEnv(), config);
+}
+//#endregion
+export { BytePlusTranscriptionAdapter, buildRecognizeRequestBody, byteplusTranscription, createBytePlusTranscription, mapRecognizeResponse, normalizeAudioInput };
+
+//# sourceMappingURL=transcription.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transcription.js","names":[],"sources":["../../../src/adapters/transcription.ts"],"sourcesContent":["import { BaseTranscriptionAdapter } from '@tanstack/ai/adapters'\nimport { arrayBufferToBase64, 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 {\n  BYTEPLUS_ASR_RESOURCE_HEADER,\n  BYTEPLUS_ASR_RESOURCE_ID,\n} from '../audio/wire-types'\nimport type {\n  TokenUsage,\n  TranscriptionOptions,\n  TranscriptionResult,\n  TranscriptionSegment,\n  TranscriptionWord,\n} from '@tanstack/ai'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\nimport type { BytePlusVoiceConfig } from '../utils/client'\nimport type { BytePlusTranscriptionModel } from '../model-meta'\nimport type {\n  BytePlusASRAudio,\n  BytePlusASRRecognizeRequest,\n  BytePlusASRRecognizeResponse,\n  BytePlusASRUtterance,\n} from '../audio/wire-types'\nimport type { BytePlusTranscriptionProviderOptions } from '../audio/transcription-provider-options'\n\n/** Path of the synchronous (\"flash\") Seed ASR endpoint. */\nconst RECOGNIZE_FLASH_PATH = '/api/v3/auc/bigmodel/recognize/flash'\n\n/**\n * BytePlus-specific extension of `TranscriptionWord` carrying the per-word\n * confidence Seed ASR returns. The cross-provider contract has no field for\n * it, so callers who want it narrow the array — the same pattern the Grok\n * adapter uses:\n *\n * ```ts\n * const words = result.words as Array<BytePlusTranscriptionWord> | undefined\n * ```\n */\nexport interface BytePlusTranscriptionWord extends TranscriptionWord {\n  /** Model confidence for the word, when Seed ASR returns one. */\n  confidence?: number\n}\n\n/** Default `user.uid` echoed into BytePlus' request logs. */\nconst DEFAULT_UID = 'tanstack-ai'\n\n/**\n * BytePlus Seed Speech transcription (ASR) adapter.\n *\n * Talks to `POST {baseURL}/api/v3/auc/bigmodel/recognize/flash` — the\n * synchronous \"flash\" endpoint, which returns the whole transcript in one\n * response rather than requiring a submit/poll cycle. It accepts audio up to\n * 2 hours long or 100 MB, either as a publicly reachable URL or as base64\n * bytes.\n *\n * Two BytePlus-specific details:\n *\n * - The model is selected by the `X-Api-Resource-Id` header\n *   (`volc.seedasr.auc_turbo`), not by a `model` field in the body. The\n *   package's `seed-asr` model id exists to satisfy the SDK contract and to\n *   give logs a stable value.\n * - Authentication uses `X-Api-Key` with the **Seed Speech** key, which is a\n *   different key from `ARK_API_KEY`.\n *\n * All timings on the wire are milliseconds; they are converted to seconds to\n * match the cross-provider `TranscriptionResult`.\n *\n * @example\n * ```ts\n * const adapter = byteplusTranscription('seed-asr')\n * const result = await generateTranscription({\n *   adapter,\n *   audio: 'https://example.com/interview.mp3',\n *   language: 'en-US',\n * })\n * ```\n */\nexport class BytePlusTranscriptionAdapter<\n  TModel extends BytePlusTranscriptionModel = BytePlusTranscriptionModel,\n> extends BaseTranscriptionAdapter<\n  TModel,\n  BytePlusTranscriptionProviderOptions\n> {\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 transcribe(\n    options: TranscriptionOptions<BytePlusTranscriptionProviderOptions>,\n  ): Promise<TranscriptionResult> {\n    const {\n      logger,\n      model,\n      audio,\n      language,\n      prompt,\n      responseFormat,\n      modelOptions,\n    } = options\n\n    logger.request(\n      `activity=generateTranscription provider=byteplus model=${model}`,\n      { provider: 'byteplus', model },\n    )\n\n    if (prompt) {\n      logger.warn(\n        'BytePlus Seed ASR has no prompt-biasing field on the flash endpoint — the `prompt` option is ignored.',\n        { provider: 'byteplus', model },\n      )\n    }\n\n    // The flash endpoint answers with one JSON shape and offers no format\n    // negotiation, so srt/vtt/text/verbose_json can't be honoured. `segments`\n    // on the result carry the timings a caller would have wanted from srt/vtt.\n    if (responseFormat !== undefined && responseFormat !== 'json') {\n      logger.warn(\n        `BytePlus Seed ASR always returns JSON — the requested responseFormat \"${responseFormat}\" is ignored. Build srt/vtt from result.segments if you need them.`,\n        { provider: 'byteplus', model, responseFormat },\n      )\n    }\n\n    try {\n      const audioPayload = await normalizeAudioInput(\n        audio,\n        modelOptions?.audio_format,\n      )\n      const body = buildRecognizeRequestBody({\n        audio: audioPayload,\n        language,\n        modelOptions,\n      })\n\n      const response = await this.fetchImpl(\n        `${this.baseURL}${RECOGNIZE_FLASH_PATH}`,\n        {\n          method: 'POST',\n          headers: bytePlusVoiceHeaders(this.apiKey, {\n            ...this.defaultHeaders,\n            [BYTEPLUS_ASR_RESOURCE_HEADER]: BYTEPLUS_ASR_RESOURCE_ID,\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, 'transcription')\n      }\n\n      const data = payload as BytePlusASRRecognizeResponse\n      const text = data.result?.text ?? data.transcript\n\n      // The flash endpoint can answer HTTP 200 while carrying the numeric\n      // error envelope, so an absent transcript is a failure rather than an\n      // empty result.\n      if (typeof text !== 'string') {\n        throw bytePlusVoiceError(response.status, payload, 'transcription')\n      }\n\n      // An empty string is well-formed, so it isn't an error — silence is a\n      // legitimate transcription. But it is also what a 200-wrapped failure\n      // looks like, so say so rather than handing back a successful, empty\n      // result with no signal.\n      if (text === '' && !hasUtterances(data)) {\n        logger.warn(\n          `byteplus: transcription returned an empty transcript with no ` +\n            `utterances. This is a valid result for silent audio, and is also ` +\n            `what a 200-wrapped failure looks like.`,\n          { provider: this.name, model },\n        )\n      }\n\n      // Seed ASR doesn't echo the language back, so report the one that was\n      // actually sent — which is `modelOptions.language` when it overrode the\n      // cross-provider hint.\n      const requestedLanguage = modelOptions?.language ?? language\n\n      return {\n        id: generateId(this.name),\n        model,\n        ...mapRecognizeResponse(data, text, logger),\n        ...(requestedLanguage !== undefined && { language: requestedLanguage }),\n      }\n    } catch (error) {\n      logger.errors('byteplus.transcribe fatal', {\n        error: toRunErrorPayload(error, 'byteplus.transcribe failed'),\n        source: 'byteplus.transcribe',\n      })\n      throw error\n    }\n  }\n}\n\n/**\n * Build the JSON body for `POST /api/v3/auc/bigmodel/recognize/flash`.\n *\n * `show_utterances` defaults to `true` so the response carries the\n * per-utterance breakdown that populates `segments` and `words`.\n */\nexport function buildRecognizeRequestBody(options: {\n  audio: BytePlusASRAudio\n  language: string | undefined\n  modelOptions: BytePlusTranscriptionProviderOptions | undefined\n}): BytePlusASRRecognizeRequest {\n  const { audio, language, modelOptions } = options\n\n  const resolvedLanguage = modelOptions?.language ?? language\n\n  return {\n    user: { uid: modelOptions?.uid ?? DEFAULT_UID },\n    audio,\n    request: {\n      model_name: modelOptions?.model_name ?? 'bigmodel',\n      show_utterances: modelOptions?.show_utterances ?? true,\n      ...(modelOptions?.enable_itn !== undefined && {\n        enable_itn: modelOptions.enable_itn,\n      }),\n      ...(modelOptions?.enable_punc !== undefined && {\n        enable_punc: modelOptions.enable_punc,\n      }),\n      ...(modelOptions?.enable_ddc !== undefined && {\n        enable_ddc: modelOptions.enable_ddc,\n      }),\n      ...(modelOptions?.enable_speaker_info !== undefined && {\n        enable_speaker_info: modelOptions.enable_speaker_info,\n      }),\n      ...(resolvedLanguage !== undefined && { language: resolvedLanguage }),\n    },\n  }\n}\n\n/**\n * Turn a recognition response into the transcript-shaped half of a\n * `TranscriptionResult`. Wire timings are milliseconds; everything returned\n * here is seconds.\n */\nexport function mapRecognizeResponse(\n  data: BytePlusASRRecognizeResponse,\n  text: string,\n  logger?: InternalLogger,\n): Omit<TranscriptionResult, 'id' | 'model'> {\n  const utterances = data.result?.utterances ?? data.utterances ?? []\n  // `id` numbers the segments we emit, not the utterances we were given, so\n  // dropping an untimed utterance doesn't leave a hole in the sequence.\n  const segments = utterances\n    .flatMap((utterance) => toSegment(utterance))\n    .map((segment, index) => ({ ...segment, id: index }))\n\n  const rawWords = utterances.flatMap((utterance) => utterance.words ?? [])\n  const words = rawWords.flatMap((word) => {\n    if (\n      typeof word.text !== 'string' ||\n      typeof word.start_time !== 'number' ||\n      typeof word.end_time !== 'number'\n    ) {\n      return []\n    }\n    const mapped: BytePlusTranscriptionWord = {\n      word: word.text,\n      start: msToSeconds(word.start_time),\n      end: msToSeconds(word.end_time),\n    }\n    if (word.confidence !== undefined) mapped.confidence = word.confidence\n    return [mapped]\n  })\n\n  // Untimed entries are dropped rather than emitted with NaN timings, but a\n  // silent drop leaves the caller unable to tell \"the provider sent no\n  // timings\" from \"the adapter discarded them\" — the two have very different\n  // fixes, and a field rename upstream (e.g. `text` → `word`) would empty\n  // these arrays without a single error anywhere.\n  const droppedWords = rawWords.length - words.length\n  if (droppedWords > 0) {\n    logger?.warn(\n      `byteplus: dropped ${droppedWords} of ${rawWords.length} word(s) with ` +\n        `missing or non-numeric timings.`,\n      { provider: 'byteplus' },\n    )\n  }\n  const droppedSegments = utterances.length - segments.length\n  if (droppedSegments > 0) {\n    logger?.warn(\n      `byteplus: dropped ${droppedSegments} of ${utterances.length} ` +\n        `utterance(s) with missing or non-numeric timings.`,\n      { provider: 'byteplus' },\n    )\n  }\n\n  const durationMs = data.audio_info?.duration\n  const duration =\n    typeof durationMs === 'number' && durationMs > 0\n      ? msToSeconds(durationMs)\n      : undefined\n\n  // Seed ASR is duration-billed and reports no token counts, so `usage`\n  // carries only the audio length — the same shape the Grok and OpenAI\n  // whisper paths use.\n  const usage: TokenUsage | undefined =\n    duration !== undefined\n      ? {\n          promptTokens: 0,\n          completionTokens: 0,\n          totalTokens: 0,\n          durationSeconds: duration,\n        }\n      : undefined\n\n  return {\n    text,\n    ...(duration !== undefined && { duration }),\n    ...(segments.length > 0 && { segments }),\n    ...(words.length > 0 && { words }),\n    ...(usage !== undefined && { usage }),\n  }\n}\n\n/**\n * Convert one utterance into a segment, or nothing when it carries no\n * timings. The `id` is a placeholder — the caller renumbers after filtering.\n */\n/**\n * True when the response carries at least one utterance, in either envelope\n * form. Used to tell \"silent audio\" from a 200-wrapped failure: a genuinely\n * empty transcript usually still arrives with no utterances, so the pairing is\n * a hint rather than proof — hence a warning rather than a throw.\n */\nfunction hasUtterances(data: BytePlusASRRecognizeResponse): boolean {\n  return (data.result?.utterances ?? data.utterances ?? []).length > 0\n}\n\nfunction toSegment(\n  utterance: BytePlusASRUtterance,\n): Array<TranscriptionSegment> {\n  if (\n    typeof utterance.start_time !== 'number' ||\n    typeof utterance.end_time !== 'number'\n  ) {\n    return []\n  }\n  const speaker = utterance.additions?.speaker\n  return [\n    {\n      id: 0,\n      start: msToSeconds(utterance.start_time),\n      end: msToSeconds(utterance.end_time),\n      text: utterance.text ?? '',\n      ...(speaker !== undefined && { speaker }),\n    },\n  ]\n}\n\n/**\n * **Must verify when the Seed Speech key lands.** Every timing this adapter\n * reads — `audio_info.duration`, and each utterance's and word's\n * `start_time` / `end_time` — is assumed to be milliseconds. That comes from\n * the Volcengine flash-recognition reference this endpoint derives from\n * (a 2.499 s clip reports `duration: 2499`), not from a BytePlus response we\n * have seen. If BytePlus reports seconds instead, every duration, segment and\n * word timing here is 1000× too small, and this is the only place to fix.\n */\nfunction msToSeconds(milliseconds: number): number {\n  return milliseconds / 1000\n}\n\n/**\n * Turn the cross-provider `audio` input into the endpoint's `audio` block.\n *\n * URLs are passed through untouched — Seed ASR fetches them itself, which\n * avoids pulling large media through this process. Everything else is sent as\n * base64 `data`, with the container inferred from the input's MIME type or\n * filename when the caller didn't pin `audio_format`.\n */\nexport async function normalizeAudioInput(\n  audio: TranscriptionOptions['audio'],\n  formatHint: string | undefined,\n): Promise<BytePlusASRAudio> {\n  const withFormat = (\n    payload: BytePlusASRAudio,\n    inferred?: string,\n  ): BytePlusASRAudio => {\n    const format = formatHint ?? inferred\n    return format ? { ...payload, format } : payload\n  }\n\n  if (typeof audio === 'string') {\n    if (/^https?:\\/\\//i.test(audio)) {\n      return withFormat({ url: audio }, extensionOf(audio))\n    }\n    const dataUrl = /^data:([^;,]+)?(?:;[^,]*)*,(.*)$/s.exec(audio)\n    if (dataUrl) {\n      return withFormat({ data: dataUrl[2] ?? '' }, formatFromMime(dataUrl[1]))\n    }\n    // A bare string that is neither a URL nor a data URL is already base64.\n    return withFormat({ data: audio })\n  }\n\n  if (audio instanceof ArrayBuffer) {\n    return withFormat({ data: arrayBufferToBase64(audio) })\n  }\n\n  const data = arrayBufferToBase64(await audio.arrayBuffer())\n  const inferred =\n    ('name' in audio && typeof audio.name === 'string'\n      ? extensionOf(audio.name)\n      : undefined) ?? formatFromMime(audio.type)\n  return withFormat({ data }, inferred)\n}\n\nfunction extensionOf(pathOrName: string): string | undefined {\n  const withoutQuery = pathOrName.split(/[?#]/)[0] ?? ''\n  const match = /\\.([a-z0-9]+)$/i.exec(withoutQuery)\n  return match?.[1]?.toLowerCase()\n}\n\nfunction formatFromMime(mime: string | undefined): string | undefined {\n  if (!mime || !mime.startsWith('audio/')) return undefined\n  const subtype = mime.slice('audio/'.length).toLowerCase()\n  if (subtype === 'mpeg') return 'mp3'\n  if (subtype === 'x-wav' || subtype === 'wave') return 'wav'\n  return subtype.replace(/^x-/, '')\n}\n\n/**\n * Creates a BytePlus Seed Speech transcription adapter with an explicit API\n * key.\n *\n * The key is the **Seed Speech** key, not the Ark key used by the chat, image\n * and video adapters.\n */\nexport function createBytePlusTranscription<\n  TModel extends BytePlusTranscriptionModel = BytePlusTranscriptionModel,\n>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<BytePlusVoiceConfig, 'apiKey'>,\n): BytePlusTranscriptionAdapter<TModel> {\n  return new BytePlusTranscriptionAdapter(model, { ...config, apiKey })\n}\n\n/**\n * Creates a BytePlus Seed Speech transcription adapter, reading the API key\n * from `BYTEPLUS_VOICE_API_KEY`.\n *\n * @throws Error if `BYTEPLUS_VOICE_API_KEY` is not set.\n */\nexport function byteplusTranscription<\n  TModel extends BytePlusTranscriptionModel = BytePlusTranscriptionModel,\n>(\n  model: TModel,\n  config?: Omit<BytePlusVoiceConfig, 'apiKey'>,\n): BytePlusTranscriptionAdapter<TModel> {\n  return createBytePlusTranscription(\n    model,\n    getBytePlusVoiceApiKeyFromEnv(),\n    config,\n  )\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,143 @@
+import { BaseTTSAdapter } from '@tanstack/ai/adapters';
+import { TTSOptions } from '@tanstack/ai';
+import { InternalLogger } from '@tanstack/ai/adapter-internals';
+import { BytePlusVoiceConfig } from '../utils/client.js';
+import { BytePlusTTSModel } from '../model-meta.js';
+import { BytePlusTTSAudioFormat, BytePlusTTSCreateRequest } from '../audio/wire-types.js';
+import { BytePlusTTSProviderOptions, BytePlusTTSResult } from '../audio/tts-provider-options.js';
+/**
+ * Voice used when neither `TTSOptions.voice` nor `modelOptions.speaker` is
+ * set — the English female "Stokie" voice from the TTS 2.0 generation.
+ */
+export declare const BYTEPLUS_DEFAULT_TTS_SPEAKER = "en_female_stokie_uranus_bigtts";
+/**
+ * Hard cap on a single Seed Speech synthesis, in seconds. Longer scripts must
+ * be split across calls and stitched client-side.
+ *
+ * The cap applies to the *pre-rate* length the service bills on — the
+ * `original_duration` it returns. The delivered clip can run longer than this
+ * when `speech_rate` slows it down.
+ */
+export declare const BYTEPLUS_TTS_MAX_OUTPUT_SECONDS = 120;
+/**
+ * BytePlus Seed Speech text-to-speech adapter.
+ *
+ * Talks to `POST {baseURL}/api/v3/tts/create` on the Seed Speech voice host.
+ * Two things differ from the Ark-hosted adapters in this package:
+ *
+ * - **Separate API key.** Seed Speech authenticates with `X-Api-Key` and its
+ *   own key (`BYTEPLUS_VOICE_API_KEY`). An `ARK_API_KEY` sent here is
+ *   rejected with `45000010 Invalid X-Api-Key`.
+ * - **120 s output cap.** A single call synthesises at most
+ *   {@link BYTEPLUS_TTS_MAX_OUTPUT_SECONDS} seconds of audio; longer scripts
+ *   have to be split and stitched client-side. The cap is measured before
+ *   `speech_rate` is applied, so a slowed clip can play for longer than that
+ *   — `result.duration` is the delivered length and `result.originalDuration`
+ *   is the metered one.
+ *
+ * Streaming synthesis (`tts/unidirectional` and the WebSocket API) is not
+ * covered by this adapter — note that endpoint spells the text field `text`,
+ * while this one uses `text_prompt`.
+ *
+ * @example
+ * ```ts
+ * const adapter = byteplusSpeech('seed-audio-1.0')
+ * const result = await generateSpeech({
+ *   adapter,
+ *   text: 'welcome to the guitar store',
+ *   voice: 'en_female_stokie_uranus_bigtts',
+ *   format: 'mp3',
+ * })
+ * ```
+ */
+export declare class BytePlusTTSAdapter<TModel extends BytePlusTTSModel = BytePlusTTSModel> extends BaseTTSAdapter<TModel, BytePlusTTSProviderOptions> {
+    readonly name: "byteplus";
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly defaultHeaders;
+    private readonly fetchImpl;
+    constructor(model: TModel, config: BytePlusVoiceConfig);
+    generateSpeech(options: TTSOptions<BytePlusTTSProviderOptions>): Promise<BytePlusTTSResult>;
+}
+/**
+ * Build the JSON body for `POST /api/v3/tts/create`, resolving the voice,
+ * output format and rate fields in one place.
+ *
+ * Returns the request `body`, the resolved `audioFormat` and the
+ * `sampleRate`, which the caller reports on the result and turns into a
+ * `contentType`.
+ */
+export declare function buildTTSRequestBody(options: {
+    model: string;
+    text: string;
+    voice: string | undefined;
+    format: TTSOptions['format'] | undefined;
+    speed: number | undefined;
+    modelOptions: BytePlusTTSProviderOptions | undefined;
+    logger: InternalLogger;
+}): {
+    body: BytePlusTTSCreateRequest;
+    audioFormat: BytePlusTTSAudioFormat;
+    sampleRate: number;
+};
+/**
+ * Convert the cross-provider `TTSOptions.speed` multiplier into Seed Speech's
+ * `speech_rate` percentage.
+ *
+ * ```
+ * speech_rate = clamp(round((speed - 1) * 100), -50, 100)
+ * ```
+ *
+ * so `0.5 → -50`, `1.0 → 0`, `1.5 → 50`, `2.0 → 100`.
+ *
+ * The range `-50`..`100` and both multiplier anchors (`-50` = 0.5×,
+ * `100` = 2×) are documented, and hold on both the `/tts/create` and
+ * `/tts/unidirectional` endpoints.
+ *
+ * `TTSOptions.speed` spans a wider 0.25×–4× than the endpoint supports, so
+ * anything outside 0.5×–2× clamps (and warns) rather than erroring.
+ */
+export declare function toSpeechRate(speed: number, logger?: InternalLogger): number;
+/**
+ * MIME type for a Seed Speech output format.
+ *
+ * `pcm` is raw little-endian 16-bit samples, so its media type has to carry
+ * the sample rate (RFC 3551/3555). The adapter always resolves a rate, so one
+ * is always available here.
+ */
+export declare function getContentType(format: BytePlusTTSAudioFormat, sampleRate?: number): string;
+/**
+ * Coerce a `duration` / `original_duration` field to a usable number of
+ * seconds.
+ *
+ * Both are documented as float **seconds**, so this only parses the string
+ * form and drops values that can't be a length (zero, negative, non-numeric).
+ * Note that `duration` may legitimately exceed
+ * {@link BYTEPLUS_TTS_MAX_OUTPUT_SECONDS} — a clip synthesised at
+ * `speech_rate: -50` runs at half speed, so up to 120 s of billed audio can
+ * be delivered as up to 240 s of playback. Do not "correct" a large value
+ * here; the cap applies to `original_duration`.
+ *
+ * The subtitle timings are the mixed-unit exception: those are milliseconds
+ * and are passed through untouched on {@link BytePlusTTSResult.subtitle}.
+ */
+export declare function toDurationSeconds(raw: number | string | undefined): number | undefined;
+/**
+ * Creates a BytePlus Seed Speech TTS adapter with an explicit API key.
+ *
+ * The key is the **Seed Speech** key, not the Ark key used by the chat, image
+ * and video adapters.
+ *
+ * @example
+ * ```ts
+ * const adapter = createBytePlusSpeech('seed-audio-1.0', process.env.BYTEPLUS_VOICE_API_KEY!)
+ * ```
+ */
+export declare function createBytePlusSpeech<TModel extends BytePlusTTSModel = BytePlusTTSModel>(model: TModel, apiKey: string, config?: Omit<BytePlusVoiceConfig, 'apiKey'>): BytePlusTTSAdapter<TModel>;
+/**
+ * Creates a BytePlus Seed Speech TTS adapter, reading the API key from
+ * `BYTEPLUS_VOICE_API_KEY`.
+ *
+ * @throws Error if `BYTEPLUS_VOICE_API_KEY` is not set.
+ */
+export declare function byteplusSpeech<TModel extends BytePlusTTSModel = BytePlusTTSModel>(model: TModel, config?: Omit<BytePlusVoiceConfig, 'apiKey'>): BytePlusTTSAdapter<TModel>;