@hypit/hypit 0.1.3 → 0.1.5

package/packages/provider-hyperframes-local/src/render.ts

@@ -1,6 +1,6 @@
 import { createReadStream } from "node:fs";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
-import { availableParallelism, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { EndpointInvocationContext } from "@hypit/endpoint-kit";
 import { stageHyperframesProject } from "@hypit/hyperframes/project";
@@ -14,16 +14,23 @@ import type { HyperframesExecutionOptions } from "./options.js";
 import { assert, positiveInteger } from "./process.js";
 import { runCaptureProcess } from "./capture-process.js";
 import { finished } from "node:stream/promises";
+import { autoWorkerLimit } from "./concurrency.js";
 
 export type HyperframesRenderProgress =
+  | { readonly phase: "staging" | "encoding" | "storing"; readonly elapsedMs: number }
+  | { readonly phase: "decoding"; readonly completed: number; readonly total: number; readonly elapsedMs: number }
+  | { readonly phase: "worker-progress"; readonly worker: number; readonly completed: number; readonly elapsedMs: number }
   | { readonly phase: "prepared"; readonly workers: number; readonly sourceFrames: number; readonly elapsedMs: number }
-  | { readonly phase: "worker-initializing" | "worker-start" | "worker-complete"; readonly worker: number; readonly range: MediaFrameRange;
+  | { readonly phase: "worker-initializing" | "worker-start"; readonly worker: number; readonly range: MediaFrameRange;
+      readonly browserPid: number | undefined; readonly elapsedMs: number }
+  | { readonly phase: "worker-complete"; readonly worker: number; readonly completed: number;
       readonly browserPid: number | undefined; readonly elapsedMs: number }
   | { readonly phase: "complete"; readonly frames: number; readonly elapsedMs: number };
 
 export type RenderHyperframesVisualOptions = HyperframesExecutionOptions & {
   readonly resources: EndpointInvocationContext["resources"];
   readonly signal?: AbortSignal;
+  readonly onDiagnostic?: (diagnostic: import("@hypit/runtime").ExecutionDiagnostic) => Promise<void>;
   readonly onProgress?: (event: HyperframesRenderProgress) => void;
 };
 
@@ -36,7 +43,8 @@ export function resolveExecutionOptions(options: HyperframesExecutionOptions) {
   const browserGpu = options.browserGpu ?? "hardware";
   assert(["auto", "software", "hardware"].includes(browserGpu), "HyperFrames browserGpu is invalid");
   return {
-    workers: workers === "auto" ? Math.min(4, Math.max(1, Math.floor(availableParallelism() / 2))) : workers,
+    workers,
+    maxWorkers: workers === "auto" ? positiveInteger(options.maxWorkers ?? autoWorkerLimit(), "maxWorkers") : workers,
     quality, browserGpu,
     ffmpegPath: options.ffmpegPath ?? "ffmpeg",
     ffprobePath: options.ffprobePath ?? "ffprobe",
@@ -52,6 +60,11 @@ export function resolveExecutionOptions(options: HyperframesExecutionOptions) {
   };
 }
 
+/** Same deterministic reservation for Runtime admission and the capture attempt. */
+export function renderWorkerLimit(config: ReturnType<typeof resolveExecutionOptions>, frameCount: number, fps: number): number {
+  return Math.min(config.maxWorkers, config.workers === "auto" ? Math.max(1, Math.ceil(frameCount / fps)) : frameCount);
+}
+
 /** Execute one attempt. Its deadline includes resource preparation and output storage. */
 export async function renderHyperframesVisual(
   request: HyperframesVisualRequest,
@@ -61,14 +74,32 @@ export async function renderHyperframesVisual(
   const config = resolveExecutionOptions(options);
   const { document } = request;
   const range = request.range ?? { startFrame: 0, endFrameExclusive: document.frameCount };
+  const frameCount = range.endFrameExclusive - range.startFrame;
   const controller = new AbortController();
   const signal = options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
   const started = performance.now();
+  let phaseStarted = started;
   let phase = "preparing resources";
   const timer = setTimeout(() => controller.abort(new Error(`HyperFrames render timed out during ${phase}`)), config.processTimeoutMs);
   let work: string | undefined;
+  const diagnostics: Promise<void>[] = [];
+  const diagnostic = (message: string) => {
+    if (options.onDiagnostic === undefined) return;
+    const pending = options.onDiagnostic({ level: "info", message });
+    diagnostics.push(pending);
+    void pending.catch(() => {});
+  };
+  const changePhase = (next: string) => {
+    const now = performance.now();
+    diagnostic(`${phase}: ${Math.round(now - phaseStarted)} ms`);
+    phaseStarted = now;
+    phase = next;
+  };
   try {
     signal.throwIfAborted();
+    await options.onDiagnostic?.({ level: "info", message:
+      `Render ${frameCount} frames; workers ${config.workers} (limit ${renderWorkerLimit(config, frameCount, document.frameRate.numerator / document.frameRate.denominator)}); opaque fast PNG; quality ${config.quality}; GPU ${config.browserGpu}; encoder ${config.ffmpegPath}` });
+    options.onProgress?.({ phase: "staging", elapsedMs: 0 });
     work = await mkdtemp(join(tmpdir(), "hypit-hyperframes-local-"));
     await stageHyperframesProject({ document, directory: work, signal,
       read: async (artifact, readSignal) => {
@@ -82,13 +113,20 @@ export async function renderHyperframesVisual(
         ffprobePath: config.ffprobePath, processTimeoutMs: config.processTimeoutMs,
         maxProbeOutputBytes: config.maxProcessOutputBytes, signal: probeSignal! }),
     });
-    phase = "rendering frames";
+    changePhase("decoding source frames");
     await runCaptureProcess({ document, range, config, directory: work,
       engineModule: import.meta.resolve("@hyperframes/engine"),
       producerModule: import.meta.resolve("@hyperframes/producer"),
-    }, signal, (event) => options.onProgress?.({ ...event, elapsedMs: Math.round(performance.now() - started) }));
+    }, signal, (event) => {
+      if (event.phase === "prepared") changePhase("starting browsers");
+      if (event.phase === "worker-start" && phase === "starting browsers") changePhase("capturing frames");
+      if (event.phase === "encoding") changePhase("encoding and verifying video");
+      options.onProgress?.({ ...event, elapsedMs: Math.round(performance.now() - started) });
+    },
+      undefined, options.onDiagnostic);
     signal.throwIfAborted();
-    phase = "storing output";
+    changePhase("storing output");
+    options.onProgress?.({ phase: "storing", elapsedMs: Math.round(performance.now() - started) });
     const output = join(work, "visual.mp4");
     let artifact;
     if (isStreamingResourceStore(options.resources)) {
@@ -100,7 +138,9 @@ export async function renderHyperframesVisual(
       artifact = await options.resources.put(await readFile(output, { signal }), "video/mp4", { signal });
     }
     signal.throwIfAborted();
-    const frameCount = range.endFrameExclusive - range.startFrame;
+
+    changePhase("complete");
+    await Promise.all(diagnostics);
     options.onProgress?.({ phase: "complete", frames: frameCount, elapsedMs: Math.round(performance.now() - started) });
     return sealRenderedVisual({ frameRate: document.frameRate, frameCount, canvas: document.canvas, artifact });
   } catch (error) {
@@ -110,5 +150,6 @@ export async function renderHyperframesVisual(
   } finally {
     clearTimeout(timer);
     if (work !== undefined) await rm(work, { recursive: true, force: true });
+    await Promise.all(diagnostics);
   }
 }

package/packages/provider-hypihub/README.md

@@ -1,17 +1,26 @@
 # `@hypit/provider-hypihub`
 
 Thin Hypit Runtime Provider for a HypiHub deployment. It is an optional default gateway for
-paid generation and WhisperX alignment requests; callers may keep their own Provider and select HypiHub only
-when its OAuth login is configured.
+paid generation and WhisperX alignment requests. Select it for a chosen HypiHub account, with OAuth
+or an API key in the configured Credential Store; other Providers remain ordinary Profile choices.
 
-It maps the currently shipped image/video model capabilities to HypiHub, including image edits and
+`doctor` is read-only. If a stored OAuth access token needs refresh, it reports that account access
+and refresh validity remain unchecked; it does not rotate credentials or conclude that their Store
+is read-only. Authorized execution and pricing reads retain the normal refresh-and-persist path.
+An actual refresh rejection calls for reconnecting the selected account.
+
+Its mapping table declares the image/video/speech model capabilities it implements, including image edits and
 image-to-video first-frame inputs, submits jobs, polls them, downloads the first-class assets and
 admits them into the current Build's working byte area. Image references use HypiHub's documented
 `reference_images` object shape (`[{ "url": "…" }]`); video references use the public
-`reference_image_urls`, `reference_videos`, and `reference_audios` fields (with `ref_video_url`
-for one video). First/last-frame images use `first_frame` and `last_frame`.
+`reference_image_urls`, `reference_videos`, and `reference_audios` fields. A single reference video
+remains in `reference_videos`; `ref_video_url` is reserved for a model's source-video port. First/last-frame images use `first_frame` and `last_frame`.
+
+Seedance 2.5 (`@hypit/seedance` model `2.5`) maps to `bytedance/seedance-2-5` and supports
+`480p`, `720p` and `1080p`. The Provider passes the authored `resolution` to `POST /v1/videos`;
+omitting it in the Seedance Surface defaults to `720p`.
 
-The current HypiHub GPT Image 2 route exposes the same request surface as its KIE upstream:
+The current HypiHub GPT Image 2 route has these service-specific limits:
 
 | Resolution | Ratios unavailable at this Endpoint | `background` |
 | --- | --- | --- |
@@ -19,10 +28,14 @@ The current HypiHub GPT Image 2 route exposes the same request surface as its KI
 | `2K` | `5:4`, `4:5`, `3:1`, `1:3`, `9:21` | omit |
 | `4K` | `3:1`, `1:3`, `9:21` | omit |
 
-HypiHub owns this support check independently: it neither imports the KIE Provider nor narrows the
-GPT Image model package. When the service surface changes, this Provider can change without changing
+HypiHub owns this support check independently: it leaves the GPT Image model package unchanged. When the service surface changes, this Provider can change without changing
 the model or another Provider.
 
+Model identity is preserved across input modes: Seedream 5 Lite references use the Lite image-edit
+route, and Grok 1.5 Preview remains the Preview model. A deployment's current catalogue may offer
+newer models or omit one implemented here. Availability and unsupported-input errors retain their
+service explanation; they do not imply expired credentials or authorize substituting another model.
+
 For moving portraits, [Volcengine Matting](../volcengine-matting/README.md) maps
 `@hypit/volcengine-matting@1#matte-portrait-video` to `POST /v1/videos` with
 `model: "matte-portrait-video"`, `ref_video_url` and `format` (`WEBM` by default, or `MOV`).
@@ -31,8 +44,8 @@ references; the returned job uses the same polling and asset collection lifecycl
 account's `/v1/models` establishes availability. The processed video enters ordinary Normalize,
 then either semantic alignment for a Script performance or Media Track for B-roll.
 
-The existing [Background Removal](../background-removal/README.md) package handles single images
-through KIE Recraft. This Provider does not bind that separate image capability either.
+[Background Removal](../background-removal/README.md) declares a separate single-image capability.
+This Provider does not currently implement it; select a project Provider for that operation.
 
 Runtime Profile example:
 
@@ -64,8 +77,16 @@ Resources are uploaded through a session from `POST /v1/files/uploads`, followed
 regional multipart instructions returned by HypiHub. The Provider follows the server-selected part
 size and part concurrency, retries a failed part with a fresh signed URL, completes or cancels that
 one upload, and then passes the returned HTTPS URL to generation or transcription. One
-Resource identity is uploaded once within one Runtime operation. Hypit keeps no upload catalog or
-cross-Build cache. Embedded callers may replace this transport with `publicAssetUrl`.
+Resource identity with the same declared person-reference classification is uploaded once within one Runtime operation. Hypit keeps no upload catalog or
+cross-Build cache. Seedance visual references can carry `personReference` in their media fields;
+the mapping declares it as a resource-transport field and the upload session receives
+`is_person_reference`, preserving true, false and omission. It stays out of the generation body.
+HypiHub stores the authored classification and prepares the applicable upstream person reference;
+this Provider does not detect faces or select an upstream private-avatar group.
+
+Embedded callers may replace transport with `publicAssetUrl(artifact, resources, fields)`. That
+callback receives the declared resource fields and must preserve any required service preparation,
+such as uploading a marked person reference through HypiHub before returning its URL.
 
 OAuth login stores the access token, refresh token and expiry as one opaque credential value. The
 browser callback only confirms that authorization returned to the CLI; the CLI reports success after
@@ -87,13 +108,23 @@ catalog to verify configured capabilities; ordinary preflight never makes that r
 declares HypiHub's public pricing page, `https://hypit.ai/commercial/pricing/`, as its price source.
 For each selected Need, `readPricing` resolves the corresponding HypiHub model and returns the service's
 authenticated `GET /v1/pricing?model=<model>` response unchanged together with that URL. It covers
-generation, alignment, Voice Design, and Voice Clone through the same mechanism;
+generation, alignment, Voice Design and Voice Clone through the same mechanism;
 the Provider does not maintain a second list of billing formulas or calculate a request total.
 
-HypiHub declares MiMo Voice Design and Voice Clone together with every other capability it serves; it
-never hides one. Voice Design produces an accepted voice-reference Resource, and Voice Clone uses
-that reference to produce independent speech. Hypit does not expose MiMo preset voices. When another
-selected Endpoint offers the same capability (a local WhisperX or the official MiMo
+The Provider declares its implemented speech capabilities alongside image, video and alignment.
+Voice Design produces an accepted voice-reference Resource, and Voice Clone uses that
+reference to produce independent speech. All of them use `POST /v1/audio/speech`:
+
+| Package | Capability | HypiHub model | Request fields |
+| --- | --- | --- | --- |
+| `@hypit/mimo-speech` | `mimo-v2.5-tts-voicedesign` | `mimo-v2.5-tts-voicedesign` | `input`, `voice_description` |
+| `@hypit/mimo-speech` | `mimo-v2.5-tts-voiceclone` | `mimo-v2.5-tts-voiceclone` | `input`, `reference_audio`, optional `prompt` |
+| `@hypit/fishaudio-speech` | `voice-design-1` | `fishaudio/voice-design-1` | `input`, `voice_description` |
+| `@hypit/fishaudio-speech` | `voice-clone` | `fishaudio/voice-clone` | `input`, `reference_audio`, constant `voice_description` title |
+| `@hypit/elevenlabs-speech` | `eleven_ttv_v3` | `eleven_ttv_v3` | `input`, `voice_description` |
+
+Each returned preview becomes one member of the audio set. These Model packages do not expose preset
+voices. When another selected Endpoint offers the same capability (such as local WhisperX or a project-owned speech
 Provider), the Runtime Profile's `bindings` say which Endpoint serves it.
 
 Execution policy remains local to this Provider:

package/packages/provider-hypihub/package.json

@@ -18,6 +18,8 @@
   },
   "devDependencies": {
     "@hypit/driver-node": "workspace:*",
+    "@hypit/elevenlabs-speech": "workspace:*",
+    "@hypit/fishaudio-speech": "workspace:*",
     "@hypit/mimo-speech": "workspace:*",
     "@hypit/seedance": "workspace:*",
     "@hypit/speech": "workspace:*",

package/packages/provider-hypihub/src/mapping.ts

@@ -9,16 +9,18 @@ const SEEDREAM: ModuleRef = { name: "@hypit/seedream", version: "1" };
 const MINIMAX: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
 const GROK: ModuleRef = { name: "@hypit/grok-imagine", version: "1" };
 const MIMO_SPEECH: ModuleRef = { name: "@hypit/mimo-speech", version: "1" };
+const FISHAUDIO_SPEECH: ModuleRef = { name: "@hypit/fishaudio-speech", version: "1" };
+const ELEVENLABS_SPEECH: ModuleRef = { name: "@hypit/elevenlabs-speech", version: "1" };
 
 const seedance = (name: string, model: string): GenerationWireMapping => ({
   capability: { module: SEEDANCE, name }, result: "video", routes: [{ model }],
   fields: {
     prompt: { as: "value", field: "prompt" },
-    referenceImage: { as: "urlArray", field: "reference_image_urls" },
-    referenceVideo: { as: "urlArray", field: "reference_videos" },
+    referenceImage: { as: "urlArray", field: "reference_image_urls", resourceFields: ["personReference"] },
+    referenceVideo: { as: "urlArray", field: "reference_videos", resourceFields: ["personReference"] },
     referenceAudio: { as: "urlArray", field: "reference_audios" },
-    firstFrame: { as: "url", field: "first_frame" },
-    lastFrame: { as: "url", field: "last_frame" },
+    firstFrame: { as: "url", field: "first_frame", resourceFields: ["personReference"] },
+    lastFrame: { as: "url", field: "last_frame", resourceFields: ["personReference"] },
     resolution: { as: "value", field: "resolution" },
     aspectRatio: { as: "value", field: "aspect_ratio" },
     duration: { as: "value", field: "seconds" },
@@ -65,7 +67,7 @@ export const hypiHubMappings: readonly GenerationWireMapping[] = [
   })),
   {
     capability: { module: SEEDREAM, name: "seedream-5-lite" }, result: "image", routes: [
-      { model: "seedream/5-pro-image-to-image", whenPresent: ["images"] },
+      { model: "seedream/5-lite-image-to-image", whenPresent: ["images"] },
       { model: "seedream/5-lite-text-to-image" },
     ],
     fields: {
@@ -108,8 +110,7 @@ export const hypiHubMappings: readonly GenerationWireMapping[] = [
   },
   {
     capability: { module: GROK, name: "grok-imagine-video-1.5-preview" }, result: "video", routes: [
-      { model: "grok-imagine/image-to-video", whenPresent: ["images"] },
-      { model: "grok-imagine/text-to-video" },
+      { model: "grok-imagine-video-1.5-preview" },
     ],
     fields: {
       prompt: { as: "value", field: "prompt" }, duration: { as: "value", field: "seconds" },
@@ -132,6 +133,29 @@ export const hypiHubMappings: readonly GenerationWireMapping[] = [
       voiceReference: { as: "urlArray", field: "reference_audio" },
     },
   },
+  {
+    capability: { module: FISHAUDIO_SPEECH, name: "voice-design-1" }, result: "audio", routes: [{ model: "fishaudio/voice-design-1" }],
+    fields: {
+      text: { as: "value", field: "input" },
+      voiceDescription: { as: "value", field: "voice_description" },
+    },
+  },
+  {
+    capability: { module: FISHAUDIO_SPEECH, name: "voice-clone" }, result: "audio", routes: [{ model: "fishaudio/voice-clone" }],
+    // Fish Audio titles its transient cloned voice; the title has no authored meaning.
+    constants: { voice_description: "reference" },
+    fields: {
+      text: { as: "value", field: "input" },
+      voiceReference: { as: "urlArray", field: "reference_audio" },
+    },
+  },
+  {
+    capability: { module: ELEVENLABS_SPEECH, name: "eleven_ttv_v3" }, result: "audio", routes: [{ model: "eleven_ttv_v3" }],
+    fields: {
+      text: { as: "value", field: "input" },
+      voiceDescription: { as: "value", field: "voice_description" },
+    },
+  },
 ];
 
 function capabilityKey(ref: CapabilityRef): string {

package/packages/provider-hypihub/src/oauth.ts

@@ -5,6 +5,12 @@ import { requestDeadline } from "@hypit/runtime-kit";
 const OAUTH_CLIENT_ID = "hyc_d5d5e8e7131b0c877756e66c";
 const REFRESH_SKEW_MS = 60_000;
 
+/** Read-only diagnostics can identify expiry without attempting credential rotation. */
+export function hypiHubCredentialNeedsRefresh(secret: string, now = Date.now()): boolean {
+  const expiresAt = decodeOAuth2Credential(secret)?.expiresAt;
+  return expiresAt !== undefined && expiresAt <= now + REFRESH_SKEW_MS;
+}
+
 type OAuthTokenResponse = {
   readonly access_token?: unknown;
   readonly refresh_token?: unknown;

package/packages/provider-hypihub/src/provider.ts

@@ -18,7 +18,7 @@ import type { WhisperXTranscriptResponse } from "@hypit/whisperx";
 import { hypiHubRouteForCapability, hypiHubRoutes } from "./routes.js";
 import { HypiHubUploader } from "./upload.js";
 import type { RuntimeDoctorDiagnostic } from "@hypit/runtime-kit";
-import { createHypiHubAuth } from "./oauth.js";
+import { createHypiHubAuth, hypiHubCredentialNeedsRefresh } from "./oauth.js";
 import type { HypiHubAuth } from "./oauth.js";
 
 export const hypiHubProviderModuleRef = { name: "@hypit/provider-hypihub", version: "1" } as const;
@@ -45,7 +45,7 @@ export type CreateHypiHubProviderOptions = {
   readonly transcriptionModel?: string;
   readonly fetch?: typeof globalThis.fetch;
   /** Overrides HypiHub's negotiated upload transport for referenced Resources. */
-  readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore) => Promise<string>;
+  readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore, fields?: Readonly<Record<string, string | number | boolean>>) => Promise<string>;
 };
 
 type Handle = { readonly contract: "hypit.hypihub-operation@1"; readonly jobId: string; readonly route: string; readonly startedAt: number };
@@ -69,7 +69,7 @@ function credential(credentials: Readonly<Record<string, EndpointCredential>>) {
 }
 function guidedMessage(error: unknown): string {
   const message = error instanceof Error ? error.message : String(error);
-  return /API key is unavailable|HypiHub login is unavailable|HTTP (?:401|403|404)\b|not enabled for|model_not_found|no_capable_provider/iu.test(message)
+  return /API key is unavailable|HypiHub login is unavailable|HTTP 401\b/iu.test(message)
     ? `${message}. Sign in to HypiHub at https://hypit.ai with hypit auth login`
     : message;
 }
@@ -155,11 +155,14 @@ class HypiHubClient {
     }
     throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
-  async upload(artifact: BlobRef, resources: ResourceStore, auth: HypiHubAuth): Promise<string> {
+  async upload(artifact: BlobRef, resources: ResourceStore, auth: HypiHubAuth, fields?: Readonly<Record<string, string | number | boolean>>): Promise<string> {
     const bytes = await resources.get(artifact.resource);
     assert(bytes !== undefined, `HypiHub reference artifact ${artifact.resource} is unavailable`);
     assert(bytes.byteLength === artifact.size, `HypiHub reference artifact ${artifact.resource} size differs`);
-    return await this.uploader.upload({ bytes, mediaType: artifact.mediaType }, auth);
+    const personReference = fields?.personReference;
+    assert(personReference === undefined || typeof personReference === "boolean", "HypiHub personReference must be a boolean");
+    return await this.uploader.upload({ bytes, mediaType: artifact.mediaType,
+      ...(personReference === undefined ? {} : { isPersonReference: personReference }) }, auth);
   }
 
   async transcribe(body: Record<string, unknown>, auth: HypiHubAuth): Promise<Record<string, unknown>> {
@@ -300,6 +303,11 @@ export async function diagnoseHypiHubProvider(
 ): Promise<readonly RuntimeDoctorDiagnostic[]> {
   const apiKey = context.credentials.apiKey?.secret;
   assert(typeof apiKey === "string" && apiKey.length > 0, "HypiHub login is unavailable");
+  if (hypiHubCredentialNeedsRefresh(apiKey)) return [{
+    severity: "warning",
+    code: "HYPIHUB_OAUTH_REFRESH_UNCHECKED",
+    message: "The stored HypiHub access token needs refresh. Read-only doctor has not checked account access or refresh validity. Authorized execution can refresh through a writable Credential Store; reconnect if that refresh is rejected.",
+  }];
   const client = new HypiHubClient({
     baseUrl: apiBaseUrl(options.baseUrl ?? "https://hypit.ai/v1"),
     timeout: options.requestTimeoutMs ?? 30_000,
@@ -373,9 +381,9 @@ async function synthesizeAudio(client: HypiHubClient, context: EndpointInvocatio
   const route = hypiHubRouteForCapability(context.need.capability);
   assert(route !== undefined && route.media === "audio", "HypiHub does not implement this exact capability");
   const auth = authFor(context, client);
-  const compiled = await route.compile(context.need.constraints, async (artifact) => publicAssetUrl === undefined
-    ? await client.upload(artifact, context.resources, auth)
-    : await publicAssetUrl(artifact, context.resources));
+  const compiled = await route.compile(context.need.constraints, async (artifact, fields) => publicAssetUrl === undefined
+    ? await client.upload(artifact, context.resources, auth, fields)
+    : await publicAssetUrl(artifact, context.resources, fields));
   await verifyModelRoute(client, auth, compiled.model, "audio_speech");
   const audio = await client.speech(auth, { model: compiled.model, ...(compiled.input as Record<string, unknown>) });
   const artifacts = await Promise.all(audio.map(async (item) => await context.resources.put(item.bytes, item.mediaType)));
@@ -390,13 +398,14 @@ function endpoint(client: HypiHubClient, pollIntervalMs: number, maxOperationMs:
         assert(route !== undefined, "HypiHub does not implement this exact capability");
         const auth = authFor(context, client);
         const uploaded = new Map<string, Promise<string>>();
-        const resolve = (artifact: BlobRef): Promise<string> => {
-          const existing = uploaded.get(artifact.resource);
+        const resolve = (artifact: BlobRef, fields?: Readonly<Record<string, string | number | boolean>>): Promise<string> => {
+          const key = JSON.stringify([artifact.resource, canonicalize(fields ?? {})]);
+          const existing = uploaded.get(key);
           if (existing !== undefined) return existing;
           const promise = publicAssetUrl === undefined
-            ? client.upload(artifact, context.resources, auth)
-            : publicAssetUrl(artifact, context.resources);
-          uploaded.set(artifact.resource, promise);
+            ? client.upload(artifact, context.resources, auth, fields)
+            : publicAssetUrl(artifact, context.resources, fields);
+          uploaded.set(key, promise);
           return promise;
         };
         const compiled = await route.compile(context.need.constraints, resolve);
@@ -511,9 +520,11 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
       assertWhisperXEvidenceWav(bytes, request.sampleFrames);
       const auth = authFor(context, client);
       await verifyModelRoute(client, auth, transcriptionModel, "transcriptions");
+      await context.reportProgress?.({ phase: "Preparing audio for hosted transcription" });
       const url = options.publicAssetUrl === undefined
         ? await client.upload(request.audio, context.resources, auth)
         : await options.publicAssetUrl(request.audio, context.resources);
+      await context.reportProgress?.({ phase: "Transcribing and aligning words" });
       const response = await client.transcribe({
         model: transcriptionModel,
         url,
@@ -524,6 +535,7 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
       const evidence = sealAlignedTranscriptEvidence({
         passages: interpretWhisperXTranscript(response as WhisperXTranscriptResponse, request.sampleFrames),
       });
+      await context.reportProgress?.({ phase: "Word timing ready" });
       return { value: { kind: "inline", value: canonicalize(evidence) } };
     } catch (error) {
       throw new Error(guidedMessage(error), { cause: error });

package/packages/provider-hypihub/src/routes.ts

@@ -117,8 +117,7 @@ function normalizeHypiHubRequest(
       ? (item as Record<string, unknown>).url : item).filter((item): item is string => typeof item === "string" && item.length > 0);
     if (urls.length > 0) input.reference_image_urls = urls;
   }
-  if (Array.isArray(videoRefs) && videoRefs.length === 1) input.ref_video_url = videoRefs[0];
-  else if (Array.isArray(videoRefs) && videoRefs.length > 1) input.reference_videos = videoRefs;
+  if (Array.isArray(videoRefs) && videoRefs.length > 0) input.reference_videos = videoRefs;
   if (Array.isArray(audioRefs) && audioRefs.length > 0) input.reference_audios = audioRefs;
   return { model: request.model, input: canonicalize(input) };
 }

package/packages/provider-hypihub/src/upload.ts

@@ -70,6 +70,7 @@ export type HypiHubUploadInput = {
   readonly mediaType: string;
   readonly filename?: string;
   readonly purpose?: string;
+  readonly isPersonReference?: boolean;
 };
 
 type PartDeclaration = {
@@ -385,6 +386,7 @@ export class HypiHubUploader {
           bytes: input.bytes.byteLength,
           mime_type: input.mediaType,
           purpose: input.purpose ?? "reference",
+          ...(input.isPersonReference === undefined ? {} : { is_person_reference: input.isPersonReference }),
           sha256: digest,
           head_base64: Buffer.from(input.bytes.subarray(0, 512)).toString("base64"),
         }),

package/packages/provider-media-local/README.md

@@ -37,7 +37,7 @@ These are this FFmpeg implementation's intermediate encodings; Source and Track
 to use ordinary SynchronizedMedia. Transform currently emits opaque MP4, so perform trim/retime
 before matting when the resulting clip needs transparency.
 
-The result is ordinary SynchronizedMedia. Speech Track and Media Track consume its transparent
+The result is ordinary SynchronizedMedia. Timeline assembly and Media Track consume its transparent
 picture through their existing visual outputs; choosing the A-roll or B-roll role belongs to the
 Source. Local HyperFrames extracts alpha-preserving PNGs and composites them against the authored
 Canvas and lower visual layers before encoding the final MP4.
@@ -53,6 +53,5 @@ programme-audio rendering and final muxing remain Build-only. This is declared p
 Runtime and Studio contain no media capability allowlist.
 
 Video-backed normalization is video-authoritative so an AAC packet tail cannot extend the program
-past its final picture. Audio-only normalization is audio-authoritative. The AWS Lambda media Provider
-must return the same public contracts and timing laws; Lambda is an execution topology, not another
-author meaning.
+past its final picture. Audio-only normalization is audio-authoritative. Other implementations of these capabilities must preserve the same public values and timing laws;
+a different execution topology leaves author meaning unchanged.

package/packages/provider-whisperx-local/README.md

@@ -30,6 +30,41 @@ Provider; it is a different deployment package but must return the same
 The configured model, device, compute mode and batch size are checked through `/health` before use.
 This prevents a warm process with an incompatible inference configuration from accepting work.
 
+## Choose model and hardware
+
+The default `small` / `cpu` / `int8` is a modest-machine execution default, not a quality ranking.
+For multilingual transcription with quality as the priority and suitable hardware, consider
+`large-v3`. For example, an NVIDIA CUDA installation with sufficient memory can explicitly select:
+
+```json
+"whisperx.local": {
+  "use": "@hypit/provider-whisperx-local",
+  "config": {
+    "expectedModel": "large-v3",
+    "expectedDevice": "cuda",
+    "expectedCompute": "float16",
+    "expectedBatchSize": 4
+  }
+}
+```
+
+This is an example deployment, not a promise that every GPU has enough memory. Adjust batch size
+and compute mode for the actual device. On CPU, `int8` is the practical starting point; a larger
+model still takes more preparation and inference work. The packaged faster-whisper backend uses
+CTranslate2: Apple Silicon does not imply CUDA or support for a PyTorch `mps` setting here.
+An already ready smaller model can be useful for a short clear reference. Choose the local model
+or hosted service for the actual language, material and time available rather than installing
+successively larger models as a routine sequence.
+
+`expectedModel` selects speech recognition. WhisperX separately loads the language-specific
+alignment model when that language is first requested. A larger ASR model can improve the words
+fed into alignment, but does not select a larger aligner or guarantee better timing by itself.
+The health response identifies the loaded ASR configuration; it does not establish that every
+language's alignment weights are cached. See [WhisperX usage](https://github.com/m-bain/whisperX#usage-)
+and [faster-whisper deployment](https://github.com/SYSTRAN/faster-whisper#usage).
+
+## Preparation and downloads
+
 The Runtime installs and starts the packaged service in the machine Program Home when this Endpoint
 is selected. The environment is reused across projects and sessions. The current local package and
 service are trusted code; this is not a community-plugin sandbox.
@@ -42,3 +77,25 @@ its configuration through `/health`. Inspect an existing Profile's address and e
 when locating that service. A custom `serviceCommand` supplies its own installation and start command.
 `hypit programs status` checks the Programs selected by the supplied Profile; `programs up` prepares
 and starts them. The managed installation does not require a global `whisperx` shell command.
+
+Preparation and service processes inherit the environment of the command starting them. Set
+network and cache variables there before `programs up` or `runtime up`. A service already running
+retains its earlier environment. Inspect its reported log before deciding whether a selected
+Program needs restarting, and account for active work using it.
+
+Preparation commands write `install.log`; the running service writes `program.log`, with stderr in
+`program.err.log` on Windows. Inspect the stderr file for Python model-loading and download messages.
+The service health endpoint becomes available after ASR loading. A startup readiness wait expiring
+can leave that process still loading; check its reported PID and logs before starting another process.
+
+Python installation, Python packages, NLTK sentence data, ASR weights and language-alignment weights
+are separate downloads. `UV_PYTHON_INSTALL_MIRROR` configures a Python distribution mirror;
+`HF_ENDPOINT` and `HF_HOME` configure Hugging Face access/cache. Alignment models can also come
+from torchaudio's download hosts. These settings do not redirect NLTK's own downloader.
+
+Managed installation uses `uv sync --frozen` with the distributed lockfile, including its artifact
+URLs. `PIP_INDEX_URL` does not configure uv, and `UV_DEFAULT_INDEX` is an index-resolution setting,
+not a general rewrite of those frozen URLs. Inspect the actual transfer destination. For blocked
+locked downloads, use an appropriate network/proxy route or an already populated compatible cache;
+an operator-managed installation can instead provide `serviceCommand` with the expected service
+identity. Ordinary production keeps the distributed dependency selection intact.

package/packages/provider-whisperx-local/src/program.ts

@@ -124,6 +124,7 @@ export function localWhisperXProgram(options: LocalWhisperXProgramOptions): Mana
       stateRoot,
       installation: {
         probe: installationProbe,
+        prepareBeforeStart: true,
         commands: [{
           command: "uv",
           args: ["sync", "--project", localWhisperXManagedProject, "--frozen", "--no-editable"],

package/packages/provider-whisperx-local/src/provider.ts

@@ -141,6 +141,7 @@ export function createLocalWhisperXProvider(config: CreateLocalWhisperXProviderO
           const audioPath = join(work, "alignment-evidence.wav");
           await writeFile(audioPath, audio);
           const signal = AbortSignal.timeout(requestTimeoutMs);
+          await context.reportProgress?.({ phase: "Checking local transcription service" });
           const healthResponse = await fetch(`${normalizedBaseUrl}/health`, { signal });
           const health = await limitedJson(healthResponse, Math.min(maxResponseBytes, 64 * 1024), "WhisperX health");
           assert(health.value !== null && typeof health.value === "object" && !Array.isArray(health.value),
@@ -164,6 +165,7 @@ export function createLocalWhisperXProvider(config: CreateLocalWhisperXProviderO
             && healthValue.compute === expectedCompute
             && healthValue.batchSize === expectedBatchSize,
           "WhisperX service runtime identity differs from the configured Provider");
+          await context.reportProgress?.({ phase: "Transcribing and aligning words" });
           const transcriptionResponse = await fetch(`${normalizedBaseUrl}/transcribe`, {
             method: "POST",
             headers: { "content-type": "application/json" },
@@ -181,6 +183,7 @@ export function createLocalWhisperXProvider(config: CreateLocalWhisperXProviderO
           const evidence: AlignedTranscriptEvidence = sealAlignedTranscriptEvidence({
             passages,
           });
+          await context.reportProgress?.({ phase: "Word timing ready" });
           return result(canonicalize(evidence));
         } finally {
           await rm(work, { recursive: true, force: true }).catch(() => {});