nite/video-edit-planner-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: choose transcription environment by video locality

Browse Source 
- Choose Windows vs WSL execution based on where the video file lives
- Windows-host videos (/mnt/c, /mnt/d, C:, D:) should use PowerShell and Windows-local transcription project
- WSL/Linux videos (/home, /var, Linux mounts) should use Linux/WSL commands
- Keep Windows uv UNC-path warning, but only when Windows execution is chosen
- Add reference doc with Windows and WSL command templates
This commit is contained in:
nite
2026-07-14 14:11:04 +08:00
parent 3c4a0de8a5
commit 279d0a85d8
2 changed files with 84 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SKILL.md
+13 -14
View File
@@ -101,14 +101,13 @@ Use the bundled `funasr-script` in `scripts/transcription/`. **Prefer Fun-ASR-Na
**Critical: when you tell the user you will provide a command, include it immediately in the same response.** Do not say "I'll give you the transcription command" and then move on to other topics without actually printing the command. The user should never have to ask "you said you'd give me the command but didn't."
**If the agent detects it is running in WSL**, it should provide PowerShell commands for the user to run on the Windows host, not Linux commands. For example, convert the SKILL_DIR and VIDEO_PATH to their Windows equivalents (e.g., `C:\Users\...` instead of `/mnt/c/...`). However, if the user is comfortable running commands directly in WSL (e.g., they use WSL as their primary terminal), Linux commands with `/mnt/...` paths are fine — assess the user's environment before deciding.
**Choose the execution environment based on where the video file lives, not based only on where the agent runs.** Keep heavy media I/O local to the filesystem that stores the video:
**WSL constraint: uv cannot run from WSL UNC paths.** If the skill is installed inside the WSL filesystem (e.g., `~/.hermes/skills/...`), the Windows `uv` command cannot operate on it directly via UNC paths like `\\wsl.localhost\...` — it will fail with directory errors. When the agent detects WSL and the skill lives in the WSL filesystem, it should give the user one of these options:
- If the video is on the Windows host filesystem (for example a WSL path under `/mnt/c/...`, `/mnt/d/...`, etc.), prefer running transcription on the Windows host with PowerShell and Windows paths (`C:\...`, `D:\...`). This avoids routing large video reads through WSL and usually gives better hardware/GPU access.
- If the video is inside the WSL/Linux filesystem (for example `/home/...`, `/var/...`, or another Linux mount), prefer running transcription in WSL/Linux with Linux paths. Do not force Windows just because the agent itself is running in WSL.
- If the location is ambiguous, ask the user where the video is stored and where they want the workload to run.
1. **Clone the repo on Windows** (recommended): `git clone https://git.nite07.com/nite/video-edit-planner-skill.git C:\Users\<user>\video-edit-planner` then run `uv` from `C:\Users\<user>\video-edit-planner\scripts\transcription`.
2. **Let the agent copy the scripts**: the agent copies `scripts/transcription/` to a Windows path (e.g., `/mnt/c/Users/<user>/AppData/Local/Temp/vedit-transcription/`) and gives the user a PowerShell command pointing there.
Either way, the transcription command the user receives should use a **Windows local path** (`C:\...`), never a UNC path.
**Windows `uv` constraint:** Windows `uv` should not operate on WSL UNC paths like `\\wsl.localhost\...` or `\\wsl$\...`; it can fail while managing `.venv` directories. Therefore, when the chosen execution environment is Windows, the transcription project itself must also be available under a Windows-local path. Follow `references/wsl-windows-uv-transcription.md`: either clone the skill repo on Windows, or copy `scripts/transcription/` to a Windows-local directory, then run `uv` from that local Windows path.
Command templates (adjust paths for the user's environment):
@@ -368,9 +367,9 @@ Some material sites may block automated access (anti-bot, Cloudflare, CAPTCHA).
Before any operation expected to take >1 minute (first-time `uv sync`, transcription of long videos, large frame extraction):
1. **Generate the command and give it to the user to execute manually**, rather than running it in the agent's own environment. This avoids blocking the conversation and lets the user run it on a more powerful machine (e.g., a Windows host while the agent runs in WSL).
2. If the agent runs in WSL, provide PowerShell commands with Windows local paths (e.g., `C:\Users\...` instead of `/mnt/c/...`) for the user to run on the Windows host.
3. Do not point Windows `uv` at `\\wsl.localhost\...` or `\\wsl$\...` paths. Put/clone/copy the transcription project under a Windows local directory first, then run `uv` there.
1. **Generate the command and give it to the user to execute manually**, rather than running it in the agent's own environment. This avoids blocking the conversation and lets the user run it where the media I/O is fastest.
2. Choose PowerShell/Windows commands when the video file is on the Windows host filesystem (`/mnt/c/...`, `/mnt/d/...`, or a Windows path like `C:\...`). Choose Linux/WSL commands when the video file is stored in the WSL/Linux filesystem (`/home/...`, `/var/...`, etc.).
3. Do not point Windows `uv` at `\\wsl.localhost\...` or `\\wsl$\...` paths. If Windows execution is chosen, put/clone/copy the transcription project under a Windows local directory first, then run `uv` there.
4. After the user reports completion, the agent should verify the output exists before proceeding.
## Self-contained setup
@@ -383,20 +382,20 @@ cd SKILL_DIR/scripts/transcription && uv sync
This creates an isolated venv with `funasr`, `torch`, `torchaudio`. If the user has previously installed these packages via uv in other projects, uv's cache will reuse them — first-time cost is only the link step.
If the agent runs in WSL and the skill is installed under the WSL filesystem, do **not** run Windows `uv` against the WSL path. Instead, tell the user to prepare a Windows-local copy of the transcription project first:
If Windows execution is chosen because the video is on the Windows host filesystem, and the skill is installed under the WSL filesystem, do **not** run Windows `uv` against the WSL path. Instead, tell the user to prepare a Windows-local copy of the transcription project first:
```powershell
# Option A: clone the full skill repo on Windows (recommended)
# Option A: clone the full skill repo on Windows (recommended for repeated use)
git clone https://git.nite07.com/nite/video-edit-planner-skill.git "$env:USERPROFILE\\video-edit-planner-skill"
Set-Location "$env:USERPROFILE\\video-edit-planner-skill\\scripts\\transcription"
uv sync
# Option B: after the agent copies scripts/transcription to a Windows-local directory
# Option B: after the agent copies scripts/transcription to a Windows-local directory (one-off use)
Set-Location "C:\\Users\\<user>\\AppData\\Local\\Temp\\vedit-transcription"
uv sync
```
Subsequent transcription commands should also use that same Windows-local transcription directory.
Subsequent Windows transcription commands should also use that same Windows-local transcription directory. If the video is stored inside WSL/Linux, run `uv sync` and transcription in WSL instead.
## Common pitfalls
@@ -411,7 +410,7 @@ Subsequent transcription commands should also use that same Windows-local transc
9. **Hardcoding output language.** The edit plan table and all user-facing text must follow the user's language, not a fixed language. The English table in Step 8 is a template — translate columns and content to match the user's language at runtime.
10. **Dropping audio tracks during clip extraction.** The default clip command maps only `0:v:0` (video-only) for fast frame extraction. If the user plans to import the clip into a video editor, use `--all-streams` (or `-map 0`) to preserve all audio tracks. Always ask the user which they need.
11. **Using `~/whisperx_output/` or other separate output directories.** All artifacts (transcription JSON, clips, frames, index file) must go in the same directory as the video file. The `--output-dir` flag should always point to the video's own directory. This keeps everything co-located and portable.
12. **Running transcription commands in the agent's own environment.** Transcription is long-running and resource-intensive. Generate the command and give it to the user to execute on their host machine. If the agent runs in WSL, provide PowerShell commands with Windows local paths. Never ask Windows `uv` to run from `\\wsl.localhost\...` / `\\wsl$\...`; clone or copy the transcription project to `C:\...` first.
12. **Choosing execution environment solely from where the agent runs.** Choose based on where the video file lives. Windows-host video (`/mnt/c`, `/mnt/d`, `C:\...`, `D:\...`) → PowerShell/Windows-local transcription project. WSL/Linux video (`/home/...`, `/var/...`) → WSL/Linux commands. Never ask Windows `uv` to run from `\\wsl.localhost\...` / `\\wsl$\...`; clone or copy the transcription project to `C:\...` first when Windows execution is chosen.
13. **Saying you'll provide a command but not including it.** If you mention giving the user a transcription command, include it immediately in that same response. Do not move on to other content without printing the actual command. The user should never have to ask for it.
14. **Sending a wall of free-text questions.** When gathering editing requirements, use structured one-at-a-time multiple-choice questions via the runtime's clarify/prompt tool. This is far more effective than dumping 10 questions as a paragraph.
references/wsl-windows-uv-transcription.md
+71
View File
@@ -0,0 +1,71 @@
# Choosing Windows vs WSL for `uv` transcription
Use this reference when the agent may be running in WSL but the user has both a Windows host and a WSL/Linux environment.
## Core rule: follow the video file
Choose the execution environment based on **where the video file is stored**, not based only on where the agent runs.
| Video location | Preferred execution | Why |
|---|---|---|
| Windows host filesystem (`C:\...`, `D:\...`, or WSL paths like `/mnt/c/...`, `/mnt/d/...`) | Windows host, PowerShell, Windows paths | Keeps heavy video reads local to Windows; usually better host/GPU access |
| WSL/Linux filesystem (`/home/...`, `/var/...`, Linux project directories) | WSL/Linux shell, Linux paths | Keeps heavy video reads local to Linux; avoids Windows reading through WSL UNC |
| Ambiguous / network / external drive | Ask the user | Storage locality and GPU/tool availability may differ |
Do **not** assume Windows execution just because the agent itself runs in WSL. If the video is genuinely inside the WSL filesystem, running the Linux transcription project in WSL is the correct choice.
## Windows `uv` constraint
When Windows execution is chosen, do **not** ask Windows `uv` to operate on the skill's WSL filesystem path (`\\wsl.localhost\...` / `\\wsl$\...`). Windows `uv` can fail while creating or removing `.venv` directories on UNC-backed WSL paths.
Instead, make the transcription project available under a Windows-local path and run `uv` there.
Recommended options:
1. **Windows-local clone** (best for repeated use)
```powershell
git clone https://git.nite07.com/nite/video-edit-planner-skill.git "$env:USERPROFILE\video-edit-planner-skill"
Set-Location "$env:USERPROFILE\video-edit-planner-skill\scripts\transcription"
uv sync
```
2. **Windows-local copy** (best for one-off use)
- Agent copies `scripts/transcription/` from the WSL skill directory to a Windows path, e.g. `/mnt/c/Users/<user>/AppData/Local/Temp/vedit-transcription/`.
- Then give the user:
```powershell
Set-Location "C:\Users\<user>\AppData\Local\Temp\vedit-transcription"
uv sync
```
## Windows command shape
Use this when the video is stored on the Windows host filesystem:
```powershell
$SkillTranscription = "$env:USERPROFILE\video-edit-planner-skill\scripts\transcription"
$Video = "D:\Videos\example.mkv"
$VideoDir = Split-Path -Parent $Video
uv run --directory $SkillTranscription funasr-nano $Video --track 2 --output-dir $VideoDir
```
For multiple tracks, run once per track and record each resulting JSON in the index.
## WSL/Linux command shape
Use this when the video is stored inside the WSL/Linux filesystem:
```bash
SKILL_TRANSCRIPTION="$HOME/.hermes/skills/media/video-edit-planner/scripts/transcription"
VIDEO="$HOME/videos/example.mkv"
VIDEO_DIR="$(dirname "$VIDEO")"
uv run --directory "$SKILL_TRANSCRIPTION" funasr-nano "$VIDEO" --track 2 --output-dir "$VIDEO_DIR"
```
If the user installed the skill somewhere else, adjust `SKILL_TRANSCRIPTION` accordingly.
## Notes for agents
- Prefer Fun-ASR-Nano unless the user explicitly wants a fast preview.
- Give the command immediately when promising a command.
- Keep all outputs next to the video file.
- Avoid separate output directories such as `~/whisperx_output/`; transcription JSON, clips, frames, and the index should stay with the video.
- Use Windows paths (`C:\...`, `D:\...`) only for Windows execution; use Linux paths for WSL execution.