刷到一段有价值的视频，想把里面的观点整理成笔记，往往要反复暂停、回放，再一点点敲出来。视频适合观看，但要搜索一句话、摘录一段内容，或者把信息放进自己的资料库，文字通常更方便。
最近，我开源了一个 Python 项目：douyin_text_extraction。
它做的事情很直接：粘贴抖音链接或完整分享文本，把视频里的语音转成可复制、可下载的文字。 项目提供 Web 界面、命令行和 HTTP API，也支持在本机运行语音识别模型。
项目地址：github.com/likebeans/douyin_text_extraction
这篇文章聊聊它怎么用，以及从一个分享链接到一段文字，中间有哪些值得展开的实现细节。
一个链接 拿到可继续使用的文字
项目支持抖音短链接、视频链接、精选页链接和完整分享文本。复制分享内容后，可以直接交给工具处理，不必先手动删除里面的文案。
拿到转写结果后，有三种使用方式：
-
通过 Web 页面使用。 粘贴链接、开始提取，在页面里阅读和复制全文，也可以下载 TXT。页面适配手机屏幕，本机配置页支持选择识别方式和本地模型。
-
通过命令行使用。 输出 Markdown、TXT 或 JSON，并指定保存路径，适合放进自己的脚本。
-
通过 HTTP API 接入。 获得转写正文以及视频标题、作者、时长、来源链接等元数据，交给其他程序继续处理。
这些能力和安装入口都整理在 README 中。
工具处理的是视频音轨中的语音，画面文字和字幕不在识别范围内。如果视频只有文字画面，没有对应的人声，就不能靠语音转写还原其中的内容。
本地和云端识别可以按需要选择
语音识别放在哪里运行，会直接影响本机资源占用、配置方式和数据流向。项目目前提供三种选择：
| 识别方式 | 运行位置 | 适合的需求 |
|---|---|---|
| SenseVoiceSmall | 本机 CPU | 处理中文口语，希望本地识别、无需配置云端 API Key |
| Whisper | 本机 CPU 或可用的 CUDA GPU | 希望自行选择模型大小，结合硬件权衡资源与处理时间 |
| DashScope | 云端 | 希望减少本机计算量，接受配置 API Key 并按服务方规则付费 |
项目默认使用 DashScope；切到本地模式后，默认引擎为 Whisper。想使用 SenseVoiceSmall，需要明确设置 LOCAL_ASR_ENGINE=sensevoice。
本地引擎通过可选依赖安装。这样，选择云端路线时，就不必同时安装本地推理需要的大型依赖。Whisper 可选 tiny、base、small、medium、large 和 turbo，具体效果仍需结合实际音频判断。
这里的“本地”指语音识别在本机执行：解析抖音链接、下载视频，以及首次获取模型，仍然需要网络。模型选择、依赖和运行方式详见语音识别说明。
先把本地中文识别跑起来
下面以 SenseVoiceSmall 为例。准备好 Python 3.10+、uv 和 FFmpeg，并确认终端执行 ffmpeg -version 能看到版本信息。
先获取代码并创建配置文件：
git clone https://github.com/likebeans/douyin_text_extraction.git
cd douyin_text_extraction
cp .env.example .env
Windows PowerShell 可将最后一行换成 Copy-Item .env.example .env。如果已经有自己的 .env，直接修改已有文件即可。
安装中文本地识别依赖：
uv sync --locked --extra local-chinese
编辑 .env，将对应配置改为：
ASR_PROVIDER=local
LOCAL_ASR_ENGINE=sensevoice
检查配置，然后启动 Web 服务：
uv run --extra local-chinese douyin-extract config-check
uv run --extra local-chinese douyin-web
打开 http://127.0.0.1:5000，粘贴抖音分享链接，点击“开始提取”，等待结果返回即可。
SenseVoiceSmall 首次使用会下载约 163 MB 的模型压缩包，解压后约 240 MB。第一次提取包含模型准备过程，长音频和 CPU 转写也可能需要较长时间。
启动时请保留 --extra local-chinese。 uv run 会同步依赖，省略对应选项可能移除之前安装的可选引擎。配置页切换引擎也不会自动安装依赖。这些安装细节以及 Whisper、DashScope 的启动方式，可以对照 README 快速开始。
从分享链接到文字的实现流程
核心流程可以分成链接解析、媒体信息获取、语音识别和结果输出。Web 与 CLI 共同调用 ExtractionService，两种入口复用同一套提取逻辑。
这部分编排集中在 src/service.py：入口负责检查配置，随后解析链接、获取视频信息、检查时长，最后选择本地或云端识别流程。界面和命令行可以围绕同一份结果，提供各自合适的交互。
分享文本先变成统一的视频信息
链接解析模块会从分享文本中提取平台 URL，处理短链接跳转，再从地址或页面数据中定位视频 ID。视频信息获取模块继续读取分享页里的 window._ROUTER_DATA，整理出媒体地址以及标题、作者、时长等信息。
这里有个容易忽略的情况：页面返回 HTTP 200，也可能暂时没有视频详情。项目针对这种情况进行有限重试，同时区分访问被拒绝和数据异常，避免对所有失败都重复请求。具体实现可看 parser.py 和 fetcher.py。
SenseVoice 的长音频切分保留完整采样
本地流程先通过 FFmpeg 将音轨转换成 16 kHz、单声道、PCM WAV，再交给识别引擎。SenseVoiceSmall 使用 sherpa-onnx 加载 int8 模型，在 CPU 上完成识别，结果可包含标点。
对于较长音频，程序将每段长度限制在 20 秒以内，并在大约第 12～20 秒之间寻找能量较低的位置作为切分点。这样可以尽量在较安静的位置切开，同时连续保留整段音频的采样。
这个细节对内容完整性很重要：声音小的讲话仍会进入识别流程，只有全零的数字静音片段会被跳过。识别结果只移除已知模型控制标签；正文中的口语重复会被保留。实现见 sensevoice_client.py。
Whisper 兼顾模型复用和重复传播问题
Whisper 模型加载后会在进程内复用，切换模型时清理旧模型缓存，避免同时缓存多个大型模型。
转写参数中，项目使用 beam_size=5，并设置 condition_on_previous_text=False，让后续窗口不继续依赖前面窗口的转写文本。这项选择旨在减少错误上下文持续传播形成的重复循环；口音、背景音乐和多人重叠说话仍可能带来识别错误。
这些设置都在 local_asr_client.py 中，便于根据自己的音频样本进一步调试。
云端直接识别失败时可以启用 OSS 备用流程
DashScope 路线先把解析得到的媒体 URL 交给云端识别。直接识别失败，并且用户已启用、配置 OSS 后，才会进入备用流程：下载视频、提取音频、上传到自己的 OSS Bucket，再把音频地址交给 DashScope。
OSS 默认使用限时签名 URL，可以配合私有 Bucket。直接识别不依赖本地 FFmpeg，启用备用流程后才需要它。相关代码在 asr_client.py，配置方式见 OSS 说明。
这样，云端路线既保留了直接提交媒体地址的简洁流程，也为直接转写失败提供了一个可选处理路径。
用 CLI 和 API 接入自己的工作流
如果希望把结果放进笔记、内容归档或后续程序，CLI 会更方便。仍以已经配置好的 SenseVoiceSmall 为例：
# 默认输出 Markdown 并保存到 output 目录
uv run --extra local-chinese douyin-extract extract "抖音链接或分享文本"
# 将 JSON 结果保存到指定路径
uv run --extra local-chinese douyin-extract extract "抖音链接" --format json --output reports/result.json
# 只向终端输出 JSON
uv run --extra local-chinese douyin-extract extract "抖音链接" --format json --no-save
JSON 模式下，标准输出只包含 JSON，诊断信息写入标准错误。这个设计让其他程序可以直接解析结果，无需先从日志里分离正文。对应实现在 main.py。
Web 服务也提供 POST /api/extract。在默认本机配置、未设置访问令牌的情况下，可以这样调用，将占位链接替换为真实链接：
curl --fail-with-body \
-H 'Content-Type: application/json' \
-d '{"link":"https://v.douyin.com/你的短链接/"}' \
http://127.0.0.1:5000/api/extract
成功响应包含 success、metadata 和 text。设置 WEB_API_TOKEN 后，请求需携带 Authorization: Bearer <token> 或 X-API-Token。
接口当前在 HTTP 请求中同步完成提取，调用方需要等待结果，并根据视频长度设置超时；超过并发上限时会返回 429。完整字段和接入说明见 API 文档。
拿到文本后，可以继续接入自己实现的摘要、关键词提取或知识库入库流程。例如，把一段知识分享转写成文字，校对后生成学习笔记，或者保留标题、作者和原始链接，方便检索时回到视频核对。这些属于围绕转写结果构建的下游应用。
让安装和使用也成为项目的一部分
把整条流程做成工具，还要处理模型之外的问题。项目为媒体下载设置了大小和总时限，为 FFmpeg 设置了执行超时；本地转写为每次提取创建独立临时目录，并按配置清理。这些细节都能在 音频处理模块 和 提取服务 中找到。
仓库还提供 Docker Compose 配置、测试和 GitHub Actions 工作流。CI 配置覆盖 Python 3.10、3.12 和 3.13，并包含 wheel 构建及安装后的 CLI、Web 资源检查，帮助发现打包时遗漏模板或静态文件的问题。参见 CI 配置。
日常使用时，仍需留意两个实际条件：语音识别结果可能出现错字，尤其是方言、商品型号和重叠人声，需要对照原视频校对；链接解析依赖平台页面，页面结构、访问策略以及视频可见性变化，都可能导致提取失败。
默认视频时长上限为 600 秒，可以通过配置调整。长视频的处理时间仍取决于所选模型、硬件和网络，相关参数见环境变量配置说明。
欢迎试用和参与
这个项目的目标，是让抖音视频里的口述内容更容易被整理和继续使用。你可以用 Web 页面处理一个视频，也可以通过 CLI 或 API，把这一步放进自己的程序。
项目代码采用 MIT 许可；识别模型权重遵循各自的许可，尤其是 SenseVoiceSmall，使用前请阅读项目中的模型许可说明。
如果你正好需要这样的工具，欢迎拿一个自己熟悉的视频试试，对照原视频看看转写效果。
觉得有帮助的话，欢迎点一个 Star。遇到安装问题、某类链接无法解析，或者希望补充一种输出方式，也欢迎提交 Issue 或 PR。具体的使用反馈，能让这个工具继续变得更好用。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/m0_63309778/article/details/169364226
