@deepseek-ai/dsh-experimental-api-speech-to-text 0.1.7-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/experimental/api-speech-to-text/README.md
+README.md: ecc83c15b4217323c074733ae77259261598803c
+README.zh.md: 46ac6a16c902c32f2effb23a98141b1afbdccd37

package/README.md

@@ -0,0 +1,78 @@
+---
+description: "Expose bounded transient transcription through the authenticated Web Remote."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-experimental-api-speech-to-text
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The `speech` Remote connects browser recordings to `ctx.speechToText`. It exposes provider discovery and one complete-recording transcription call.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Compose with the speech Service Definition and Typert. `maxAudioBytes` and `maxDurationSeconds` limit accepted recordings. The browser UI mounts this package’s generated `/remote` contribution when enabled.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Maintainer details — click to expand</summary>
+
+`catalog()` exposes provider identities, the default selection and recording limits. `transcribe()` validates canonical base64 and 16 kHz mono PCM16 WAV before resolving the selected provider. The existing gateway owns authentication and cancellation transport. Audio is transient, never a Session event or attachment; only the user’s later ordinary submission records recognized text. No runtime invariant companion is published because validation is stateless and preparation belongs to the provider.
+
+`follow()` streams complete catalogs, including preparation states and current preferences. `prepare()` starts or joins a Host task; `cancelPreparation()` explicitly cancels it. `configure()` persists the supplied preference fields. A disconnected observer does not cancel preparation.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+[Voice input subsystem](../../../docs/subsystems/voice-input.md)
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as recordings and preparation remain outside model requests; ordinary user submission owns any later text.
+
+#### KV Cache effect
+
+No direct effect; ordinary submission owns the message content.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- No file upload, persistent transcript history or streaming protocol is exposed. Base64 adds transport overhead; recordings remain bounded by the advertised limits.
+
+-----
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Maintainer details — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,78 @@
+---
+description: "通过带认证的 Web Remote 提供有界临时转写。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-experimental-api-speech-to-text
+
+[English](README.md) | 中文
+
+## 概述
+
+`speech` Remote 将浏览器录音连接至 `ctx.speechToText`，提供 Provider 发现和完整录音转写调用。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用此包
+
+与语音服务定义和 Typert 组合。`maxAudioBytes` 与 `maxDurationSeconds` 限制接收的录音。浏览器 UI 启用时挂载本包生成的 `/remote` 贡献。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>维护者信息 — 点击展开</summary>
+
+`catalog()` 暴露 Provider 标识、默认选择与录音限制。`transcribe()` 在解析指定 Provider 前校验规范 base64 与 16 kHz 单声道 PCM16 WAV。现有网关负责认证和取消传输。音频是临时数据，不成为 Session 事件或附件；只有用户之后的普通提交才记录识别文字。不发布运行时不变量伴随模块，因为校验无状态，准备属于 Provider。
+
+`follow()` 推送包含准备状态和当前偏好的完整目录。`prepare()` 启动或加入 Host 任务；`cancelPreparation()` 显式取消任务。`configure()` 持久化传入的偏好字段。观察连接断开不会取消准备。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+[语音输入子系统](../../../docs/subsystems/voice-input.zh.md)
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为录音与准备不进入模型请求；之后的文字由普通用户提交拥有。
+
+#### KV 缓存影响
+
+没有直接影响；普通提交拥有消息内容。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 不提供文件上传、持久化转写历史或流式协议。Base64 会增加传输开销；录音受公布的限制约束。
+
+-----
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者信息 — 点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,218 @@
+import z from "@deepseek-ai/schemastery";
+import { Remote, RemoteError, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { validateWave } from "@deepseek-ai/dsh-experimental-speech-to-text/wave";
+//#region lib/types/index.js
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) if (kind === "field") initializers.unshift(_);
+		else descriptor[key] = _;
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+let SpeechController = (() => {
+	let _classSuper = TypertRemoteService;
+	let _instanceExtraInitializers = [];
+	let _catalog_decorators;
+	let _follow_decorators;
+	let _configure_decorators;
+	let _prepare_decorators;
+	let _cancelPreparation_decorators;
+	let _transcribe_decorators;
+	return class SpeechController extends _classSuper {
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_catalog_decorators = [Remote];
+			_follow_decorators = [Remote({ mode: "stream" })];
+			_configure_decorators = [Remote];
+			_prepare_decorators = [Remote];
+			_cancelPreparation_decorators = [Remote];
+			_transcribe_decorators = [Remote];
+			__esDecorate(this, null, _catalog_decorators, {
+				kind: "method",
+				name: "catalog",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "catalog" in obj,
+					get: (obj) => obj.catalog
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _follow_decorators, {
+				kind: "method",
+				name: "follow",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "follow" in obj,
+					get: (obj) => obj.follow
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _configure_decorators, {
+				kind: "method",
+				name: "configure",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "configure" in obj,
+					get: (obj) => obj.configure
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _prepare_decorators, {
+				kind: "method",
+				name: "prepare",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "prepare" in obj,
+					get: (obj) => obj.prepare
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _cancelPreparation_decorators, {
+				kind: "method",
+				name: "cancelPreparation",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "cancelPreparation" in obj,
+					get: (obj) => obj.cancelPreparation
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _transcribe_decorators, {
+				kind: "method",
+				name: "transcribe",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "transcribe" in obj,
+					get: (obj) => obj.transcribe
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		config = __runInitializers(this, _instanceExtraInitializers);
+		static inject = ["speechToText", "typert"];
+		static Config = z.object({
+			maxAudioBytes: z.natural().min(46).default(4 * 1024 * 1024),
+			maxDurationSeconds: z.number().min(1).default(120)
+		});
+		constructor(ctx, config) {
+			super(ctx, "speechController", { namespace: "speech" });
+			this.config = config;
+		}
+		/**
+		* Read provider choices without preparing a recognizer.
+		* @returns available providers, resolved default, and recording limits.
+		*/
+		catalog() {
+			return {
+				...this.ctx.speechToText.snapshot(),
+				...this.config
+			};
+		}
+		/**
+		* Follow provider readiness independently of Session and preparation lifetimes.
+		* @param signal - Client observation lifetime.
+		* @returns initial and subsequent complete readiness snapshots.
+		*/
+		async *follow(signal) {
+			for await (const snapshot of this.ctx.speechToText.follow(signal)) yield {
+				...snapshot,
+				...this.config
+			};
+		}
+		/**
+		* Persist the user's recognition preferences.
+		* @param patch - changed preference fields.
+		* @returns after preferences are saved.
+		*/
+		configure(patch) {
+			return this.ctx.speechToText.configure(patch);
+		}
+		/**
+		* Start or join one Host-owned preparation task.
+		* @param providerId - selected recognizer.
+		*/
+		prepare(providerId) {
+			this.ctx.speechToText.prepare(providerId);
+		}
+		/**
+		* Explicitly cancel resource preparation.
+		* @param providerId - selected recognizer.
+		* @returns after the preparation task settles.
+		*/
+		cancelPreparation(providerId) {
+			return this.ctx.speechToText.cancelPreparation(providerId);
+		}
+		/**
+		* Validate and transcribe one recording through the explicit provider selection.
+		* @param request - canonical WAV encoded as base64, provider id and language hint.
+		* @param signal - Client cancellation or Remote contribution disposal.
+		* @returns final transcript without adding a Session event.
+		*/
+		async transcribe(request, signal) {
+			signal.throwIfAborted();
+			const encoded = request.audioBase64;
+			if (encoded.length > Math.ceil(this.config.maxAudioBytes / 3) * 4) throw new RemoteError("speech/invalid-audio", "Audio is invalid or exceeds the configured byte limit", { reason: "encoding-or-size" });
+			const audio = Buffer.from(encoded, "base64");
+			try {
+				if (audio.toString("base64") !== encoded) throw new Error("Audio must use canonical base64 encoding");
+				if (audio.length > this.config.maxAudioBytes) throw new Error("Audio exceeds the configured byte limit");
+				validateWave(audio, this.config.maxDurationSeconds);
+				const spec = this.ctx.speechToText.resolve({
+					audio,
+					...request.providerId === void 0 ? {} : { providerId: request.providerId },
+					...request.language === void 0 ? {} : { language: request.language }
+				});
+				return await this.ctx.speechToText.transcribe(spec, signal);
+			} catch (error) {
+				signal.throwIfAborted();
+				const reason = error instanceof Error ? error.message : String(error);
+				throw new RemoteError("speech/transcription-failed", reason, { reason });
+			}
+		}
+	};
+})();
+//#endregion
+export { SpeechController as default };

package/lib/typert.host.d.ts

@@ -0,0 +1,3 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
+
+export declare const TYPERT: unknown