biliLive-tools

Appearance

Webhook ​

Webhook 功能可以让录播软件与 biliLive-tools 自动配合，实现录制完成后自动处理、上传等功能。

支持的其他录播软件 ​

B站录播姬 ​

  1. 在 biliLive-tools 中配置

    • 设置"录播姬工作目录"为录播姬的工作目录

  2. 在录播姬中配置

    • 打开录播姬设置
    • 找到 WebhookV2 设置
    • 填入地址：http://127.0.0.1:18010/webhook/bililiverecorder

blrec ​

  • 打开 blrec 设置
  • 找到 Webhook 设置
  • 填入地址：http://127.0.0.1:18010/webhook/blrec
  • 必须勾选"视频文件创建"和"视频文件完成"两个事件，建议直接勾选全部事件

注意

blrec 的 Webhook 依赖于"视频文件创建"和"视频文件完成"两个事件，缺一不可。

特别说明 ​

如果开启了 blrec 的"转换为MP4"功能，请关闭该功能，使用 biliLive-tools 的"转封装为MP4"功能。

Oneliverec ​

配置步骤 ​

  • 打开 oneliverec 设置
  • 找到 Webhook 设置
  • 填入地址：http://127.0.0.1:18010/webhook/oneliverec
  • 必须启用"格式转换"
  • 必须选中"视频转换完成"事件，建议直接勾选全部事件

注意

  1. 必须启用"格式转换"
  2. Webhook事件必须选中"视频转换完成"事件

DDTV ​

配置步骤 ​

  • 打开"设置" -> "文件与路径设置"
  • 将"录制文件保存路径"设置为绝对路径
  • 启用"弹幕录制"
  • 填入地址：http://127.0.0.1:18010/webhook/ddtv

注意

由于 DDTV 的 Webhook 参数比较特殊，无法保证任意配置下的可用性。

自定义 Webhook ​

如果你使用的录播软件不在支持列表中，可以自行构造参数调用接口。

接口信息 ​

  • 地址：http://127.0.0.1:18010/webhook/custom
  • 方法：POST
  • Content-Type：application/json

参数说明 ​

参数类型必填说明
eventstring是事件类型：FileClosed、FileOpening、FileError
filePathstring是视频文件的绝对路径
coverPathstring否视频封面的绝对路径，为空时会读取同名jpg文件
danmuPathstring否视频弹幕xml文件，为空时会读取同名xml文件
roomIdnumber是房间号，用于断播续传
timestring是用于标题格式化的时间，示例："2021-05-14T17:52:54.946"
titlestring是标题，用于格式化视频标题
usernamestring是主播名称，用于格式化视频标题
platformstring否视频平台，用于某些地方的占位符
live_start_timestring否直播开始时间，用于弹幕分析
live_titlestring否直播标题，用于弹幕分析

事件类型 ​

  • FileOpening：文件开始录制
  • FileClosed：文件录制完成
  • FileError：文件错误，将该视频标注为错误，避免阻塞流程

断播续传

如果想使用断播续传功能，需要在上一个 FileClosed 事件后，在设置的时间间隔内发送 FileOpening 事件。

示例 ​

bash
curl --location 'http://127.0.0.1:18010/webhook/custom' \
--header 'Content-Type: application/json' \
--data '{
    "event":"FileClosed",
    "filePath":"D:\\aa.mp4",
    "coverPath":"D:\\aa.jpg",
    "danmuPath":"D:\\aa.xml",
    "roomId":93589,
    "time":"2021-05-14T17:52:54.946",
    "title":"我是猪",
    "username":"djw",
    "platform":"bilibili",
    "live_start_time":"2021-05-14T17:52:54.946",
    "live_title":"直播标题"
}'

Webhook 配置 ​

全局配置 ​

在"设置" -> "Webhook"中配置全局默认行为：

基础配置 ​

  • Webhook开关：启用/禁用 Webhook 功能
  • 录播姬工作目录：录播姬的工作目录（仅录播姬需要）

自动化处理 ​

  • 转封装为MP4：自动将FLV转换为MP4
  • 压制弹幕：自动将弹幕压制到视频中
  • 高能进度条：自动生成高能进度条
  • 自动上传：自动上传到B站
  • 自动同步：自动同步到云存储

上传配置 ​

  • 账号：选择上传使用的B站账号
  • 标题格式：标题模板

其他 ​

  • 是否启用
  • 转封装设置
  • 压制设置
  • 上传设置
  • 同步设置
  • 等等...

直播间配置 ​

为每个直播间单独配置 Webhook 行为：

  1. 打开"Webhook配置"
  2. 点击"添加配置"
  3. 选择房间号
  4. 配置该房间的处理规则

提示

直播间配置优先级高于全局配置。

标题模板引擎 ​

Webhook 标题支持 ejs模板引擎，可以实现复杂的标题格式化。

占位符 ​

同时也支持 占位符：

  • {{title}} - 直播标题
  • {{user}} - 主播名
  • {{roomId}} - 房间号
  • {{filename}} - 视频文件名
  • {{now}} - 视频录制时间（示例：2024.01.24）
  • {{yyyy}} - 年
  • {{MM}} - 月（补零）
  • {{dd}} - 日（补零）
  • {{HH}} - 时（补零）
  • {{mm}} - 分（补零）
  • {{ss}} - 秒（补零）

ejs ​

1.5.0起 Webhook 标题支持ejs模板引擎，具体语法参考文档，如果标题超过80字，会被自动截断，会优先执行模板引擎，之后会对占位符进行替换，如果有语法错误，会被跳过，优先保证上传。

可用变量 ​

typescript
{
  title: string; // 直播间标题
  user: string; // 主播名称
  time: Date; // 直播开始时间
  roomId: number | string; // 房间号
}

示例 ​

示例1：使用 ejs

<%= user %>-<%= time.getFullYear() %><%= String(time.getMonth() + 1).padStart(2, "0") %>直播录像

渲染结果：djw-202408直播录像

示例2：使用占位符

{{user}}的直播录像-{{title}}

渲染结果：djw的直播录像-今天打游戏

示例3：混合使用

<% if (roomId == 123456) { %>特殊房间<% } else { %>{{user}}的直播<% } %>

注意

如果标题超过80字,会被自动截断。

断播续传 ​

断播续传功能可以将主播的一场直播的多个片段自动合并上传到同一个视频中。

功能说明 ​

什么是断播续传？ ​

由于网络波动或设置分段原因，一场直播可能被切割成多个文件。断播续传功能可以智能识别这些属于同一场直播的文件，上传到同一个分P中。

一场直播的定义 ​

满足以下条件的文件会被认为是同一场直播：

  • 同一个主播（同一个房间号）
  • 本次文件创建时间与上一个文件结束写入时间相差不超过设定时间（默认10分钟）

启用断播续传 ​

  1. 打开"设置" -> "Webhook"
  2. 找到"断播续传"选项
  3. 启用"断播续传开关"
  4. 设置"续传时间间隔"（默认10分钟）

配置选项 ​

续传时间间隔 ​

设置判断是否为同一场直播的时间间隔。

推荐值：

  • 网络稳定：5-10分钟
  • 网络不稳定：15-30分钟
  • 经常断流：30-60分钟

注意

间隔过长可能导致不同场次的直播被合并。

保留原文件 ​

合并后可以选择是否保留原始片段文件。

  • 保留：占用更多空间，但可以恢复
  • 删除：节省空间，但无法恢复

使用场景 ​

场景1：网络波动导致断流 ​

主播直播中网络波动，导致录制被中断，几分钟后恢复。

不使用断播续传：

  • 生成2个视频文件
  • 需要分别上传为2个视频
  • 观众体验不好

使用断播续传：

  • 上传到一个分P中
  • 自动上传
  • 观众无感知

场景2：设置时长分段 ​

为避免单个文件过大，设置每小时分段。

不使用断播续传：

  • 一场3小时直播生成3个文件
  • 需要上传为三个视频
  • 管理麻烦

使用断播续传：

  • 上传到一个分P中
  • 自动上传
  • 观众无感知

场景3：主播中途下播 ​

主播直播2小时后下播休息，1小时后重新开播。

续传间隔 < 1小时：

  • 不会合并，识别为2场直播 ✅

续传间隔 > 1小时：

  • 会被合并，识别为1场直播 ❌

建议

根据主播习惯调整续传间隔。

注意事项 ​

开启录制后，不要频繁开关，可能会有奇怪的错误。

配置查找 ​

查找顺序 ​

  1. 查找与 roomId 完全匹配的配置
  2. 如果没有找到，使用全局默认配置
  3. 如果全局配置未启用，跳过处理

配置优先级 ​

直播间配置 > 全局配置

示例 ​

假设配置如下：

  • 全局配置：转封装=开启，自动上传=开启
  • 房间123456配置：转封装=关闭

当收到房间123456的Webhook时：

  • 转封装：关闭（使用直播间配置）
  • 自动上传：开启（直播间配置未设置，使用全局配置）

常见问题 ​

Webhook 没有触发 ​

  1. 检查 Webhook 开关是否启用
  2. 检查录播软件的 Webhook 地址是否正确
  3. 检查端口是否被占用
  4. 查看日志文件排查问题

文件路径找不到 ​

  1. Docker 环境下检查卷映射是否一致
  2. 检查路径是否为绝对路径
  3. 检查文件是否真实存在

弹幕文件找不到 ​

Webhook 会自动查找同名的 XML 文件，确保：

  1. 弹幕文件与视频文件在同一目录
  2. 弹幕文件名与视频文件名一致（除扩展名外）
  3. 弹幕文件扩展名为 .xml

上传失败 ​

  1. 检查 B站账号是否登录
  2. 检查网络连接
  3. 增加重试次数
  4. 查看详细错误信息

Released under the GPLv3 License.

Copyright © 2024-present renmu123