1. 项目概述：一个无需Cookie的B站视频下载与转录工具

最近在折腾AI智能体（Agent）的时候，发现了一个挺有意思的项目，叫 rrrrrredy/bilibili-video 。简单来说，这是一个为OpenClaw AI Agent设计的技能（Skill），它的核心功能是帮你下载B站的视频，并且能把视频里的语音转成文字。最吸引我的一点是，它整个过程不需要你登录B站，也不需要提供任何Cookie，直接通过公开的API就能搞定。这对于我们这些经常需要处理视频素材、做内容分析或者单纯想离线观看的用户来说，简直太方便了。我自己试了一下，从下载到转录，一条命令就能跑通，非常适合集成到自动化工作流里。如果你也在用OpenClaw，或者对视频内容处理有需求，这个工具值得你花时间了解一下。

这个项目本质上是一个脚本集合，它巧妙地组合了几个成熟的开源工具：用 curl 或类似方式调用B站公开API获取视频流地址，用 ffmpeg 处理音视频分离，最后用 faster-whisper 这个本地化的语音识别模型把音频转成文字。整个流程设计得非常清晰，没有冗余的依赖，跑起来也很轻量。接下来，我就结合自己的使用经验，把这个工具从原理到实操，再到可能遇到的坑，给你掰开揉碎了讲清楚。

2. 核心功能与设计思路拆解

2.1 为什么可以“无Cookie”下载？

这是这个项目第一个值得说道的技术点。通常我们下载B站视频，可能会想到用 yt-dlp 这类工具，但它们往往需要配置Cookie来模拟登录状态，以获取更高清晰度的资源或规避一些限制。这个项目反其道而行之，它瞄准的是B站对未登录用户也开放的“公开API”。

具体来说，B站视频播放页面在加载时，会向一个叫 playurl 的接口请求视频流的CDN地址。这个接口在用户未登录时，依然会返回一个默认清晰度（通常是360P或480P）的视频流地址。 bilibili-video 项目就是通过模拟这个网络请求，直接获取到CDN链接，然后使用 curl 或 wget 进行下载。这样做的好处显而易见：

  1. 零门槛 ：用户无需折腾如何获取和更新Cookie，开箱即用。
  2. 安全性高 ：不涉及用户账户信息，避免了Cookie泄露的风险。
  3. 稳定性好 ：公开接口的变动相对缓慢，且针对未登录用户的服务通常比较稳定。

当然，这种方式的局限性在于，你通常只能下载到较低清晰度的视频（如360P/480P）。对于绝大多数以获取音频内容进行转录为主要目的的场景来说，这个清晰度已经完全足够了，因为音频质量并不会随着视频清晰度降低而显著受损，反而因为文件体积小，下载和处理速度更快。

2.2 工具链选型：为什么是它们？

项目的第二个设计亮点在于其精简而高效的工具链选型。每一个环节的工具都是经过深思熟虑的。

  • 下载与列表获取 ：项目脚本里可能直接使用 curl 调用API，而对于“获取UP主最新视频列表”这个功能，则引入了 yt-dlp 。这里的选择很聪明。 yt-dlp 是网络视频下载的瑞士军刀，其 --flat-playlist 参数可以非常高效、稳定地解析B站UP主空间页面的视频列表，获取BV号等信息。把专业的事情交给专业的工具，避免了重复造轮子去解析复杂的网页结构。
  • 音视频处理 ： ffmpeg 是毋庸置疑的选择。它是音视频处理领域的标准工具，几乎无所不能。在这里，它负责将下载下来的视频文件中的音频流无损（或指定质量）地提取出来，生成一个适合后续语音识别模型处理的音频文件（如WAV或MP3）。
  • 语音转录 ：这是核心中的核心。项目选择了 faster-whisper 而不是OpenAI官方的Whisper。 faster-whisper 是Whisper模型的一个重新实现，它使用了CTranslate2作为推理引擎，其最大的优势就是 速度 和 资源占用 。它支持INT8量化，能在CPU上实现较快的推理速度，这对于没有独立GPU的普通用户来说非常友好。同时，它保持了Whisper模型在中英文混合语音识别上的高准确率。

这一套组合拳下来，形成了一个从获取视频地址，到下载，到预处理，再到核心AI识别的完整、高效且轻量的流水线。

2.3 作为OpenClaw Skill的设计哲学

这个项目不仅仅是一组脚本，它被精心打包成了一个 OpenClaw Skill 。这意味着它遵循了OpenClaw智能体的技能开发规范，可以无缝地被OpenClaw Agent调用。其设计哲学体现了AI智能体应用的典型思路：

  1. 原子化操作 ：每一个功能（如下载、转录音频）都被封装成独立的、可被智能体理解和调用的操作。这使得智能体可以灵活地组合这些技能来完成更复杂的任务，比如“找到某个UP主的最新视频，下载并总结其内容”。
  2. 自然语言接口 ：在Skill的描述中，定义了诸如“B站视频下载 BV1xxx”、“b站视频转文字 BV1xxx”这样的自然语言指令。用户可以直接用说话的方式让智能体去执行任务，极大地降低了使用门槛。
  3. 一体化流水线 ：提供的 fetch_video.sh 脚本展示了一个“端到端”的最佳实践。用户只需提供一个BV号，脚本就会自动执行下载、提取音频、转录文字的全过程。这既方便了直接使用，也为智能体如何串联多个技能提供了范本。

这种设计让工具的价值超越了“下载器”本身，变成了一个可被AI调用的、具有理解和服务能力的数字模块。

3. 环境准备与详细安装指南

要运行这个项目，你需要准备好基础环境。以下步骤我亲自验证过，能确保你顺利跑起来。

3.1 基础系统依赖安装

这些是项目运行所需的底层命令工具，大部分Linux/macOS系统可能已部分安装，但建议逐一检查。

# 在Ubuntu/Debian系统上，可以使用apt安装
sudo apt update
sudo apt install -y curl ffmpeg python3-pip

# 在macOS上，使用Homebrew安装
brew install curl ffmpeg python
  • curl ：用于从网络API获取数据或下载文件。它是调用B站公开API的关键。
  • ffmpeg ：音视频处理的基石。确保安装的版本支持常见的编解码器。
  • python3-pip ：Python的包管理工具，用于安装后续的Python依赖。

注意 ：在某些极其精简的Docker镜像或服务器环境中， ffmpeg 可能需要额外安装编码器库。如果后续音频提取步骤报错，可以尝试安装 sudo apt install -y libavcodec-extra 。

3.2 Python环境与核心依赖

项目的主要逻辑由Python脚本实现，我们需要安装特定的Python包。

# 确保使用pip3，避免与系统Python2的pip混淆
pip3 install yt-dlp faster-whisper

# 如果想安装特定版本以确保兼容性，可以指定
# pip3 install yt-dlp==2024.04.09 faster-whisper==0.10.0
  • yt-dlp ：如前所述，用于获取UP主视频列表。它的更新非常频繁，以应对网站改版。
  • faster-whisper ：本地语音识别模型。第一次运行时，它会自动从Hugging Face下载指定的Whisper模型（默认为 base 模型）。请确保网络通畅，且磁盘有足够空间（ base 模型约几百MB）。

3.3 获取bilibili-video技能

你有两种方式将技能安装到你的OpenClaw环境中。

方法一：通过OpenClaw CLI安装（推荐） 如果你的OpenClaw环境已经配置好，并且CLI工具可用，这是最简洁的方式。

openclaw skill install bilibili-video

这条命令会从默认的技能仓库（通常是GitHub）拉取该技能，并安装到OpenClaw的技能目录下（例如 ~/.openclaw/skills/ ）。

方法二：手动Git克隆 如果CLI安装遇到问题，或者你想直接查看源码，可以手动克隆仓库。

# 假设你的OpenClaw技能目录在 ~/.openclaw/skills/
git clone https://github.com/rrrrredy/bilibili-video.git ~/.openclaw/skills/bilibili-video

克隆后，你需要确保技能目录的权限正确，并且OpenClaw Agent有权限读取和执行其中的脚本。

3.4 环境验证

安装完成后，进行一个快速验证，确保主要工具就绪。

# 检查curl和ffmpeg
curl --version | head -1
ffmpeg -version | head -1

# 检查Python包
python3 -c "import yt_dlp; print('yt-dlp version:', yt_dlp.version.__version__)"
python3 -c "from faster_whisper import WhisperModel; print('faster-whisper imported successfully')"

如果以上命令都没有报错，那么基础环境就搭建完成了。

4. 核心使用场景与实操详解

环境准备好了，我们来实战。这个技能主要通过两种方式使用：一是通过OpenClaw Agent用自然语言交互，二是直接调用其底层脚本。这里我们重点讲更通用、更底层的脚本使用方式，这能帮你理解其工作原理，也方便你集成到自己的其他脚本中。

4.1 场景一：下载指定BV号的视频

这是最核心的功能。假设我们要下载BV号是 BV1GJ41187du 的视频。

直接使用项目提供的流水线脚本： 项目根目录下的 scripts/fetch_video.sh 是一个封装好的流水线脚本。你需要先进入技能目录。

cd ~/.openclaw/skills/bilibili-video
bash scripts/fetch_video.sh BV1GJ41187du

这个脚本会依次执行：

  1. 调用内部方法获取视频的CDN播放地址。
  2. 使用 curl 下载视频文件（通常为 .flv 或 .mp4 格式）。
  3. 使用 ffmpeg 从视频中提取音频（默认为 .mp3 格式）。
  4. 调用 transcribe.py 脚本，使用 faster-whisper 将音频转录为文本。 执行完毕后，你会在当前目录下找到生成的文件，例如 BV1GJ41187du.mp4 、 BV1GJ41187du.mp3 和 BV1GJ41187du.txt 。

手动分步执行（理解原理）： 如果你想更精细地控制每一步，或者脚本某一步出错需要调试，可以手动执行。

# 1. 获取视频信息（这里需要查看脚本内部如何构造API请求，模拟实现）
# 假设脚本里获取到的视频流URL是：https://example.com/video.flv
VIDEO_URL="https://example.com/video.flv"

# 2. 下载视频
curl -L -o "BV1GJ41187du.mp4" "${VIDEO_URL}"

# 3. 提取音频
ffmpeg -i "BV1GJ41187du.mp4" -q:a 0 -map a "BV1GJ41187du.mp3"
# 参数解释：
# -i 输入文件
# -q:a 0 表示音频质量最高（VBR，范围0-9，0最好）
# -map a 只提取音频流
# 也可以输出为wav格式，对转录更友好：-acodec pcm_s16le -ar 16000 "audio.wav"

# 4. 转录音频
python3 scripts/transcribe.py --audio_path "BV1GJ41187du.mp3" --output_path "BV1GJ41187du.txt"

4.2 场景二：仅提取音频或仅转录

有时你可能已经有视频文件，只需要音频；或者有音频文件，只需要文字。

仅提取音频： 如果你通过其他方式获得了视频文件，可以单独使用 ffmpeg 命令。

ffmpeg -i your_video.mp4 -vn -acodec libmp3lame -ab 128k output_audio.mp3
# -vn 表示不要视频流
# -acodec libmp3lame 指定MP3编码器
# -ab 128k 设置音频比特率为128kbps

仅转录文字： 直接调用转录脚本，指向你的音频文件。

python3 ~/.openclaw/skills/bilibili-video/scripts/transcribe.py --audio_path "/path/to/your/audio.wav"

转录脚本通常支持一些参数，你可以通过 --help 查看：

python3 scripts/transcribe.py --help
# 可能支持的参数：--model_size (tiny, base, small等), --language (zh, en等), --device (cpu, cuda)

4.3 场景三：获取UP主的最新视频列表

这个功能依赖于 yt-dlp 。它并不是去下载视频，而是解析UP主的主页，获取视频列表信息。

# 假设你想获取UID为12345678的UP主的最近5个视频
yt-dlp --flat-playlist --get-id --match-filter "duration > 60" "https://space.bilibili.com/12345678/video" | head -5
  • --flat-playlist ：只列出列表，不下载。
  • --get-id ：只输出视频ID（对于B站就是BV号）。
  • --match-filter "duration > 60" ：一个过滤器示例，只列出时长大于60秒的视频。你可以根据需要调整或移除。
  • head -5 ：取前5条结果。

执行后，你会得到一串BV号列表，接下来就可以用场景一的方法循环处理它们了。你可以将这个命令与Shell脚本结合，实现批量自动化处理。

UP_UID="12345678"
VIDEO_COUNT=3

for bv in $(yt-dlp --flat-playlist --get-id "https://space.bilibili.com/${UP_UID}/video" | head -${VIDEO_COUNT}); do
    echo "处理视频: ${bv}"
    bash scripts/fetch_video.sh "${bv}"
    # 可以在这里添加后续处理，比如分析转录文本
done

5. 脚本解析与自定义修改

要真正掌握这个工具，或者让它更贴合你的需求，有必要深入看看它的脚本。我们重点分析两个核心脚本。

5.1 fetch_video.sh 工作流解析

这个Shell脚本是项目的大脑，它协调了整个流程。我们拆解一下它的典型逻辑（具体代码可能随版本更新，以下为原理性伪代码）：

#!/bin/bash
# 1. 参数检查
BV_ID=$1
if [ -z "$BV_ID" ]; then
    echo "Usage: $0 <BV号>"
    exit 1
fi

# 2. 获取视频信息（核心）
# 这里通常会调用一个Python脚本或使用curl模拟API，解析出视频标题、清晰度列表和播放URL。
# 例如：VIDEO_URL=$(python3 get_video_info.py $BV_ID)
VIDEO_URL="从API获取到的实际视频流地址"
VIDEO_TITLE="获取到的视频标题"

# 3. 下载视频
echo "正在下载视频: $VIDEO_TITLE"
curl -L -o "${BV_ID}.mp4" "$VIDEO_URL"

# 4. 提取音频
echo "正在提取音频..."
ffmpeg -i "${BV_ID}.mp4" -q:a 0 -map a "${BV_ID}.mp3" -y 2>/dev/null
# -y 选项自动覆盖已存在文件，2>/dev/null 隐藏ffmpeg信息输出

# 5. 调用转录脚本
echo "开始语音转录..."
python3 scripts/transcribe.py --audio_path "${BV_ID}.mp3" --output_path "${BV_ID}.txt"

echo "全部完成！视频: ${BV_ID}.mp4, 音频: ${BV_ID}.mp3, 字幕: ${BV_ID}.txt"

自定义点：

  • 输出目录 ：你可以在脚本开头设置一个 OUTPUT_DIR 变量，修改所有的输出路径，让文件更规整。
  • 音频格式 ：如果你希望转录效果更好，可以将MP3改为WAV格式（ -acodec pcm_s16le -ar 16000 "${BV_ID}.wav" ），并记得修改转录脚本的输入参数。
  • 错误处理 ：可以增加更完善的错误检查，比如下载失败重试、ffmpeg执行状态检查等。

5.2 transcribe.py 转录配置解析

这是执行语音识别的Python脚本，核心是调用 faster_whisper 库。

# 脚本内容示意
from faster_whisper import WhisperModel
import argparse

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--audio_path", required=True)
    parser.add_argument("--output_path", default="transcript.txt")
    parser.add_argument("--model_size", default="base") # 模型大小：tiny, base, small, medium, large
    parser.add_argument("--language", default="zh")     # 语言：zh, en, ja等，或None自动检测
    parser.add_argument("--device", default="cpu")      # 设备：cpu 或 cuda
    args = parser.parse_args()

    # 加载模型（首次运行会自动下载）
    model = WhisperModel(args.model_size, device=args.device, compute_type="int8")
    # compute_type="int8" 表示使用8位整数量化，在CPU上速度更快，精度损失可接受

    # 转录
    segments, info = model.transcribe(args.audio_path, language=args.language, beam_size=5)
    print(f"检测到语言：{info.language}， 概率：{info.language_probability}")

    # 输出文本
    with open(args.output_path, 'w', encoding='utf-8') as f:
        for segment in segments:
            print(f"[{segment.start:.2f}s -> {segment.end:.2f}s] {segment.text}")
            f.write(f"{segment.text}\n")

if __name__ == "__main__":
    main()

关键参数调整建议：

  • --model_size ：这是速度与精度的权衡。 tiny 模型最快，但识别精度最低，适合短句或对实时性要求高的场景。 base 模型是默认选择，在速度和精度上取得了很好的平衡，适合大多数情况。 small / medium / large 模型精度依次提升，但所需内存和计算时间也大幅增加。对于长视频转录， base 通常是性价比最高的选择。
  • --language ：如果你明确知道视频语言，指定语言（如 zh ）可以提高识别准确率和速度。如果不确定，可以设置为 None ，让模型自动检测，但可能会略微增加处理时间。
  • --device ：如果你有NVIDIA GPU且配置好了CUDA环境，可以设置为 cuda ，这将极大提升转录速度。对于CPU用户， int8 量化是保证速度的关键。

实操心得 ：处理长音频（如1小时以上的课程）时， faster-whisper 可能会占用较多内存。如果遇到内存不足的问题，可以尝试将音频文件预先切割成多个小段（例如每10分钟一段），然后分段转录，最后合并文本。 ffmpeg 可以很方便地做到音频切割。

6. 常见问题与故障排查实录

在实际使用中，你可能会遇到一些问题。下面是我踩过的一些坑以及解决办法。

6.1 视频下载失败或速度极慢

可能原因及排查：

  1. API失效或变更 ：B站的公开API并非官方承诺的稳定接口，有可能发生变动。这是“无Cookie”方案最大的潜在风险。

    • 排查 ：检查 fetch_video.sh 脚本中构造API请求的部分。可以尝试手动用浏览器开发者工具（F12），在B站视频播放页面的“网络（Network）”选项卡中，过滤 playurl 或 api.bilibili.com 的请求，观察其URL格式、参数和头部信息（Headers），与脚本中的进行对比。
    • 解决 ：根据最新的请求格式，更新脚本中的API请求逻辑。这可能涉及到添加新的URL参数（如 bvid 、 cid 、 qn 清晰度）或修改HTTP头部（如 Referer , User-Agent ）。

  2. 网络或CDN问题 ：获取到的CDN链接可能在某些网络环境下访问不畅。

    • 排查 ：手动复制脚本打印出的或从API获取的视频流URL，用 curl -I <URL> 测试是否能正常访问，观察返回的状态码。
    • 解决 ：可以尝试在运行脚本的机器上配置代理。由于项目说明中提到“Upstream proxy for CDN access (auto-configured in sandbox)”，如果你在OpenClaw的沙箱环境中运行，代理可能已自动配置。如果在自己的机器上，可能需要手动设置 http_proxy 和 https_proxy 环境变量。

6.2 音频提取过程报错

常见错误： 

ffmpeg: command not found

解决 ：按照本文“3.1 基础系统依赖安装”部分，正确安装 ffmpeg 。

Unsupported codec or file format

解决 ：这可能是下载的视频文件本身损坏，或者 ffmpeg 不支持其封装格式。尝试重新下载视频。也可以尝试在 ffmpeg 命令中指定输出音频编码器，如 -acodec libmp3lame 。

6.3 faster-whisper 转录失败或速度慢

问题：首次运行时卡住不动 原因 ： faster-whisper 正在从Hugging Face下载模型文件。 base 模型大约几百MB，网络不好时会很慢。 解决 ：耐心等待，或检查网络连接。你可以通过设置环境变量 HF_ENDPOINT=https://hf-mirror.com 来使用国内镜像加速下载。

问题：转录时内存不足（OOM） 原因 ：处理超长音频时，尤其是使用 large 模型，会消耗大量内存。 解决 ：

  1. 换用更小的模型，如 --model_size base 。
  2. 在转录命令中增加 --vad_filter=True 参数，启用语音活动检测（VAD），可以过滤静音段，减少内存压力。
  3. 如前所述，预先将长音频切割成小段。

问题：转录结果全是英文或乱码 原因 ：模型语言检测错误。 解决 ：明确指定语言参数 --language zh 。对于中英混合的视频，指定中文通常也能较好地识别其中的英文单词。

6.4 关于OpenClaw Skill的调用问题

问题：安装了技能，但OpenClaw Agent无法识别命令 解决 ：

  1. 确保技能安装路径正确，通常在 ~/.openclaw/skills/ 下，并且目录名是 bilibili-video 。
  2. 重启你的OpenClaw Agent进程，让它重新加载技能列表。
  3. 检查OpenClaw的日志，看是否有技能加载错误的信息。

6.5 功能扩展与进阶思路

这个项目提供了一个优秀的起点，你可以基于它进行扩展：

  1. 批量处理与任务队列 ：结合获取UP主列表的功能，编写一个守护脚本，定时获取指定UP主的新视频，自动下载并转录，实现无人值守的内容收集。
  2. 集成到内容分析流水线 ：将转录得到的文本，接入到另一个AI技能（例如基于大语言模型的摘要总结、关键词提取、情感分析技能），构建一个从视频到结构化见解的完整管道。
  3. 支持更多视频源 ：研究其他视频平台（如YouTube、抖音）的公开API或解析方式，用类似的架构（下载->提取音频->转录）扩展技能，使其成为一个通用的视频内容处理工具。
  4. 优化转录后处理 ： faster-whisper 输出的文本是按时间戳分段的。你可以编写后处理脚本，将这些片段合并成更连贯的段落，并加上标点符号优化（虽然Whisper本身已具备一定的加标点能力，但仍有提升空间）。

这个项目的价值在于它展示了一种简洁、实用的技术集成方案。它没有追求大而全，而是把几个关键工具用脚本粘合起来，解决了一个明确的需求。无论是直接使用，还是作为你自定义工作流的参考，它都能给你带来不少启发。

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

Agent 网关崩溃恢复实战：OpenRouter 多模型路由下的心跳与热更新陷阱

avatar 龙虾开发者社区
cover

OpenClaw 网关如何用结构化日志与账本控制多模型 Fallback 成本？

avatar 龙虾开发者社区
cover

为什么你的 ClawAgent 工具调用总失败？沙箱权限与 MCP 协议三大误区排查

avatar 龙虾开发者社区