diff --git a/.gitignore b/.gitignore index 22d34ee..633804d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ **/target auth_data *.sqlite -*.json video debug* +node_modules +docs/.vitepress/cache +docs/.vitepress/dist \ No newline at end of file diff --git a/README.md b/README.md index ef44162..bbaeca1 100644 --- a/README.md +++ b/README.md @@ -24,156 +24,21 @@ ### 文件排布 ![文件](./assets/dir.png) -## 配置文件说明 -> [!NOTE] -> 在 Docker 环境中，`~` 会被展开为 `/app`。 - -程序默认会将配置文件存储于 `~/.config/bili-sync/config.toml`，数据库文件存储于 `~/.config/bili-sync/data.sqlite`，如果发现不存在会新建并写入默认配置。 - -配置文件加载时会进行简单校验，默认配置无法通过校验，程序会报错终止运行。 - -可以下载程序后直接运行程序，看到报错后参考报错信息对默认配置进行修改，修改正确后即可正常运行。 - -对于配置文件中的 `credential`，请参考[凭据获取流程](https://nemo2011.github.io/bilibili-api/#/get-credential)。 - -配置文件中的 `video_name` 和 `page_name` 支持使用模板，模板的替换语法请参考示例。模板中的内容在执行时会被动态替换为对应的内容。 - -video_name 支持设置 bvid（视频编号）、title（视频标题）、upper_name（up 主名称）、upper_mid（up 主 id）。 - -page_name 除支持 video 的全部参数外，还支持 ptitle（分 P 标题）、pid（分 P 页号）。 - -对于每个 favorite_list 的下载路径，程序会在其下建立如下的文件夹： - -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 - ``` - -对于 filter_option 的可选值，请前往 [analyzer.rs](https://github.com/amtoaer/bili-sync/blob/main/src/bilibili/analyzer.rs) 查看。 - -对于 danmaku_option 的项含义，请前往 [danmaku/mod.rs](https://github.com/amtoaer/bili-sync/blob/main/src/bilibili/danmaku/canvas/mod.rs) 与 [原项目的说明](https://github.com/gwy15/danmu2ass?tab=readme-ov-file#%E5%91%BD%E4%BB%A4%E8%A1%8C) 查看。 - -## 配置文件示例 - -```toml -# 视频所处文件夹的名称 -video_name = "{{title}}" -# 视频分页文件的命名 -page_name = "{{bvid}}" -# 扫描运行的间隔（单位：秒） -interval = 1200 -# emby 演员信息的保存位置 -upper_path = "/home/amtoaer/.config/nas/emby/metadata/people/" - -[credential] -# Bilibili 的 Web 端身份凭据，需要凭据才能下载高清视频 -sessdata = "" -bili_jct = "" -buvid3 = "" -dedeuserid = "" -ac_time_value = "" - -[filter_option] -# 视频、音频流的筛选选项，程序会使用范围内质量最高的流 -# 注意设置范围过小可能导致无满足条件的流，推荐仅调整质量上限和编码优先级 -video_max_quality = "Quality8k" -video_min_quality = "Quality360p" -audio_max_quality = "QualityHiRES" -audio_min_quality = "Quality64k" -codecs = [ - "AV1", - "HEV", - "AVC", -] -no_dolby_video = false -no_dolby_audio = false -no_hdr = false -no_hires = false - -[danmaku_option] -# 弹幕的一些相关选项，如字体、字号、透明度、停留时间、是否加粗等 -duration = 12.0 -font = "黑体" -font_size = 25 -width_ratio = 1.2 -horizontal_gap = 20.0 -lane_size = 32 -float_percentage = 0.5 -bottom_percentage = 0.3 -opacity = 76 -bold = true -outline = 0.8 -time_offset = 0.0 - -[favorite_list] -# 收藏夹 ID = 存储的位置 -52642258 = "/home/amtoaer/HDDs/Videos/Bilibilis/混剪" -``` - -## Docker Compose 文件示例 - -该项目为 `Linux/amd64` 与 `Linux/arm64` 提供了 Docker 版本镜像。 - -Docker 版包含该平台对应版本的可执行文件（位于`/app/bili-sync-rs`），并预装了 FFmpeg，其它用法与普通版本完全一致。（可查看 [用于构建镜像的 Dockerfile](./Dockerfile) ） - -以下是一个 Docker Compose 的编写示例： -```yaml -services: - bili-sync-rs: - image: amtoaer/bili-sync-rs:v2.0.0 - restart: unless-stopped - network_mode: bridge - tty: true # 该选项请仅在日志终端支持彩色输出时启用，否则日志中可能会出现乱码 - # user: 1000:1000 # 非必需设置项，说明见下 - hostname: bili-sync-rs - container_name: bili-sync-rs - volumes: - - /home/amtoaer/.config/nas/bili-sync-rs:/app/.config/bili-sync - # 以及一些其它必要的挂载，确保此处的挂载与 bili-sync-rs 的配置相匹配 - # ... - logging: - driver: "local" -``` -### user 的设置 -- 可设置为宿主机适当用户的 uid 及 gid (`$uid:$gid`)，使项目下载的文件的所有者与该处设置的用户保持一致，不设置默认为 root -- 执行 `id ${user}` 以获得 `user` 用户的 uid 及 gid ，了解更多可参阅 [Docker文档](https://docs.docker.com/engine/reference/run/#user) - -## 路线图 - -- [x] 凭证认证 -- [x] 视频选优 -- [x] 视频下载 -- [x] 支持并发下载 -- [x] 支持作为 daemon 运行 -- [x] 构建 nfo 和 poster 文件，方便以单集形式导入 emby -- [x] 支持收藏夹翻页，下载全部历史视频 -- [x] 对接数据库，提前检查，按需下载 -- [x] 支持弹幕下载 -- [x] 更好的错误处理 -- [x] 更好的日志 -- [x] 请求过快出现风控的 workaround -- [x] 提供简单易用的打包（如 docker） -- [ ] 支持 UP 主合集下载 +## 功能与路线图 + +- [x] 使用用户填写的凭据认证，并在必要时自动刷新 +- [x] 支持收藏夹与视频列表/视频合集的下载 +- [x] 自动选择用户设置范围内最优的视频和音频流，并在下载完成后使用 FFmpeg 合并 +- [x] 使用 Tokio 与 Reqwest，对视频、视频分页进行异步并发下载 +- [x] 使用媒体服务器支持的文件命名，方便一键作为媒体库导入 +- [x] 当前轮次下载失败会在下一轮下载时重试，失败次数过多自动丢弃 +- [x] 使用数据库保存媒体信息，避免对同个视频的多次请求 +- [x] 打印日志，并在请求出现风控时自动终止，等待下一轮执行 +- [x] 提供多平台的二进制可执行文件，为 Linux 平台提供了立即可用的 Docker 镜像 +- [ ] 支持对“稍后再看”内视频的自动扫描与下载 +- [ ] 下载单个文件时支持断点续传与并发下载 + ## 参考与借鉴 diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts new file mode 100644 index 0000000..d6b23ec --- /dev/null +++ b/docs/.vitepress/config.mts @@ -0,0 +1,100 @@ +import { defineConfig } from "vitepress"; +import taskLists from "markdown-it-task-lists"; + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + title: "bili-sync", + description: "基于 rust tokio 的哔哩哔哩同步工具", + lang: "zh-Hans", + sitemap: { + hostname: "https://bili-sync.github.io", + }, + lastUpdated: true, + cleanUrls: true, + metaChunk: true, + themeConfig: { + outline: { + label: "页面导航", + level: "deep", + }, + // https://vitepress.dev/reference/default-theme-config + nav: [ + { text: "主页", link: "/" }, + { + text: "更新日志", + items: [ + { + text: "程序本体", + link: "https://github.com/amtoaer/bili-sync/releases", + }, + { + text: "文档页面", + link: "https://github.com/search?q=repo:amtoaer/bili-sync+docs&type=commits", + }, + ], + }, + ], + sidebar: [ + { + text: "简介", + items: [ + { text: "什么是 bili-sync？", link: "/introduction" }, + { text: "快速开始", link: "/quick-start" }, + ], + }, + { + text: "细节", + items: [ + { text: "配置文件", link: "/configuration" }, + { text: "命令行参数", link: "/args" }, + ], + }, + { + text: "参考", + items: [ + { text: "获取收藏夹信息", link: "/favorite" }, + { + text: "获取视频合集/视频列表信息", + link: "/collection", + }, + ], + }, + ], + socialLinks: [ + { icon: "github", link: "https://github.com/amtoaer/bili-sync" }, + ], + search: { + provider: "local", + }, + notFound: { + title: "你来到了没有知识的荒原", + quote: "这里什么都没有", + linkText: "返回首页", + }, + docFooter: { + prev: "上一页", + next: "下一页", + }, + lastUpdated: { + text: "上次更新于", + }, + returnToTopLabel: "回到顶部", + sidebarMenuLabel: "菜单", + darkModeSwitchLabel: "主题", + lightModeSwitchTitle: "切换到浅色模式", + darkModeSwitchTitle: "切换到深色模式", + }, + markdown: { + config: (md) => { + md.use(taskLists); + }, + theme: { + light: "github-light", + dark: "github-dark", + }, + }, + head: [ + ["link", { rel: "icon", type: "image/svg+xml", href: "/icon.svg" }], + ["link", { rel: "icon", type: "image/png", href: "/icon.png" }], + ], +}); diff --git a/docs/args.md b/docs/args.md new file mode 100644 index 0000000..ded9c96 --- /dev/null +++ b/docs/args.md @@ -0,0 +1,27 @@ +# 命令行参数 + +程序支持有限的命令行参数，可以通过执行 `bili-sync-rs --help` 查看说明。 + +```shell +bili-sync/target/debug docs_vitepress* ⇡ +❯ ./bili-sync-rs --help +基于 rust tokio 编写的 bilibili 收藏夹同步下载工具 + +Usage: bili-sync-rs [OPTIONS] + +Options: + -s, --scan-only [env: SCAN_ONLY=] + -l, --log-level [env: RUST_LOG=] [default: None,bili_sync=info] + -h, --help Print help + -V, --version Print version +``` + +可以看到除版本和帮助信息外，程序仅支持两个参数，参数除可以通过命令行设置外，还可通过环境变量设置。 + +## `--scan-only` + +`--scan-only` 参数用于仅扫描列表，而不实际执行下载操作。该参数的主要目的是[方便用户从 v1 迁移](https://github.com/amtoaer/bili-sync/issues/66#issuecomment-2066642481)，新用户不需要关注。 + +## `--log-level` + +`--log-level` 参数用于设置日志级别，一般可以维持默认。该参数与 Rust 程序中 `RUST_LOG` 的语义相同，可以查看[相关文档](https://docs.rs/env_logger/latest/env_logger/#enabling-logging)获取详细信息。 \ No newline at end of file diff --git a/docs/assets/collection.png b/docs/assets/collection.png new file mode 100644 index 0000000..e0755fb Binary files /dev/null and b/docs/assets/collection.png differ diff --git a/docs/assets/detail.png b/docs/assets/detail.png new file mode 100644 index 0000000..e95c6c5 Binary files /dev/null and b/docs/assets/detail.png differ diff --git a/docs/assets/dir.png b/docs/assets/dir.png new file mode 100644 index 0000000..9987d66 Binary files /dev/null and b/docs/assets/dir.png differ diff --git a/docs/assets/favorite.png b/docs/assets/favorite.png new file mode 100644 index 0000000..b9324d5 Binary files /dev/null and b/docs/assets/favorite.png differ diff --git a/docs/assets/icon.png b/docs/assets/icon.png new file mode 100644 index 0000000..506c973 Binary files /dev/null and b/docs/assets/icon.png differ diff --git a/docs/assets/overview.png b/docs/assets/overview.png new file mode 100644 index 0000000..b395262 Binary files /dev/null and b/docs/assets/overview.png differ diff --git a/docs/assets/play.png b/docs/assets/play.png new file mode 100644 index 0000000..21cc27f Binary files /dev/null and b/docs/assets/play.png differ diff --git a/docs/assets/season.png b/docs/assets/season.png new file mode 100644 index 0000000..c55e59b Binary files /dev/null and b/docs/assets/season.png differ diff --git a/docs/assets/series.png b/docs/assets/series.png new file mode 100644 index 0000000..1e37f63 Binary files /dev/null and b/docs/assets/series.png differ diff --git a/docs/bun.lockb b/docs/bun.lockb new file mode 100755 index 0000000..f6d6abd Binary files /dev/null and b/docs/bun.lockb differ diff --git a/docs/collection.md b/docs/collection.md new file mode 100644 index 0000000..7fb81b8 --- /dev/null +++ b/docs/collection.md @@ -0,0 +1,32 @@ +# 获取视频合集/视频列表信息 + +要说明的是，视频合集和视频列表虽然在哔哩哔哩网站交互上行为类似，但在接口层级是两个不同的概念。可以简单将视频列表理解为一个老旧版本的视频合集。 + +在调试过程中我注意到视频列表的 ID 可以通过某种规则转换为视频合集的 ID，从而成功调用视频合集的接口，但由于不清楚具体的转换策略，在 bili-sync 的实现中还是将其当成两种类型处理。 + +## 区分方法 + +这两种类型可以很容易地通过如下手段区分： +1. 两者的名称前缀不同，视频合集会有显式的“合集”字样 +2. 两者的图标不同 + +如下图所示，“合集【命运方舟全剧情解说】”是视频合集，而“阿拉德冒险记”是视频列表。 +![image](./assets/collection.png) + +在 bili-sync 的设计中，视频合集的 key 为 `season:{mid}:{season_id}`，而视频列表的 key 为 `series:{mid}:{series_id}`。 + +## 参数获取 + +了解了区分方法后，我们可以通过如下步骤获取视频合集/视频列表的信息。 + +### 视频合集 + +![image](./assets/season.png) + +该视频合集的 key 为 `season:521722088:1987140`。 + +### 视频列表 + +![image](./assets/series.png) + +该视频列表的 key 为 `series:521722088:387214`。 \ No newline at end of file diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..da274a5 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,181 @@ +# 配置文件 + +默认的配置文件已经在[快速开始](/quick-start)中给出，该文档对配置文件的各个参数依次详细解释。 + +## video_name 与 page_name + +`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 + ``` + +这两个参数支持使用模板，其中用 {{ }} 包裹的模板变量在执行时会被动态替换为对应的内容。 + +对于 `video_name`，支持设置 bvid（视频编号）、title（视频标题）、upper_name（up 主名称）、upper_mid（up 主 id）。 + +对于 `page_name`，除支持 video 的全部参数外，还支持 ptitle（分 P 标题）、pid（分 P 页号）。 + +为了解决文件名可能过长的问题，程序为模板引入了 `truncate` 函数。如 {{ truncate title 10 }} 表示截取 `title` 的前 10 个字符。 + +## `interval` + +表示程序每次执行扫描下载的间隔时间，单位为秒。 + +## `upper_path` + +UP 主头像和信息的保存位置。对于使用 Emby、Jellyfin 媒体服务器的用户，需确保此处路径指向 Emby、Jellyfin 配置中的 `/metadata/people/` 才能够正常在媒体服务器中显示 UP 主的头像。 + +## `nfo_time_type` + +表示在视频信息中使用的时间类型，可选值为 `favtime`（收藏时间）和 `pubtime`（发布时间）。 + +视频合集/视频列表不存在 `favtime`，程序实现中将 `favtime` 设置为与 `pubtime` 相同，因此该设置对视频合集/视频列表没有影响。 + +## `credential` + +哔哩哔哩账号的身份凭据，请参考[凭据获取流程](https://nemo2011.github.io/bilibili-api/#/get-credential)获取并对应填写至配置文件中，后续 bili-sync 会在必要时自动刷新身份凭据，不再需要手动管理。 + +推荐使用匿名窗口获取，避免潜在的冲突。 + +## `filter_option` + +过滤选项，用于设置程序的过滤规则，程序会从过滤结果中选择最优的视频、音频流下载。 + +这些内容的可选值可前往 [analyzer.rs](https://github.com/amtoaer/bili-sync/blob/24d0da0bf3ea65fd45d07587e4dcdbb24d11a589/crates/bili_sync/src/bilibili/analyzer.rs#L10-L55) 中查看。 + +注意将过滤范围设置过小可能导致筛选不到符合要求的流导致下载失败，建议谨慎修改。 + +### `video_max_quality` + +视频流允许的最高质量。 + +### `video_min_quality` + +视频流允许的最低质量。 + +### `audio_max_quality` + +音频流允许的最高质量。 + +### `audio_min_quality` + +音频流允许的最低质量。 + +### `codecs` + +这是 bili-sync 选择视频编码的优先级顺序，优先级按顺序从高到低。此处对编码格式做一个简单说明： + ++ AVC 又称 H.264，是目前使用最广泛的视频编码格式，绝大部分设备可以使用硬件解码播放该格式的视频（也因此播放普遍流畅），但是同等画质下视频体积较大。 + ++ HEV(C) 又称 H.265，与 AV1 都是新一代的视频编码格式。这两种编码相比 AVC 有更好的压缩率，同等画质下视频体积更小，但由于相对较新，硬件解码支持不如 AVC 广泛。如果你的播放设备不支持则只能使用软件解码播放，这种情况下可能导致播放卡顿、机器发热等问题。 + +建议查阅自己常用播放设备对这三种编码的硬件解码支持情况以选择合适的编码格式，如果硬件支持 HEV 或 AV1，那么可以将其优先级调高。 + +而如果你的设备不支持，或者单纯懒得查询，那么推荐将 AVC 放在第一位以获得最好的兼容性。 + +### `no_dolby_video` + +是否禁用杜比视频流。 + +### `no_dolby_audio` + +是否禁用杜比音频流。 + +### `no_hdr` + +是否禁用 HDR 视频流。 + +### `no_hires` + +是否禁用 Hi-Res 音频流。 + +## `danmaku_option` + +弹幕的设置选项，用于设置下载弹幕的样式，几乎全部取自[上游仓库](https://github.com/gwy15/danmu2ass)。 + +### `duration` + +弹幕在屏幕上的持续时间，单位为秒。 + +### `font` + +弹幕的字体。 + +### `font_size` + +弹幕的字体大小。 + +### `width_ratio` + +计算弹幕宽度的比例，为避免重叠可以调大这个数值。 + +### `horizontal_gap` + +两条弹幕之间最小的水平距离。 + +### `lane_size` + +弹幕所占据的高度，即“行高度/行间距”。 + +### `float_percentage` + +屏幕上滚动弹幕最多高度百分比。 + +### `bottom_percentage` + +屏幕上底部弹幕最多高度百分比。 + +### `opacity` + +透明度，取值范围为 0-255。透明度可以通过 opacity / 255 计算得到。 + +### `bold` + +是否加粗。 + +### `outline` + +描边宽度。 + +### `time_offset` + +时间轴偏移，>0 会让弹幕延后，<0 会让弹幕提前，单位为秒。 + +## `favorite_list` + +你想要下载的收藏夹与想要保存的位置。简单示例： +```toml +3115878158 = "/home/amtoaer/Downloads/bili-sync/测试收藏夹" +``` +收藏夹 ID 的获取方式可以参考[这里](/favorite)。 + +## `collection_list` + +你想要下载的视频合集/视频列表与想要保存的位置。注意“视频合集”与“视频列表”是两种不同的类型。在配置文件中需要做区分： +```toml +"series:387051756:432248" = "/home/amtoaer/Downloads/bili-sync/测试视频列表" +"season:1728547:101343" = "/home/amtoaer/Downloads/bili-sync/测试合集" +``` + +具体说明可以参考[这里](/collection)。 diff --git a/docs/favorite.md b/docs/favorite.md new file mode 100644 index 0000000..1c1569e --- /dev/null +++ b/docs/favorite.md @@ -0,0 +1,5 @@ +# 获取收藏夹信息 + +收藏夹的 ID 获取非常简单，在网页端打开自己的收藏夹列表，切换到你想要获取的收藏夹，然后查看 URL 地址栏中的 `fid` 参数内容即可。 + +![image](./assets/favorite.png) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a46e55c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,58 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + +title: bili-sync +titleTemplate: 由 Rust & Tokio 驱动的哔哩哔哩同步工具 + +hero: + name: "bili-sync" + text: "由 Rust & Tokio 驱动的哔哩哔哩同步工具" + # tagline: My great project tagline + actions: + - theme: brand + text: 什么是 bili-sync？ + link: /introduction + - theme: alt + text: 快速开始 + link: /quick-start + - theme: alt + text: GitHub + link: https://github.com/amtoaer/bili-sync + image: + src: /assets/icon.png + alt: bili-sync + +features: + - icon: 🤖 + title: 无需干预 + details: 自动选择最优的视频和音频配置 + - icon: 💾 + title: 专为 NAS 设计 + details: 可被 Emby、Jellyfin 等媒体服务器一键识别 + - icon: 🐳 + title: 部署简单 + details: 提供简单易用的 docker 镜像 +--- + + \ No newline at end of file diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000..59163d7 --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,37 @@ +# bili-sync 是什么？ + +bili-sync 是一款专为 NAS 用户编写的哔哩哔哩同步工具。 + +它的基本的工作原理是使用用户填写的凭据定期扫描视频合集、收藏夹等，获取到本地未下载过的内容并保存到本地，维持本地视频库与哔哩哔哩网站的同步。 + +下载的内容包括视频、封面、弹幕、标签与简介信息等，这些文件整体保持与 Emby、Jellyfin 等媒体服务器软件兼容的文件布局，使得目的文件夹可以直接被作为媒体库添加到这些软件中，无需干预自动识别。 + +## 使用截图 + +> [!WARNING] +> 媒体库类型请选择“混合内容”，否则可能导致多页视频无法正常显示。 + + + +### 概览 +![概览](/assets/overview.png) +### 详情 +![详情](/assets/detail.png) +### 播放（使用 infuse） +![播放](/assets/play.png) +### 文件排布 +![文件](/assets/dir.png) + +## 功能与路线图 + +- [x] 使用用户填写的凭据认证，并在必要时自动刷新 +- [x] 支持收藏夹与视频列表/视频合集的下载 +- [x] 自动选择用户设置范围内最优的视频和音频流，并在下载完成后使用 FFmpeg 合并 +- [x] 使用 Tokio 与 Reqwest，对视频、视频分页进行异步并发下载 +- [x] 使用媒体服务器支持的文件命名，方便一键作为媒体库导入 +- [x] 当前轮次下载失败会在下一轮下载时重试，失败次数过多自动丢弃 +- [x] 使用数据库保存媒体信息，避免对同个视频的多次请求 +- [x] 打印日志，并在请求出现风控时自动终止，等待下一轮执行 +- [x] 提供多平台的二进制可执行文件，为 Linux 平台提供了立即可用的 Docker 镜像 +- [ ] 支持对“稍后再看”内视频的自动扫描与下载 +- [ ] 下载单个文件时支持断点续传与并发下载 diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..bdcc839 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,12 @@ +{ + "dependencies": {}, + "devDependencies": { + "markdown-it-task-lists": "^2.1.1", + "vitepress": "^1.2.3" + }, + "scripts": { + "docs:dev": "vitepress dev", + "docs:build": "vitepress build", + "docs:preview": "vitepress preview" + } +} diff --git a/docs/public/icon.png b/docs/public/icon.png new file mode 100644 index 0000000..11374c7 Binary files /dev/null and b/docs/public/icon.png differ diff --git a/docs/public/icon.svg b/docs/public/icon.svg new file mode 100644 index 0000000..c918334 --- /dev/null +++ b/docs/public/icon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..c6b17d7 --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,168 @@ +# 快速开始 + +程序使用 Rust 编写，不需要 Runtime 且并为各个平台提供了预编译文件，绝大多数情况下是没有使用障碍的。 + +## 程序获取 + +程序为各个平台提供了预构建的二进制文件，并且打包了 `Linux/amd64` 与 `Linux/arm64` 两个平台的 Docker 镜像。用户可以自行选择使用哪种方式运行。 + +### 其一：下载平台二进制文件运行 + +> [!CAUTION] +> 如果你使用这种方式运行，请确保 FFmpeg 已被正确安装且位于 PATH 中，可通过执行 `ffmpeg` 命令访问。 + +在[程序发布页](https://github.com/amtoaer/bili-sync/releases)选择最新版本中对应机器架构的压缩包，解压后会获取一个名为 `bili-sync-rs` 的可执行文件，直接双击执行。 + +### 其二： 使用 Docker Compose 运行 + +Linux/amd64 与 Linux/arm64 两个平台可直接使用 Docker 或 Docker Compose 运行，此处以 Compose 为例： +> 请注意其中的注释，有不清楚的地方可以先继续往下看。 + +```yaml +services: + bili-sync-rs: + # 不推荐使用 latest 这种模糊的 tag，最好直接指明版本号 + image: amtoaer/bili-sync-rs:latest + restart: unless-stopped + network_mode: bridge + # 该选项请仅在日志终端支持彩色输出时启用，否则日志中可能会出现乱码 + tty: true + # 非必需设置项，推荐设置为宿主机用户的 uid 及 gid (`$uid:$gid`) + # 可以执行 `id ${user}` 获取 `user` 用户的 uid 及 gid + # 程序下载的所有文件权限将与此处的用户保持一致，不设置默认为 Root + user: 1000:1000 + hostname: bili-sync-rs + container_name: bili-sync-rs + volumes: + - ${你希望存储程序配置的目录}:/app/.config/bili-sync + # 还需要有一些其它必要的挂载，包括 up 主信息位置、视频下载位置 + # 这些目录不是固定的，只需要确保此处的挂载与 bili-sync-rs 的配置文件相匹配 + # ... + # 如果你使用的是群晖系统，请移除最后的 logging 配置，否则会导致日志不显示 + logging: + driver: "local" +``` + +使用该 compose 文件，执行 `docker compose up -d` 即可运行。 + +## 程序配置 + +> [!NOTE] +> 在 Docker 环境中，`~` 会被展开为 `/app`。 + +你是否遇到了程序的 panic？别担心，这是正常情况。 + +程序默认会将配置文件存储于 `~/.config/bili-sync/config.toml`，数据库文件存储于 `~/.config/bili-sync/data.sqlite`。 + +在启动时程序会尝试加载配置文件，如果发现不存在会新建并写入默认配置。 + +获得配置内容后，程序会对其做一次简单的校验，因为默认配置中不包含凭据信息与要下载的收藏夹、视频合集/视频列表，因此程序会拒绝运行而发生 panic。我们只需要在程序生成的默认配置上做一些简单修改即可成功运行。 + +当前版本的默认示例文件如下： +```toml +video_name = "{{title}}" +page_name = "{{bvid}}" +interval = 1200 +upper_path = "/Users/amtoaer/Library/Application Support/bili-sync/upper_face" +nfo_time_type = "favtime" + +[credential] +sessdata = "" +bili_jct = "" +buvid3 = "" +dedeuserid = "" +ac_time_value = "" + +[filter_option] +video_max_quality = "Quality8k" +video_min_quality = "Quality360p" +audio_max_quality = "QualityHiRES" +audio_min_quality = "Quality64k" +codecs = [ + "AV1", + "HEV", + "AVC", +] +no_dolby_video = false +no_dolby_audio = false +no_hdr = false +no_hires = false + +[danmaku_option] +duration = 15.0 +font = "黑体" +font_size = 25 +width_ratio = 1.2 +horizontal_gap = 20.0 +lane_size = 32 +float_percentage = 0.5 +bottom_percentage = 0.3 +opacity = 76 +bold = true +outline = 0.8 +time_offset = 0.0 + +[favorite_list] + +[collection_list] +``` + +看起来很长，但绝大部分选项是不需要做修改的。正常情况下，我们只需要关注： ++ `interval` ++ `upper_path` ++ `credential` ++ `codecs` ++ `favorite_list` ++ `collection_list` + +以下逐条说明。 + +### `interval` + +表示程序每次执行扫描下载的间隔时间，单位为秒。 + +### `upper_path` + +UP 主头像和信息的保存位置。对于使用 Emby、Jellyfin 媒体服务器的用户，需确保此处路径指向 Emby、Jellyfin 配置中的 `/metadata/people/` 才能够正常在媒体服务器中显示 UP 主的头像。 + +### `credential` + +哔哩哔哩账号的身份凭据，请参考[凭据获取流程](https://nemo2011.github.io/bilibili-api/#/get-credential)获取并对应填写至配置文件中，后续 bili-sync 会在必要时自动刷新身份凭据，不再需要手动管理。 + +推荐使用匿名窗口获取，避免潜在的冲突。 + +### `codecs` + +这是 bili-sync 选择视频编码的优先级顺序，优先级按顺序从高到低。此处对编码格式做一个简单说明： + ++ AVC 又称 H.264，是目前使用最广泛的视频编码格式，绝大部分设备可以使用硬件解码播放该格式的视频（也因此播放普遍流畅），但是同等画质下视频体积较大。 + ++ HEV(C) 又称 H.265，与 AV1 都是新一代的视频编码格式。这两种编码相比 AVC 有更好的压缩率，同等画质下视频体积更小，但由于相对较新，硬件解码支持不如 AVC 广泛。如果你的播放设备不支持则只能使用软件解码播放，这种情况下可能导致播放卡顿、机器发热等问题。 + +建议查阅自己常用播放设备对这三种编码的硬件解码支持情况以选择合适的编码格式，如果硬件支持 HEV 或 AV1，那么可以将其优先级调高。 + +而如果你的设备不支持，或者单纯懒得查询，那么推荐将 AVC 放在第一位以获得最好的兼容性。 + +### `favorite_list` + +你想要下载的收藏夹与想要保存的位置。简单示例： +```toml +3115878158 = "/home/amtoaer/Downloads/bili-sync/测试收藏夹" +``` +收藏夹 ID 的获取方式可以参考[这里](/favorite)。 + +### `collection_list` + +你想要下载的视频合集/视频列表与想要保存的位置。注意“视频合集”与“视频列表”是两种不同的类型。在配置文件中需要做区分： +```toml +"series:387051756:432248" = "/home/amtoaer/Downloads/bili-sync/测试视频列表" +"season:1728547:101343" = "/home/amtoaer/Downloads/bili-sync/测试合集" +``` + +具体说明可以参考[这里](/collection)。 + +## 运行 + +在配置文件填写完毕后，我们可以直接运行程序。如果配置文件无误，程序会自动开始下载收藏夹中的视频。并每隔 `interval` 秒重新扫描一次。 + +如果你希望了解更详细的配置项说明，可以查询[这里](/configuration)。