fix: pin transcription project to Python 3.12

- Set bundled FunASR transcription project to Python 3.12 - Restrict requires-python to >=3.12,<3.13 and refresh uv.lock - Document Windows editdistance wheel issue on Python 3.13 - Update README/SKILL prerequisites to recommend Python 3.12 - Add Windows FunASR uv setup troubleshooting reference
2026-07-14 14:40:01 +08:00
parent 0005ba554e
commit 790c775eac
8 changed files with 222 additions and 635 deletions
@@ -0,0 +1,62 @@
+# Windows FunASR uv setup notes
+
+Use when preparing the bundled transcription project on the Windows host for videos stored on `C:\...` or `D:\...`.
+
+## Execution-location rule
+
+If the video is on the Windows host filesystem, run the long transcription on Windows with PowerShell and Windows paths. Do not give `wsl ...` transcription commands just because the agent itself runs in WSL. The agent may use `powershell.exe` from WSL for lightweight setup/debugging, but the user-facing long command should be native PowerShell.
+
+## Correct command shape
+
+```powershell
+$TransDir = "$env:USERPROFILE\video-edit-planner-skill\scripts\transcription"
+$Video = "D:\Videos\output.mp4"
+$VideoDir = Split-Path -Parent $Video
+
+uv run --directory $TransDir funasr-nano $Video --list-tracks
+uv run --directory $TransDir funasr-nano $Video --track 2 --output-dir $VideoDir
+uv run --directory $TransDir funasr-nano $Video --track 3 --output-dir $VideoDir
+```
+
+Outputs should be written next to the video (`$VideoDir`).
+
+## Debugging `uv sync` from a WSL agent
+
+Capture real stderr/stdout to a log to avoid PowerShell's `NativeCommandError` wrapping:
+
+```powershell
+$TransDir = "$env:USERPROFILE\video-edit-planner-skill\scripts\transcription"
+$Log = Join-Path $TransDir "uv-sync-debug.log"
+Set-Location $TransDir
+uv sync *> $Log
+$Code = $LASTEXITCODE
+Write-Host "uv sync exit code: $Code"
+Get-Content $Log -Tail 160
+```
+
+From WSL, wrap this in `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command '...'`.
+
+## `editdistance` / Python version pitfall
+
+Observed failure:
+
+```text
+Failed to build `editdistance==0.8.1`
+error: Microsoft Visual C++ 14.0 or greater is required
+hint: editdistance was included because funasr -> editdistance
+```
+
+Cause: the selected Windows Python version may not have a prebuilt wheel for `editdistance==0.8.1`, so uv attempts a source build. Verified: `editdistance==0.8.1` has Windows wheels for CPython 3.12, but not for CPython 3.13.
+
+This transcription project is pinned to Python 3.12 via `.python-version` and `requires-python = ">=3.12,<3.13"`. If an older clone still selects 3.13, update it and rebuild `.venv`:
+
+```powershell
+$TransDir = "$env:USERPROFILE\video-edit-planner-skill\scripts\transcription"
+Set-Location $TransDir
+Set-Content .python-version "3.12"
+# Also set pyproject requires-python to a compatible range such as >=3.12,<3.13 if maintaining the project.
+Remove-Item -Recurse -Force .venv
+uv sync
+```
+
+Avoid defaulting to installing MSVC Build Tools unless the user explicitly prefers compiling native packages on Windows.