koishi-plugin-tts-base 1.0.0

package/lib/commands.d.ts

@@ -0,0 +1,3 @@
+import { Context } from 'koishi';
+import { Config } from './config';
+export declare function apply(ctx: Context, config: Config): void;

package/lib/compatible.d.ts

@@ -0,0 +1,8 @@
+import { Context, h, Service } from 'koishi';
+import { TTSInput, TTSProvider } from './types';
+export declare abstract class VitsCompatible extends Service implements TTSProvider {
+    constructor(ctx: Context);
+    abstract provideVoiceIds(): Promise<string[]>;
+    abstract say(input: TTSInput): Promise<h>;
+    isSupportVoiceId(voiceId: string | string[]): Promise<boolean>;
+}

package/lib/config.d.ts

@@ -0,0 +1,10 @@
+import { Schema } from 'koishi';
+export declare const name = "tts-base";
+export interface Config {
+    defaultSpeaker?: string;
+}
+export declare const Config: Schema<Config>;
+export declare const usage = "\n\u672C\u63D2\u4EF6\u4F5C\u4E3A tts \u670D\u52A1\u7684\u524D\u7F6E\u57FA\u7840\u63D2\u4EF6\u3002\n\u6B64\u63D2\u4EF6\u6CA1\u6709\u5305\u542B\u4EFB\u4F55\u8BED\u97F3\u670D\u52A1\uFF0C\u5B83\u53EA\u662F\u4E00\u4E2A\u524D\u7F6E\u63D2\u4EF6\u3002";
+export declare const inject: {
+    optional: string[];
+};

package/lib/index.cjs

@@ -0,0 +1,240 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name2 in all)
+    __defProp(target, name2, { get: all[name2], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/locales/zh-CN.yml
+var require_zh_CN = __commonJS({
+  "src/locales/zh-CN.yml"(exports2, module2) {
+    module2.exports = { commands: { tts: { description: "使用 TTS 朗读文本。", usage: "tts <text> [-s <speaker>]", examples: "tts 你好世界\ntts 你好世界 -s speaker1", options: { speaker: "选择说话人音色。" }, messages: { "no-speaker": "未指定说话人音色，请在配置中设置默认说话人或使用 -s 选项指定。", "invalid-speaker": "无效的说话人音色：{0}。", "generate-failed": "TTS 生成失败，请稍后再试。" } } } };
+  }
+});
+
+// src/locales/en-US.yml
+var require_en_US = __commonJS({
+  "src/locales/en-US.yml"(exports2, module2) {
+    module2.exports = { commands: { tts: { description: "Read text aloud using TTS.", usage: "tts <text> [-s <speaker>]", examples: "tts Hello world\ntts Hello world -s speaker1", options: { speaker: "Select speaker voice." }, messages: { "no-speaker": "No speaker specified. Please set a default speaker in config or use -s option.", "invalid-speaker": "Invalid speaker voice: {0}.", "generate-failed": "TTS generation failed, please try again later." } } } };
+  }
+});
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BaseTTSProvider: () => BaseTTSProvider,
+  Config: () => Config,
+  TTSService: () => TTSService,
+  VitsCompatible: () => VitsCompatible,
+  apply: () => apply2,
+  inject: () => inject,
+  name: () => name,
+  usage: () => usage
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/service.ts
+var import_koishi = require("koishi");
+var TTSService = class extends import_koishi.Service {
+  constructor(ctx, config) {
+    super(ctx, "tts", true);
+    this.ctx = ctx;
+    this.config = config;
+    if (!ctx["vits"]) {
+      ctx.set("vits", this);
+    }
+  }
+  static {
+    __name(this, "TTSService");
+  }
+  _voiceIds = [];
+  _voiceHandlers = [];
+  _voiceProvider = [];
+  registerVoiceId(id) {
+    this._voiceIds.push(id);
+    this._updateSchema();
+    const disposeFn = /* @__PURE__ */ __name(() => {
+      this._voiceIds.splice(this._voiceIds.indexOf(id), 1);
+    }, "disposeFn");
+    return this[import_koishi.Context.current].effect(() => disposeFn);
+  }
+  hasVoiceId(id) {
+    return this._voiceIds.includes(id);
+  }
+  getVoiceIds() {
+    return Object.freeze(this._voiceIds);
+  }
+  registerVoiceIds(voices) {
+    this._voiceIds.push(...voices);
+    this._updateSchema();
+    const disposeFn = /* @__PURE__ */ __name(() => {
+      for (const voice of voices) {
+        this._voiceIds.splice(this._voiceIds.indexOf(voice), 1);
+      }
+    }, "disposeFn");
+    return this[import_koishi.Context.current].effect(() => disposeFn);
+  }
+  registerVoiceProvider(provider) {
+    this._voiceProvider.push(provider);
+    const disposeFn = /* @__PURE__ */ __name(() => {
+      this._voiceProvider.splice(this._voiceProvider.indexOf(provider), 1);
+    }, "disposeFn");
+    return this[import_koishi.Context.current].effect(() => disposeFn);
+  }
+  registerHandler(handler) {
+    if (typeof handler === "function") {
+      handler = { say: handler };
+    }
+    this._voiceHandlers.push(handler);
+    const disposeFn = /* @__PURE__ */ __name(() => {
+      this._voiceHandlers.splice(this._voiceHandlers.indexOf(handler), 1);
+    }, "disposeFn");
+    return this[import_koishi.Context.current].effect(() => disposeFn);
+  }
+  async say(input) {
+    if (typeof input === "string") {
+      input = { input, voiceId: this._voiceIds[0] };
+    }
+    input.speaker_id = input.voiceId;
+    await this._lazyInitVoiceProvider();
+    for (const handler of this._voiceHandlers) {
+      if (handler.isSupportVoiceId && !handler.isSupportVoiceId(input.voiceId)) {
+        continue;
+      }
+      try {
+        return await handler.say(input);
+      } catch (error) {
+      }
+    }
+    if (this.ctx["vits"]) {
+      return await this.ctx["vits"].say(input);
+    }
+    throw new Error(
+      `voice id ${input.voiceId} not found or generation failed`
+    );
+  }
+  async _lazyInitVoiceProvider() {
+    for (const provider of this._voiceProvider) {
+      if (this._voiceHandlers.indexOf(provider) !== -1) {
+        continue;
+      }
+      this.registerVoiceIds(await provider.provideVoiceIds());
+      this._voiceHandlers.push(provider);
+    }
+  }
+  _updateSchema() {
+    this.ctx.schema.set(
+      "voices",
+      import_koishi.Schema.union(
+        this._voiceIds.map((id) => import_koishi.Schema.const(id)).concat(import_koishi.Schema.const("????").hidden())
+      )
+    );
+  }
+};
+var BaseTTSProvider = class {
+  constructor(ctx, config) {
+    this.config = config;
+    ctx.tts.registerVoiceProvider(this);
+  }
+  static {
+    __name(this, "BaseTTSProvider");
+  }
+  async isSupportVoiceId(voiceId) {
+    return true;
+  }
+};
+
+// src/commands.ts
+function apply(ctx, config) {
+  ctx.command("tts <text:text>", { checkArgCount: true }).option("speaker", "-s <speaker:string>").action(async ({ session, options }, text) => {
+    const voiceId = options.speaker ?? config.defaultSpeaker;
+    if (!voiceId) {
+      return session.text(".no-speaker");
+    }
+    if (!ctx.tts.hasVoiceId(voiceId)) {
+      return session.text(".invalid-speaker", [voiceId]);
+    }
+    try {
+      const audio = await ctx.tts.say({
+        input: text,
+        voiceId
+      });
+      return audio;
+    } catch (e) {
+      ctx.logger.error(e);
+      return session.text(".generate-failed");
+    }
+  });
+}
+__name(apply, "apply");
+
+// src/config.ts
+var import_koishi2 = require("koishi");
+var name = "tts-base";
+var Config = import_koishi2.Schema.object({
+  defaultSpeaker: import_koishi2.Schema.dynamic("voices").description(
+    "Default speaker voice ID / 默认说话人音色"
+  )
+});
+var usage = `
+本插件作为 tts 服务的前置基础插件。
+此插件没有包含任何语音服务，它只是一个前置插件。`;
+var inject = {
+  optional: ["vits"]
+};
+
+// src/compatible.ts
+var import_koishi3 = require("koishi");
+var VitsCompatible = class extends import_koishi3.Service {
+  static {
+    __name(this, "VitsCompatible");
+  }
+  constructor(ctx) {
+    super(ctx, "vits", true);
+    ctx.tts.registerVoiceProvider(this);
+  }
+  async isSupportVoiceId(voiceId) {
+    return true;
+  }
+};
+
+// src/index.ts
+function apply2(ctx, config) {
+  ctx.i18n.define("zh-CN", require_zh_CN());
+  ctx.i18n.define("en-US", require_en_US());
+  ctx.plugin(TTSService, config);
+  ctx.plugin(
+    {
+      apply,
+      inject: ["tts"]
+    },
+    config
+  );
+}
+__name(apply2, "apply");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseTTSProvider,
+  Config,
+  TTSService,
+  VitsCompatible,
+  apply,
+  inject,
+  name,
+  usage
+});

package/lib/index.d.ts

@@ -0,0 +1,7 @@
+import { Context } from 'koishi';
+import { Config } from './config';
+export * from './config';
+export declare function apply(ctx: Context, config: Config): void;
+export * from './service';
+export * from './compatible';
+export * from './types';

package/lib/index.mjs

@@ -0,0 +1,210 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+// src/locales/zh-CN.yml
+var require_zh_CN = __commonJS({
+  "src/locales/zh-CN.yml"(exports, module) {
+    module.exports = { commands: { tts: { description: "使用 TTS 朗读文本。", usage: "tts <text> [-s <speaker>]", examples: "tts 你好世界\ntts 你好世界 -s speaker1", options: { speaker: "选择说话人音色。" }, messages: { "no-speaker": "未指定说话人音色，请在配置中设置默认说话人或使用 -s 选项指定。", "invalid-speaker": "无效的说话人音色：{0}。", "generate-failed": "TTS 生成失败，请稍后再试。" } } } };
+  }
+});
+
+// src/locales/en-US.yml
+var require_en_US = __commonJS({
+  "src/locales/en-US.yml"(exports, module) {
+    module.exports = { commands: { tts: { description: "Read text aloud using TTS.", usage: "tts <text> [-s <speaker>]", examples: "tts Hello world\ntts Hello world -s speaker1", options: { speaker: "Select speaker voice." }, messages: { "no-speaker": "No speaker specified. Please set a default speaker in config or use -s option.", "invalid-speaker": "Invalid speaker voice: {0}.", "generate-failed": "TTS generation failed, please try again later." } } } };
+  }
+});
+
+// src/service.ts
+import { Context, Schema, Service } from "koishi";
+var TTSService = class extends Service {
+  constructor(ctx, config) {
+    super(ctx, "tts", true);
+    this.ctx = ctx;
+    this.config = config;
+    if (!ctx["vits"]) {
+      ctx.set("vits", this);
+    }
+  }
+  static {
+    __name(this, "TTSService");
+  }
+  _voiceIds = [];
+  _voiceHandlers = [];
+  _voiceProvider = [];
+  registerVoiceId(id) {
+    this._voiceIds.push(id);
+    this._updateSchema();
+    const disposeFn = /* @__PURE__ */ __name(() => {
+      this._voiceIds.splice(this._voiceIds.indexOf(id), 1);
+    }, "disposeFn");
+    return this[Context.current].effect(() => disposeFn);
+  }
+  hasVoiceId(id) {
+    return this._voiceIds.includes(id);
+  }
+  getVoiceIds() {
+    return Object.freeze(this._voiceIds);
+  }
+  registerVoiceIds(voices) {
+    this._voiceIds.push(...voices);
+    this._updateSchema();
+    const disposeFn = /* @__PURE__ */ __name(() => {
+      for (const voice of voices) {
+        this._voiceIds.splice(this._voiceIds.indexOf(voice), 1);
+      }
+    }, "disposeFn");
+    return this[Context.current].effect(() => disposeFn);
+  }
+  registerVoiceProvider(provider) {
+    this._voiceProvider.push(provider);
+    const disposeFn = /* @__PURE__ */ __name(() => {
+      this._voiceProvider.splice(this._voiceProvider.indexOf(provider), 1);
+    }, "disposeFn");
+    return this[Context.current].effect(() => disposeFn);
+  }
+  registerHandler(handler) {
+    if (typeof handler === "function") {
+      handler = { say: handler };
+    }
+    this._voiceHandlers.push(handler);
+    const disposeFn = /* @__PURE__ */ __name(() => {
+      this._voiceHandlers.splice(this._voiceHandlers.indexOf(handler), 1);
+    }, "disposeFn");
+    return this[Context.current].effect(() => disposeFn);
+  }
+  async say(input) {
+    if (typeof input === "string") {
+      input = { input, voiceId: this._voiceIds[0] };
+    }
+    input.speaker_id = input.voiceId;
+    await this._lazyInitVoiceProvider();
+    for (const handler of this._voiceHandlers) {
+      if (handler.isSupportVoiceId && !handler.isSupportVoiceId(input.voiceId)) {
+        continue;
+      }
+      try {
+        return await handler.say(input);
+      } catch (error) {
+      }
+    }
+    if (this.ctx["vits"]) {
+      return await this.ctx["vits"].say(input);
+    }
+    throw new Error(
+      `voice id ${input.voiceId} not found or generation failed`
+    );
+  }
+  async _lazyInitVoiceProvider() {
+    for (const provider of this._voiceProvider) {
+      if (this._voiceHandlers.indexOf(provider) !== -1) {
+        continue;
+      }
+      this.registerVoiceIds(await provider.provideVoiceIds());
+      this._voiceHandlers.push(provider);
+    }
+  }
+  _updateSchema() {
+    this.ctx.schema.set(
+      "voices",
+      Schema.union(
+        this._voiceIds.map((id) => Schema.const(id)).concat(Schema.const("????").hidden())
+      )
+    );
+  }
+};
+var BaseTTSProvider = class {
+  constructor(ctx, config) {
+    this.config = config;
+    ctx.tts.registerVoiceProvider(this);
+  }
+  static {
+    __name(this, "BaseTTSProvider");
+  }
+  async isSupportVoiceId(voiceId) {
+    return true;
+  }
+};
+
+// src/commands.ts
+function apply(ctx, config) {
+  ctx.command("tts <text:text>", { checkArgCount: true }).option("speaker", "-s <speaker:string>").action(async ({ session, options }, text) => {
+    const voiceId = options.speaker ?? config.defaultSpeaker;
+    if (!voiceId) {
+      return session.text(".no-speaker");
+    }
+    if (!ctx.tts.hasVoiceId(voiceId)) {
+      return session.text(".invalid-speaker", [voiceId]);
+    }
+    try {
+      const audio = await ctx.tts.say({
+        input: text,
+        voiceId
+      });
+      return audio;
+    } catch (e) {
+      ctx.logger.error(e);
+      return session.text(".generate-failed");
+    }
+  });
+}
+__name(apply, "apply");
+
+// src/config.ts
+import { Schema as Schema2 } from "koishi";
+var name = "tts-base";
+var Config = Schema2.object({
+  defaultSpeaker: Schema2.dynamic("voices").description(
+    "Default speaker voice ID / 默认说话人音色"
+  )
+});
+var usage = `
+本插件作为 tts 服务的前置基础插件。
+此插件没有包含任何语音服务，它只是一个前置插件。`;
+var inject = {
+  optional: ["vits"]
+};
+
+// src/compatible.ts
+import { Service as Service2 } from "koishi";
+var VitsCompatible = class extends Service2 {
+  static {
+    __name(this, "VitsCompatible");
+  }
+  constructor(ctx) {
+    super(ctx, "vits", true);
+    ctx.tts.registerVoiceProvider(this);
+  }
+  async isSupportVoiceId(voiceId) {
+    return true;
+  }
+};
+
+// src/index.ts
+function apply2(ctx, config) {
+  ctx.i18n.define("zh-CN", require_zh_CN());
+  ctx.i18n.define("en-US", require_en_US());
+  ctx.plugin(TTSService, config);
+  ctx.plugin(
+    {
+      apply,
+      inject: ["tts"]
+    },
+    config
+  );
+}
+__name(apply2, "apply");
+export {
+  BaseTTSProvider,
+  Config,
+  TTSService,
+  VitsCompatible,
+  apply2 as apply,
+  inject,
+  name,
+  usage
+};

package/lib/service.d.ts

@@ -0,0 +1,26 @@
+import { Context, h, Service } from 'koishi';
+import { Config, TTSHandler, TTSInput, TTSProvider } from '.';
+export declare class TTSService extends Service {
+    ctx: Context;
+    config: Config;
+    private _voiceIds;
+    private _voiceHandlers;
+    private _voiceProvider;
+    constructor(ctx: Context, config: Config);
+    registerVoiceId(id: string): () => void;
+    hasVoiceId(id: string): boolean;
+    getVoiceIds(): Readonly<string[]>;
+    registerVoiceIds(voices: string[]): () => void;
+    registerVoiceProvider(provider: TTSProvider): () => void;
+    registerHandler(handler: TTSHandler | TTSHandler['say']): () => void;
+    say(input: TTSInput | string): Promise<h>;
+    private _lazyInitVoiceProvider;
+    private _updateSchema;
+}
+export declare abstract class BaseTTSProvider<T = any> implements TTSProvider {
+    config: T;
+    constructor(ctx: Context, config: T);
+    abstract provideVoiceIds(): Promise<string[]>;
+    abstract say(input: TTSInput): Promise<h>;
+    isSupportVoiceId(voiceId: string | string[]): Promise<boolean>;
+}

package/lib/types.d.ts

@@ -0,0 +1,20 @@
+import { h, Session } from 'koishi';
+import { TTSService } from './service';
+export interface TTSHandler {
+    say(input: TTSInput): Promise<h>;
+    isSupportVoiceId?(voiceId: string | string[]): Promise<boolean>;
+}
+export interface TTSProvider extends TTSHandler {
+    provideVoiceIds(): Promise<string[]>;
+}
+export interface TTSInput {
+    session?: Session;
+    input: string | h;
+    speaker_id?: string | number;
+    voiceId?: string;
+}
+declare module 'koishi' {
+    interface Context {
+        tts: TTSService;
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "koishi-plugin-tts-base",
+  "description": "tts 服务基础插件",
+  "version": "1.0.0",
+  "main": "lib/index.cjs",
+  "module": "lib/index.mjs",
+  "typings": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./lib/index.mjs",
+      "require": "./lib/index.cjs",
+      "types": "./lib/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "type": "module",
+  "files": [
+    "lib",
+    "dist"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin",
+    "tts",
+    "tts-base",
+    "service"
+  ],
+  "peerDependencies": {
+    "koishi": "^4.18.10"
+  },
+  "devDependencies": {
+    "esbuild": "^0.20.2",
+    "esbuild-register": "^3.6.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-n": "^16.6.2",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-promise": "^7.2.1",
+    "koishi-plugin-puppeteer": "^3.9.0"
+  },
+  "koishi": {
+    "description": {
+      "zh": "tts 服务基础插件"
+    },
+    "service": {
+      "implements": [
+        "tts"
+      ]
+    }
+  },
+  "bugs": {
+    "url": "https://github.com/dingyi222666/koishi-plugin-tts-base/issues"
+  },
+  "homepage": "https://github.com/dingyi222666/koishi-plugin-tts-base#readme",
+  "repository": "git@github.com:dingyi222666/koishi-plugin-tts-base.git",
+  "author": "dingyi222666 <dingyi222666@foxmail.com>"
+}

package/readme.md

@@ -0,0 +1,209 @@
+# koishi-plugin-tts-base
+
+[![npm](https://img.shields.io/npm/v/koishi-plugin-tts-base?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-tts-base)
+
+TTS 服务的前置基础插件，为 Koishi 提供统一的 TTS 服务接口。
+
+## 功能
+
+- 提供统一的 `ctx.tts` 服务接口
+- 支持多个 TTS Provider 同时注册
+- 动态音色选择（配置界面自动显示可用音色）
+- 兼容旧版 `vits` 服务
+- 内置 `tts` 命令，支持 `-s` 选项选择音色
+
+## 用户使用
+
+```
+tts <文本>              # 使用默认音色朗读
+tts <文本> -s <音色>    # 使用指定音色朗读
+```
+
+## 开发者指南
+
+### 注册 TTS Provider
+
+推荐使用 `BaseTTSProvider` 基类来实现你的 TTS Provider：
+
+```typescript
+import { Context, h } from 'koishi'
+import { BaseTTSProvider, TTSInput } from 'koishi-plugin-tts-base'
+
+export interface Config {
+    // 你的配置
+}
+
+class MyTTSProvider extends BaseTTSProvider<Config> {
+    constructor(ctx: Context, config: Config) {
+        super(ctx, config)
+    }
+
+    async provideVoiceIds(): Promise<string[]> {
+        // 返回你的 TTS 服务支持的音色列表
+        return ['voice1', 'voice2', 'voice3']
+    }
+
+    async say(input: TTSInput): Promise<h> {
+        const text = input.input.toString()
+        const voiceId = input.voiceId
+
+        // 调用你的 TTS 服务生成音频
+        const audioBuffer = await this.generateAudio(text, voiceId)
+
+        return h.audio(audioBuffer, 'audio/wav')
+    }
+
+    async isSupportVoiceId(voiceId: string): Promise<boolean> {
+        // 可选：判断是否支持该音色
+        return ['voice1', 'voice2', 'voice3'].includes(voiceId)
+    }
+
+    private async generateAudio(
+        text: string,
+        voiceId: string
+    ): Promise<Buffer> {
+        // 实现你的音频生成逻辑
+    }
+}
+
+export function apply(ctx: Context, config: Config) {
+    ctx.plugin(MyTTSProvider, config)
+}
+
+export const inject = ['tts']
+```
+
+### 手动注册（不使用基类）
+
+如果你需要更灵活的控制，可以手动注册：
+
+```typescript
+import { Context } from 'koishi'
+import { TTSProvider } from 'koishi-plugin-tts-base'
+
+export function apply(ctx: Context) {
+    const provider: TTSProvider = {
+        async provideVoiceIds() {
+            return ['voice1', 'voice2']
+        },
+        async say(input) {
+            // 生成音频...
+            return h.audio(buffer, 'audio/wav')
+        },
+        async isSupportVoiceId(voiceId) {
+            return true
+        }
+    }
+
+    // 注册 provider
+    ctx.tts.registerVoiceProvider(provider)
+}
+
+export const inject = ['tts']
+```
+
+### 仅注册 Handler（不提供音色列表）
+
+如果你的服务支持任意音色或者音色由其他插件提供：
+
+```typescript
+ctx.tts.registerHandler({
+    async say(input) {
+        return h.audio(buffer, 'audio/wav')
+    },
+    async isSupportVoiceId(voiceId) {
+        return voiceId.startsWith('my-prefix-')
+    }
+})
+
+// 或者简写
+ctx.tts.registerHandler(async (input) => {
+    return h.audio(buffer, 'audio/wav')
+})
+```
+
+### 仅注册音色 ID
+
+```typescript
+// 注册单个音色
+ctx.tts.registerVoiceId('my-voice')
+
+// 注册多个音色
+ctx.tts.registerVoiceIds(['voice1', 'voice2', 'voice3'])
+```
+
+### Vits 兼容模式
+
+如果你需要兼容旧版 `vits` 服务（让依赖 `vits` 的插件也能使用你的 TTS 服务），使用 `VitsCompatible`：
+
+```typescript
+import { Context, h } from 'koishi'
+import { VitsCompatible, TTSInput } from 'koishi-plugin-tts-base'
+
+class MyVitsProvider extends VitsCompatible {
+    constructor(ctx: Context) {
+        super(ctx)
+    }
+
+    async provideVoiceIds(): Promise<string[]> {
+        return ['vits-voice1', 'vits-voice2']
+    }
+
+    async say(input: TTSInput): Promise<h> {
+        // 兼容旧版 speaker_id 参数
+        const speakerId = input.speaker_id ?? input.voiceId
+        // ...
+        return h.audio(buffer, 'audio/wav')
+    }
+}
+
+export function apply(ctx: Context) {
+    ctx.plugin(MyVitsProvider)
+}
+
+export const inject = ['tts']
+```
+
+使用 `VitsCompatible` 后，你的服务会同时注册为 `ctx.vits` 和 `ctx.tts` 的 provider。
+
+## API 参考
+
+### TTSService
+
+| 方法                                           | 说明                    |
+| ---------------------------------------------- | ----------------------- |
+| `say(input: TTSInput \| string)`               | 生成语音                |
+| `registerVoiceId(id: string)`                  | 注册单个音色 ID         |
+| `registerVoiceIds(ids: string[])`              | 注册多个音色 ID         |
+| `registerHandler(handler: TTSHandler)`         | 注册语音处理器          |
+| `registerVoiceProvider(provider: TTSProvider)` | 注册语音提供者          |
+| `hasVoiceId(id: string)`                       | 检查音色是否存在        |
+| `getVoiceIds()`                                | 获取所有已注册的音色 ID |
+
+### TTSInput
+
+```typescript
+interface TTSInput {
+    input: string | h // 要朗读的文本
+    voiceId?: string // 音色 ID
+    speaker_id?: string // 兼容旧版 vits 的参数
+    session?: Session // 可选的会话对象
+}
+```
+
+### TTSHandler
+
+```typescript
+interface TTSHandler {
+    say(input: TTSInput): Promise<h>
+    isSupportVoiceId?(voiceId: string): Promise<boolean>
+}
+```
+
+### TTSProvider
+
+```typescript
+interface TTSProvider extends TTSHandler {
+    provideVoiceIds(): Promise<string[]>
+}
+```