From bf77c945339f8e3fa9fb063bcd9dcbd78996d8a0 Mon Sep 17 00:00:00 2001
From: matt <mattstyles333@gmail.com>
Date: Wed, 12 Aug 2026 22:43:38 +0100
Subject: [PATCH 1/2] Add Grok STT as the default transcription provider
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Grok STT already ships word-level timestamps, diarization, and filler-word
retention. Normalize its words into the existing Scribe-shaped schema so
pack/render/timeline_view stay unchanged. ElevenLabs remains available
via --provider elevenlabs.

Vision composites stay local (timeline_view PNGs) — no API to swap.
---
 .env.example                |   4 +-
 README.md                   |  21 ++---
 SKILL.md                    |  14 ++--
 helpers/transcribe.py       | 161 +++++++++++++++++++++++++++++++-----
 helpers/transcribe_batch.py |  22 +++--
 install.md                  |  47 ++++++-----
 pyproject.toml              |   2 +-
 7 files changed, 206 insertions(+), 65 deletions(-)

diff --git a/.env.example b/.env.example
index 4c49a949..b85fcd2c 100644
--- a/.env.example
+++ b/.env.example
@@ -1 +1,3 @@
-ELEVENLABS_API_KEY=
+XAI_API_KEY=
+# Optional fallback (helpers/transcribe.py --provider elevenlabs)
+# ELEVENLABS_API_KEY=
diff --git a/README.md b/README.md
index 0f7b2649..9ed4a10d 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,9 @@
 
 # video-use
 
-Introducing **video-use** — edit videos with Claude Code. 100% open source.
+Introducing **video-use** — edit videos with Grok, Claude Code, or any coding agent. 100% open source.
 
-Drop raw footage in a folder, chat with Claude Code, get `final.mp4` back. Works for any content — talking heads, montages, tutorials, travel, interviews — without presets or menus.
+Drop raw footage in a folder, chat with your agent, get `final.mp4` back. Works for any content — talking heads, montages, tutorials, travel, interviews — without presets or menus.
 
 Try video-use in [Browser Use Cloud](https://cloud.browser-use.com/v4?utm_campaign=video-use-use-in-cloud&utm_source=github).
 
@@ -22,21 +22,21 @@ Try video-use in [Browser Use Cloud](https://cloud.browser-use.com/v4?utm_campai
 
 ## Setup prompt
 
-Paste into Claude Code, Codex, Hermes, Openclaw, or any agent with shell access:
+Paste into Grok, Claude Code, Codex, Hermes, Openclaw, or any agent with shell access:
 
 ```text
 Set up https://github.com/browser-use/video-use for me.
 
-Read install.md first to install this repo, wire up ffmpeg, register the skill with whichever agent you're running under, and set up the ElevenLabs API key — ask me to paste it when you need it. Then read SKILL.md for daily usage, and always read helpers/ because that's where the editing scripts live. After install, don't transcribe anything on your own — just tell me it's ready and wait for me to drop footage into a folder.
+Read install.md first to install this repo, wire up ffmpeg, register the skill with whichever agent you're running under, and set up the xAI API key — ask me to paste it when you need it. Then read SKILL.md for daily usage, and always read helpers/ because that's where the editing scripts live. After install, don't transcribe anything on your own — just tell me it's ready and wait for me to drop footage into a folder.
 ```
 
-The agent handles the clone, dependencies, skill registration, and prompts you once for your ElevenLabs API key (grab one at [elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys)).
+The agent handles the clone, dependencies, skill registration, and prompts you once for your xAI API key (grab one at [console.x.ai](https://console.x.ai/team/default/api-keys)).
 
 Then point your agent at a folder of raw takes:
 
 ```bash
 cd /path/to/your/videos
-claude    # or codex, hermes, etc.
+grok      # or claude, codex, hermes, etc.
 ```
 
 For always-on editing from your own VPS or Telegram, run the agent through [Browser Use Box](https://browser-use.com/bux). [Watch the 15-second demo](https://www.tiktok.com/@browser_use/video/7639824093721758989).
@@ -54,7 +54,8 @@ If you'd rather do it by hand:
 ```bash
 # 1. Clone and symlink into your agent's skills directory
 git clone https://github.com/browser-use/video-use ~/Developer/video-use
-ln -sfn ~/Developer/video-use ~/.claude/skills/video-use        # Claude Code
+ln -sfn ~/Developer/video-use ~/.grok/skills/video-use          # Grok
+# ln -sfn ~/Developer/video-use ~/.claude/skills/video-use      # Claude Code
 # ln -sfn ~/Developer/video-use ~/.codex/skills/video-use       # Codex
 
 # 2. Install deps
@@ -63,9 +64,9 @@ uv sync                         # or: pip install -e .
 brew install ffmpeg             # required
 brew install yt-dlp             # optional, for downloading online sources
 
-# 3. Add your ElevenLabs API key
+# 3. Add your xAI API key
 cp .env.example .env
-$EDITOR .env                    # ELEVENLABS_API_KEY=...
+$EDITOR .env                    # XAI_API_KEY=...
 ```
 
 ## How it works
@@ -76,7 +77,7 @@ The LLM never watches the video. It **reads** it — through two layers that tog
   <img src="static/timeline-view.svg" alt="timeline_view composite — filmstrip + speaker track + waveform + word labels + silence-gap cut candidates" width="100%">
 </p>
 
-**Layer 1 — Audio transcript (always loaded).** One ElevenLabs Scribe call per source gives word-level timestamps, speaker diarization, and audio events (`(laughter)`, `(applause)`, `(sigh)`). All takes pack into a single ~12KB `takes_packed.md` — the LLM's primary reading view.
+**Layer 1 — Audio transcript (always loaded).** One Grok STT call per source gives word-level timestamps, speaker diarization, and filler-word retention (ElevenLabs Scribe is still available via `--provider elevenlabs`). All takes pack into a single ~12KB `takes_packed.md` — the LLM's primary reading view.
 
 ```
 ## C0103  (duration: 43.0s, 8 phrases)
diff --git a/SKILL.md b/SKILL.md
index fa4b776d..451d3146 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -24,8 +24,8 @@ These are the things where deviation produces silent failures or broken output.
 3. **30ms audio fades at every segment boundary** (`afade=t=in:st=0:d=0.03,afade=t=out:st={dur-0.03}:d=0.03`). Otherwise audible pops at every cut.
 4. **Overlays use `setpts=PTS-STARTPTS+T/TB`** to shift the overlay's frame 0 to its window start. Otherwise you see the middle of the animation during the overlay window.
 5. **Master SRT uses output-timeline offsets**: `output_time = word.start - segment_start + segment_offset`. Otherwise captions misalign after segment concat.
-6. **Never cut inside a word.** Snap every cut edge to a word boundary from the Scribe transcript.
-7. **Pad every cut edge.** Working window: 30–200ms. Scribe timestamps drift 50–100ms — padding absorbs the drift. Tighter for fast-paced, looser for cinematic.
+6. **Never cut inside a word.** Snap every cut edge to a word boundary from the word-level transcript.
+7. **Pad every cut edge.** Working window: 30–200ms. ASR timestamps drift tens of milliseconds — padding absorbs the drift. Tighter for fast-paced, looser for cinematic.
 8. **Word-level verbatim ASR only.** Never SRT/phrase mode (loses sub-second gap data). Never normalized fillers (loses editorial signal).
 9. **Cache transcripts per source.** Never re-transcribe unless the source file itself changed.
 10. **Parallel sub-agents for multiple animations.** Never sequential. Spawn N at once via the `Agent` tool; total wall time ≈ slowest one.
@@ -45,7 +45,7 @@ The skill lives in `video-use/`. User footage lives wherever they put it. All se
     ├── project.md               ← memory; appended every session
     ├── takes_packed.md          ← phrase-level transcripts, the LLM's primary reading view
     ├── edl.json                 ← cut decisions
-    ├── transcripts/<name>.json  ← cached raw Scribe JSON
+    ├── transcripts/<name>.json  ← cached raw STT JSON
     ├── animations/slot_<id>/    ← per-animation source + render + reasoning
     ├── clips_graded/            ← per-segment extracts with grade + fades
     ├── master.srt               ← output-timeline subtitles
@@ -59,7 +59,7 @@ The skill lives in `video-use/`. User footage lives wherever they put it. All se
 
 First-time install lives in `install.md` (clone, deps, ffmpeg, skill registration, API key). Don't re-run it every session; on cold start just verify:
 
-- `ELEVENLABS_API_KEY` resolves — either in the environment or in `.env` at the video-use repo root. If missing, ask the user to paste one and write it to `.env` (never to the user's `<videos_dir>`).
+- `XAI_API_KEY` resolves — either in the environment or in `.env` at the video-use repo root. If missing, ask the user to paste one and write it to `.env` (never to the user's `<videos_dir>`). `ELEVENLABS_API_KEY` is an optional fallback (`--provider elevenlabs`).
 - `ffmpeg` + `ffprobe` on PATH.
 - Python deps installed (`uv sync` or `pip install -e .` inside the repo).
 - Node.js + npm available if the session needs HyperFrames or Remotion slots. HyperFrames currently requires Node.js 22+.
@@ -67,11 +67,11 @@ First-time install lives in `install.md` (clone, deps, ffmpeg, skill registratio
 - First-use animation setup happens inside the slot directory, never at the video-use repo root. HyperFrames can be invoked with `npx --yes hyperframes ...`; Remotion can be scaffolded with `npx create-video@latest` or installed as a project-local dependency before using its `remotion render` command.
 - This skill vendors `skills/manim-video/`. Read its SKILL.md when building a Manim slot.
 
-Helpers (`helpers/transcribe.py`, `helpers/render.py`, etc.) live alongside this SKILL.md. Resolve their paths relative to the directory containing this file — the skill is typically symlinked at `~/.claude/skills/video-use/` or `~/.codex/skills/video-use/`.
+Helpers (`helpers/transcribe.py`, `helpers/render.py`, etc.) live alongside this SKILL.md. Resolve their paths relative to the directory containing this file — the skill is typically symlinked at `~/.grok/skills/video-use/`, `~/.claude/skills/video-use/`, or `~/.codex/skills/video-use/`.
 
 ## Helpers
 
-- **`transcribe.py <video>`** — single-file Scribe call. `--num-speakers N` optional. Cached.
+- **`transcribe.py <video>`** — single-file Grok STT call (ElevenLabs Scribe via `--provider elevenlabs`). `--num-speakers N` optional (Scribe only). Cached.
 - **`transcribe_batch.py <videos_dir>`** — 4-worker parallel transcription. Use for multi-take.
 - **`pack_transcripts.py --edit-dir <dir>`** — `transcripts/*.json` → `takes_packed.md` (phrase-level, break on silence ≥ 0.5s).
 - **`timeline_view.py <video> <start> <end>`** — filmstrip + waveform PNG. On-demand visual drill-down. **Not a scan tool** — use it at decision points, not constantly.
@@ -310,7 +310,7 @@ Things that consistently fail regardless of style:
 - **Hierarchical pre-computed codec formats** with USABILITY / tone tags / shot layers. Over-engineering. Derive from the transcript at decision time.
 - **Hand-tuned moment-scoring functions.** The LLM picks better than any heuristic you'll write.
 - **Whisper SRT / phrase-level output.** Loses sub-second gap data. Always word-level verbatim.
-- **Running Whisper locally on CPU.** Slow and it normalizes fillers. Use hosted Scribe.
+- **Running Whisper locally on CPU.** Slow and it normalizes fillers. Use hosted Grok STT (or ElevenLabs Scribe).
 - **Burning subtitles into base before compositing overlays.** Overlays hide them. (Hard Rule 1.)
 - **Single-pass filtergraph when you have overlays.** Double re-encodes. Use per-segment extract → concat.
 - **Linear animation easing.** Looks robotic. Always cubic.
diff --git a/helpers/transcribe.py b/helpers/transcribe.py
index 26d3906e..951e226a 100644
--- a/helpers/transcribe.py
+++ b/helpers/transcribe.py
@@ -1,13 +1,16 @@
-"""Transcribe a video with ElevenLabs Scribe.
+"""Transcribe a video with Grok STT (default) or ElevenLabs Scribe.
 
-Extracts mono 16kHz audio via ffmpeg, uploads to Scribe with verbatim +
-diarize + audio events + word-level timestamps, writes the full response
-to <edit_dir>/transcripts/<video_stem>.json.
+Extracts mono 16kHz audio via ffmpeg, uploads with diarization + word-level
+timestamps + filler-word retention, writes a Scribe-shaped transcript to
+<edit_dir>/transcripts/<video_stem>.json so pack/render/timeline_view stay
+provider-agnostic.
 
 Cached: if the output file already exists, the upload is skipped.
 
 Usage:
     python helpers/transcribe.py <video_path>
+    python helpers/transcribe.py <video_path> --provider grok
+    python helpers/transcribe.py <video_path> --provider elevenlabs
     python helpers/transcribe.py <video_path> --edit-dir /custom/edit
     python helpers/transcribe.py <video_path> --language en
     python helpers/transcribe.py <video_path> --num-speakers 2
@@ -27,22 +30,53 @@
 import requests
 
 
+GROK_STT_URL = "https://api.x.ai/v1/stt"
 SCRIBE_URL = "https://api.elevenlabs.io/v1/speech-to-text"
+PROVIDERS = ("grok", "elevenlabs")
+KEY_FOR_PROVIDER = {
+    "grok": "XAI_API_KEY",
+    "elevenlabs": "ELEVENLABS_API_KEY",
+}
 
 
-def load_api_key() -> str:
+def _read_key(name: str) -> str:
     for candidate in [Path(__file__).resolve().parent.parent / ".env", Path(".env")]:
-        if candidate.exists():
-            for line in candidate.read_text().splitlines():
-                line = line.strip()
-                if not line or line.startswith("#") or "=" not in line:
-                    continue
-                k, v = line.split("=", 1)
-                if k.strip() == "ELEVENLABS_API_KEY":
-                    return v.strip().strip('"').strip("'")
-    v = os.environ.get("ELEVENLABS_API_KEY", "")
+        if not candidate.exists():
+            continue
+        for line in candidate.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, v = line.split("=", 1)
+            if k.strip() != name:
+                continue
+            val = v.strip().strip('"').strip("'")
+            if val:
+                return val
+    return os.environ.get(name, "").strip()
+
+
+def resolve_provider(explicit: str | None) -> str:
+    if explicit:
+        if explicit not in PROVIDERS:
+            sys.exit(f"unknown --provider {explicit!r} (want {'|'.join(PROVIDERS)})")
+        return explicit
+    if _read_key("XAI_API_KEY"):
+        return "grok"
+    if _read_key("ELEVENLABS_API_KEY"):
+        return "elevenlabs"
+    sys.exit(
+        "XAI_API_KEY not found in .env or environment "
+        "(or set ELEVENLABS_API_KEY / --provider elevenlabs)"
+    )
+
+
+def load_api_key(provider: str | None = None) -> str:
+    provider = resolve_provider(provider)
+    name = KEY_FOR_PROVIDER[provider]
+    v = _read_key(name)
     if not v:
-        sys.exit("ELEVENLABS_API_KEY not found in .env or environment")
+        sys.exit(f"{name} not found in .env or environment")
     return v
 
 
@@ -55,6 +89,75 @@ def extract_audio(video_path: Path, dest: Path) -> None:
     subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
 
 
+def grok_to_scribe(payload: dict) -> dict:
+    """Normalize Grok STT words into the Scribe-shaped schema pack/render expect.
+
+    Grok returns {text, start, end, speaker?} with no type / spacing / audio_event
+    entries. We add type=word, map speaker→speaker_id, and synthesize spacing
+    tokens from inter-word gaps so silence-aware packing still works.
+    """
+    words_out: list[dict] = []
+    prev_end: float | None = None
+    for w in payload.get("words") or []:
+        start = w.get("start")
+        if start is None:
+            continue
+        end = w.get("end", start)
+        if prev_end is not None and start > prev_end:
+            words_out.append({
+                "type": "spacing",
+                "text": " ",
+                "start": prev_end,
+                "end": start,
+            })
+        entry: dict = {
+            "type": "word",
+            "text": w.get("text") or "",
+            "start": start,
+            "end": end,
+        }
+        speaker = w.get("speaker")
+        if speaker is not None:
+            entry["speaker_id"] = f"speaker_{speaker}"
+        words_out.append(entry)
+        prev_end = end
+    return {
+        "text": payload.get("text", ""),
+        "language": payload.get("language"),
+        "duration": payload.get("duration"),
+        "provider": "grok",
+        "words": words_out,
+    }
+
+
+def call_grok_stt(
+    audio_path: Path,
+    api_key: str,
+    language: str | None = None,
+) -> dict:
+    # Verbatim + fillers: do not set format=true (that runs ITN).
+    form: list[tuple[str, str]] = [
+        ("diarize", "true"),
+        ("filler_words", "true"),
+    ]
+    if language:
+        form.append(("language", language))
+
+    with open(audio_path, "rb") as f:
+        resp = requests.post(
+            GROK_STT_URL,
+            headers={"Authorization": f"Bearer {api_key}"},
+            data=form,
+            files={"file": (audio_path.name, f, "audio/wav")},
+            timeout=1800,
+        )
+
+    if resp.status_code != 200:
+        raise RuntimeError(f"Grok STT returned {resp.status_code}: {resp.text[:500]}")
+
+    return grok_to_scribe(resp.json())
+
+
 def call_scribe(
     audio_path: Path,
     api_key: str,
@@ -84,7 +187,10 @@ def call_scribe(
     if resp.status_code != 200:
         raise RuntimeError(f"Scribe returned {resp.status_code}: {resp.text[:500]}")
 
-    return resp.json()
+    payload = resp.json()
+    if isinstance(payload, dict):
+        payload.setdefault("provider", "elevenlabs")
+    return payload
 
 
 def transcribe_one(
@@ -94,11 +200,13 @@ def transcribe_one(
     language: str | None = None,
     num_speakers: int | None = None,
     verbose: bool = True,
+    provider: str | None = None,
 ) -> Path:
     """Transcribe a single video. Returns path to transcript JSON.
 
     Cached: returns existing path immediately if the transcript already exists.
     """
+    provider = resolve_provider(provider)
     transcripts_dir = edit_dir / "transcripts"
     transcripts_dir.mkdir(parents=True, exist_ok=True)
     out_path = transcripts_dir / f"{video.stem}.json"
@@ -109,7 +217,7 @@ def transcribe_one(
         return out_path
 
     if verbose:
-        print(f"  extracting audio from {video.name}", flush=True)
+        print(f"  extracting audio from {video.name} [{provider}]", flush=True)
 
     t0 = time.time()
     with tempfile.TemporaryDirectory() as tmp:
@@ -118,7 +226,10 @@ def transcribe_one(
         size_mb = audio.stat().st_size / (1024 * 1024)
         if verbose:
             print(f"  uploading {video.stem}.wav ({size_mb:.1f} MB)", flush=True)
-        payload = call_scribe(audio, api_key, language, num_speakers)
+        if provider == "grok":
+            payload = call_grok_stt(audio, api_key, language)
+        else:
+            payload = call_scribe(audio, api_key, language, num_speakers)
 
     out_path.write_text(json.dumps(payload, indent=2))
     dt = time.time() - t0
@@ -133,7 +244,7 @@ def transcribe_one(
 
 
 def main() -> None:
-    ap = argparse.ArgumentParser(description="Transcribe a video with ElevenLabs Scribe")
+    ap = argparse.ArgumentParser(description="Transcribe a video with Grok STT or ElevenLabs Scribe")
     ap.add_argument("video", type=Path, help="Path to video file")
     ap.add_argument(
         "--edit-dir",
@@ -141,6 +252,12 @@ def main() -> None:
         default=None,
         help="Edit output directory (default: <video_parent>/edit)",
     )
+    ap.add_argument(
+        "--provider",
+        choices=PROVIDERS,
+        default=None,
+        help="STT backend. Default: grok if XAI_API_KEY is set, else elevenlabs.",
+    )
     ap.add_argument(
         "--language",
         type=str,
@@ -151,7 +268,7 @@ def main() -> None:
         "--num-speakers",
         type=int,
         default=None,
-        help="Optional number of speakers when known. Improves diarization accuracy.",
+        help="Optional speaker count (ElevenLabs only). Improves diarization accuracy.",
     )
     args = ap.parse_args()
 
@@ -160,7 +277,8 @@ def main() -> None:
         sys.exit(f"video not found: {video}")
 
     edit_dir = (args.edit_dir or (video.parent / "edit")).resolve()
-    api_key = load_api_key()
+    provider = resolve_provider(args.provider)
+    api_key = load_api_key(provider)
 
     transcribe_one(
         video=video,
@@ -168,6 +286,7 @@ def main() -> None:
         api_key=api_key,
         language=args.language,
         num_speakers=args.num_speakers,
+        provider=provider,
     )
 
 
diff --git a/helpers/transcribe_batch.py b/helpers/transcribe_batch.py
index 5aeb1d68..8ec93592 100644
--- a/helpers/transcribe_batch.py
+++ b/helpers/transcribe_batch.py
@@ -1,12 +1,14 @@
 """Batch-transcribe every video in a directory with 4 parallel workers.
 
-Walks <videos_dir> for common video extensions, runs ElevenLabs Scribe on
-each, writes transcripts to <videos_dir>/edit/transcripts/<name>.json.
+Walks <videos_dir> for common video extensions, runs Grok STT (default) or
+ElevenLabs Scribe on each, writes transcripts to
+<videos_dir>/edit/transcripts/<name>.json.
 
 Cached per-file: any source that already has a transcript is skipped.
 
 Usage:
     python helpers/transcribe_batch.py <videos_dir>
+    python helpers/transcribe_batch.py <videos_dir> --provider grok
     python helpers/transcribe_batch.py <videos_dir> --workers 4
     python helpers/transcribe_batch.py <videos_dir> --num-speakers 2
     python helpers/transcribe_batch.py <videos_dir> --edit-dir /custom/edit
@@ -20,7 +22,7 @@
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 
-from transcribe import load_api_key, transcribe_one
+from transcribe import PROVIDERS, load_api_key, resolve_provider, transcribe_one
 
 
 VIDEO_EXTS = {".mp4", ".MP4", ".mov", ".MOV", ".mkv", ".MKV", ".avi", ".AVI", ".m4v"}
@@ -44,6 +46,12 @@ def main() -> None:
         help="Edit output directory (default: <videos_dir>/edit)",
     )
     ap.add_argument("--workers", type=int, default=4, help="Parallel workers (default: 4)")
+    ap.add_argument(
+        "--provider",
+        choices=PROVIDERS,
+        default=None,
+        help="STT backend. Default: grok if XAI_API_KEY is set, else elevenlabs.",
+    )
     ap.add_argument(
         "--language",
         type=str,
@@ -54,7 +62,7 @@ def main() -> None:
         "--num-speakers",
         type=int,
         default=None,
-        help="Optional number of speakers. Improves diarization when known.",
+        help="Optional speaker count (ElevenLabs only). Improves diarization when known.",
     )
     args = ap.parse_args()
 
@@ -77,9 +85,10 @@ def main() -> None:
         print("nothing to do")
         return
 
-    api_key = load_api_key()
+    provider = resolve_provider(args.provider)
+    api_key = load_api_key(provider)
 
-    print(f"transcribing {len(pending)} files with {args.workers} parallel workers")
+    print(f"transcribing {len(pending)} files with {args.workers} parallel workers [{provider}]")
     t0 = time.time()
 
     errors: list[tuple[Path, str]] = []
@@ -93,6 +102,7 @@ def main() -> None:
                 language=args.language,
                 num_speakers=args.num_speakers,
                 verbose=False,
+                provider=provider,
             ): v
             for v in pending
         }
diff --git a/install.md b/install.md
index b3b4d7ff..160fc953 100644
--- a/install.md
+++ b/install.md
@@ -1,6 +1,6 @@
 ---
 name: video-use-install
-description: Install video-use into the current agent (Claude Code, Codex, Hermes, Openclaw, etc.) and wire up ffmpeg + the ElevenLabs API key so the user can start editing immediately.
+description: Install video-use into the current agent (Grok, Claude Code, Codex, Hermes, Openclaw, etc.) and wire up ffmpeg + the xAI API key so the user can start editing immediately.
 ---
 
 # video-use install
@@ -9,21 +9,21 @@ Use this file only for first-time install or reconnect. For daily editing, read
 
 ## What you're doing
 
-You're setting up a conversation-driven video editor for the user. After install, the user drops raw footage into any folder, runs their agent (`claude`, `codex`, etc.) there, and says "edit these into a launch video." You do the rest by reading `SKILL.md`.
+You're setting up a conversation-driven video editor for the user. After install, the user drops raw footage into any folder, runs their agent (`grok`, `claude`, `codex`, etc.) there, and says "edit these into a launch video." You do the rest by reading `SKILL.md`.
 
 Three things must exist on this machine:
 
 1. The `video-use` repo cloned somewhere stable.
 2. `ffmpeg` on `$PATH` (plus optional `yt-dlp` for online sources).
-3. An ElevenLabs API key in `.env` at the repo root (for Scribe transcription).
+3. An xAI API key in `.env` at the repo root (for Grok STT). ElevenLabs Scribe is an optional fallback.
 
 And one thing must be true about the current agent:
 
-4. It can discover `SKILL.md` — either via a global skills directory (`~/.claude/skills/`, `~/.codex/skills/`) or via a `CLAUDE.md` / system-prompt import.
+4. It can discover `SKILL.md` — either via a global skills directory (`~/.grok/skills/`, `~/.claude/skills/`, `~/.codex/skills/`) or via a system-prompt import.
 
 ## Install prompt contract
 
-- Do everything yourself. Only ask the user for things you cannot generate — the ElevenLabs API key, and confirmation before `brew install`.
+- Do everything yourself. Only ask the user for things you cannot generate — the xAI API key, and confirmation before `brew install`.
 - Prefer a stable clone path like `~/Developer/video-use` (not `/tmp`, not `~/Downloads`).
 - The skill references helpers by bare name (`transcribe.py`, `render.py`). That works because SKILL.md and `helpers/` ship together — keep them as siblings when you register the skill.
 - After install, verify by running one real command against one real file. Don't declare success on file-existence checks alone.
@@ -71,6 +71,13 @@ If `brew` / `apt` / `pacman` requires a sudo prompt, tell the user the exact com
 
 Figure out which agent you are running under, and register once. A symlink of the whole repo directory is the right shape — helpers/ needs to sit next to SKILL.md.
 
+- **Grok** (`~/.grok/` present):
+
+    ```bash
+    mkdir -p ~/.grok/skills
+    ln -sfn ~/Developer/video-use ~/.grok/skills/video-use
+    ```
+
 - **Claude Code** (`~/.claude/` present):
 
     ```bash
@@ -85,31 +92,33 @@ Figure out which agent you are running under, and register once. A symlink of th
     ln -sfn ~/Developer/video-use "${CODEX_HOME:-$HOME/.codex}/skills/video-use"
     ```
 
-- **Hermes / Openclaw / another agent with a skills directory**: symlink `~/Developer/video-use` into that agent's skills directory under the name `video-use`. If the agent has no skills directory, add a line to its system prompt / config pointing at `~/Developer/video-use/SKILL.md` (e.g. an `@~/Developer/video-use/SKILL.md` import in a `CLAUDE.md`-equivalent).
+- **Hermes / Openclaw / another agent with a skills directory**: symlink `~/Developer/video-use` into that agent's skills directory under the name `video-use`. If the agent has no skills directory, add a line to its system prompt / config pointing at `~/Developer/video-use/SKILL.md`.
 
-If you can't tell which agent you're in, ask the user once: "which agent am I running under — Claude Code, Codex, or something else?" Then pick the right target.
+If you can't tell which agent you're in, ask the user once: "which agent am I running under — Grok, Claude Code, Codex, or something else?" Then pick the right target.
 
-### 5. ElevenLabs API key
+### 5. xAI API key
 
-Scribe (ElevenLabs) does all transcription. Without a key, nothing transcribes.
+Grok STT does transcription by default. Without a key, nothing transcribes. ElevenLabs Scribe remains available via `--provider elevenlabs`.
 
 1. Check existing state in this order and stop at the first hit:
 
     ```bash
     # a) env var already exported
-    [ -n "$ELEVENLABS_API_KEY" ] && echo "env"
+    [ -n "$XAI_API_KEY" ] && echo "env"
     # b) .env at repo root already has it
-    grep -q '^ELEVENLABS_API_KEY=..' ~/Developer/video-use/.env 2>/dev/null && echo "dotenv"
+    grep -q '^XAI_API_KEY=..' ~/Developer/video-use/.env 2>/dev/null && echo "dotenv"
+    # c) optional Scribe fallback
+    [ -n "$ELEVENLABS_API_KEY" ] && echo "elevenlabs-env"
     ```
 
-2. If neither is set, ask the user exactly once:
+2. If neither xAI nor ElevenLabs is set, ask the user exactly once:
 
-    > I need an ElevenLabs API key for transcription (word-level timestamps, speaker diarization, filler tagging). Grab one at https://elevenlabs.io/app/settings/api-keys and paste it here — I'll write it to `~/Developer/video-use/.env`. Or if you already have it exported as `ELEVENLABS_API_KEY`, say "use env" and I'll skip.
+    > I need an xAI API key for Grok STT (word-level timestamps, speaker diarization, filler tagging). Grab one at https://console.x.ai/team/default/api-keys and paste it here — I'll write it to `~/Developer/video-use/.env`. Or if you already have it exported as `XAI_API_KEY`, say "use env" and I'll skip.
 
     When the user pastes a key, write it to `~/Developer/video-use/.env`:
 
     ```bash
-    printf 'ELEVENLABS_API_KEY=%s\n' "$KEY" > ~/Developer/video-use/.env
+    printf 'XAI_API_KEY=%s\n' "$KEY" > ~/Developer/video-use/.env
     chmod 600 ~/Developer/video-use/.env
     ```
 
@@ -119,8 +128,8 @@ Scribe (ElevenLabs) does all transcription. Without a key, nothing transcribes.
 
     ```bash
     curl -s -o /dev/null -w '%{http_code}\n' \
-      -H "xi-api-key: $(sed -n 's/^ELEVENLABS_API_KEY=//p' ~/Developer/video-use/.env)" \
-      https://api.elevenlabs.io/v1/user
+      -H "Authorization: Bearer $(sed -n 's/^XAI_API_KEY=//p' ~/Developer/video-use/.env)" \
+      https://api.x.ai/v1/models
     ```
 
     `200` means the key works. `401` means the user pasted a wrong/expired key — ask once more and stop. Anything else (network, 5xx), move on and verify during first real transcription.
@@ -141,7 +150,7 @@ Full transcription test is optional at install time — it burns Scribe credits.
 Tell the user, in one short message:
 
 - Where the skill is installed (`~/Developer/video-use`).
-- That they should `cd` into their footage folder and start their agent there (e.g. `claude`).
+- That they should `cd` into their footage folder and start their agent there (e.g. `grok`, `claude`).
 - That a good first message is: *"edit these into a launch video"* or *"inventory these takes and propose a strategy."*
 - That all outputs land in `<videos_dir>/edit/` — the repo stays clean.
 
@@ -158,5 +167,5 @@ Tell the user, in one short message:
 - `yt-dlp` is optional. Don't block install on it; install lazily the first time a user asks to pull from a URL.
 - Node.js/npm are only needed for HyperFrames or Remotion slots. HyperFrames currently requires Node.js 22+.
 - HyperFrames, Remotion, and Manim are optional animation engines. Don't install or prefer one globally during setup; pick the engine per animation slot in `SKILL.md`. HyperFrames can run through `npx --yes hyperframes ...` in the slot directory. Remotion can be scaffolded with `npx create-video@latest` or installed inside the slot before rendering.
-- Never run transcription as part of install verification unless the user explicitly asks — Scribe costs real money.
-- If the user is on Linux without a package manager Claude recognizes, print the manual `ffmpeg` install URL and wait rather than guessing.
+- Never run transcription as part of install verification unless the user explicitly asks — STT costs real money.
+- If the user is on Linux without a package manager the agent recognizes, print the manual `ffmpeg` install URL and wait rather than guessing.
diff --git a/pyproject.toml b/pyproject.toml
index c2cff294..cdcd4a42 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,7 +1,7 @@
 [project]
 name = "video-use"
 version = "0.1.0"
-description = "Conversation-driven video editor skill for Claude Code"
+description = "Conversation-driven video editor skill for Grok, Claude Code, and other coding agents"
 license = { file = "LICENSE" }
 requires-python = ">=3.10"
 dependencies = [

From 8438591839eaf966243d1470d3294c23d35697bc Mon Sep 17 00:00:00 2001
From: matt <mattstyles333@gmail.com>
Date: Wed, 12 Aug 2026 22:45:51 +0100
Subject: [PATCH 2/2] Keep ElevenLabs as a first-class STT key

Existing ELEVENLABS_API_KEY-only .env files keep working with no flags.
Either key is enough; if both are set, Grok STT is used unless
--provider elevenlabs. Install upserts one variable and never truncates .env.
---
 .env.example          |  5 +++--
 README.md             | 10 +++++-----
 SKILL.md              |  4 ++--
 helpers/transcribe.py | 10 +++++++---
 install.md            | 44 +++++++++++++++++++++++++++----------------
 5 files changed, 45 insertions(+), 28 deletions(-)

diff --git a/.env.example b/.env.example
index b85fcd2c..fbc0ce20 100644
--- a/.env.example
+++ b/.env.example
@@ -1,3 +1,4 @@
+# Either key is enough. If both are set, Grok STT is used unless you pass
+# --provider elevenlabs.
 XAI_API_KEY=
-# Optional fallback (helpers/transcribe.py --provider elevenlabs)
-# ELEVENLABS_API_KEY=
+ELEVENLABS_API_KEY=
diff --git a/README.md b/README.md
index 9ed4a10d..c39b5523 100644
--- a/README.md
+++ b/README.md
@@ -27,10 +27,10 @@ Paste into Grok, Claude Code, Codex, Hermes, Openclaw, or any agent with shell a
 ```text
 Set up https://github.com/browser-use/video-use for me.
 
-Read install.md first to install this repo, wire up ffmpeg, register the skill with whichever agent you're running under, and set up the xAI API key — ask me to paste it when you need it. Then read SKILL.md for daily usage, and always read helpers/ because that's where the editing scripts live. After install, don't transcribe anything on your own — just tell me it's ready and wait for me to drop footage into a folder.
+Read install.md first to install this repo, wire up ffmpeg, register the skill with whichever agent you're running under, and set up an xAI or ElevenLabs API key — ask me to paste it when you need it. Then read SKILL.md for daily usage, and always read helpers/ because that's where the editing scripts live. After install, don't transcribe anything on your own — just tell me it's ready and wait for me to drop footage into a folder.
 ```
 
-The agent handles the clone, dependencies, skill registration, and prompts you once for your xAI API key (grab one at [console.x.ai](https://console.x.ai/team/default/api-keys)).
+The agent handles the clone, dependencies, skill registration, and prompts you once for a key — [xAI](https://console.x.ai/team/default/api-keys) or [ElevenLabs](https://elevenlabs.io/app/settings/api-keys). Either works. Existing `ELEVENLABS_API_KEY` setups keep working.
 
 Then point your agent at a folder of raw takes:
 
@@ -64,9 +64,9 @@ uv sync                         # or: pip install -e .
 brew install ffmpeg             # required
 brew install yt-dlp             # optional, for downloading online sources
 
-# 3. Add your xAI API key
+# 3. Add an xAI and/or ElevenLabs API key (either is enough)
 cp .env.example .env
-$EDITOR .env                    # XAI_API_KEY=...
+$EDITOR .env                    # XAI_API_KEY=... and/or ELEVENLABS_API_KEY=...
 ```
 
 ## How it works
@@ -77,7 +77,7 @@ The LLM never watches the video. It **reads** it — through two layers that tog
   <img src="static/timeline-view.svg" alt="timeline_view composite — filmstrip + speaker track + waveform + word labels + silence-gap cut candidates" width="100%">
 </p>
 
-**Layer 1 — Audio transcript (always loaded).** One Grok STT call per source gives word-level timestamps, speaker diarization, and filler-word retention (ElevenLabs Scribe is still available via `--provider elevenlabs`). All takes pack into a single ~12KB `takes_packed.md` — the LLM's primary reading view.
+**Layer 1 — Audio transcript (always loaded).** One Grok STT or ElevenLabs Scribe call per source gives word-level timestamps, speaker diarization, and filler-word retention. If both keys are set, Grok is used unless you pass `--provider elevenlabs`. All takes pack into a single ~12KB `takes_packed.md` — the LLM's primary reading view.
 
 ```
 ## C0103  (duration: 43.0s, 8 phrases)
diff --git a/SKILL.md b/SKILL.md
index 451d3146..13d7ad8a 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -59,7 +59,7 @@ The skill lives in `video-use/`. User footage lives wherever they put it. All se
 
 First-time install lives in `install.md` (clone, deps, ffmpeg, skill registration, API key). Don't re-run it every session; on cold start just verify:
 
-- `XAI_API_KEY` resolves — either in the environment or in `.env` at the video-use repo root. If missing, ask the user to paste one and write it to `.env` (never to the user's `<videos_dir>`). `ELEVENLABS_API_KEY` is an optional fallback (`--provider elevenlabs`).
+- `XAI_API_KEY` or `ELEVENLABS_API_KEY` resolves — environment or `.env` at the video-use repo root. Either is enough. If both are set, Grok STT is used unless you pass `--provider elevenlabs`. An existing ElevenLabs-only `.env` keeps working with no flags. If neither is set, ask the user to paste one and write it to `.env` (never to the user's `<videos_dir>`). Do not overwrite the other key if `.env` already has it.
 - `ffmpeg` + `ffprobe` on PATH.
 - Python deps installed (`uv sync` or `pip install -e .` inside the repo).
 - Node.js + npm available if the session needs HyperFrames or Remotion slots. HyperFrames currently requires Node.js 22+.
@@ -71,7 +71,7 @@ Helpers (`helpers/transcribe.py`, `helpers/render.py`, etc.) live alongside this
 
 ## Helpers
 
-- **`transcribe.py <video>`** — single-file Grok STT call (ElevenLabs Scribe via `--provider elevenlabs`). `--num-speakers N` optional (Scribe only). Cached.
+- **`transcribe.py <video>`** — single-file STT call. Auto: Grok if `XAI_API_KEY` is set, else ElevenLabs Scribe. Force with `--provider grok|elevenlabs`. `--num-speakers N` optional (Scribe only). Cached.
 - **`transcribe_batch.py <videos_dir>`** — 4-worker parallel transcription. Use for multi-take.
 - **`pack_transcripts.py --edit-dir <dir>`** — `transcripts/*.json` → `takes_packed.md` (phrase-level, break on silence ≥ 0.5s).
 - **`timeline_view.py <video> <start> <end>`** — filmstrip + waveform PNG. On-demand visual drill-down. **Not a scan tool** — use it at decision points, not constantly.
diff --git a/helpers/transcribe.py b/helpers/transcribe.py
index 951e226a..2a7c7149 100644
--- a/helpers/transcribe.py
+++ b/helpers/transcribe.py
@@ -1,4 +1,8 @@
-"""Transcribe a video with Grok STT (default) or ElevenLabs Scribe.
+"""Transcribe a video with Grok STT or ElevenLabs Scribe.
+
+Accepts either XAI_API_KEY or ELEVENLABS_API_KEY. An existing ElevenLabs-only
+.env keeps working with no flags. If both keys are set, Grok STT is used
+unless you pass --provider elevenlabs.
 
 Extracts mono 16kHz audio via ffmpeg, uploads with diarization + word-level
 timestamps + filler-word retention, writes a Scribe-shaped transcript to
@@ -66,8 +70,8 @@ def resolve_provider(explicit: str | None) -> str:
     if _read_key("ELEVENLABS_API_KEY"):
         return "elevenlabs"
     sys.exit(
-        "XAI_API_KEY not found in .env or environment "
-        "(or set ELEVENLABS_API_KEY / --provider elevenlabs)"
+        "need XAI_API_KEY or ELEVENLABS_API_KEY in .env or the environment "
+        "(existing ElevenLabs-only setups keep working; pass --provider to force one)"
     )
 
 
diff --git a/install.md b/install.md
index 160fc953..18d4dbd6 100644
--- a/install.md
+++ b/install.md
@@ -1,6 +1,6 @@
 ---
 name: video-use-install
-description: Install video-use into the current agent (Grok, Claude Code, Codex, Hermes, Openclaw, etc.) and wire up ffmpeg + the xAI API key so the user can start editing immediately.
+description: Install video-use into the current agent (Grok, Claude Code, Codex, Hermes, Openclaw, etc.) and wire up ffmpeg + an xAI or ElevenLabs API key so the user can start editing immediately.
 ---
 
 # video-use install
@@ -15,7 +15,7 @@ Three things must exist on this machine:
 
 1. The `video-use` repo cloned somewhere stable.
 2. `ffmpeg` on `$PATH` (plus optional `yt-dlp` for online sources).
-3. An xAI API key in `.env` at the repo root (for Grok STT). ElevenLabs Scribe is an optional fallback.
+3. An `XAI_API_KEY` and/or `ELEVENLABS_API_KEY` in `.env` at the repo root. Either is enough. Existing ElevenLabs-only installs keep working.
 
 And one thing must be true about the current agent:
 
@@ -23,7 +23,7 @@ And one thing must be true about the current agent:
 
 ## Install prompt contract
 
-- Do everything yourself. Only ask the user for things you cannot generate — the xAI API key, and confirmation before `brew install`.
+- Do everything yourself. Only ask the user for things you cannot generate — an xAI or ElevenLabs API key if neither is already set, and confirmation before `brew install`.
 - Prefer a stable clone path like `~/Developer/video-use` (not `/tmp`, not `~/Downloads`).
 - The skill references helpers by bare name (`transcribe.py`, `render.py`). That works because SKILL.md and `helpers/` ship together — keep them as siblings when you register the skill.
 - After install, verify by running one real command against one real file. Don't declare success on file-existence checks alone.
@@ -96,40 +96,52 @@ Figure out which agent you are running under, and register once. A symlink of th
 
 If you can't tell which agent you're in, ask the user once: "which agent am I running under — Grok, Claude Code, Codex, or something else?" Then pick the right target.
 
-### 5. xAI API key
+### 5. Transcription API key (xAI or ElevenLabs)
 
-Grok STT does transcription by default. Without a key, nothing transcribes. ElevenLabs Scribe remains available via `--provider elevenlabs`.
+Either key works. An existing `ELEVENLABS_API_KEY`-only `.env` is a complete install — do not ask for xAI. If both are set, Grok STT is used unless the user passes `--provider elevenlabs`.
 
 1. Check existing state in this order and stop at the first hit:
 
     ```bash
-    # a) env var already exported
-    [ -n "$XAI_API_KEY" ] && echo "env"
-    # b) .env at repo root already has it
-    grep -q '^XAI_API_KEY=..' ~/Developer/video-use/.env 2>/dev/null && echo "dotenv"
-    # c) optional Scribe fallback
+    [ -n "$XAI_API_KEY" ] && echo "xai-env"
+    grep -q '^XAI_API_KEY=..' ~/Developer/video-use/.env 2>/dev/null && echo "xai-dotenv"
     [ -n "$ELEVENLABS_API_KEY" ] && echo "elevenlabs-env"
+    grep -q '^ELEVENLABS_API_KEY=..' ~/Developer/video-use/.env 2>/dev/null && echo "elevenlabs-dotenv"
     ```
 
-2. If neither xAI nor ElevenLabs is set, ask the user exactly once:
+2. If neither key is set, ask the user exactly once:
 
-    > I need an xAI API key for Grok STT (word-level timestamps, speaker diarization, filler tagging). Grab one at https://console.x.ai/team/default/api-keys and paste it here — I'll write it to `~/Developer/video-use/.env`. Or if you already have it exported as `XAI_API_KEY`, say "use env" and I'll skip.
+    > I need an API key for transcription (word-level timestamps, speaker diarization, filler tagging). xAI (`XAI_API_KEY`, https://console.x.ai/team/default/api-keys) or ElevenLabs (`ELEVENLABS_API_KEY`, https://elevenlabs.io/app/settings/api-keys) — either works. Paste one here and I'll write it to `~/Developer/video-use/.env`. Or if you already have it exported, say "use env" and I'll skip.
 
-    When the user pastes a key, write it to `~/Developer/video-use/.env`:
+    When the user pastes a key, upsert **only that variable**. Never truncate `.env` — an existing ElevenLabs line must survive adding xAI, and vice versa:
 
     ```bash
-    printf 'XAI_API_KEY=%s\n' "$KEY" > ~/Developer/video-use/.env
-    chmod 600 ~/Developer/video-use/.env
+    ENV=~/Developer/video-use/.env
+    touch "$ENV"
+    # KEY_NAME is XAI_API_KEY or ELEVENLABS_API_KEY
+    if grep -q "^${KEY_NAME}=" "$ENV"; then
+      tmp=$(mktemp)
+      sed "s|^${KEY_NAME}=.*|${KEY_NAME}=${KEY}|" "$ENV" > "$tmp" && mv "$tmp" "$ENV"
+    else
+      printf '%s=%s\n' "$KEY_NAME" "$KEY" >> "$ENV"
+    fi
+    chmod 600 "$ENV"
     ```
 
     Never echo the key back in tool output. Never commit `.env`.
 
-3. Sanity check with a cheap, quota-free call:
+3. Sanity check with a cheap, quota-free call for whichever key you just wrote (or found):
 
     ```bash
+    # xAI
     curl -s -o /dev/null -w '%{http_code}\n' \
       -H "Authorization: Bearer $(sed -n 's/^XAI_API_KEY=//p' ~/Developer/video-use/.env)" \
       https://api.x.ai/v1/models
+
+    # ElevenLabs
+    curl -s -o /dev/null -w '%{http_code}\n' \
+      -H "xi-api-key: $(sed -n 's/^ELEVENLABS_API_KEY=//p' ~/Developer/video-use/.env)" \
+      https://api.elevenlabs.io/v1/user
     ```
 
     `200` means the key works. `401` means the user pasted a wrong/expired key — ask once more and stop. Anything else (network, 5xx), move on and verify during first real transcription.