feat(asr): add optional SenseVoice/FunASR provider

[LauraGPT]

Summary

• Add a local SenseVoiceASR provider backed by FunASR, with lazy model loading, model caching, serialized inference, chunked processing, native timestamp parsing, and a separately loaded fsmn-vad model.
• Expose model/device selection through CLI, TOML, environment variables, and desktop settings; normalize encoded audio bytes to 16 kHz mono WAV before inference.
• Keep funasr, torch, and torchaudio in the optional sensevoice extra. Hide the desktop option when any of these packages is missing. This presence-based gate is not a complete runtime health check.
• Document that a local ASR model path does not replace the separately resolved VAD model or guarantee offline model loading. Explain timestamp fallback and that later optimization/translation stages can send text to configured external services.
• Remove a leading SentencePiece word-boundary marker from aligned words so it does not appear in word-level or sentence-level subtitles. Preserve native millisecond timestamps.

The default iic/SenseVoiceSmall checkpoint supports Chinese, Cantonese, English, Japanese, and Korean. This PR does not add a FunASR HTTP server, Paraformer, speaker diarization, or a universal performance claim. Desktop release builds do not bundle the optional runtime; the extra is for source/Python installations.

Closes #1137

Current Follow-up (2026-09-29)

Head 2bd66acf4e66833009350d210695fc74b9b2c662 follows 3141cdce1c4ba355bb75abc3fbe8f7efddcf8f0a with a two-file fix and regression tests. No dependency, lockfile, model-loading, or inference configuration changes. The commit is SSH-signed and DCO-signed-off; earlier commits were not rewritten.

The official FunASR SenseVoice.post implementation retains the SentencePiece marker when the first token starts with it. Executing that extracted postprocessing function alone with deterministic token/timestamp input reproduced this output shape, without loading a model. Both added consumer tests failed before the fix and passed afterward; they cover word and sentence modes across two results and assert exact text and timestamps. This is a source-contract and unit regression, not a new acoustic evaluation.

Validation used the existing isolated Python 3.12.3 environment from September 22, with the optional runtime installed:

• python -m pytest tests/test_cli tests/test_dubbing tests/test_asr/test_sensevoice_asr.py tests/test_asr/test_platform_utils.py -q: 94 passed, 1 warning. Provider-only run: 8 passed; these are included in the 94, not additional distinct tests.
• ruff check videocaptioner/ tests/test_asr/test_sensevoice_asr.py: passed.
• ruff format --check videocaptioner/core/asr/sensevoice.py tests/test_asr/test_sensevoice_asr.py: passed.
• pyright --pythonpath <test-environment>/bin/python videocaptioner/cli/ videocaptioner/core/asr/sensevoice.py videocaptioner/core/utils/platform_utils.py: 0 errors, 0 warnings. The separate environment-location message remains because the configured .venv directory is absent; the interpreter was explicitly selected.
• uv pip check --python <test-environment>/bin/python: all 142 installed packages compatible. No new installation or dependency resolution is claimed.
• uv build: sdist and wheel built. Provider bytes in both artifacts match the reviewed candidate. This was a packaging smoke test, not a release.
• git diff --check, SSH signature verification, and independent source review: passed; no actionable P1/P2 review findings.

The provider tests use fake inference. No model downloads, model inference, GPU/MPS checks, desktop UI acceptance, or external translation calls were performed in this follow-up.

Hosted Status

Observed at 2026-09-29T05:28:37.879006+00:00 for head 2bd66acf4e66833009350d210695fc74b9b2c662: CI completed/action_required; Claude Code Review completed/action_required; Build Desktop Apps completed/action_required. Check runs returned: 0.

No workflow approval, merge, or release was performed. Local validation is not a substitute for hosted CI.

Historical Validation (2026-09-22)

The preceding head 3141cdce1c4ba355bb75abc3fbe8f7efddcf8f0a added eight documentation lines to aeaa7de5e6cafab6655b0210920b64c6027a6f7f. At that time:

• uv sync --frozen --extra sensevoice --python 3.12, uv lock --check, and checks of all 142 installed packages passed.
• FunASR 1.3.14, Torch 2.13.0+cu130, torchaudio 2.11.0+cu130, and provider imports passed. CUDA was hidden.
• The corresponding unit selection had 92 passed, 5 warnings. Native Ruff, CLI/targeted Pyright, Markdown preservation checks, and packaging from a tracked-source export passed. Existing 26 fenced blocks and links were unchanged; the export used the no-Git fallback package version and its source bytes were verified.
• Real CPU CLI transcription ran on tests/fixtures/audio/zh.mp3 (2.628 s) and en.mp3 (3.132 s), each producing 10 timestamped segments with expected Chinese/English weather text, nonempty text, positive durations, and ordered nonoverlapping bounds within the audio. The CLI used --asr sensevoice --sensevoice-device cpu --word-timestamps --format json, explicit languages, and an existing local SenseVoiceSmall path. These runs did not mock the model.

The separate VAD model was downloaded through ModelScope during that earlier run despite the local ASR path. Those short-fixture checks are not offline guarantees, long-audio benchmarks, GPU/MPS validation, packaged-desktop acceptance, or external-translation validation, and were not rerun on the current fix.

Full-repository Pyright historically reported 4 errors and 11 warnings, with errors in core/translate/base.py, core/translate/llm_translator.py (two), and core/tts/siliconflow.py. The current narrow type check does not establish full-repository type-check success; the full check was not rerun.

The previous head's CI, Claude Code Review, and Build Desktop Apps had action_required with no jobs started. These are historical records, not current-head success.

[LauraGPT]

Follow-up for head 658b2ee: the three new workflow runs are still action_required with zero jobs, so no test has failed; they need maintainer approval before GitHub can start them:

• CI
• Claude Code Review
• Build Desktop Apps

This head also fixes a desktop packaging gap found during review: SenseVoice is now hidden unless the complete optional runtime (funasr, torch, and torchaudio) is available. Local verification is green: 92 focused tests, Ruff and targeted Pyright, sdist/wheel build, optional-runtime imports, and real CPU transcription of the Chinese and English fixtures.

Could a maintainer approve the current runs when convenient?

[LauraGPT]

Pushed head aeaa7de5e6cafab6655b0210920b64c6027a6f7f after rechecking this PR in an environment that installs the optional SenseVoice runtime.

What changed:

• Fixed the missing-optional-dependency test so it patches the same import path used by production code: importlib.import_module("funasr"). This keeps the test meaningful even when videocaptioner[sensevoice] is installed.
• Ran the current project Ruff formatter on the PR-touched CLI/config/entity files so the current locked toolchain passes ruff format --check.

Fresh validation on ind-gpu8 with uv sync --group dev --extra sensevoice:

uv run pytest tests/test_asr/test_sensevoice_asr.py tests/test_asr/test_platform_utils.py tests/test_cli/test_config.py tests/test_cli/test_parser.py -q
# 78 passed

uv run ruff check <PR-touched ASR/CLI/test files>
uv run ruff format --check <PR-touched ASR/CLI/test files>
uv run pyright videocaptioner/core/asr/sensevoice.py videocaptioner/cli/validators.py
python -m py_compile <PR-touched Python files>
git diff --check
uv build --sdist --wheel

All of the above passed. GitHub reports the PR as mergeable; the remaining workflow runs still need maintainer approval before they can execute on the fork.