FunASR-powered video transcription, subtitle generation, and LLM-assisted clipping tool with a local Gradio UI.
Python ai-toolsai-video-editingasrauto-subtitleschinesecontent-creationfunasrfunclipgradiollmparaformerspeech-recognitionspeech-to-textsubtitles-generatortranscriptionvideo-editingvideo-processingvideo-subtitlesvideo-transcriptionwhisper-alternative
docs: clarify isolated installation and startup failures
LauraGPT99fe66b08668
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.ymlindex 480e545..1baf84d 100644--- a/.github/workflows/tests.yml+++ b/.github/workflows/tests.yml@@ -34,4 +34,4 @@ jobs:python -m pip check- name: Test Gradio runtime compatibility- run: python -m pytest -q tests/test_gradio_runtime_compat.py+ run: python -m pytest -q tests/test_gradio_runtime_compat.py tests/test_installation_docs.pydiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 27bff1b..9f3dadb 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -35,19 +35,20 @@ When a fix needs a release, link the released version and ask the reporter to re```bashgit clone https://github.com/modelscope/FunClip.gitcd FunClip-python3 -m venv .venv+python3.12 -m venv .venvsource .venv/bin/activate-pip install -r requirements.txt+python -m pip install -r requirements.txt+python -m pip check```-FunClip's current Fun-ASR-Nano, SenseVoice, and subtitle compatibility paths require `funasr>=1.3.26`.+Install a matching PyTorch/torchaudio pair for your platform before the remaining requirements; see [installation and troubleshooting](docs/installation.md#english). Keep this environment separate from native Transformers 5.x examples. FunClip's current model and subtitle compatibility paths require `funasr>=1.4.9`.## ValidationRun the focused checks that match your change. For documentation, issue templates, package metadata, and provider-routing changes, start with:```bash-python3 -m pytest -q tests/test_github_templates.py tests/test_funasr_requirement.py tests/test_openai_api.py+python -m pytest -q tests/test_github_templates.py tests/test_funasr_requirement.py tests/test_installation_docs.py tests/test_openai_api.pypython3 -m py_compile funclip/launch.py funclip/videoclipper.py funclip/utils/subtitle_utils.pygit diff --check```diff --git a/README.md b/README.mdindex dca0182..65ded3f 100644--- a/README.md+++ b/README.md@@ -53,20 +53,24 @@### Python env install-FunClip basic functions rely on a python environment only.+Use a separate Python environment for FunClip. The commands below use Python 3.12; install a matching PyTorch/torchaudio pair for your platform before the remaining requirements. See the [installation and troubleshooting guide](docs/installation.md#english) for the Linux CPU recipe, Windows activation and certificate errors.```shell-# clone funclip repogit clone https://github.com/modelscope/FunClip.gitcd FunClip-# install Python requirments-pip install -r ./requirements.txt+python3.12 -m venv .venv+. .venv/bin/activate+python -m pip install -r requirements.txt+python -m pip check+python funclip/launch.py --help```+Keep this environment on the repository's **Transformers 4.x** requirements. Nano's separate native **Transformers 5.x** quickstart is not an upgrade command for an existing FunClip installation.+For a versioned snapshot, download [FunClip-2.2.1.tar.gz](https://github.com/modelscope/FunClip/releases/download/v2.2.1/FunClip-2.2.1.tar.gz) or [FunClip-2.2.1.zip](https://github.com/modelscope/FunClip/releases/download/v2.2.1/FunClip-2.2.1.zip), then verify it with the published [SHA256SUMS](https://github.com/modelscope/FunClip/releases/download/v2.2.1/SHA256SUMS). Model weights are downloaded separately when FunClip starts and are not included in these source archives.-FunClip v2.2.1 keeps the supported Gradio 4 runtime and renders built-in subtitles with Pillow so the selected foreground color survives video encoding. Existing installations should run `pip install -U -r requirements.txt` before restarting.+FunClip v2.2.1 keeps the supported Gradio 4 runtime and renders built-in subtitles with Pillow so the selected foreground color survives video encoding. Existing installations should run `python -m pip install -U -r requirements.txt` inside their FunClip environment before restarting.-FunClip's current model and subtitle compatibility paths require `funasr>=1.4.9`. This includes the MOSS vLLM adapter, long-audio generation controls, normalized `sentence_info` speaker segments, and the earlier SenseVoice and realtime fixes. If you installed FunClip before this requirement was updated, run `pip install -U "funasr>=1.4.9"` before starting the Gradio service. [Release notes](https://github.com/modelscope/FunASR/releases/tag/v1.4.9) · [PyPI](https://pypi.org/project/funasr/1.4.9/)+FunClip's current model and subtitle compatibility paths require `funasr>=1.4.9`. This includes the MOSS vLLM adapter, long-audio generation controls, normalized `sentence_info` speaker segments, and the earlier SenseVoice and realtime fixes. If you installed FunClip before this requirement was updated, run `python -m pip install -U "funasr>=1.4.9"` before starting the Gradio service. [Release notes](https://github.com/modelscope/FunASR/releases/tag/v1.4.9) · [PyPI](https://pypi.org/project/funasr/1.4.9/)### imagemagick install (Optional)diff --git a/README_zh.md b/README_zh.mdindex c4a2edd..49a534a 100644--- a/README_zh.md+++ b/README_zh.md@@ -55,20 +55,24 @@### Python环境安装-FunClip的运行仅依赖于一个Python环境,若您是一个小白开发者,可以先了解下如何使用Python,pip等~+为 FunClip 创建独立的 Python 环境。以下使用 Python 3.12;安装其余依赖前,请先安装适合当前平台且版本匹配的 PyTorch/torchaudio。[安装与排错指南](docs/installation.md#中文)提供 Linux CPU 示例、Windows 激活方式和证书错误的处理顺序。```shell-# 克隆funclip仓库git clone https://github.com/modelscope/FunClip.gitcd FunClip-# 安装相关Python依赖-pip install -r ./requirements.txt+python3.12 -m venv .venv+. .venv/bin/activate+python -m pip install -r requirements.txt+python -m pip check+python funclip/launch.py --help```+此环境继续使用仓库要求的 **Transformers 4.x**。Nano 原生 **Transformers 5.x** 快速开始是另一条独立路径,不应直接用于升级已有 FunClip 环境。+如需固定版本,可下载 [FunClip-2.2.1.tar.gz](https://github.com/modelscope/FunClip/releases/download/v2.2.1/FunClip-2.2.1.tar.gz) 或 [FunClip-2.2.1.zip](https://github.com/modelscope/FunClip/releases/download/v2.2.1/FunClip-2.2.1.zip),并使用发布页提供的 [SHA256SUMS](https://github.com/modelscope/FunClip/releases/download/v2.2.1/SHA256SUMS) 校验文件。模型权重会在 FunClip 启动时单独下载,不包含在源码归档中。-FunClip v2.2.1 使用 Pillow 渲染可选字幕颜色,并继续在 Gradio 4 环境中要求 `starlette<1.0`。已有安装请在重启前执行 `pip install -U -r requirements.txt`。容器用户可用 `--listen` 监听全部网卡;只有同时显式传入 `--share` 才会创建 Gradio 公网分享链接。+FunClip v2.2.1 使用 Pillow 渲染可选字幕颜色,并继续在 Gradio 4 环境中要求 `starlette<1.0`。已有安装请在 FunClip 环境中执行 `python -m pip install -U -r requirements.txt` 后重启。容器用户可用 `--listen` 监听全部网卡;只有同时显式传入 `--share` 才会创建 Gradio 公网分享链接。-FunClip 当前模型与字幕兼容路径需要 `funasr>=1.4.9`,其中包括 MOSS 的 vLLM 适配器、长音频生成上限、归一化的 `sentence_info` 说话人分段,以及此前的 SenseVoice 和实时修复。如果你之前已经安装过 FunClip,请先执行 `pip install -U "funasr>=1.4.9"`,再启动 Gradio 服务。[发布说明](https://github.com/modelscope/FunASR/releases/tag/v1.4.9) · [PyPI](https://pypi.org/project/funasr/1.4.9/)+FunClip 当前模型与字幕兼容路径需要 `funasr>=1.4.9`,其中包括 MOSS 的 vLLM 适配器、长音频生成上限、归一化的 `sentence_info` 说话人分段,以及此前的 SenseVoice 和实时修复。如果你之前已经安装过 FunClip,请先执行 `python -m pip install -U "funasr>=1.4.9"`,再启动 Gradio 服务。[发布说明](https://github.com/modelscope/FunASR/releases/tag/v1.4.9) · [PyPI](https://pypi.org/project/funasr/1.4.9/)### 安装 ImageMagick(可选)diff --git a/docs/installation.md b/docs/installation.mdnew file mode 100644index 0000000..346c917--- /dev/null+++ b/docs/installation.md@@ -0,0 +1,91 @@+# Installation And Startup / 安装与启动++[English](#english) · [中文](#中文)++## 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](https://pytorch.org/get-started/locally/), then install this repository's requirements.++Linux x86-64 CPU example, in a new environment:++```bash+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:++```powershell+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.++### 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](https://pip.pypa.io/en/stable/topics/https-certificates/).++**The package was installed, but this Python cannot find it:** compare the interpreter and pip paths before reinstalling anything:++```bash+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.++**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:++```bash+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](https://github.com/modelscope/FunClip/issues/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](https://www.funasr.com/en/docs/native-transformers.html). 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 官方安装说明](https://pytorch.org/get-started/locally/)选择适合平台的匹配版本,不要直接替换正在运行的生产服务环境。++Windows 可以使用上面的完整 `.venv\Scripts\python.exe` 路径,不必修改 PowerShell 执行策略。后续安装、检查和启动都应使用同一个解释器。++`python funclip/launch.py --help` 只检查导入与参数解析,不下载模型、不启动公网服务,也不证明识别或视频导出成功。`pip check` 只检查依赖声明是否兼容,不能代替动态库加载、模型下载或真实推理测试。++### 按报错阶段处理++**安装时出现 `CERTIFICATE_VERIFY_FAILED`:** 先处理 HTTPS 证书信任问题。下载未完成,后续出现 `No module named 'funasr'` 并不说明依赖清单漏了这个包。检查失败域名、系统时间、代理和 pip 源;使用操作系统/Python 发行版提供的证书,企业代理则使用经管理员认可的 CA。不要通过关闭校验或随意信任主机绕过错误。受信任 CA 的 `--cert`/`PIP_CERT` 配置见 [pip 官方证书说明](https://pip.pypa.io/en/stable/topics/https-certificates/)。++**安装成功却找不到模块:** 运行英文部分的解释器和版本检查命令。确认 `sys.executable`、`python -m pip --version` 指向同一个虚拟环境,再用相同的 `python` 启动。不要把另一个 shell、IDE 或 notebook 的安装结果当成当前环境已经装好。++**调用栈已经进入 `site-packages/funasr`:** 包已经被找到,不能仅凭中间的 `pkgutil`/导入堆栈判断缺少哪个依赖。先运行上面的独立 `AutoModel` 导入检查,再执行 `--help`,保留包含最后一行异常的完整 traceback。[#147](https://github.com/modelscope/FunClip/issues/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 指南](https://www.funasr.com/docs/native-transformers.html)。原生转写本身不提供 FunClip 所需的完整时间戳视频裁剪流程。diff --git a/tests/test_github_templates.py b/tests/test_github_templates.pyindex d922f3e..3ff438e 100644--- a/tests/test_github_templates.py+++ b/tests/test_github_templates.py@@ -52,7 +52,7 @@ def test_contributing_guide_documents_local_validation_path():text = guide.read_text()required = ["pip install -r requirements.txt",- "python3 -m pytest -q tests/test_github_templates.py tests/test_funasr_requirement.py tests/test_openai_api.py",+ "python -m pytest -q tests/test_github_templates.py tests/test_funasr_requirement.py tests/test_installation_docs.py tests/test_openai_api.py","python3 -m py_compile funclip/launch.py funclip/videoclipper.py funclip/utils/subtitle_utils.py","Audio or video input","Screenshots or clips",diff --git a/tests/test_installation_docs.py b/tests/test_installation_docs.pynew file mode 100644index 0000000..3ca5c3a--- /dev/null+++ b/tests/test_installation_docs.py@@ -0,0 +1,41 @@+from pathlib import Path++import pytest+++ROOT = Path(__file__).resolve().parents[1]++[email protected]("filename", ["README.md", "README_zh.md", "CONTRIBUTING.md"])+def test_installation_entries_use_one_python_environment(filename):+ text = (ROOT / filename).read_text()+ assert "-m venv .venv" in text+ assert "python -m pip install -r requirements.txt" in text+ assert "python -m pip check" in text+ assert "docs/installation.md" in text+++def test_contributor_minimum_matches_application_requirements():+ requirement = next(+ line for line in (ROOT / "requirements.txt").read_text().splitlines()+ if line.startswith("funasr>=")+ )+ assert requirement in (ROOT / "CONTRIBUTING.md").read_text()+++def test_troubleshooting_keeps_tls_and_runtime_boundaries():+ guide = (ROOT / "docs/installation.md").read_text()+ assert "CERTIFICATE_VERIFY_FAILED" in guide+ assert "sys.executable" in guide+ assert "python -m pip --version" in guide+ assert "python -m pip config debug" in guide+ assert "from funasr import AutoModel" in guide+ assert "https://pip.pypa.io/en/stable/topics/https-certificates/" in guide+ assert "https://www.funasr.com/docs/native-transformers.html" in guide+ assert "https://www.funasr.com/en/docs/native-transformers.html" in guide+ assert "Transformers 4.x" in guide and "Transformers 5.x" in guide+ for block in guide.split("```")[1::2]:+ if block.startswith(("bash\n", "shell\n", "powershell\n")):+ assert "--trusted-host" not in block+ assert "verify=False" not in block+ assert "PIP_TRUSTED_HOST=" not in block