docs: clarify isolated installation and startup failures

.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.py

CONTRIBUTING.md

@@ -35,19 +35,20 @@ When a fix needs a release, link the released version and ask the reporter to re
 ```bash
 git clone https://github.com/modelscope/FunClip.git
 cd FunClip
-python3 -m venv .venv
+python3.12 -m venv .venv
 source .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`.
 
 ## Validation
 
 Run 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.py
 python3 -m py_compile funclip/launch.py funclip/videoclipper.py funclip/utils/subtitle_utils.py
 git diff --check
 ```

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 repo
 git clone https://github.com/modelscope/FunClip.git
 cd 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)
 

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.git
 cd 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（可选）
 

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 所需的完整时间戳视频裁剪流程。

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",

tests/test_installation_docs.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+@pytest.mark.parametrize("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