Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs: update Hypit skill environment guidance (#65)

rponeawad95eab3b1145
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index becc5bba..e61264a6 100644
--- a/.agents/skills/hypit/SKILL.md
+++ b/.agents/skills/hypit/SKILL.md
@@ -11,9 +11,11 @@ that reference names required child references, read those completely in the sta
Keep `.svml` Author Source, `.svs` Recipe Source, `.svrun` Run Source, and
`hypit.runtime.json` Runtime Profile as separate languages and responsibilities.
-Every route uses the machine-wide Hypit Distribution and an independent author project.
-`references/environment.md` establishes that boundary and installs the Distribution only when the
-`hypit` command is genuinely absent. Read it before the first command of any route.
+Every route uses a Hypit Distribution and an independent author project. Prefer an installed
+machine-wide CLI; when the task is running from a Hypit contributor checkout, use that checkout's
+Node entrypoints instead. The npm package is not currently published, so absence of the `hypit`
+command is not permission to install it from the registry. `references/environment.md` establishes
+the boundary and launcher selection. Read it before the first command of any route.
## Route
diff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.md
index 92145fda..33cef1df 100644
--- a/.agents/skills/hypit/references/environment.md
+++ b/.agents/skills/hypit/references/environment.md
@@ -6,15 +6,16 @@ Hypit has three different lifetimes. Never collapse them into one directory.
- The **skill** is agent guidance. Install it globally once so later sessions and unrelated projects
can discover the same copy.
-- The **Distribution** is the globally installed `hypit` npm package. It owns the CLI, Studio,
- official packages and packaged Python service source.
+- The **Distribution** is either an already installed machine-wide Hypit package or the Hypit
+ contributor checkout the task is deliberately running from. It owns the CLI, Studio, official
+ packages and packaged Python service source.
- The **project** is the author's directory. It owns Sources, assets, project-local packages,
`hypit.runtime.json`, `.hypit/` Build state and output files.
An ordinary user does not clone the repository and does not run pnpm, Corepack, `npm link`, or a
service's `uv sync` by hand. A clone is only a contributor checkout.
-## Install once, reuse in every session
+## Select a Distribution; do not assume registry publication
The skill must be global; the skills CLI's default is project-local:
@@ -22,24 +23,51 @@ The skill must be global; the skills CLI's default is project-local:
npx skills add hypit-ai/hypit --global
```
-Check the program before installing it:
+First check for an already installed program:
```text
hypit paths --json
```
-Only when the command is missing, install the Distribution once:
+If that command is missing, do **not** run `npm install --global hypit`: the npm package is not
+currently published. Check whether the current directory or one of its ancestors is a Hypit
+contributor checkout. A checkout has all of these:
```text
-npm install --global hypit
+package.json (name: "hypit")
+bin/hypit.mjs
+packages/reference-video-tools/bin/reference-video-tools.mjs
```
-Do not replace this with `npx hypit`, and do not reinstall it for a new project or a new agent
-session. `hypit paths --json` reports the current project boundary, project state, machine Program
-Home, machine npm package home and installed Distribution. Those paths are facts; no repository
-locator or environment lock is involved.
+In that checkout, prepare dependencies only when they are absent or stale, using the contributor
+workflow and the pinned lockfile:
-Updates are an explicit package-manager operation, never an automatic mutation during authoring:
+```text
+corepack enable
+corepack pnpm install --frozen-lockfile
+```
+
+Then use the checkout entrypoints directly for the rest of the route:
+
+```text
+node <checkout>/bin/hypit.mjs paths --json
+node <checkout>/packages/reference-video-tools/bin/reference-video-tools.mjs <subcommand> ...
+```
+
+In every reference that abbreviates these as `hypit` and `hypit-reference-video-tools`, interpret
+them as the selected launchers above. Do not globally link the checkout, use `npx hypit`, or install
+dependencies into an author project. Run reference-video-tool commands that share reference state
+from the same working directory, even though their launcher lives in the checkout.
+
+If neither an installed CLI nor a contributor checkout is available, report that no runnable Hypit
+Distribution is present and stop. A registry install is not a recovery path.
+
+`hypit paths --json` reports the current project boundary, project state, machine Program Home,
+machine npm package home and selected Distribution. Those paths are facts; no repository locator or
+environment lock is involved.
+
+Updates to an installed, published Distribution are an explicit package-manager operation, never an
+automatic mutation during authoring:
```text
npm outdated --global hypit
@@ -50,6 +78,7 @@ npx skills update --global
Use `hypit --version` to report the installed Distribution. Check npm only when the user asks about
updates or during deliberate environment maintenance; do not add a registry request to every route.
+Do not run those npm commands for a contributor checkout; update it through its repository workflow.
After updating Hypit, stop an idle Runtime Worker before the next Build so the next process loads the
new Distribution. Existing project Sources and accepted Build records remain in the project.
@@ -72,19 +101,116 @@ node scripts/check-environment.mjs
`hypit` and Node are required. `ffmpeg` and `ffprobe` are required by local media and preview paths.
`uv` is required only when the selected Runtime Profile uses a managed Python program such as
-WhisperX or OpenCV. For both services, install the interpreter once:
+WhisperX or OpenCV. Install `uv` with the host package manager, then let `uv` install the pinned
+Python interpreter.
-```text
+### Install FFmpeg prerequisites on Windows
+
+Install a current FFmpeg build so both `ffmpeg.exe` and `ffprobe.exe` are available on `PATH`.
+The preferred machine-wide route is Winget:
+
+```powershell
+winget install --id Gyan.FFmpeg.Shared -e
+ffmpeg -version
+ffprobe -version
+```
+
+If Winget is unavailable, download the current essentials ZIP from
+`https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip`, extract it to a stable
+directory such as `C:\Tools\ffmpeg`, and add its `bin` directory (for example,
+`C:\Tools\ffmpeg\bin`) to the user or machine `PATH`. Open a new PowerShell window and verify:
+
+```powershell
+ffmpeg -version
+ffprobe -version
+```
+
+Do not install FFmpeg into an author project or rely on a temporary download directory; the
+executables are host prerequisites shared by Hypit projects.
+
+### Install WhisperX prerequisites on Windows
+
+Use Windows 10 or 11 x64 in PowerShell:
+
+```powershell
+winget install --id astral-sh.uv -e
+uv --version
uv python install 3.13
```
-Then let the Runtime own installation and reuse:
+Open a new PowerShell session if `uv` is not immediately on `PATH` after the Winget install.
+
+### Install WhisperX prerequisites on macOS
+
+Use macOS 13 or newer:
+
+```bash
+brew install uv
+uv --version
+uv python install 3.13
+```
+
+If Homebrew is not installed, install `uv` using Astral's current official installation method;
+do not improvise a Python `pip install` for this managed-program workflow.
+
+### Let Hypit install and run WhisperX
+
+The project Runtime Profile must select the local WhisperX Endpoint. A minimal endpoint inside the
+profile's `runtime.config.endpoints` is:
+
+```json
+"whisperx.local": {
+ "use": "@hypit/provider-whisperx-local",
+ "config": { "defaultConcurrency": 1 }
+}
+```
+
+Then select and provision the Profile with the chosen Hypit launcher:
```text
hypit runtime use hypit.runtime.json
-hypit doctor
hypit runtime up
hypit runtime status
+hypit doctor
+```
+
+`runtime up` owns the WhisperX installation: it creates or reuses the managed environment in the
+machine Program Home, installs the locked service, prepares NLTK `punkt_tab`, starts the loopback
+service on `127.0.0.1:8765`, and then starts the Worker. The first start may download the selected
+Whisper and language-alignment model weights, so it can take substantially longer than later starts.
+Do not run `uv sync` in an author project and do not install the `whisperx` Python package by hand.
+
+Verify a running service with `hypit programs status` or `hypit doctor`. If preparation fails, read
+`hypit runtime logs`; for a contributor checkout only, `services/whisperx/README.md` contains the
+manual `uv sync --frozen`, prepare and check commands used to diagnose the packaged service.
+
+If `runtime up` reports that NLTK `punkt_tab` is missing because Python's downloader was blocked by
+a proxy or SSRF policy, install the same archive from NLTK's official data repository into the
+managed WhisperX data root, then run `hypit runtime up` again. Do this only for that explicit network
+failure; ordinary installs stay Runtime-managed.
+
+Windows PowerShell:
+
+```powershell
+$whisperxData = Join-Path $env:LOCALAPPDATA "Hypit\programs\whisperx\nltk_data"
+$download = Join-Path $env:TEMP ("hypit-punkt-" + [guid]::NewGuid().ToString("N"))
+New-Item -ItemType Directory -Path $download | Out-Null
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nltk/nltk_data/gh-pages/packages/tokenizers/punkt_tab.zip" -OutFile (Join-Path $download "punkt_tab.zip")
+New-Item -ItemType Directory -Path (Join-Path $whisperxData "tokenizers") -Force | Out-Null
+Expand-Archive -LiteralPath (Join-Path $download "punkt_tab.zip") -DestinationPath (Join-Path $whisperxData "tokenizers") -Force
+hypit runtime up
+```
+
+macOS:
+
+```bash
+whisperx_data="$HOME/Library/Application Support/Hypit/programs/whisperx/nltk_data"
+download_dir="$(mktemp -d)"
+mkdir -p "$whisperx_data/tokenizers"
+curl -L "https://raw.githubusercontent.com/nltk/nltk_data/gh-pages/packages/tokenizers/punkt_tab.zip" \
+ -o "$download_dir/punkt_tab.zip"
+unzip -q "$download_dir/punkt_tab.zip" -d "$whisperx_data/tokenizers"
+hypit runtime up
```
`runtime up` probes each selected program. It creates that program's environment only when absent or
@@ -135,7 +261,8 @@ changes an exact adapter dependency, the next explicit `runtime up` lets npm upd
## Contributor checkout
-Only someone changing Hypit itself clones the repository. In that checkout, follow
+Only someone changing Hypit itself clones the repository. A task already running from that checkout
+may also use it as the Distribution when no installed CLI exists, as described above. Follow
`docs/guide/develop.md` and use its pinned pnpm version and official `pnpm-lock.yaml`. Never place an
author project or its local packages inside that checkout.