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