# 配置说明

## 基本设置

### 绑定地址

程序 Web Server 监听的地址，程序启动时会监听该地址，成功后可通过 `http://${bind_address}` 访问管理页。

该配置会在程序重启时生效。

### 同步间隔（秒）

表示程序每次执行扫描下载的间隔时间，单位为秒。

### 视频名称模板、分页名称模板

视频名称模板（`video_name`）和分页名称模板（`page_name`）用于设置下载文件的命名规则。对于所有下载的内容，将会维持如下的目录结构：

1. 单页视频：

    ```bash
    ├── {video_name}
    │   ├── {page_name}.mp4
    │   ├── {page_name}.nfo
    │   └── {page_name}-poster.jpg
    ```

2. 多页视频：

    ```bash
    ├── {video_name}
    │   ├── poster.jpg
    │   ├── Season 1
    │   │   ├── {page_name} - S01E01.mp4
    │   │   ├── {page_name} - S01E01.nfo
    │   │   ├── {page_name} - S01E01-thumb.jpg
    │   │   ├── {page_name} - S01E02.mp4
    │   │   ├── {page_name} - S01E02.nfo
    │   │   └── {page_name} - S01E02-thumb.jpg
    │   └── tvshow.nfo
    ```

这两个模板参数会在运行时解析，其中用 <code v-pre>{{  }}</code> 包裹的模板变量会被动态替换为对应的内容。

对于 `video_name`，支持设置 bvid（视频编号）、title（视频标题）、upper_name（up 主名称）、upper_mid（up 主 id）、pubtime（视频发布时间）、fav_time（视频收藏时间）。

对于 `page_name`，除支持 video 的全部参数外，还支持 ptitle（分 P 标题）、pid（分 P 页号）。

为了解决文件名可能过长的问题，程序为模板引入了 `truncate` 函数。如 <code v-pre>{{ truncate title 10 }}</code> 表示截取 `title` 的前 10 个字符。

> [!TIP]
> 1. 仅收藏夹视频会区分 `fav_time` 和 `pubtime`，其它类型下载两者的取值是完全相同的；
> 2. `fav_time` 和 `pubtime` 的格式受[时间格式](#时间格式)控制。

此外，`video_name` 和 `page_name` 还支持使用路径分割符，如 <code v-pre>{{ upper_mid }}/{{ title }}_{{ pubtime }}</code> 表示视频会根据 UP 主 id 将视频分到不同的文件夹中。

推荐仅在 `video_name` 中使用路径分割符，暂不清楚在 `page_name` 中使用路径分割符导致分页存储到子文件夹后是否还能被媒体服务器正确识别。

> [!CAUTION]
> **路径分隔符**在不同平台定义不同，Windows 下为 `\`，MacOS 和 Linux 下为 `/`。

### UP 主头像保存路径

UP 主头像和信息的保存位置。对于使用 Emby、Jellyfin 媒体服务器的用户，需确保此处路径指向 Emby、Jellyfin 配置中的 `/metadata/people/` 才能够正常在媒体服务器中显示 UP 主的头像。

### 时间格式

用于设置 `fav_time` 和 `pubtime` 在视频名称模板、分页名称模板中使用时的显示格式，支持的格式符号可以参考 [chrono strftime 文档](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)。

### 后端 API 认证 Token

表示调用程序管理 API 需要的身份凭据，程序会对 API 请求进行身份验证，身份验证不通过会拒绝访问。

在修改该 Token 后需要对应修改前端保存的 Token，才能正常访问管理页面。


### 启动 CDN 排序

表示程序每次执行扫描下载的间隔时间，单位为秒。

## B 站认证

哔哩哔哩账号的身份凭据，请参考[凭据获取流程](https://nemo2011.github.io/bilibili-api/#/get-credential)获取并对应填写，后续 bili-sync 会在必要时自动刷新身份凭据，不再需要手动管理。

推荐使用匿名窗口获取，避免潜在的冲突。

## 视频质量

该页配置大部分都是显而易见的，仅对视频编码格式偏好进行说明。

### 视频编码格式偏好

这是 bili-sync 选择视频编码的优先级顺序，优先级按顺序从高到低。此处对编码格式做一个简单说明：

+ AVC 又称 H.264，是目前使用最广泛的视频编码格式，绝大部分设备可以使用硬件解码播放该格式的视频（也因此播放普遍流畅），但是同等画质下视频体积较大。

+ HEV(C) 又称 H.265，与 AV1 都是新一代的视频编码格式。这两种编码相比 AVC 有更好的压缩率，同等画质下视频体积更小，但由于相对较新，硬件解码支持不如 AVC 广泛。如果你的播放设备不支持则只能使用软件解码播放，这种情况下可能导致播放卡顿、机器发热等问题。

建议查阅自己常用播放设备对这三种编码的硬件解码支持情况以选择合适的编码格式，如果硬件支持 HEV 或 AV1，那么可以将其优先级调高。

而如果你的设备不支持，或者单纯懒得查询，那么推荐将 AVC 放在第一位以获得最好的兼容性。

## 弹幕渲染

弹幕的设置选项，用于设置下载弹幕的样式，几乎全部取自[上游仓库](https://github.com/gwy15/danmu2ass)。

### 弹幕持续时间（秒）

弹幕在屏幕上的持续时间，单位为秒。

### 字体

弹幕使用的字体。

### 字体大小

弹幕的字体大小。

### 宽度比例

计算弹幕宽度的比例，为避免重叠可以调大这个数值。

### 水平间距

两条弹幕之间最小的水平距离。

### 轨道大小

弹幕所占据的高度，即“行高度/行间距”。

### 滚动弹幕高度百分比

屏幕上滚动弹幕最多高度百分比。

### 底部弹幕高度百分比

屏幕上底部弹幕最多高度百分比。

### 透明度（0-255）

透明度，取值范围为 0-255。实际透明度百分比为 `透明度 / 255`。


### 描边宽度

弹幕的描边宽度。

### 时间偏移（秒）

时间轴偏移，>0 会让弹幕延后，<0 会让弹幕提前，单位为秒。

### 粗体显示

弹幕是否加粗。

## 高级设置

该页主要用于调整程序的请求与下载行为。

> [!TIP]
> 1. 一般来说，视频、分页的并发数不需要过大；
> 2. 请求频率限制可以根据网络环境和 api 请求频率进行调整，如果经常遇到风控可以优先调小该值。

### 视频并发数、分页并发数

视频并发数（video）和分页并发数（page）是控制 bili-sync 视频下载任务并发度的配置项。

程序的处理逻辑是严格从上到下的，即程序会首先并发处理多个 video，每个 video 内再并发处理多个 page，程序的并发度可以简单衡量为 `video * page`（很多 video 都只有单个 page，实际会更接近 `video * 1`），`video` 和 `page` 两个参数就是控制此处的，调节这两个参数可以宏观上控制程序的并发度。

### NFO 时间类型

表示在视频 NFO 文件中使用的时间类型，可选值为收藏时间和发布时间。

仅收藏夹视频会对这两项进行区分，其它类型的视频这两者取值完全相同。

### 请求频率限制

每个执行的任务内部都会发起若干 api 请求以获取信息，这些请求的整体频率受到请求频率的限制，使用漏桶算法实现。超过这个频率的请求会被暂时阻塞，直到漏桶中有空间为止。

时间间隔（毫秒）与限制请求数共同表明的意思时：程序在每个时间间隔内最多允许多少个请求。调节这一项可以从微观上控制程序的并行度，同时也是最直接、最显著的控制 api 请求频率的方法。

据观察 b 站风控限制大多集中在主站，因此目前请求频率限制仅作用于主站的各类请求，如请求各类视频列表、视频信息、获取流下载地址等，对实际的视频、图片下载过程不做限制。

### 单文件分块下载

单文件分块下载是指将单个视频文件分成多个小块进行下载，这可能有助于提高下载速度。

程序会首先为这个文件预分配空间，接着将文件分成若干个大小相同的块，为每个块启动单独的异步任务并行下载。


#### 下载分块数

表示单个文件分成多少个小块，默认值为 4。

#### 启动分块下载的文件大小阈值（字节）

表示当单个文件大小超过多少字节时，才会启动分块下载。默认值为 20971520（20 MB）。

如果文件过小，分块成本可能会超过分块下载带来的收益，因此使用该阈值决定下载策略。