@hypit/hypit 0.0.1 → 0.1.1

package/packages/visual-ir/src/style.ts

@@ -0,0 +1,222 @@
+/** Structural style vocabulary. Renderer programs own their richer layout and code formats. */
+export const VISUAL_IR_V1 = "hypit.visual-ir@1" as const;
+
+/**
+ * Closed CSS-shaped vocabulary for public visual Visual IR v1.
+ *
+ * Values remain serialized declarations because the target is browser based,
+ * but components cannot silently extend the language by inventing another CSS
+ * property. New semantics require a versioned IR revision; unusual visuals use
+ * CompositableSurface instead.
+ */
+export const VISUAL_STYLE_NAMES_V1 = [
+  "-webkit-background-clip",
+  "-webkit-box-decoration-break",
+  "-webkit-box-orient",
+  "-webkit-line-clamp",
+  "-webkit-text-fill-color",
+  "-webkit-text-stroke",
+  "-webkit-text-stroke-color",
+  "-webkit-text-stroke-width",
+  "align-content",
+  "align-items",
+  "align-self",
+  "aspect-ratio",
+  "background",
+  "backdrop-filter",
+  "mix-blend-mode",
+  "isolation",
+  "background-clip",
+  "background-color",
+  "background-image",
+  "background-position",
+  "background-repeat",
+  "background-size",
+  "border",
+  "border-bottom",
+  "border-bottom-color",
+  "border-bottom-left-radius",
+  "border-bottom-right-radius",
+  "border-bottom-style",
+  "border-bottom-width",
+  "border-color",
+  "border-left",
+  "border-left-color",
+  "border-left-style",
+  "border-left-width",
+  "border-radius",
+  "border-right",
+  "border-right-color",
+  "border-right-style",
+  "border-right-width",
+  "border-style",
+  "border-top",
+  "border-top-color",
+  "border-top-left-radius",
+  "border-top-right-radius",
+  "border-top-style",
+  "border-top-width",
+  "border-width",
+  "bottom",
+  "box-decoration-break",
+  "box-shadow",
+  "box-sizing",
+  "clip-path",
+  "color",
+  "column-gap",
+  "column-count",
+  "direction",
+  "display",
+  "filter",
+  "flex",
+  "flex-basis",
+  "flex-direction",
+  "flex-grow",
+  "flex-shrink",
+  "flex-wrap",
+  "font-family",
+  "font-feature-settings",
+  "font-kerning",
+  "font-size",
+  "font-style",
+  "font-synthesis",
+  "font-variant-caps",
+  "font-variation-settings",
+  "font-weight",
+  "gap",
+  "grid-area",
+  "grid-template-columns",
+  "grid-template-rows",
+  "height",
+  "inset",
+  "justify-content",
+  "justify-items",
+  "justify-self",
+  "left",
+  "letter-spacing",
+  "line-height",
+  "margin",
+  "margin-bottom",
+  "margin-left",
+  "margin-right",
+  "margin-top",
+  "max-height",
+  "max-width",
+  "min-height",
+  "min-width",
+  "object-fit",
+  "object-position",
+  "opacity",
+  "outline",
+  "outline-color",
+  "outline-style",
+  "outline-width",
+  "overflow",
+  "overflow-wrap",
+  "overflow-x",
+  "overflow-y",
+  "padding",
+  "padding-bottom",
+  "padding-left",
+  "padding-right",
+  "padding-top",
+  "paint-order",
+  "perspective",
+  "perspective-origin",
+  "position",
+  "right",
+  "row-gap",
+  "text-align",
+  "text-decoration",
+  "text-decoration-color",
+  "text-decoration-line",
+  "text-decoration-skip-ink",
+  "text-decoration-style",
+  "text-decoration-thickness",
+  "text-overflow",
+  "text-indent",
+  "text-orientation",
+  "text-spacing-trim",
+  "text-shadow",
+  "text-transform",
+  "text-underline-offset",
+  "top",
+  "tab-size",
+  "transform",
+  "transform-origin",
+  "transform-style",
+  "vertical-align",
+  "visibility",
+  "white-space",
+  "width",
+  "word-break",
+  "word-spacing",
+  "writing-mode",
+] as const;
+
+export type VisualStyleNameV1 = typeof VISUAL_STYLE_NAMES_V1[number];
+
+const STYLE_NAMES = new Set<string>(VISUAL_STYLE_NAMES_V1);
+
+export const VISUAL_STYLE_ENUM_VALUES_V1 = {
+  "box-sizing": ["border-box", "content-box"],
+  direction: ["ltr", "rtl"],
+  display: ["block", "inline", "inline-block", "flex", "inline-flex", "grid", "inline-grid", "-webkit-box", "none"],
+  "flex-direction": ["row", "row-reverse", "column", "column-reverse"],
+  "flex-wrap": ["nowrap", "wrap", "wrap-reverse"],
+  "object-fit": ["contain", "cover", "fill", "none", "scale-down"],
+  overflow: ["visible", "hidden", "clip"],
+  "overflow-x": ["visible", "hidden", "clip"],
+  "overflow-y": ["visible", "hidden", "clip"],
+  position: ["absolute", "relative"],
+  "text-align": ["left", "right", "center", "start", "end", "justify"],
+  "text-transform": ["none", "capitalize", "uppercase", "lowercase"],
+  visibility: ["visible", "hidden"],
+  "white-space": ["normal", "nowrap", "pre", "pre-wrap", "pre-line", "break-spaces"],
+  "writing-mode": ["horizontal-tb", "vertical-rl", "vertical-lr"],
+} as const satisfies Partial<Record<VisualStyleNameV1, readonly string[]>>;
+
+const ENUM_VALUES = new Map<string, ReadonlySet<string>>(
+  Object.entries(VISUAL_STYLE_ENUM_VALUES_V1)
+    .map(([name, values]) => [name, new Set<string>(values)]),
+);
+
+export function assertVisualStyleV1(
+  name: string,
+  value: string | number,
+  label: string,
+): void {
+  if (!/^-?[a-z][a-z0-9-]*$/u.test(name)) {
+    throw new Error(`${label} contains invalid style name ${name}.`);
+  }
+  if (!STYLE_NAMES.has(name)) {
+    throw new Error(`${label} style ${name} is outside ${VISUAL_IR_V1}.`);
+  }
+  const values = ENUM_VALUES.get(name);
+  if (values !== undefined) {
+    if (typeof value !== "string" || !values.has(value)) {
+      throw new Error(`${label} style ${name} has unsupported value ${String(value)}.`);
+    }
+    return;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`${label} contains a non-finite style value.`);
+    return;
+  }
+  if (value.length === 0) throw new Error(`${label} contains an empty style value.`);
+  if (/url\s*\(/iu.test(value)) {
+    throw new Error(`${label} must use typed Artifact references instead of CSS url().`);
+  }
+  if (/(?:-webkit-)?image-set\s*\(/iu.test(value)) {
+    throw new Error(`${label} must use typed Artifact references instead of CSS image-set().`);
+  }
+  if (/[;{}]/u.test(value)) {
+    throw new Error(`${label} contains a style value that escapes its declaration.`);
+  }
+  if (/!important|[\u0000-\u001f\u007f]/iu.test(value)) {
+    throw new Error(`${label} contains an unsafe style value.`);
+  }
+  if (/(?:var|env|attr)\s*\(/iu.test(value)) {
+    throw new Error(`${label} contains an environment-dependent style value.`);
+  }
+}

package/packages/volcengine-matting/README.md

@@ -0,0 +1,89 @@
+# `@hypit/volcengine-matting`
+
+Remove the background of a moving portrait when the composition needs the person's silhouette
+over another picture. The source video determines the performance, duration and dimensions.
+
+```svml
+<import as="matte" from="@hypit/volcengine-matting@1"/>
+<matte:Portrait id="cutout" source={performance.video}/>
+```
+
+`source` is a video Blob from a file declaration, generation or another media operation.
+`cutout.video` is the processed video Blob. `format="WEBM"` is the default; `format="MOV"`
+selects a transparent QuickTime output. This interface exposes the model's two transparent
+formats. The service's flat-background MP4 option is a different output treatment.
+
+## Prepare the processed clip for its role
+
+```svml
+<import as="program" from="@hypit/program-space@1"/>
+<import as="pipeline" from="@hypit/media-pipeline@1"/>
+<import as="whisperx" from="@hypit/whisperx@1"/>
+
+<program:Clock id="clock" frame-rate="30"/>
+<pipeline:Normalize id="cutout-media" source={cutout.video} clock={clock}
+  video="primary-moving" audio="default" span-authority="video"/>
+<whisperx:SemanticTake id="opening-semantic" narrative={story}
+  segment={story.segment.opening} media={cutout-media.media} language="en"/>
+```
+
+This excerpt assumes the performance and Script exist. Normalize keeps the transparent picture
+and prepares the selected embedded audio on the program clock. WhisperX and semantic alignment
+associate that prepared performance with the Script. Use `opening-semantic.take` in
+[Speech Track](../speech-track/README.md); its screen position and stack order are independent
+of its role as A-roll.
+
+For B-roll, normalize `cutout.video` with `audio="none"` when its sound is unwanted, then use
+`cutout-media.media` in [Media Track](../media-track/README.md). No SemanticTake is needed for
+that overlay. Existing transparency can enter Normalize directly.
+
+For example, this alternative uses the existing program's SemanticTrack and an authored Selection:
+
+```svml
+<import as="media-track" from="@hypit/media-track@1"/>
+<pipeline:Normalize id="overlay-media" source={cutout.video} clock={clock}
+  video="primary-moving" audio="none" span-authority="video"/>
+<media-track:Track id="overlay" semantic={speech.semantic} canvas={canvas}>
+  <media-track:Item media={overlay-media.media} during={story.selection.example}
+    frame={overlay-frame} appearance={look.media.overlay}/>
+</media-track:Track>
+```
+
+The Frame, Recipe and Selection belong to the composition. Add `overlay.visual` to Film and set
+its stacking order in the Recipe. The performance underneath continues to supply semantic time.
+
+The same processed clip can serve either role; matting does not choose its Track or timeline.
+The local media Provider's Transform currently emits opaque MP4. When a clip also needs trimming
+or retiming, apply that operation before matting, then normalize the cutout for its intended role.
+
+Review motion, hair, hands, translucent edges and the selected speech against the intended
+background. Reuse `cutout.video` or the prepared Output through the Run when changing placement,
+captions or graphics.
+
+## Model and Provider
+
+The capability is `@hypit/volcengine-matting@1#matte-portrait-video`, returning a GeneratedVideoSet.
+The Portrait Surface publishes its first video as `.video`. Its model ports are `source`
+(one video) and optional `format` (`WEBM` or `MOV`). It takes no generation prompt or duration.
+
+[HypiHub Provider](../provider-hypihub/README.md) maps it to `POST /v1/videos` with
+`model: "matte-portrait-video"`, `ref_video_url` and `format`. Account availability and credentials
+belong to the selected Runtime Endpoint. Submission, job polling, collection and Result storage
+use that Provider's existing video operation.
+
+To select this route explicitly in a Runtime Profile, bind the capability to an existing
+HypiHub Endpoint:
+
+```json
+{
+  "bindings": {
+    "@hypit/volcengine-matting@1#matte-portrait-video": "hypihub.default"
+  }
+}
+```
+
+Here `hypihub.default` is the Endpoint ID from that profile. The Model describes the operation;
+the Provider translates it to the service; the Endpoint supplies the account and execution settings.
+No source duration or resolution needs to be copied into the Source or Runtime Profile.
+
+The input and output formats follow [Volcengine's portrait-matting reference](https://github.com/volcengine/mediakit-cli/blob/main/skills/byted-mediakit-video/reference/matte-portrait-video.md).

package/packages/volcengine-matting/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@hypit/volcengine-matting",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": { ".": "./src/index.ts" },
+  "hypit": { "activation": "./src/activation.ts" },
+  "dependencies": {
+    "@hypit/artifact": "workspace:*",
+    "@hypit/generation": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/model-kit": "workspace:*",
+    "@hypit/protocol": "workspace:*"
+  }
+}

package/packages/volcengine-matting/src/activation.ts

@@ -0,0 +1,13 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import { portraitMattingSurface, volcengineMattingDefinition, volcengineMattingModuleRef } from "./index.js";
+import { decodePortraitMattingSurface } from "./surface.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: volcengineMattingDefinition.manifest }],
+  components: [volcengineMattingDefinition.component],
+  hostFacets: [volcengineMattingDefinition.hostFacet, createMarkupSurfaceHostFacet({
+    module: volcengineMattingModuleRef, declaration: portraitMattingSurface, handler: decodePortraitMattingSurface,
+  })],
+};
+export default hypitPackage;

package/packages/volcengine-matting/src/index.ts

@@ -0,0 +1,45 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortValue } from "@hypit/generation";
+import { defineExactModelModule } from "@hypit/model-kit";
+
+export const volcengineMattingModuleRef = { name: "@hypit/volcengine-matting", version: "1" } as const;
+
+export const portraitMattingPorts = sealGenerationPortTable({
+  model: "matte-portrait-video",
+  result: "video",
+  ports: [
+    { name: "source", value: { kind: "media", accepts: ["video"] }, minItems: 1, maxItems: 1 },
+    { name: "format", value: { kind: "enum", values: ["WEBM", "MOV"] }, minItems: 0, maxItems: 1 },
+  ],
+  requires: [],
+});
+
+export function sealPortraitMattingRequest(ports: Readonly<Record<string, readonly GenerationPortValue[]>>) {
+  return sealGenerationPortRequest(portraitMattingPorts, ports);
+}
+
+export const volcengineMattingDefinition = defineExactModelModule({
+  module: volcengineMattingModuleRef,
+  endpoints: [{ key: "portrait", requestTypeName: "PortraitMattingRequest",
+    producerName: "request-portrait-matting", ports: portraitMattingPorts }],
+});
+export const portraitMattingEndpoint = volcengineMattingDefinition.endpoints.portrait!;
+
+export const portraitMattingSurface = {
+  name: "portrait", tag: "Portrait", mode: "structured" as const,
+  outputs: [portraitMattingEndpoint.draftType, portraitMattingEndpoint.mediaBindings.source!.type],
+  vocabulary: {
+    summary: "Removes a video's background with Volcengine portrait matting and returns transparent video.",
+    attributes: [
+      { name: "id", kind: "identifier" as const, required: true, summary: "Names the processed video." },
+      { name: "source", kind: "reference" as const, required: true, accepts: [artifactTypes.blob],
+        summary: "The source video Artifact whose people remain visible." },
+      { name: "format", kind: "literal" as const, required: false, values: ["WEBM", "MOV"],
+        summary: "Transparent output container; defaults to WEBM." },
+    ],
+    ports: [{ name: "video", type: artifactTypes.blob, summary: "The processed video Artifact, before normalization." }],
+    example: '<matte:Portrait id="cutout" source={performance.video}/>',
+    notes: ["The source determines duration and dimensions. Normalize the output before using it in a track."],
+  },
+};

package/packages/volcengine-matting/src/surface.ts

@@ -0,0 +1,48 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationMediaBinding, sealGenerationRequestDraft } from "@hypit/generation";
+import type { GenerationMediaPort } from "@hypit/generation";
+import type { StructuredSurfaceHandler } from "@hypit/markup";
+import { createExactModelPrimaryGenerationFragment, exactModelMediaInputNames } from "@hypit/model-kit";
+import { canonicalize } from "@hypit/protocol";
+import { portraitMattingEndpoint as endpoint } from "./index.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+export const decodePortraitMattingSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  const { id, source, format } = element.attributes;
+  for (const name of Object.keys(element.attributes)) {
+    assert(["id", "source", "format"].includes(name), `${element.name} does not accept ${name}`);
+  }
+  assert(typeof id === "string" && id.trim().length > 0, `${element.name} requires id`);
+  assert(!element.children.some((item) => item.kind === "element" || item.value.trim()), `${element.name} must be empty`);
+  assert(typeof source === "object" && source.kind === "reference", `${element.name}.source must be a video reference`);
+  const resolved = resolveReference(source.path);
+  assert(resolved !== undefined && resolved.type.name === artifactTypes.blob.name
+    && resolved.type.module.name === artifactTypes.blob.module.name
+    && resolved.type.module.version === artifactTypes.blob.module.version, `${element.name}.source must be a Blob`);
+  if (resolved.record !== undefined) {
+    assert(resolved.record.value.kind === "blob" && resolved.record.value.mediaType.startsWith("video/"),
+      `${element.name}.source must be video media`);
+  }
+  assert(format === undefined || typeof format === "string", `${element.name}.format must be literal`);
+  const draft = sealGenerationRequestDraft(endpoint.ports, { format: [format ?? "WEBM"] });
+  const binding = sealGenerationMediaBinding(endpoint.ports.ports.find((port) => port.name === "source")! as GenerationMediaPort,
+    { role: "video" });
+  const names = exactModelMediaInputNames("source");
+  const fragment = createExactModelPrimaryGenerationFragment(endpoint, [{ name: "source", port: "source" }], []);
+  return {
+    records: [
+      { id: `${id}.draft`, type: endpoint.draftType, value: { kind: "inline", value: canonicalize(draft) }, range: element.range },
+      { id: `${id}.source-binding`, type: endpoint.mediaBindings.source!.type,
+        value: { kind: "inline", value: canonicalize(binding) }, range: element.range },
+    ],
+    fragments: [fragment],
+    components: [{ id, fragment: fragment.id, inputs: {
+      draft: { kind: "record", id: `${id}.draft` },
+      [names.binding]: { kind: "record", id: `${id}.source-binding` },
+      [names.artifact]: resolved.ref,
+    }, outputs: { video: `${id}.video` }, range: element.range }],
+  };
+};

package/packages/whisperx/README.md

@@ -0,0 +1,34 @@
+# @hypit/whisperx
+
+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.
+
+The package contains no credentials, Python environment or queue. Providers translate the typed
+request directly into provider-neutral `AlignedTranscriptEvidence`. There is no vendor-shaped
+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
+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
+emits one self-contained `SemanticTake`.
+
+When the authored Segment has no Tokens, write the same Surface without `language`. Its start and
+end Anchors map directly to the prepared media's first and final frame. There are no words to align,
+so this branch requests no evidence audio and no WhisperX capability:
+
+```svml
+<whisperx:SemanticTake id="pause" narrative={story}
+  segment={story.segment.pause} media={pause-media.media}/>
+```
+
+There is no whole-program WhisperX pass. Speech Track only receives already-semantic Takes and later
+translates their local frames when assembling the final ProgramSpace and complete semantic map.
+
+`@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.

package/packages/whisperx/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hypit/whisperx",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/media-pipeline": "workspace:*",
+    "@hypit/media": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/speech": "workspace:*",
+    "@hypit/speech-alignment": "workspace:*",
+    "@hypit/speech-evidence": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/program-space": "workspace:*"
+  }
+}

package/packages/whisperx/src/activation.ts

@@ -0,0 +1,18 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import {
+  decodeWhisperXSemanticTakeSurface, whisperXComponent,
+  whisperXManifest, whisperXModuleRef,
+  whisperXMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: whisperXManifest }],
+  components: [whisperXComponent],
+  hostFacets: [createMarkupSurfaceHostFacet({
+    module: whisperXModuleRef,
+    declaration: whisperXMarkupSurfaces.find((item) => item.name === "semantic-take")!,
+    handler: decodeWhisperXSemanticTakeSurface,
+  })],
+};
+export default hypitPackage;

package/packages/whisperx/src/component.ts

@@ -0,0 +1,64 @@
+import { plannedNeedInputs } from "@hypit/component-kit";
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { SpeechEvidenceAudio } from "@hypit/speech";
+import type { CanonicalValue, StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+
+import { whisperXRequestForEvidenceAudio } from "./evidence.js";
+import { whisperXCapabilities, whisperXProducers } from "./manifest.js";
+import type { WhisperXLanguage } from "./types.js";
+
+function inline(value: StoredValue, subject: string): CanonicalValue {
+  if (value.kind !== "inline") throw new Error(`${subject} must be inline`);
+  return value.value;
+}
+
+export const whisperXComponent = {
+  producers: [
+    {
+      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");
+        }
+        return {
+          outputs: {},
+          needs: { alignment: canonicalize(whisperXRequestForEvidenceAudio(evidence, { language })) },
+        };
+      },
+    },
+  ],
+  plannedNeeds: [{
+    producer: whisperXProducers.request,
+    port: "alignment",
+    capability: whisperXCapabilities.alignment,
+    plan({ state, step }) {
+      const operation = state.plan.steps.find((item) => item.id === step);
+      const languageRecord = operation?.inputs.language;
+      const language = languageRecord === undefined
+        ? undefined
+        : state.records.find((record) => record.id === languageRecord)?.value;
+      if (language?.kind !== "inline" || typeof language.value !== "string") return undefined;
+      return {
+        constraints: { language: language.value },
+        pendingInputs: plannedNeedInputs(state, step, { evidence: "audio" }),
+      };
+    },
+    present(specification) {
+      const fields = specification.constraints !== null
+        && typeof specification.constraints === "object"
+        && !Array.isArray(specification.constraints)
+        ? specification.constraints as Readonly<Record<string, CanonicalValue>>
+        : {};
+      const language = typeof fields.language === "string" ? fields.language : undefined;
+      return {
+        fields: language === undefined ? {} : { language: [language] },
+        references: {
+          audio: specification.pendingInputs.filter((input) => input.role === "audio").length,
+        },
+      };
+    },
+  }],
+} satisfies ComponentPackage;

package/packages/whisperx/src/evidence.ts

@@ -0,0 +1,69 @@
+import { assertSpeechEvidenceAudioIdentity } from "@hypit/speech";
+import type { SpeechEvidenceAudio } from "@hypit/speech";
+import type { WhisperXAlignmentRequest, WhisperXLanguage } from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+/** Verify the Provider-neutral request carried by the WhisperX alignment capability. */
+export function verifyWhisperXAlignmentRequest(value: unknown): WhisperXAlignmentRequest {
+  assert(value !== null && typeof value === "object" && !Array.isArray(value),
+    "WhisperX alignment request must be an object");
+  const request = value as WhisperXAlignmentRequest;
+  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"),
+  "WhisperX alignment request is invalid");
+  return request;
+}
+
+function fourCc(bytes: Uint8Array, offset: number): string {
+  return String.fromCharCode(...bytes.subarray(offset, offset + 4));
+}
+
+/** Refuse evidence bytes that would require a Provider to normalize audio a second time. */
+export function assertWhisperXEvidenceWav(bytes: Uint8Array, sampleFrames: number): void {
+  assert(bytes.byteLength >= 44 && fourCc(bytes, 0) === "RIFF" && fourCc(bytes, 8) === "WAVE",
+    "WhisperX evidence Artifact is not a WAV file");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let offset = 12;
+  let format: { readonly codec: number; readonly channels: number; readonly sampleRate: number; readonly bits: number }
+    | undefined;
+  let dataBytes: number | undefined;
+  while (offset + 8 <= bytes.byteLength) {
+    const name = fourCc(bytes, offset);
+    const size = view.getUint32(offset + 4, true);
+    const body = offset + 8;
+    assert(body + size <= bytes.byteLength, "WhisperX evidence WAV has a truncated chunk");
+    if (name === "fmt ") {
+      assert(size >= 16, "WhisperX evidence WAV fmt chunk is invalid");
+      format = {
+        codec: view.getUint16(body, true),
+        channels: view.getUint16(body + 2, true),
+        sampleRate: view.getUint32(body + 4, true),
+        bits: view.getUint16(body + 14, true),
+      };
+    } else if (name === "data") {
+      dataBytes = size;
+    }
+    offset = body + size + (size % 2);
+  }
+  assert(format?.codec === 1 && format.channels === 1 && format.sampleRate === 16_000 && format.bits === 16,
+    "WhisperX evidence must be 16 kHz mono PCM s16 WAV");
+  assert(dataBytes === sampleFrames * 2, "WhisperX evidence sample count differs from its contract");
+}
+
+export function whisperXRequestForEvidenceAudio(
+  evidence: SpeechEvidenceAudio,
+  options: { readonly language: WhisperXLanguage },
+): WhisperXAlignmentRequest {
+  assertSpeechEvidenceAudioIdentity(evidence);
+  return {
+    audio: evidence.artifact,
+    sampleFrames: evidence.sampleFrames,
+    language: options.language,
+  };
+}