@hypit/hypit 0.1.14 → 0.2.0

package/packages/studio/src/ui/syntax.ts

@@ -4,7 +4,7 @@
  * SVML has a small, closed grammar — tags, quoted strings, whole-value
  * references, and Script prose with markers — so it is tokenized directly rather
  * than through a general highlighter that has no grammar for it. The Script
- * markers are the point: `@claim … @/claim` is what a Media Item binds to, so it
+ * markers are the point: `@{claim} … @{/claim}` is what a Media Item binds to, so it
  * has to read as a distinct thing from an ordinary attribute.
  *
  * Tokens are non-overlapping and in source order. Gaps between them are plain
@@ -33,12 +33,30 @@ export type Token = {
 
 const NAME = /^[A-Za-z_][A-Za-z0-9_.:-]*/u;
 const ATTRIBUTE = /^[A-Za-z_][A-Za-z0-9_.:-]*/u;
-/**
- * The Script's own marker grammar: `@id` opens a Selection, `@/id` closes one,
- * `@id!` marks a Moment, and a leading `~` or trailing `~` chooses which side of
- * the neighbouring word the marker binds to.
- */
-const MARKER = /^~?@\/?[a-z][a-z0-9_-]*[!~]?/u;
+/** All control sigils belong inside a delimited Script marker. */
+const MARKER = /^@\{(?:(~)?([a-z][a-z0-9_-]{0,63})(!)?|\/([a-z][a-z0-9_-]{0,63})(~)?)\}/u;
+
+function unescapedIndex(source: string, character: string, from: number, to = source.length): number {
+  for (let index = from; index < to; index++) {
+    if (source[index] === "\\") { index++; continue; }
+    if (source[index] === character) return index;
+  }
+  return -1;
+}
+
+function scriptDecoration(source: string, cursor: number, push: Push, markers = true, attributes = true): number {
+  if (source[cursor] === "\\") return cursor + 2;
+  const marker = markers ? MARKER.exec(source.slice(cursor)) : null;
+  if (marker) {
+    push(cursor, cursor + marker[0].length, "marker", marker[2] ?? marker[4]);
+    return cursor + marker[0].length;
+  }
+  if (attributes && source[cursor] === "{") {
+    const end = unescapedIndex(source, "}", cursor + 1);
+    if (end >= 0) { push(cursor, end + 1, "attr"); return end + 1; }
+  }
+  return cursor + 1;
+}
 
 function localName(tag: string): string {
   const colon = tag.indexOf(":");
@@ -145,11 +163,12 @@ function tokenizeAttributes(source: string, from: number, push: Push): number {
   return cursor;
 }
 
-/** Script prose: Segment and Role Cue tags stay tags; `@id` markers stand out. */
+/** Script prose: Segment and Role Cue tags stay tags; `@{id}` markers stand out. */
 function tokenizeScriptBody(source: string, from: number, tag: string, push: Push): number {
   const close = `</${tag}>`;
   let cursor = from;
   while (cursor < source.length) {
+    if (source[cursor] === "\\") { cursor += 2; continue; }
     if (source.startsWith(close, cursor)) {
       push(cursor, cursor + 2, "punct");
       push(cursor + 2, cursor + 2 + tag.length, "tag");
@@ -164,6 +183,20 @@ function tokenizeScriptBody(source: string, from: number, tag: string, push: Pus
       continue;
     }
     if (source[cursor] === "<") {
+      const endDual = unescapedIndex(source, ">", cursor + 1);
+      const pipe = endDual < 0 ? -1 : unescapedIndex(source, "|", cursor + 1, endDual);
+      if (pipe >= 0) {
+        const shared = !source.slice(pipe + 1, endDual).trim();
+        push(cursor, cursor + 1, "punct");
+        cursor++;
+        while (cursor < pipe) cursor = scriptDecoration(source, cursor, push, shared, true);
+        push(pipe, pipe + 1, "punct");
+        cursor = pipe + 1;
+        while (cursor < endDual) cursor = scriptDecoration(source, cursor, push, true, false);
+        push(endDual, endDual + 1, "punct");
+        cursor = endDual + 1;
+        continue;
+      }
       const closing = source[cursor + 1] === "/";
       const nameStart = cursor + (closing ? 2 : 1);
       const name = NAME.exec(source.slice(nameStart));
@@ -177,19 +210,7 @@ function tokenizeScriptBody(source: string, from: number, tag: string, push: Pus
       cursor = stop;
       continue;
     }
-    // A leading `~` binds the marker to the word on its left, and is part of it.
-    if (source[cursor] === "@" || (source[cursor] === "~" && source[cursor + 1] === "@")) {
-      const marker = MARKER.exec(source.slice(cursor));
-      if (marker !== null) {
-        // Strip the affinity sigils, the `@` and the closing `/` so an opening
-        // marker, its closing marker and a Moment all report the same name.
-        const id = marker[0].replace(/^~?@\/?/u, "").replace(/[!~]$/u, "");
-        push(cursor, cursor + marker[0].length, "marker", id);
-        cursor += marker[0].length;
-        continue;
-      }
-    }
-    cursor += 1;
+    cursor = scriptDecoration(source, cursor, push);
   }
   return cursor;
 }

package/packages/temporal-markup/README.md

@@ -75,7 +75,7 @@ time and implements its own schedule or state, while the shared temporal protoco
 time came from. An outer lifetime and child activations are separate inputs when a component persists
 between events.
 
-Script's `@`, `~@`, close markers and Moment syntax belong to `@hypit/script`; media playback belongs
+Script's delimited `@{...}` Selection and Moment syntax belong to `@hypit/script`; media playback belongs
 to `@hypit/media-track`; a graphic component's reveal or preset semantics belong to that component.
 
 ## Independently bound endpoints

package/packages/video-cli/README.md

@@ -42,7 +42,8 @@ in [file CredentialStore](../credential-store-file/README.md#select-it-before-lo
 `hypit doctor --endpoint <name>` checks a selected Endpoint;
 `hypit runtime up --endpoint <name>` prepares that Endpoint and starts the Worker. Repeat the flag
 for several chosen Endpoints; omitting it prepares the whole Profile. `hypit programs up --endpoint
-<name>` prepares a local helper independently of the Worker.
+<name>` prepares and starts a local helper independently of the Worker. `hypit programs prepare
+--endpoint <name>` only prepares its selected resources, including for a service already running.
 
 With the selected execution environment:
 
@@ -67,9 +68,11 @@ hypit transcribe reference.mp4 --to notes/reference.transcript.json --language e
 hypit measure main.svml --segment hook --language en --pace normal --rounding round
 ```
 
-For `transcribe`, set `--language` to the spoken language: `en`, `zh` or `es`. Chinese speech uses `zh`, including
-Chinese speech containing English names; the requested language selects the recognition/alignment
-model, independently of the eventual caption font or script's simplified/traditional characters.
+For `transcribe`, set `--language` to an explicit lowercase two- or three-letter spoken language code,
+such as `en`, `zh` or `ko`. The selected service owns which languages it can align. Chinese speech uses `zh`, including
+Chinese speech containing English names. The request selects the recognition language and
+language-specific aligner; ASR size remains a deployment choice. Caption font and Script's
+simplified/traditional characters are independent authoring choices.
 
 `transcribe` uses the Profile's `whisperx-alignment` Endpoint (after
 extracting 16 kHz mono speech audio with ffmpeg). Direct invocation forwards the Provider's progress
@@ -142,7 +145,8 @@ Grid `samples` retain the requested times; `frames` contain the actual extracted
 It also reports every page path for `tiles`. The media layer reads existing timed text; transcription
 and its Endpoint remain separate. `boundaries` reports adjacent-frame
 change candidates and their measured scores; it does not suppress short changes or call them shots.
-`fetch` turns a link into a file with the pinned yt-dlp; [the downloader package](../yt-dlp/README.md)
+`prepare-fetch` explicitly prepares the locked downloader environment; `fetch` requires it and
+turns a link into a file with the pinned yt-dlp; [the downloader package](../yt-dlp/README.md)
 owns its dependencies, download choices and file handling. Commands that create evidence write only
 what `--to` names and refuse to overwrite. `vocabulary` reads the installed
 manifests: every package with its tags and models, or one package's Surfaces with their attributes,

package/packages/video-cli/src/capture.ts

@@ -25,6 +25,9 @@ Browser options:
   --scale <number>            Device pixel ratio (default: 1)
   --channel <name>            Installed Chrome channel, e.g. chrome
   --browser <path>            Explicit browser executable instead of a channel
+  --browser-version <version> Exact Chrome for Testing version
+  --browser-cache <directory> Cache shared by installation and capture
+  --browser-download-base-url <url> Compatible archive source for install-browser
   --headed                   Show the browser
   --timeout-ms <milliseconds> Page operation and navigation timeout
   --json                     Print all saved files with their actual dimensions
@@ -70,6 +73,7 @@ export async function runCaptureCli(argv: readonly string[], io: CliIo, cwd = pr
     args: (separator < 0 ? argv : argv.slice(0, separator)).slice(2), allowPositionals: true,
     options: {
       viewport: { type: "string" }, scale: { type: "string" }, channel: { type: "string" },
+      "browser-version": { type: "string" }, "browser-cache": { type: "string" }, "browser-download-base-url": { type: "string" },
       browser: { type: "string" }, headed: { type: "boolean" }, "timeout-ms": { type: "string" },
       json: { type: "boolean" }, debug: { type: "boolean" }, verbose: { type: "boolean" },
       "no-color": { type: "boolean" }, color: { type: "string" }, help: { type: "boolean" },
@@ -81,14 +85,19 @@ export async function runCaptureCli(argv: readonly string[], io: CliIo, cwd = pr
   });
   const values = parsed.values;
   if (values.help) { writeCaptureHelp(io); return; }
+  const managedBrowser = {
+    ...(values["browser-version"] === undefined ? {} : { version: values["browser-version"] }),
+    ...(values["browser-cache"] === undefined ? {} : { cacheDirectory: resolve(cwd, values["browser-cache"]) }),
+    ...(values["browser-download-base-url"] === undefined ? {} : { downloadBaseUrl: values["browser-download-base-url"] }),
+  };
   if (command === "install-browser") {
     if (parsed.positionals.length > 0 || args.length > 0) throw new Error("install-browser takes no positional arguments");
     for (const name of Object.keys(values)) {
-      if (!["json", "debug", "verbose", "color", "no-color"].includes(name)) throw new Error(`install-browser does not use --${name}`);
+      if (!["json", "debug", "verbose", "color", "no-color", "browser-version", "browser-cache", "browser-download-base-url"].includes(name)) throw new Error(`install-browser does not use --${name}`);
     }
     io.writeProgress?.("Preparing the capture browser…\n");
     const { installCaptureBrowser } = await import("@hypit/browser-capture");
-    const path = await installCaptureBrowser();
+    const path = await installCaptureBrowser(managedBrowser);
     io.write(values.json ? `${JSON.stringify({ format: "hypit.capture-browser@1", path })}\n` : `Capture browser ready: ${path}\n`);
     return;
   }
@@ -138,6 +147,12 @@ export async function runCaptureCli(argv: readonly string[], io: CliIo, cwd = pr
       });
     };
   }
+  if (Object.keys(managedBrowser).length > 0) options = { ...options, browser: { ...options.browser, ...managedBrowser } };
+  if (values.browser || values.channel) {
+    if (Object.keys(managedBrowser).length > 0) throw new Error("Choose managed browser options or --browser/--channel");
+    const { browser: _managed, ...externalOptions } = options;
+    options = externalOptions;
+  }
   const launch = { ...options.launch };
   if (values.browser) { launch.executablePath = resolve(cwd, values.browser); delete launch.channel; }
   if (values.channel) {

package/packages/video-cli/src/creation.ts

@@ -21,7 +21,7 @@ import { speechEvidenceTypes } from "@hypit/speech-evidence";
 import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";
 import { sealText } from "@hypit/text";
 import { whisperXCapabilities, whisperXRequestForEvidenceAudio } from "@hypit/whisperx";
-import type { WhisperXLanguage } from "@hypit/whisperx";
+import { parseWhisperXLanguage } from "@hypit/whisperx";
 
 import { videoCliDistribution } from "./distribution.js";
 import { runProcess } from "./process.js";
@@ -282,9 +282,7 @@ async function transcribe(argv: readonly string[], io: CliIo, environment: Creat
   const parsed = parseArguments(argv, ["--language", "--to", "--runtime", "--workspace"]);
   assert(parsed.positionals.length === 1, "transcribe takes exactly one audio or video file");
   const source = resolve(environment.cwd, parsed.positionals[0]!);
-  const language = parsed.options.get("--language");
-  assert(language === "en" || language === "zh" || language === "es",
-    "transcribe requires --language en|zh|es for the spoken language (use --language zh for Chinese)");
+  const language = parseWhisperXLanguage(parsed.options.get("--language"), "transcribe --language");
   const to = await destination(parsed, environment.cwd);
   const { profile, host } = await environment.openHost(
     parsed.options.get("--runtime"),
@@ -298,7 +296,7 @@ async function transcribe(argv: readonly string[], io: CliIo, environment: Creat
     id: "need:hypit-transcribe",
     capability: whisperXCapabilities.alignment,
     returns: speechEvidenceTypes.alignedTranscript,
-    constraints: whisperXRequestForEvidenceAudio(audio, { language: language as WhisperXLanguage }),
+    constraints: whisperXRequestForEvidenceAudio(audio, { language }),
     result: "record:hypit-transcribe",
   };
   const provider = await selectedProvider(host, need, profile);
@@ -437,7 +435,7 @@ export function writeCreationHelp(io: CliIo, topic?: CreationCommand): void {
       "hypit transcribe",
       "Establish word times with the whisperx-alignment Endpoint of the selected Runtime Profile.",
       "",
-      "  hypit transcribe <audio|video> --to <transcript.json> --language en|zh|es [--runtime <profile>] [--workspace <project>]",
+      "  hypit transcribe <audio|video> --to <transcript.json> --language <code> [--runtime <profile>] [--workspace <project>]",
       "",
       "Extracts 16 kHz mono speech audio with ffmpeg and writes every word with its start and end in",
       "seconds. One immediate request; no Build, Result or state.",

package/packages/video-cli/src/media.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { dirname, extname, join, resolve } from "node:path";
 
 import type { CliIo } from "@hypit/cli";
-import { downloadVideo, isVideoUrl } from "@hypit/yt-dlp";
+import { downloadVideo, isVideoUrl, prepareVideoDownload } from "@hypit/yt-dlp";
 import sharp from "sharp";
 
 import { runProcess, runProcessOutput, runProcessWithInput } from "./process.js";
@@ -15,7 +15,7 @@ import type { FrameWords, TranscriptWord } from "./transcript.js";
  * the input media. These commands expose evidence; editorial interpretation belongs to the author.
  */
 
-export const mediaCommands = ["probe", "cut", "frames", "tile", "tiles", "boundaries", "fetch"] as const;
+export const mediaCommands = ["probe", "cut", "frames", "tile", "tiles", "boundaries", "fetch", "prepare-fetch"] as const;
 export type MediaCommand = typeof mediaCommands[number];
 
 function assert(condition: unknown, message: string): asserts condition {
@@ -673,6 +673,7 @@ export function writeMediaHelp(io: CliIo, topic?: MediaCommand): void {
       "    Paginated grids (3 rows by default). Range files contain { start, end, id?, frames?, every? }."],
     boundaries: ["  hypit media boundaries <file> [--rate <samples/s>] [--threshold <0..1>]",
       "    Mechanical adjacent-frame change candidates with scores; never editorial shot labels."],
+    "prepare-fetch": ["  hypit media prepare-fetch", "    Explicitly prepare the pinned yt-dlp environment; does not fetch media."],
     fetch: ["  hypit media fetch <url> --to <video.mp4>", "    A link turned into a file with the pinned yt-dlp, video and audio together."],
   };
   const chosen = topic === undefined ? mediaCommands : [topic];
@@ -697,5 +698,11 @@ export async function runMediaCli(argv: readonly string[], io: CliIo, cwd = proc
   else if (command === "tile") await tile(rest, io, cwd);
   else if (command === "tiles") await tiles(rest, io, cwd);
   else if (command === "boundaries") await boundaries(rest, io, cwd);
-  else await fetch(rest, io, cwd);
+  else if (command === "prepare-fetch") {
+    const parsed = parseArguments(rest, []);
+    assert(parsed.positionals.length === 0, "prepare-fetch takes no positional arguments");
+    io.writeProgress?.("Preparing the selected yt-dlp environment…\n");
+    const executable = prepareVideoDownload();
+    io.write(parsed.json ? `${JSON.stringify({ executable })}\n` : `yt-dlp ready: ${executable}\n`);
+  } else await fetch(rest, io, cwd);
 }

package/packages/whisperx/README.md

@@ -3,7 +3,7 @@
 Explicit WhisperX model-family capability for the official speech program. Importing this package
 selects WhisperX; Runtime registration only binds the resulting alignment Need to a concrete
 execution endpoint. The default Hypit Skill path uses the HypiHub-hosted WhisperX endpoint; the
-trusted local worker remains an explicit fallback.
+trusted local worker remains an explicit deployment choice.
 
 The package contains no credentials, Python environment or queue. Providers translate the typed
 request directly into provider-neutral `AlignedTranscriptEvidence`. There is no vendor-shaped
@@ -11,7 +11,8 @@ Evidence wrapper or pass-through normalization node in the graph.
 
 `<whisperx:SemanticTake>` is the real-media semantic Surface. It consumes one normalized
 `SynchronizedMedia` and exactly one Script Segment. When that Segment contains Tokens, it also
-requires `language="en"`, `language="zh"` or `language="es"`. The language is passed directly to
+requires an explicit lowercase two- or three-letter language code, such as `language="ko"`.
+This package checks the code's form, not a cross-Provider support list. The language is passed directly to
 WhisperX; Script text and audio are not used to choose it implicitly. `@hypit/media-pipeline`
 projects the Take's audio to canonical 16 kHz mono `SpeechEvidenceAudio`; WhisperX sees only those
 bytes. A deterministic local alignment then combines the returned evidence with the Segment and
@@ -38,4 +39,56 @@ translates their local frames when assembling the final ProgramSpace and complet
 
 `@hypit/provider-hypihub` is the default concrete adapter; it uploads the canonical evidence audio
 and requests verbose JSON with segment- and word-level timestamps. `@hypit/provider-whisperx-local`
-remains available as an explicit local fallback.
+remains available as an explicit local deployment.
+
+
+## Language selection and local preparation
+
+```svml
+<whisperx:SemanticTake id="opening" narrative={story}
+  segment={story.segment.opening} media={opening-media.media} language="ko"/>
+```
+
+The selected service owns which languages it can align. The local service uses its pinned WhisperX
+version's default language-to-alignment-model mapping: the author does not choose weight URLs in
+SVML. ASR size and hardware are separate deployment choices (`expectedModel`, `expectedDevice`,
+`expectedCompute`). A multilingual ASR such as `small` can serve Korean; an English-only `.en`
+model cannot and is rejected explicitly. Unknown alignment languages fail in the service without
+switching language, model family or Provider. Locale aliases such as `zh-CN`, language names and
+`auto` are not interpreted by this Surface; use the service's explicit code.
+
+For local execution, merge this into the existing Runtime Profile:
+
+```json
+{
+  "endpoints": {
+    "whisperx.local": {
+      "use": "@hypit/provider-whisperx-local",
+      "config": { "expectedModel": "small", "alignmentLanguages": ["ko"] }
+    }
+  },
+  "bindings": {
+    "@hypit/whisperx@1#whisperx-alignment": "whisperx.local"
+  }
+}
+```
+
+`alignmentLanguages` declares resources to prepare on this machine. Each SVML `language` states
+what that particular Take uses; the preparation list never supplies an implicit author language.
+
+```bash
+hypit programs prepare --runtime hypit.runtime.json --endpoint whisperx.local
+hypit runtime up --runtime hypit.runtime.json --endpoint whisperx.local
+hypit build video.svrun --runtime hypit.runtime.json --follow
+```
+
+The Run references the authored SVML. Preparation downloads missing resources without starting the
+service; `runtime up` prepares if needed and starts the helper and Worker. Build only uses prepared
+resources. Adding a language to the same cache requires preparation, not a service restart.
+See the [local Provider README](../provider-whisperx-local/README.md) for cache and hardware choices.
+Other Endpoints needed by the Run must also be prepared and available.
+
+For reference analysis rather than an authored SemanticTake, use the same language code with
+`hypit transcribe source.mp4 --language ko --to transcript.json --runtime hypit.runtime.json`.
+Hosted execution uses the selected hosted deployment's models and preparation; the local
+`alignmentLanguages` option does not configure a remote service.

package/packages/whisperx/src/component.ts

@@ -6,7 +6,7 @@ import { canonicalize } from "@hypit/protocol";
 
 import { whisperXRequestForEvidenceAudio } from "./evidence.js";
 import { whisperXCapabilities, whisperXProducers } from "./manifest.js";
-import type { WhisperXLanguage } from "./types.js";
+import { parseWhisperXLanguage } from "./types.js";
 
 function inline(value: StoredValue, subject: string): CanonicalValue {
   if (value.kind !== "inline") throw new Error(`${subject} must be inline`);
@@ -19,10 +19,7 @@ export const whisperXComponent = {
       producer: whisperXProducers.request,
       handler: ({ inputs }) => {
         const evidence = inline(inputs.evidence!.value, "SpeechEvidenceAudio") as unknown as SpeechEvidenceAudio;
-        const language = inline(inputs.language!.value, "WhisperXLanguage") as unknown as WhisperXLanguage;
-        if (language !== "en" && language !== "zh" && language !== "es") {
-          throw new Error("WhisperXLanguage must be en, zh, or es");
-        }
+        const language = parseWhisperXLanguage(inline(inputs.language!.value, "WhisperXLanguage"));
         return {
           outputs: {},
           needs: { alignment: canonicalize(whisperXRequestForEvidenceAudio(evidence, { language })) },

package/packages/whisperx/src/evidence.ts

@@ -1,6 +1,7 @@
 import { assertSpeechEvidenceAudioIdentity } from "@hypit/speech";
 import type { SpeechEvidenceAudio } from "@hypit/speech";
 import type { WhisperXAlignmentRequest, WhisperXLanguage } from "./types.js";
+import { parseWhisperXLanguage } from "./types.js";
 
 function assert(condition: unknown, message: string): asserts condition {
   if (!condition) throw new Error(message);
@@ -14,9 +15,9 @@ export function verifyWhisperXAlignmentRequest(value: unknown): WhisperXAlignmen
   assert(request.audio?.kind === "blob"
     && request.audio.mediaType === "audio/wav"
     && Number.isSafeInteger(request.sampleFrames)
-    && request.sampleFrames > 0
-    && (request.language === "en" || request.language === "zh" || request.language === "es"),
+    && request.sampleFrames > 0,
   "WhisperX alignment request is invalid");
+  parseWhisperXLanguage(request.language);
   return request;
 }
 
@@ -64,6 +65,6 @@ export function whisperXRequestForEvidenceAudio(
   return {
     audio: evidence.artifact,
     sampleFrames: evidence.sampleFrames,
-    language: options.language,
+    language: parseWhisperXLanguage(options.language),
   };
 }

package/packages/whisperx/src/index.ts

@@ -12,3 +12,4 @@ export { decodeWhisperXSemanticTakeSurface } from "./surface.js";
 export { interpretWhisperXTranscript } from "./transcript.js";
 export type { WhisperXTranscriptResponse } from "./transcript.js";
 export type * from "./types.js";
+export { parseWhisperXLanguage } from "./types.js";

package/packages/whisperx/src/manifest.ts

@@ -38,8 +38,7 @@ export const whisperXMarkupSurfaces = [{
           accepts: [mediaTypes.synchronized],
           summary: "Selects the already normalized SynchronizedMedia represented by this Segment." },
         { name: "language", kind: "literal", required: false,
-          values: ["en", "zh", "es"],
-          summary: "For a Segment with Tokens, explicitly selects the English, Chinese or Spanish WhisperX models." },
+          summary: "For a Segment with Tokens, explicitly states its spoken language code. The selected service owns the available alignment models." },
       ],
       ports: [
         { name: "take", type: speechTypes.semanticTake,
@@ -50,7 +49,7 @@ export const whisperXMarkupSurfaces = [{
       notes: [
         "A Segment with Tokens states all five attributes and sends its prepared audio for alignment.",
         "An empty Segment omits language and maps its authored start/end Anchors directly to the prepared-media boundaries.",
-        "For speech, language is never detected from Script text or audio; each alignment call states en, zh or es explicitly.",
+        "For speech, each alignment call states an explicit lowercase two- or three-letter language code; language is not inferred from Script text or audio.",
         "Importing this package is what selects the WhisperX model family; the Runtime separately binds the alignment Need to an Endpoint.",
       ],
     },

package/packages/whisperx/src/surface.ts

@@ -13,7 +13,7 @@ import { mediaTypes } from "@hypit/media";
 
 import { whisperXBoundarySemanticTakeFragment, whisperXSemanticTakeFragment } from "./fragment.js";
 import { whisperXTypes } from "./manifest.js";
-import type { WhisperXLanguage } from "./types.js";
+import { parseWhisperXLanguage } from "./types.js";
 
 function reference(
   element: StructuredElement,
@@ -61,16 +61,13 @@ export const decodeWhisperXSemanticTakeSurface: StructuredSurfaceHandler = ({ el
       fragments: [whisperXBoundarySemanticTakeFragment],
     };
   }
-  const language = stringAttribute(element, "language");
-  if (language !== "en" && language !== "zh" && language !== "es") {
-    throw new Error(`${element.name}.language must be en, zh, or es`);
-  }
+  const language = parseWhisperXLanguage(stringAttribute(element, "language"), `${element.name}.language`);
   const languageId = `${id}.language`;
   return {
     records: [{
       id: languageId,
       type: whisperXTypes.language,
-      value: { kind: "inline", value: language as WhisperXLanguage },
+      value: { kind: "inline", value: language },
       range: element.range,
     }],
     components: [{

package/packages/whisperx/src/types.ts

@@ -1,6 +1,14 @@
 import type { SpeechEvidenceAudio } from "@hypit/speech";
 
-export type WhisperXLanguage = "en" | "zh" | "es";
+/** Explicit language code. Executable language support belongs to the selected service. */
+export type WhisperXLanguage = string;
+
+export function parseWhisperXLanguage(value: unknown, subject = "WhisperX language"): WhisperXLanguage {
+  if (typeof value !== "string" || !/^[a-z]{2,3}$/u.test(value) || value === "und") {
+    throw new Error(`${subject} must be an explicit lowercase two- or three-letter spoken language code, such as en, zh, or ko; auto and und are not explicit languages`);
+  }
+  return value;
+}
 
 export type WhisperXAlignmentRequest = {
   readonly audio: SpeechEvidenceAudio["artifact"];

package/packages/yt-dlp/README.md

@@ -3,6 +3,7 @@
 `@hypit/yt-dlp` owns video download for the Hypit Distribution. Video CLI exposes it as:
 
 ```bash
+hypit media prepare-fetch
 hypit media fetch "https://example.com/watch?v=VIDEO_ID" --to references/source.mp4
 ```
 
@@ -18,9 +19,14 @@ Runtime Profile and creates no Build.
   preparation and overwrite policy. The target extension must be `.mp4`, `.mkv`, `.webm` or `.mov`.
 
 The downloader locates its declared `@hypit/yt-dlp-service-runtime` package through the active
-Distribution/package resolver and invokes that package's locked Python project through `uv`.
-Ship its `pyproject.toml` and `uv.lock`; the caller's location and a `services/` ancestor are irrelevant.
-`uv` and `ffmpeg` must be available on PATH; the CLI also uses `ffprobe` to report the saved media.
+Distribution/package resolver. `prepareVideoDownload()` (`media prepare-fetch`) explicitly runs
+`uv sync --frozen` into `<hostState>/programs/yt-dlp/<version>/.venv`. `downloadVideo()` only invokes
+that prepared executable and refuses a missing environment. Ship `pyproject.toml` and `uv.lock`;
+the caller's location and a `services/` ancestor are irrelevant. `uv` is needed for preparation;
+`ffmpeg` must be on PATH for fetching, and the CLI uses `ffprobe` to report the saved media.
+The default upstream extras include the EJS solver in that locked environment. Fetch explicitly
+selects the calling Node executable, ignores user yt-dlp configuration/plugins, and disables updates
+and remote component acquisition. Fetching source media remains a network operation.
 
 The request selects `bv*+ba/b`, with `res:1080,vcodec:h264` format preferences and `--no-playlist`.
 Available source streams determine the result. It stages the download in the OS temporary directory,

package/packages/yt-dlp/package.json

@@ -9,6 +9,7 @@
   },
   "dependencies": {
     "@hypit/package-loader-node": "workspace:*",
-    "@hypit/yt-dlp-service-runtime": "workspace:*"
+    "@hypit/yt-dlp-service-runtime": "workspace:*",
+    "@hypit/runtime-host-node": "workspace:*"
   }
 }

package/packages/yt-dlp/src/download.ts

@@ -5,7 +5,7 @@
  * rather than in a folder. `yt-dlp` is what turns one into a file; everything after that reads the
  * file and never learns where it came from.
  *
- * The tool is a pinned Python dependency under `services/yt-dlp`, reached through `uv`, and not a
+ * The tool is a pinned Python dependency prepared explicitly by `hypit media prepare-fetch`, not a
  * binary the machine happens to carry. `yt-dlp` releases constantly because it is chasing sites that
  * keep changing, so an unpinned copy makes the same link fetch differently on two machines. This is
  * the same shape WhisperX and OpenCV already use for their Python programs.
@@ -13,9 +13,9 @@
 import { spawnSync } from "node:child_process";
 import { copyFile, mkdtemp, readdir, rename, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, extname, join } from "node:path";
+import { extname, join } from "node:path";
 
-import { resolveNodePackageResource } from "@hypit/package-loader-node";
+import { requireVideoDownload } from "./environment.js";
 
 /**
  * Whether this is a link to fetch rather than a path to open.
@@ -33,19 +33,6 @@ export function isVideoUrl(value: string): boolean {
   }
 }
 
-/**
- * The locked uv project is a Distribution package asset, the same way WhisperX and
- * OpenCV locate their Python programs. Walking parents of this file only works
- * while the module still sits above `services/` in a contributor checkout.
- */
-function serviceProject(): string {
-  return dirname(resolveNodePackageResource(
-    "@hypit/yt-dlp-service-runtime",
-    "pyproject.toml",
-    { from: import.meta.url },
-  ));
-}
-
 /**
  * Fetch one video into exactly the file the caller named.
  *
@@ -60,10 +47,14 @@ export async function downloadVideo(url: string, target: string): Promise<void>
   if (!["mp4", "mkv", "webm", "mov"].includes(container)) {
     throw new Error(`${target} must end in .mp4, .mkv, .webm or .mov`);
   }
+  const executable = requireVideoDownload();
+  const media = spawnSync("ffmpeg", ["-version"], { encoding: "utf8", windowsHide: true, timeout: 15_000 });
+  if (media.status !== 0) throw new Error("FFmpeg is unavailable on PATH; install your selected media toolchain before fetching video");
   const work = await mkdtemp(join(tmpdir(), "hypit-fetch-"));
   try {
-    const result = spawnSync("uv", [
-      "run", "--project", serviceProject(), "--frozen", "yt-dlp",
+    const result = spawnSync(executable, [
+      "--ignore-config", "--no-update", "--no-remote-components", "--no-plugin-dirs",
+      "--no-js-runtimes", "--js-runtimes", `node:${process.execPath}`,
       "--no-playlist", "--no-progress", "--quiet",
       "--format", "bv*+ba/b",
       "--merge-output-format", container,
@@ -72,12 +63,7 @@ export async function downloadVideo(url: string, target: string): Promise<void>
       url,
     ], { encoding: "utf8", windowsHide: true, timeout: 900_000 });
 
-    if (result.error !== undefined && (result.error as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new Error(
-        "uv is not installed, and a link is fetched by a pinned yt-dlp that uv installs. It is the same "
-        + "tool the WhisperX and OpenCV programs need. Install it (https://docs.astral.sh/uv/), or download "
-        + "the video yourself and pass the path instead.");
-    }
+    if (result.error !== undefined) throw result.error;
     if (result.status !== 0) {
       throw new Error(`yt-dlp could not fetch ${url}: ${(result.stderr ?? "").trim().slice(-2000)}`);
     }

package/packages/yt-dlp/src/environment.ts

@@ -0,0 +1,36 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolveNodePackageResource } from "@hypit/package-loader-node";
+import { hypitHostStateRoot, pythonEnvironmentCommand } from "@hypit/runtime-host-node";
+
+/** One selected, locked environment. Fetching media never invokes its installer. */
+export function videoDownloadEnvironment() {
+  const project = dirname(resolveNodePackageResource("@hypit/yt-dlp-service-runtime", "pyproject.toml", { from: import.meta.url }));
+  const version = /"yt-dlp(?:\[[^\]]+\])?==([^"]+)"/u.exec(readFileSync(join(project, "pyproject.toml"), "utf8"))?.[1];
+  if (version === undefined) throw new Error("yt-dlp runtime must declare its exact upstream version");
+  const environment = join(hypitHostStateRoot(), "programs", "yt-dlp", version, ".venv");
+  return { project, version, environment, executable: pythonEnvironmentCommand(environment, "yt-dlp") };
+}
+
+export function requireVideoDownload(): string {
+  const selected = videoDownloadEnvironment();
+  const result = spawnSync(selected.executable, ["--ignore-config", "--version"], { encoding: "utf8", windowsHide: true, timeout: 15_000 });
+  // PyPI normalizes date-version leading zeroes; the executable retains them.
+  const release = (value: string) => value.trim().split(".").map((part) => part.replace(/^0+(?=\d)/u, "")).join(".");
+  if (result.status !== 0 || release(result.stdout ?? "") !== release(selected.version)) {
+    throw new Error(`yt-dlp ${selected.version} is not ready at ${selected.executable}; run hypit media prepare-fetch. ${result.error?.message ?? result.stderr?.trim() ?? ""}`);
+  }
+  return selected.executable;
+}
+
+/** Explicit provisioning. uv owns dependency resolution and the environment. */
+export function prepareVideoDownload(): string {
+  const selected = videoDownloadEnvironment();
+  const result = spawnSync("uv", ["sync", "--project", selected.project, "--frozen", "--no-dev"], {
+    env: { ...process.env, UV_PROJECT_ENVIRONMENT: selected.environment },
+    stdio: ["ignore", "inherit", "inherit"], windowsHide: true,
+  });
+  if (result.error || result.status !== 0) throw new Error(`yt-dlp preparation failed: ${result.error?.message ?? `uv exited ${result.status}`}`);
+  return requireVideoDownload();
+}

package/packages/yt-dlp/src/index.ts

@@ -1 +1,2 @@
 export { downloadVideo, isVideoUrl } from "./download.js";
+export { prepareVideoDownload, requireVideoDownload } from "./environment.js";