@hypit/hypit 0.1.3 → 0.1.5

package/packages/speech-track/README.md

@@ -1,51 +0,0 @@
-# `@hypit/speech-track`
-
-Assemble ordered SemanticTakes into a semantic timeline and its original sound. The performance
-carrying the Script is the A-roll, whether its picture fills the screen, appears in an inset,
-is a transparent cutout, or is covered by other pictures. This role establishes time; the visual
-composition decides where and how that material appears.
-
-```svml
-<speech:Track id="speech">
-  <speech:Take source={opening.take}/>
-  <speech:Take source={answer.take}/>
-</speech:Track>
-```
-
-The Takes are already normalized and semantic. Source order and actual prepared lengths establish
-the shared ProgramSpace. Local word positions and Segment boundaries become global positions.
-One Take may contain several speakers or camera cuts; a wordless Take supplies its media boundaries.
-
-| Output | Use |
-| --- | --- |
-| `.semantic` | Semantic time and prepared materials for Film, Caption, Media and project components |
-| `.audio` | Original performance sound at its assembled positions |
-
-Select `.audio` in Film when that sound belongs in the result. This explicit convenience projection
-keeps the prepared source at its original speed and gain; a Take without audio contributes no clip.
-For independent music, effects or authored mixing choices, use [Audio Track](../audio-track/README.md).
-
-## Present the performance
-
-[Media Track](../media-track/README.md#display-a-semantic-performance) can consume the assembled
-performance through a Media Performance:
-
-```svml
-<media:Track id="performance" semantic={speech.semantic} canvas={canvas}>
-  <media:Performance during="program" frame={layout.full}
-    appearance={look.performance}/>
-</media:Track>
-```
-
-Include `performance.visual` and `speech.audio` in Film. The Media Recipe supplies `stack-order`,
-fit, clipping, rounded corners, border and other presentation choices. A selected window that starts
-inside a Take begins at the matching source frame. Presentation continues across Take boundaries.
-
-A project component can also consume `.semantic` and use `projectSemanticMedia` from
-`@hypit/hypit/semantic-track` to obtain selected material spans and their source positions. When video and
-graphics share layout or motion, that component can own both in one visual program. Independent
-Caption or other overlays can remain separate Tracks.
-
-[Media Pipeline](../media-pipeline/README.md) owns preparation;
-[Semantic Track](../semantic-track/README.md) owns the timeline and its projections.
-The [Studio Companion](../speech-track-studio/src/index.ts) exposes the original audio clips.

package/packages/speech-track/src/activation.ts

@@ -1,19 +0,0 @@
-import { createMarkupSurfaceHostFacet } from "@hypit/markup";
-import {
-  decodeSpeechTrackSurface, speechTrackComponent, speechTrackManifest,
-  speechTrackModuleRef,
-  speechTrackMarkupSurfaces,
-} from "./index.js";
-
-export const hypitPackage = {
-  format: "hypit.node-package@1" as const,
-  modules: [{
-    manifest: speechTrackManifest,
-  }],
-  components: [speechTrackComponent],
-  hostFacets: [createMarkupSurfaceHostFacet({
-    module: speechTrackModuleRef,
-    declaration: speechTrackMarkupSurfaces.find((item) => item.name === "track")!, handler: decodeSpeechTrackSurface,
-  })],
-};
-export default hypitPackage;

package/packages/speech-track/src/index.ts

@@ -1,7 +0,0 @@
-/** Official Speech Track authoring and deterministic SemanticTrack assembly. */
-export { speechTrackComponent } from "./component.js";
-export { createSpeechTrackFragment } from "./fragment.js";
-export { speechTrackManifest, speechTrackMarkupSurfaces, speechTrackModuleRef, speechTrackProducers, speechTrackTypes, speechTrackHeaderSchema, speechTrackSetSchema } from "./manifest.js";
-export { appendSpeechTrackTake, assembleSpeechTrack, assertSpeechTrackHeader, assertSpeechTrackSet, createSpeechTrackSet, sealSpeechTrackHeader } from "./program.js";
-export { decodeSpeechTrackSurface } from "./surface.js";
-export type * from "./types.js";

package/packages/speech-track/src/manifest.ts

@@ -1,73 +0,0 @@
-import { semanticTakeSchema, speechDependency, speechTypes } from "@hypit/speech";
-import { compositionDependency, compositionTypes } from "@hypit/composition";
-import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
-import type { ModuleManifest, ValueSchema } from "@hypit/protocol";
-export const speechTrackModuleRef = { name: "@hypit/speech-track", version: "1" } as const;
-export const speechTrackTypes = {
-  header: { module: speechTrackModuleRef, name: "SpeechTrackHeader" },
-  trackSet: { module: speechTrackModuleRef, name: "SpeechTrackSet" },
-} as const;
-export const speechTrackProducers = {
-  createSet: { module: speechTrackModuleRef, name: "create-track-set" },
-  appendTake: { module: speechTrackModuleRef, name: "append-track-take" },
-  assembleTrack: { module: speechTrackModuleRef, name: "assemble-semantic-track" },
-} as const;
-export const speechTrackHeaderSchema: ValueSchema = { kind: "object", fields: { id: { schema: { kind: "string", minLength: 1 } } } };
-export const speechTrackSetSchema: ValueSchema = { kind: "object", fields: { takes: { schema: { kind: "array", items: { kind: "object", fields: { semantic: { schema: semanticTakeSchema } } } } } } };
-export const speechTrackMarkupSurfaces = [{
-  name: "track", tag: "Track", mode: "structured",
-  outputs: [speechTrackTypes.header, semanticTrackTypes.track, compositionTypes.audioTrack],
-  vocabulary: {
-    summary: "Assembles ordered SemanticTakes into one semantic timeline and its original performance audio.",
-    attributes: [{ name: "id", kind: "identifier", required: true, summary: "Names the semantic assembly and its outputs." }],
-    children: [{ tag: "Take", cardinality: "many", summary: "A prepared SemanticTake in performance order.",
-      attributes: [{ name: "source", kind: "reference", required: true, accepts: [speechTypes.semanticTake], summary: "The normalized, aligned performance." }] }],
-    ports: [
-      { name: "semantic", type: semanticTrackTypes.track, summary: "The semantic timeline, retaining its prepared material." },
-      { name: "audio", type: compositionTypes.audioTrack, summary: "Original performance audio aligned to that timeline; select it explicitly in Film." },
-    ],
-    example: '<speech:Track id="speech"><speech:Take source={opening.take}/><speech:Take source={answer.take}/></speech:Track>',
-    notes: ["Use Media or a project visual component to present the performance. Those components choose placement and motion independently of semantic assembly."],
-  },
-}] as const;
-export const speechTrackManifest: ModuleManifest = {
-  format: "hypit.module@1",
-  name: speechTrackModuleRef.name,
-  version: speechTrackModuleRef.version,
-  dependencies: [
-    speechDependency,
-    compositionDependency,
-    semanticTrackDependency,
-  ],
-  types: [
-    { name: speechTrackTypes.header.name },
-    { name: speechTrackTypes.trackSet.name },
-  ],
-  capabilities: [],
-  producers: [
-    {
-      name: speechTrackProducers.createSet.name,
-      inputs: [],
-      outputs: [{ name: "set", type: speechTrackTypes.trackSet }],
-      needs: [],
-    },
-    {
-      name: speechTrackProducers.appendTake.name,
-      inputs: [
-        { name: "set", type: speechTrackTypes.trackSet },
-        { name: "take", type: speechTypes.semanticTake },
-      ],
-      outputs: [{ name: "set", type: speechTrackTypes.trackSet }],
-      needs: [],
-    },
-    {
-      name: speechTrackProducers.assembleTrack.name,
-      inputs: [
-        { name: "header", type: speechTrackTypes.header },
-        { name: "set", type: speechTrackTypes.trackSet },
-      ],
-      outputs: [{ name: "track", type: semanticTrackTypes.track }],
-      needs: [],
-    },
-  ],
-};

package/packages/speech-track/src/program.ts

@@ -1,64 +0,0 @@
-import { assertSemanticTakeIdentity } from "@hypit/speech";
-import type { SemanticTake } from "@hypit/speech";
-import { sealSemanticTrack } from "@hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/semantic-track";
-import type { SpeechTrackHeader, SpeechTrackSet, SpeechTrackTake } from "./types.js";
-function assert(condition: unknown, message: string): asserts condition {
-  if (!condition) throw new Error(message);
-}
-export function sealSpeechTrackHeader(value: SpeechTrackHeader): SpeechTrackHeader { return { id: value.id }; }
-export function assertSpeechTrackHeader(value: SpeechTrackHeader): void {
-  assert(value.id.trim().length > 0, "SpeechTrackHeader id must not be empty");
-}
-function sealSpeechTrackSet(value: SpeechTrackSet): SpeechTrackSet { return structuredClone(value); }
-function assertTake(take: SpeechTrackTake): void { assertSemanticTakeIdentity(take.semantic); }
-export function assertSpeechTrackSet(value: SpeechTrackSet): void {
-  const segments = new Set<string>();
-  for (const take of value.takes) {
-    assertSemanticTakeIdentity(take.semantic);
-    const segmentId = take.semantic.segment.segmentId;
-    assert(!segments.has(segmentId), `Speech Track repeats Segment ${segmentId}`);
-    segments.add(segmentId);
-  }
-}
-
-export function createSpeechTrackSet(): SpeechTrackSet {
-  return sealSpeechTrackSet({
-    takes: [],
-  });
-}
-
-function appendTake(
-  set: SpeechTrackSet,
-  take: SpeechTrackTake,
-): SpeechTrackSet {
-  assertSpeechTrackSet(set);
-  assertTake(take);
-  assert(!set.takes.some((item) => item.semantic.segment.segmentId === take.semantic.segment.segmentId),
-    `Speech Track repeats Segment ${take.semantic.segment.segmentId}`);
-  return sealSpeechTrackSet({
-    takes: [...set.takes, take],
-  });
-}
-
-export function appendSpeechTrackTake(set: SpeechTrackSet, semantic: SemanticTake): SpeechTrackSet {
-  return appendTake(set, { semantic });
-}
-
-export function assembleSpeechTrack(
-  header: SpeechTrackHeader,
-  set: SpeechTrackSet,
-): SemanticTrack {
-  assertSpeechTrackHeader(header);
-  assertSpeechTrackSet(set);
-  assert(set.takes.length > 0, "Speech Track must contain at least one Take");
-  for (const take of set.takes) assertTake(take);
-  const narrativeId = set.takes[0]!.semantic.narrativeId;
-  assert(set.takes.every((take) => take.semantic.narrativeId === narrativeId),
-    "Speech Track cannot mix Takes from different Narratives");
-  return sealSemanticTrack({
-    id: header.id,
-    narrativeId,
-    items: set.takes.map((item) => ({ take: item.semantic })),
-  });
-}

package/packages/speech-track/src/surface.ts

@@ -1,35 +0,0 @@
-import { assertAttributes, assertEmptyElement, localName, textAttribute, type StructuredSurfaceHandler } from "@hypit/markup";
-import { sameType } from "@hypit/protocol";
-import { speechTypes } from "@hypit/speech";
-import { createSpeechTrackFragment } from "./fragment.js";
-import { speechTrackTypes } from "./manifest.js";
-
-export const decodeSpeechTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  assertAttributes(element, ["id"]);
-  const id = textAttribute(element, "id");
-  const takes = element.children.flatMap(child => {
-    if (child.kind === "text") {
-      if (child.value.trim()) throw new Error("Speech Track accepts only Take children.");
-      return [];
-    }
-    if (localName(child.name) !== "Take") throw new Error("Speech Track accepts only Take children.");
-    assertAttributes(child, ["source"]);
-    assertEmptyElement(child);
-    const source = child.attributes.source;
-    if (typeof source !== "object" || source.kind !== "reference") throw new Error("Speech Take source must be a reference.");
-    const resolved = resolveReference(source.path);
-    if (resolved === undefined || !sameType(resolved.type, speechTypes.semanticTake)) throw new Error("Speech Take source must be a SemanticTake.");
-    return [resolved];
-  });
-  const inputs = takes.map((_, index) => ({ takeName: `take-${index + 1}` }));
-  const fragment = createSpeechTrackFragment({ takes: inputs });
-  return {
-    records: [{ id: `${id}.header`, type: speechTrackTypes.header, value: { kind: "inline", value: { id } }, range: element.range }],
-    fragments: [fragment],
-    components: [{ id, fragment: fragment.id, inputs: {
-      header: { kind: "record", id: `${id}.header` },
-      ...Object.fromEntries(takes.map((take, index) => [inputs[index]!.takeName, take.ref])),
-    }, outputs: { semantic: `${id}.semantic`, audio: `${id}.audio` }, range: element.range }],
-    exports: [`${id}.semantic`, `${id}.audio`],
-  };
-};

package/packages/speech-track/src/types.ts

@@ -1,6 +0,0 @@
-import type { SemanticTake } from "@hypit/speech";
-export type SpeechTrackHeader = { readonly id: string };
-export type SpeechTrackTake = { readonly semantic: SemanticTake };
-export type SpeechTrackSet = { readonly takes: readonly SpeechTrackTake[] };
-export type SpeechTrackInput = { readonly takeName: string };
-export type SpeechTrackFragmentOptions = { readonly takes: readonly SpeechTrackInput[] };

package/packages/speech-track-studio/README.md

@@ -1,3 +0,0 @@
-# `@hypit/speech-track-studio`
-
-Hypit Studio Companion for the original audio projection of `@hypit/speech-track`.

package/packages/speech-track-studio/package.json

@@ -1,14 +0,0 @@
-{
-  "name": "@hypit/speech-track-studio",
-  "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/speech-track": "workspace:*",
-    "@hypit/composition": "workspace:*",
-    "@hypit/studio-adapter": "workspace:*"
-  }
-}

package/packages/speech-track-studio/src/activation.ts

@@ -1,7 +0,0 @@
-import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";
-import { speechTrackStudioTrackCompanions } from "./index.js";
-
-export default {
-  format: "hypit.node-package@1" as const,
-  hostFacets: [createStudioTrackCompanionHostFacet(speechTrackStudioTrackCompanions)],
-};

package/packages/speech-track-studio/src/index.ts

@@ -1,40 +0,0 @@
-import { speechTrackModuleRef } from "@hypit/speech-track";
-import { compositionTypes } from "@hypit/composition";
-import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
-import { artifactPreview, previewLayer } from "@hypit/studio-adapter";
-type SpeechAudioTrack = {
-  readonly clips?: readonly {
-    readonly id: string;
-    readonly subjectId?: string;
-    readonly artifact?: { readonly resource?: string };
-  }[];
-};
-
-function projectSpeechAudio(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
-  const clips = new Map(((context.track.value as SpeechAudioTrack).clips ?? [])
-    .map((clip) => [clip.id, clip] as const));
-  return context.generic().map((entity) => {
-    const id = entity.presentId ?? entity.authoredId;
-    const clip = clips.get(id);
-    const subjectId = clip?.subjectId;
-    return {
-      ...entity,
-      authoredId: subjectId ?? id,
-      display: {
-        title: subjectId ?? entity.authoredId,
-        layers: clip?.artifact?.resource === undefined ? [] : [previewLayer(artifactPreview("audio", clip.artifact.resource), "waveform")],
-      },
-      presentation: { entity: "audio-clip", chrome: "standard" },
-    };
-  });
-}
-
-export const speechTrackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
-  {
-    id: "audio", role: "track",
-    output: { type: compositionTypes.audioTrack, surface: "track", modules: [speechTrackModuleRef] },
-    family: "speech-audio", tone: "green", label: "Speech Audio", icon: "waveform",
-    bindings: [], inspector: [], project: projectSpeechAudio,
-    lane: { heightPx: 48 },
-  },
-];