助眠音频插件使用指南（项目已废弃，接口不再维护）

发表于 更新于 分类于 阅读次数：

在聊天框中获取助眠音频，涵盖钢琴、雨声、脑波、自然等多种类型，并附带睡前故事。
作者: 蜥蜴

⚠️ 项目状态

本项目已废弃，所对接的第三方接口不再维护，插件可能无法正常返回音频。

本文保留作为使用记录与实现参考。如需在现有机器人中使用，请自行评估接口可用性。

背景

助眠音频的获取通常需要打开专门的 App 或网站，逐条播放并收藏。若希望在日常聊天中直接获取，需要通过机器人调用第三方音频接口。

koishi-plugin-asmr-lizard 将音频获取、时长探测、分段发送等流程整合为一条聊天指令，覆盖钢琴、雨声、脑波、自然与睡前故事等类型。

工具定位

koishi-plugin-asmr-lizard 是一款基于 Koishi 框架的助眠音频插件，主要能力如下：

能力 说明
分类获取 支持钢琴、雨声、脑波、自然、故事五种类型
随机获取 输入「随机」从全部类型中随机选取
封面与标题推送 返回音频标题与封面图
智能分段 音频长度超过 5 分钟时自动切分发送
发送方式可选 支持语音消息与文件两种方式
失败重试 分段发送失败时自动重试，最多 3 次

当前版本为 2.0.1，依赖 Koishi ^4.18.0，并需搭配 koishi-plugin-ffmpeg 与 koishi-plugin-silk 使用。

安装

前置条件

  • 已搭建并可正常运行的 Koishi 项目（koishi-app）
  • 已完成音频发送所需的服务配置（如 ffmpeg、silk，见下文）

方式一：通过插件市场安装（推荐）

  1. 启动 Koishi 项目，打开控制台（默认地址 http://localhost:5140）。
  2. 进入左侧「插件市场」。
  3. 在搜索框中输入 asmr-lizard。
  4. 找到插件后点击「添加」，Koishi 会自动完成依赖安装与配置写入。

方式二：通过 npm 安装

在 Koishi 项目根目录执行：

1
npm install koishi-plugin-asmr-lizard

随后在 koishi.yml 中手动添加配置：

1
2
3
4
plugins:
  asmr-lizard:
    sendMode: file
    apiHead: https://www.hhlqilongzhu.cn/

方式三：通过 yarn / pnpm 安装

若项目使用 yarn 或 pnpm，可执行：

1
2
3
4
5
# yarn
yarn add koishi-plugin-asmr-lizard

# pnpm
pnpm add koishi-plugin-asmr-lizard

安装附加依赖

插件声明了 inject: ['ffmpeg']，音频时长探测与分段依赖 koishi-plugin-ffmpeg；若通过语音方式发送，还需要 koishi-plugin-silk 进行格式转换。二者均需在 Koishi 项目中安装并启用：

1
npm install koishi-plugin-ffmpeg koishi-plugin-silk

在 koishi.yml 中相应配置：

1
2
3
4
5
6
7
plugins:
  ffmpeg:
    # 按需配置，通常保持默认即可
  silk:
    # 按需配置
  asmr-lizard:
    sendMode: file

验证安装

在任意已接入机器人的聊天窗口输入：

1
助眠

若能返回支持的类型提示，则说明安装成功。

配置

配置项

参数 类型 默认值 取值 说明
sendMode string file voice / file 音频发送方式。voice 为语音消息，file 为文件
apiHead string https://www.hhlqilongzhu.cn/ — 第三方接口地址前缀，默认值请勿更改

配置示例

1
2
3
4
plugins:
  asmr-lizard:
    sendMode: file
    apiHead: https://www.hhlqilongzhu.cn/

sendMode 控制音频的发送形式。选择 voice 时，音频将作为语音消息发送，需要 koishi-plugin-silk 支持；选择 file 时以 MP3 文件形式发送，兼容性更好。

使用流程

指令结构为 助眠 [type]，其中 type 为可选参数。

指令列表

指令 说明 示例
助眠 查看支持的全部类型 助眠
助眠 钢琴 获取钢琴类助眠音乐 助眠 钢琴
助眠 雨声 获取雨声类助眠音频 助眠 雨声
助眠 脑波 获取脑波类助眠音频 助眠 脑波
助眠 自然 获取自然类助眠音频 助眠 自然
助眠 故事 获取睡前故事 助眠 故事
助眠 随机 从全部类型中随机选取 助眠 随机

流程一：获取指定类型的助眠音频

步骤 1：发送指令

在聊天窗口输入类型名称：

1
助眠 钢琴

若不输入类型，插件将返回支持的类型清单：

1
提供以下类型：钢琴、雨声、脑波、自然、故事，输入随机则随机获取。

步骤 2：接收标题与封面

插件首先返回音频标题与封面图：

1
2
[标题]
[封面图]

步骤 3：接收音频

随后返回提示信息「正在获取音频，请耐心等待」，音频准备完成后：

  • 文件方式（sendMode: file）：以 MP3 文件发送，文件名为 <标题>.mp3
  • 语音方式（sendMode: voice）：以语音消息发送

发送完成后，提示信息自动撤回。

步骤 4：超过 5 分钟的处理

当音频时长超过 5 分钟时：

  • 提示「音频时长大于 5 分钟，将分 N 段发送。」
  • 依次切分并逐段发送
  • 若某段发送失败，自动重试，最多 3 次，并在每次重试前发送提示
  • 3 次均失败时，提示该段发送失败

流程二：随机获取音频

1
助眠 随机

插件从全部类型中随机选取一种，后续流程与流程一相同。

该方式适合不希望每次手动指定类型的场景。

使用场景

场景一：睡前助眠

在临睡前通过 助眠 雨声 或 助眠 自然 获取持续的背景音，无需切换到专门的助眠 App。

场景二：睡前故事

通过 助眠 故事 获取一段睡前故事音频，适合作为儿童睡前陪伴或在群聊中分享。

场景三：随机播放

通过 助眠 随机 由插件挑选类型，避免重复播放同一类音频。

技术实现

技术栈

技术 用途
Koishi 机器人框架
TypeScript 开发语言
koishi-plugin-ffmpeg 音频时长探测与分段
koishi-plugin-silk 语音格式转换（语音方式）
第三方音频接口 音频数据来源

接口调用

插件通过 apiHead 前缀拼接得到各类型的接口地址：

类型 路径
钢琴 api/ximalaya/ximalaya_gangqin.php
雨声 api/ximalaya/ximalaya_rain.php
脑波 api/ximalaya/ximalaya_naobo.php
自然 api/ximalaya/ximalaya_daziran.php
故事 api/ximalaya/ximalaya_gushi.php

接口返回音频的标题、封面地址与音频直链，插件再依次拉取封面与音频数据。

核心设计

音频时长探测

获取音频后，插件通过 ffmpeg 以 -f null 输出分析信息，并从中解析时长：

1
2
3
4
5
6
const durationBuffer = await ctx.ffmpeg.builder()
  .input(buffer)
  .outputOption('-f', 'null')
  .run('info');

const match = /Duration: (\d+):(\d+):(\d+\.\d+)/.exec(durationOutput);

由此得到音频的准确时长，作为是否分段的判断依据。

分段发送

当音频时长超过 5 分钟（300 秒）时，按 5 分钟为单位切分为若干段，逐段发送。切分基于 ffmpeg 的 -ss 与 -t 参数：

1
2
3
4
5
const segmentBuffer = await ctx.ffmpeg.builder()
  .input(buffer)
  .inputOption('-ss', startTime.toString())
  .outputOption('-t', maxSegmentDuration.toString(), '-f', 'mp3')
  .run('buffer');

失败重试

每一段发送最多重试 3 次。发送失败时先发送重试提示，重试成功后继续下一段；若 3 次均失败，则提示该段发送失败并继续后续分段。

语音与文件双模式

sendMode 决定音频的最终发送形式：

  • voice：通过 h.audio(buffer, 'voice/mp3') 发送，需 koishi-plugin-silk 支持格式转换
  • file：通过 h.file(buffer, 'audio/mp3', { title: '<标题>.mp3' }) 发送

封面图内联

封面图以 base64 内联方式发送，避免依赖外链域名可达性：

1
return `data:image/jpeg;base64,${Buffer.from(imageBuffer).toString('base64')}`;

发图时携带接口地址作为 referer，以适配部分接口的防盗链策略。

注意事项

1. 项目已废弃

所依赖的第三方接口已不再维护，插件可能无法正常返回音频。本文档仅作为使用记录保留。

2. 附加依赖

插件单独安装不足以保证可用，需同时安装并启用 koishi-plugin-ffmpeg。若使用 voice 方式发送，还需安装 koishi-plugin-silk。

3. 音频版权

音频内容由第三方接口提供，版权归原始权利人所有。请勿用于商业用途，亦不建议长期缓存与二次分发。

4. 分段数量

音频时长越长，分段数量越多。分段发送会连续产生多条消息，建议在群聊中酌情使用，或改用 file 方式以便接收方统一接收。

常见问题

Q1：安装后输入指令无响应？

依次检查以下项：

  • 插件是否已在控制台启用
  • koishi-plugin-ffmpeg 是否已安装并启用
  • 机器人是否已成功连接至目标平台
  • 指令是否完整输入（助眠 与类型之间以空格分隔）

Q2：语音方式发送失败？

语音方式依赖 koishi-plugin-silk。请确认已安装并启用该插件，或将 sendMode 改为 file 后重试。

Q3：获取音频时提示请求错误？

所依赖的第三方接口已不再维护，出现请求错误属预期情况。若接口临时恢复，插件仍可正常使用。

Q4：提示输入的类型不支持？

插件仅支持钢琴、雨声、脑波、自然、故事五种类型。输入其他内容时，插件将返回支持列表。可输入 助眠 随机 由插件随机选取。

Q5：是否可以自定义类型？

当前版本的接口地址由 apiHead 前缀与固定路径拼接而成，类型与路径的对应关系写死在源码中，不支持通过配置新增类型。如需扩展，需修改源码。

获取工具