FunASR-powered video transcription, subtitle generation, and LLM-assisted clipping tool with a local Gradio UI.
Installation And Startup / 安装与启动
English
Start In One Environment
Run commands from the FunClip repository root. Use Python 3.12 for the example below, and keep FunClip separate from existing ASR services. Install a matching PyTorch/torchaudio pair for your platform using the official PyTorch instructions, then install this repository's requirements.
Linux x86-64 CPU example, in a new environment:
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install --index-url https://download.pytorch.org/whl/cpu \
"torch==2.10.0" "torchaudio==2.10.0"
python -m pip install -r requirements.txt
python -m pip check
python funclip/launch.py --help
This is a CPU setup, not a CUDA recipe. For a GPU or another platform, select the appropriate matching pair before installing the remaining requirements; do not replace packages in a running production environment. Windows/macOS hardware and driver combinations need separate validation.
On Windows, you can use the environment's Python directly without changing PowerShell's execution policy:
py -3.12 -m venv .venv
# Install the platform-appropriate torch/torchaudio pair into this environment first.
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe funclip\launch.py --help
--help checks imports and argument parsing without downloading a model or starting a public service. It does not verify transcription or video export. A successful pip check only checks declared dependency compatibility, not native-library loading, model downloads or inference.
Conda Alternative (Linux x86-64 CPU)
Conda is also supported; uv is not required. With Conda already installed, run
the following from the repository root instead of creating the .venv above.
Use a new environment name if funclip already belongs to another application.
conda create -n funclip --override-channels -c conda-forge python=3.12 pip -y
conda run -n funclip python -m pip install --index-url https://download.pytorch.org/whl/cpu "torch==2.10.0" "torchaudio==2.10.0"
conda run -n funclip python -m pip install --no-compile -r requirements.txt
conda run -n funclip python -m pip check
conda run --no-capture-output -n funclip python funclip/launch.py --help
conda run -n funclip keeps installation and execution in the same environment
without depending on shell activation. --no-compile skips Python bytecode
precompilation, not dependencies or compatibility checks. If installation is
interrupted, inspect its final error and python -m pip check in this environment
before continuing; an installer report or a downloaded wheel alone is not proof
that the package was installed successfully.
The isolated CPU setup was checked with Conda 26.9.4, Python 3.12.16 and torch/torchaudio 2.10.0+cpu; see the validation scope and environment caveat in #230. This is not a CUDA, Windows or macOS recipe. The installation, native imports, CLI/Gradio checks and synthetic media I/O do not establish pretrained ASR quality or a complete recognition-to-clipping workflow.
After the checks pass, launch with
conda run --no-capture-output -n funclip python funclip/launch.py. Unlike
--help, normal startup may download models and start the configured service.
Confirm ffmpeg -version also works; install FFmpeg for your platform if absent.
If Installation Or Startup Fails
CERTIFICATE_VERIFY_FAILED during pip install: fix the HTTPS trust failure first. It means the package download did not complete, so a later No module named 'funasr' is not evidence that requirements omitted the package. Check the failing hostname, system clock, proxy and configured package indexes. Use certificates supplied by your OS/Python distribution or an approved corporate CA; never disable certificate verification or make arbitrary hosts trusted to get an install through. Pip supports an approved CA bundle through --cert/PIP_CERT; see its certificate documentation.
The package was installed, but this Python cannot find it: compare the interpreter and pip paths before reinstalling anything:
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version
python -m pip show funasr torch torchaudio gradio moviepy transformers
python -m pip check
Use that same python to launch FunClip. An IDE, notebook or shell may otherwise use another interpreter even if a bare pip command succeeded.
A fresh environment still loads another PyTorch installation's libraries:
preconfigured Linux deep-learning images may inject a system torch/lib path
through LD_LIBRARY_PATH. Even when pip check passes and the Python package
path is correct, this can mix an environment's CPU wheel with host CUDA libraries
and fail with errors such as a missing torch._C._dlpack_exchange_api.
Compare the Python executable/package path and the shared libraries actually
loaded by that process. If a foreign PyTorch library directory is confirmed,
exclude only that conflicting entry from the affected launch command's child
environment, after Conda activation. Do not globally clear LD_LIBRARY_PATH:
other entries may be needed by FFmpeg or unrelated services. Then recheck native
imports, ffmpeg -version and --help; this diagnosis does not imply every
import error has the same cause.
The traceback already enters site-packages/funasr: the package was found. Capture the complete exception, especially its final line; do not keep installing packages based only on intermediate pkgutil or import-stack frames. Check the import separately, then the application:
python -c "from funasr import AutoModel; print('FunASR import OK')"
python funclip/launch.py --help
For index/proxy diagnostics, inspect python -m pip config debug locally. Before posting output, redact credentials, tokens, proxy passwords and private index URLs. Include the FunClip commit, OS, interpreter/package versions, the failing command and the full traceback. A screenshot cut off before the final exception cannot establish the cause. These distinctions come from the two different failure paths reported in #147; that issue remains open for the original environments to be retested.
Keep The Two Transformers Routes Separate
FunClip currently requires Transformers 4.x (transformers<5.0) and huggingface_hub<1.0. Its toolkit model, clipping and Gradio paths are not the same environment as the native Nano Transformers 5.x example. Installing the native example's requirements into FunClip can violate these constraints.
For standalone native transcription, use a different virtual environment and the native Transformers guide. Native transcription alone does not provide FunClip's timestamp-based video clipping workflow.
中文
先固定一个环境
在 FunClip 仓库根目录执行命令。上面的 Linux x86-64 CPU 示例使用 Python 3.12 和独立虚拟环境,先安装匹配的 PyTorch/torchaudio,再安装 requirements.txt。GPU、Windows 或 macOS 请按 PyTorch 官方安装说明选择适合平台的匹配版本,不要直接替换正在运行的生产服务环境。
Windows 可以使用上面的完整 .venv\Scripts\python.exe 路径,不必修改 PowerShell 执行策略。后续安装、检查和启动都应使用同一个解释器。
python funclip/launch.py --help 只检查导入与参数解析,不下载模型、不启动公网服务,也不证明识别或视频导出成功。pip check 只检查依赖声明是否兼容,不能代替动态库加载、模型下载或真实推理测试。
使用 Conda(Linux x86-64 CPU)
不需要安装 uv。已有 Conda 时,可以在仓库根目录执行上面的
Conda 命令,替代 .venv 方案。
如果 funclip 环境名已被其他应用使用,请换一个新名字,并同步修改全部
conda run -n 命令,避免覆盖原有服务环境。
这条路径使用 Python 3.12,先从官方 CPU 索引安装匹配的 torch/torchaudio
2.10.0,再安装仓库依赖。conda run -n funclip 保证安装、检查和启动使用
同一个解释器,不依赖当前 shell 是否激活了环境。--no-compile 只省略
Python 字节码预编译,不跳过依赖或兼容性检查。安装中断后,应先查看最后
的异常并在同一环境运行 python -m pip check;下载完成或生成安装报告
不等于安装成功。
实际验证使用 Conda 26.9.4 / Python 3.12.16 / torch、torchaudio
2.10.0+cpu;范围及验证机的动态库注意事项见 #230 的实测回复。
安装、导入、CLI/Gradio 和合成媒体读写通过,不代表预训练 ASR 质量或完整
识别到剪辑流程已经验收;GPU、Windows、macOS 需要各自的平台配置与验证。
检查通过后可用 conda run --no-capture-output -n funclip python funclip/launch.py
启动,正常启动可能下载模型并启动配置的服务。还应确认 ffmpeg -version
成功,缺失时先安装对应平台的 FFmpeg。
按报错阶段处理
安装时出现 CERTIFICATE_VERIFY_FAILED: 先处理 HTTPS 证书信任问题。下载未完成,后续出现 No module named 'funasr' 并不说明依赖清单漏了这个包。检查失败域名、系统时间、代理和 pip 源;使用操作系统/Python 发行版提供的证书,企业代理则使用经管理员认可的 CA。不要通过关闭校验或随意信任主机绕过错误。受信任 CA 的 --cert/PIP_CERT 配置见 pip 官方证书说明。
安装成功却找不到模块: 运行英文部分的解释器和版本检查命令。确认 sys.executable、python -m pip --version 指向同一个虚拟环境,再用相同的 python 启动。不要把另一个 shell、IDE 或 notebook 的安装结果当成当前环境已经装好。
新环境仍加载了另一套 PyTorch 动态库: Linux 深度学习预装镜像可能通过
LD_LIBRARY_PATH 注入系统 torch/lib。即使 pip check 通过、Python 包路径
也正确,CPU wheel 仍可能错载宿主 CUDA 库,出现
torch._C._dlpack_exchange_api 缺失等错误。先核对解释器、包路径和进程实际
加载的动态库;确认是外部 PyTorch 目录冲突后,只在受影响启动命令的子进程
环境中、Conda 激活之后排除该条目录。不要全局清空 LD_LIBRARY_PATH,其他
目录可能供 FFmpeg 或其他服务使用。随后重新检查真实导入、ffmpeg -version
和 --help,不能把所有导入错误都归为这个原因。
调用栈已经进入 site-packages/funasr: 包已经被找到,不能仅凭中间的 pkgutil/导入堆栈判断缺少哪个依赖。先运行上面的独立 AutoModel 导入检查,再执行 --help,保留包含最后一行异常的完整 traceback。#147 的两张截图分别属于证书失败和已进入 FunASR 的导入失败,不能当作同一个问题。
需要检查代理或源配置时,在本机查看 python -m pip config debug。公开日志前,删除账号密码、token、代理凭据和私有源地址;提供 FunClip commit、操作系统、解释器与包版本、完整命令和 traceback。报告者尚未完成原环境复测时,诊断或文档更新不等于问题已经解决。
不混用 Transformers 环境
FunClip 当前依赖 Transformers 4.x 和 huggingface_hub<1.0,Nano 原生 Transformers 5.x 是另一条路径。不要在 FunClip 环境里直接执行原生示例的升级命令。
如果只需原生语音转写,请在另一个虚拟环境使用原生 Transformers 指南。原生转写本身不提供 FunClip 所需的完整时间戳视频裁剪流程。