@openclaw/gradium-speech 0.0.0 → 2026.6.9

package/README.md

@@ -1,3 +1,12 @@
-# @openclaw/gradium-speech
+# OpenClaw Gradium Plugin
 
-Reserved placeholder for the official OpenClaw plugin package. Use a published release version instead.
+Official OpenClaw plugin for Gradium.
+
+Install from OpenClaw:
+
+```bash
+openclaw plugins install @openclaw/gradium-speech
+openclaw gateway restart
+```
+
+See <https://docs.openclaw.ai/providers/gradium> for setup and configuration.

package/dist/index.js

@@ -0,0 +1,13 @@
+import { buildGradiumSpeechProvider } from "./speech-provider.js";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+//#region extensions/gradium/index.ts
+var gradium_default = definePluginEntry({
+	id: "gradium",
+	name: "Gradium Speech",
+	description: "Bundled Gradium speech provider",
+	register(api) {
+		api.registerSpeechProvider(buildGradiumSpeechProvider());
+	}
+});
+//#endregion
+export { gradium_default as default };

package/dist/shared.js

@@ -0,0 +1,38 @@
+//#region extensions/gradium/shared.ts
+const DEFAULT_GRADIUM_BASE_URL = "https://api.gradium.ai";
+const DEFAULT_GRADIUM_VOICE_ID = "YTpq7expH9539ERJ";
+const GRADIUM_VOICES = [
+	{
+		id: "YTpq7expH9539ERJ",
+		name: "Emma"
+	},
+	{
+		id: "LFZvm12tW_z0xfGo",
+		name: "Kent"
+	},
+	{
+		id: "Eu9iL_CYe8N-Gkx_",
+		name: "Tiffany"
+	},
+	{
+		id: "2H4HY2CBNyJHBCrP",
+		name: "Christina"
+	},
+	{
+		id: "jtEKaLYNn6iif5PR",
+		name: "Sydney"
+	},
+	{
+		id: "KWJiFWu2O9nMPYcR",
+		name: "John"
+	},
+	{
+		id: "3jUdJyOi9pgbxBTK",
+		name: "Arthur"
+	}
+];
+function normalizeGradiumBaseUrl(baseUrl) {
+	return (baseUrl?.trim())?.replace(/\/+$/, "") || DEFAULT_GRADIUM_BASE_URL;
+}
+//#endregion
+export { DEFAULT_GRADIUM_VOICE_ID, GRADIUM_VOICES, normalizeGradiumBaseUrl };

package/dist/speech-provider.js

@@ -0,0 +1,107 @@
+import { GRADIUM_VOICES, normalizeGradiumBaseUrl } from "./shared.js";
+import { gradiumTTS } from "./tts.js";
+import { normalizeResolvedSecretInputString } from "openclaw/plugin-sdk/secret-input";
+import { asObject, trimToUndefined } from "openclaw/plugin-sdk/speech";
+//#region extensions/gradium/speech-provider.ts
+const DEFAULT_GENERATED_AUDIO_MAX_BYTES = 16 * 1024 * 1024;
+function normalizeGradiumProviderConfig(rawConfig) {
+	const raw = asObject(asObject(rawConfig.providers)?.gradium) ?? asObject(rawConfig.gradium);
+	return {
+		apiKey: normalizeResolvedSecretInputString({
+			value: raw?.apiKey,
+			path: "messages.tts.providers.gradium.apiKey"
+		}),
+		baseUrl: normalizeGradiumBaseUrl(trimToUndefined(raw?.baseUrl)),
+		voiceId: trimToUndefined(raw?.voiceId) ?? "YTpq7expH9539ERJ"
+	};
+}
+function readGradiumProviderConfig(config) {
+	const defaults = normalizeGradiumProviderConfig({});
+	return {
+		apiKey: trimToUndefined(config.apiKey) ?? defaults.apiKey,
+		baseUrl: normalizeGradiumBaseUrl(trimToUndefined(config.baseUrl) ?? defaults.baseUrl),
+		voiceId: trimToUndefined(config.voiceId) ?? defaults.voiceId
+	};
+}
+function resolveGeneratedAudioMaxBytes(req) {
+	const configured = req.cfg.agents?.defaults?.mediaMaxMb;
+	if (typeof configured === "number" && Number.isFinite(configured) && configured > 0) return Math.floor(configured * 1024 * 1024);
+	return DEFAULT_GENERATED_AUDIO_MAX_BYTES;
+}
+function parseDirectiveToken(ctx) {
+	switch (ctx.key) {
+		case "voice":
+		case "voice_id":
+		case "voiceid":
+		case "gradium_voice":
+		case "gradiumvoice":
+			if (!ctx.policy.allowVoice) return { handled: true };
+			return {
+				handled: true,
+				overrides: {
+					...ctx.currentOverrides,
+					voiceId: ctx.value
+				}
+			};
+		default: return { handled: false };
+	}
+}
+function buildGradiumSpeechProvider() {
+	return {
+		id: "gradium",
+		label: "Gradium",
+		autoSelectOrder: 30,
+		voices: GRADIUM_VOICES.map((v) => v.id),
+		resolveConfig: ({ rawConfig }) => normalizeGradiumProviderConfig(rawConfig),
+		parseDirectiveToken,
+		listVoices: async () => GRADIUM_VOICES.map((v) => ({
+			id: v.id,
+			name: v.name
+		})),
+		isConfigured: ({ providerConfig }) => Boolean(readGradiumProviderConfig(providerConfig).apiKey || process.env.GRADIUM_API_KEY),
+		synthesize: async (req) => {
+			const config = readGradiumProviderConfig(req.providerConfig);
+			const overrides = req.providerOverrides ?? {};
+			const apiKey = config.apiKey || process.env.GRADIUM_API_KEY;
+			if (!apiKey) throw new Error("Gradium API key missing");
+			const wantsVoiceNote = req.target === "voice-note";
+			const outputFormat = wantsVoiceNote ? "opus" : "wav";
+			return {
+				audioBuffer: await gradiumTTS({
+					text: req.text,
+					apiKey,
+					baseUrl: config.baseUrl,
+					voiceId: trimToUndefined(overrides.voiceId) ?? config.voiceId,
+					outputFormat,
+					timeoutMs: req.timeoutMs,
+					maxBytes: resolveGeneratedAudioMaxBytes(req)
+				}),
+				outputFormat,
+				fileExtension: wantsVoiceNote ? ".opus" : ".wav",
+				voiceCompatible: wantsVoiceNote
+			};
+		},
+		synthesizeTelephony: async (req) => {
+			const config = readGradiumProviderConfig(req.providerConfig);
+			const overrides = req.providerOverrides ?? {};
+			const apiKey = config.apiKey || process.env.GRADIUM_API_KEY;
+			if (!apiKey) throw new Error("Gradium API key missing");
+			const outputFormat = "ulaw_8000";
+			return {
+				audioBuffer: await gradiumTTS({
+					text: req.text,
+					apiKey,
+					baseUrl: config.baseUrl,
+					voiceId: trimToUndefined(overrides.voiceId) ?? config.voiceId,
+					outputFormat,
+					timeoutMs: req.timeoutMs,
+					maxBytes: resolveGeneratedAudioMaxBytes(req)
+				}),
+				outputFormat,
+				sampleRate: 8e3
+			};
+		}
+	};
+}
+//#endregion
+export { buildGradiumSpeechProvider };

package/dist/tts.js

@@ -0,0 +1,40 @@
+import { normalizeGradiumBaseUrl } from "./shared.js";
+import { assertOkOrThrowProviderError } from "openclaw/plugin-sdk/provider-http";
+import { readResponseWithLimit } from "openclaw/plugin-sdk/response-limit-runtime";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/ssrf-runtime";
+//#region extensions/gradium/tts.ts
+const DEFAULT_TTS_MAX_BYTES = 16 * 1024 * 1024;
+async function gradiumTTS(params) {
+	const { text, apiKey, baseUrl, voiceId, outputFormat, timeoutMs, maxBytes = DEFAULT_TTS_MAX_BYTES } = params;
+	const normalizedBaseUrl = normalizeGradiumBaseUrl(baseUrl);
+	const url = `${normalizedBaseUrl}/api/post/speech/tts`;
+	const hostname = new URL(normalizedBaseUrl).hostname;
+	const { response, release } = await fetchWithSsrFGuard({
+		url,
+		init: {
+			method: "POST",
+			headers: {
+				"x-api-key": apiKey,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				text,
+				voice_id: voiceId,
+				only_audio: true,
+				output_format: outputFormat,
+				json_config: JSON.stringify({ padding_bonus: 0 })
+			})
+		},
+		timeoutMs,
+		policy: { hostnameAllowlist: [hostname] },
+		auditContext: "gradium.tts"
+	});
+	try {
+		await assertOkOrThrowProviderError(response, "Gradium API error");
+		return await readResponseWithLimit(response, maxBytes, { onOverflow: ({ maxBytes: maxBytesLocal }) => /* @__PURE__ */ new Error(`Gradium TTS audio response exceeds ${maxBytesLocal} bytes`) });
+	} finally {
+		await release();
+	}
+}
+//#endregion
+export { gradiumTTS };

package/npm-shrinkwrap.json

@@ -0,0 +1,12 @@
+{
+  "name": "@openclaw/gradium-speech",
+  "version": "2026.6.9",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@openclaw/gradium-speech",
+      "version": "2026.6.9"
+    }
+  }
+}

package/openclaw.plugin.json

@@ -0,0 +1,22 @@
+{
+  "id": "gradium",
+  "activation": {
+    "onStartup": false
+  },
+  "setup": {
+    "providers": [
+      {
+        "id": "gradium",
+        "envVars": ["GRADIUM_API_KEY"]
+      }
+    ]
+  },
+  "contracts": {
+    "speechProviders": ["gradium"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -1,14 +1,50 @@
 {
   "name": "@openclaw/gradium-speech",
-  "version": "0.0.0",
-  "description": "Reserved package name for an official OpenClaw plugin.",
-  "license": "MIT",
+  "version": "2026.6.9",
+  "description": "OpenClaw Gradium speech plugin.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/openclaw/openclaw.git"
+    "url": "https://github.com/openclaw/openclaw"
   },
-  "publishConfig": {
-    "access": "public",
-    "tag": "placeholder"
-  }
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "clawhubSpec": "clawhub:@openclaw/gradium-speech",
+      "npmSpec": "@openclaw/gradium-speech",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.6.8"
+    },
+    "compat": {
+      "pluginApi": ">=2026.6.9"
+    },
+    "build": {
+      "openclawVersion": "2026.6.9",
+      "bundledDist": false
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    },
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ]
+  },
+  "files": [
+    "dist/**",
+    "openclaw.plugin.json",
+    "npm-shrinkwrap.json",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "openclaw": ">=2026.6.9"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "bundledDependencies": []
 }