@hypit/hypit 0.1.4 → 0.1.5

package/packages/film/src/fragment.ts

@@ -1,4 +1,5 @@
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
+
 import { spatialTypes } from "@hypit/spatial";
 import { compositionTypes } from "@hypit/composition";
 import type { Track } from "@hypit/composition";
@@ -12,7 +13,7 @@ const input = (name: string) => ({ kind: "fragment-input" as const, name });
 const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
 
 function assertTrackInputs(tracks: readonly FilmTrackInput[]): FilmTrackInput[] {
-  const names = new Set(["program", "canvas", "space"]);
+  const names = new Set(["program", "canvas", "timeline"]);
   return [...tracks]
     .map((track) => ({ name: track.name.trim(), kind: track.kind }))
     .sort((left, right) => left.name.localeCompare(right.name))
@@ -45,7 +46,7 @@ export function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions)
     operations.push({
       id,
       producer: track.kind === "visual" ? filmProducers.appendVisualTrack : filmProducers.appendAudioTrack,
-      inputs: { set: operation(current), space: input("space"), track: input(track.name) },
+      inputs: { set: operation(current), timeline: input("timeline"), track: input(track.name) },
       result: { kind: "output" as const, name: "set" },
     });
     current = id;
@@ -56,7 +57,7 @@ export function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions)
     inputs: {
       program: input("program"),
       canvas: input("canvas"),
-      space: input("space"),
+      timeline: input("timeline"),
       set: operation(current),
     },
     result: { kind: "output" as const, name: "composition" },
@@ -65,7 +66,7 @@ export function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions)
     inputs: [
       { name: "program", type: filmTypes.program },
       { name: "canvas", type: spatialTypes.canvas },
-      { name: "space", type: programSpaceTypes.programSpace },
+      { name: "timeline", type: timelineTypes.track },
       ...tracks.map((track) => ({
         name: track.name,
         type: track.kind === "visual" ? compositionTypes.visualTrack : compositionTypes.audioTrack,

package/packages/film/src/manifest.ts

@@ -1,8 +1,10 @@
+import { timelineTypes } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
 import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
 import { audioTrackSchema, compositionDependency, compositionTypes, visualTrackSchema } from "@hypit/composition";
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+
 import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { semanticTrackDependency } from "@hypit/semantic-track";
+import { timelineDependency } from "@hypit/timeline";
 import { spatialDependency, spatialTypes } from "@hypit/spatial";
 import { svsManifest, svsModuleRef, svsRecipeType } from "@hypit/svs";
 
@@ -47,7 +49,7 @@ export const filmMarkupSurfaces = [{
     outputs: [filmTypes.program],
     vocabulary: {
       summary:
-        "Assembles any number of peer VisualTrack and AudioTrack references into one Composition against a Canvas and a SemanticTrack.",
+        "Assembles any number of peer VisualTrack and AudioTrack references into one Composition against a Canvas and a Timeline.",
       appearance:
         "One flat fill of the entire Canvas, in the single hexadecimal color the Recipe's `background` carries, lying behind everything else in the Frame. It covers the full Canvas width and height, holds that one color from the first Frame to the last, and never moves, fades or changes. Wherever nothing is painted over it, that color is what the Frame shows; the Film puts no mark of its own on top of it.",
       attributes: [
@@ -79,9 +81,9 @@ export const filmMarkupSurfaces = [{
           summary: "The assembled Composition, addressed as `<id>.composition`." },
       ],
       example: [
-        '<film:Film id="main" canvas={vertical} semantic={speech.semantic} appearance={recipes.film.vertical}>',
+        '<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>',
         "  <film:Track source={performance.visual}/>",
-        "  <film:Track source={speech.audio}/>",
+        "  <film:Track source={voice.audio}/>",
         "  <film:Track source={captions.track}/>",
         "</film:Film>",
       ].join("\n"),
@@ -99,8 +101,7 @@ export const filmManifest: ModuleManifest = {
   name: filmModuleRef.name,
   version: filmModuleRef.version,
   dependencies: [
-    programSpaceDependency,
-    semanticTrackDependency,
+    timelineDependency,
     spatialDependency,
     compositionDependency,
     { module: svsModuleRef },
@@ -121,7 +122,7 @@ export const filmManifest: ModuleManifest = {
       name: filmProducers.appendVisualTrack.name,
       inputs: [
         { name: "set", type: filmTypes.trackSet },
-        { name: "space", type: programSpaceTypes.programSpace },
+        { name: "timeline", type: timelineTypes.track },
         { name: "track", type: compositionTypes.visualTrack },
       ],
       outputs: [{ name: "set", type: filmTypes.trackSet }],
@@ -131,7 +132,7 @@ export const filmManifest: ModuleManifest = {
       name: filmProducers.appendAudioTrack.name,
       inputs: [
         { name: "set", type: filmTypes.trackSet },
-        { name: "space", type: programSpaceTypes.programSpace },
+        { name: "timeline", type: timelineTypes.track },
         { name: "track", type: compositionTypes.audioTrack },
       ],
       outputs: [{ name: "set", type: filmTypes.trackSet }],
@@ -142,7 +143,7 @@ export const filmManifest: ModuleManifest = {
       inputs: [
         { name: "program", type: filmTypes.program },
         { name: "canvas", type: spatialTypes.canvas },
-        { name: "space", type: programSpaceTypes.programSpace },
+        { name: "timeline", type: timelineTypes.track },
         { name: "set", type: filmTypes.trackSet },
       ],
       outputs: [{ name: "composition", type: compositionTypes.composition }],

package/packages/film/src/program.ts

@@ -1,5 +1,5 @@
+import type { Timeline } from "@hypit/timeline";
 import { assertProgramSpaceIdentity } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 import { assertCanvasSpace } from "@hypit/spatial";
 import type { CanvasSpace } from "@hypit/spatial";
 import { assertAudioTrackIdentity, assertCompositionIdentity, assertVisualTrackIdentity, sealComposition } from "@hypit/composition";
@@ -64,7 +64,7 @@ export function createFilmTrackSet(): FilmTrackSet {
   });
 }
 
-function appendTrack(set: FilmTrackSet, programSpace: ProgramSpace, track: Track): FilmTrackSet {
+function appendTrack(set: FilmTrackSet, programSpace: Timeline, track: Track): FilmTrackSet {
   assertFilmTrackSetIdentity(set);
   assertProgramSpaceIdentity(programSpace);
   if (track.kind === "visual") assertVisualTrackIdentity(track, programSpace);
@@ -78,18 +78,18 @@ function appendTrack(set: FilmTrackSet, programSpace: ProgramSpace, track: Track
   });
 }
 
-export function appendFilmVisualTrack(set: FilmTrackSet, programSpace: ProgramSpace, track: VisualTrack): FilmTrackSet {
+export function appendFilmVisualTrack(set: FilmTrackSet, programSpace: Timeline, track: VisualTrack): FilmTrackSet {
   return appendTrack(set, programSpace, track);
 }
 
-export function appendFilmAudioTrack(set: FilmTrackSet, programSpace: ProgramSpace, track: AudioTrack): FilmTrackSet {
+export function appendFilmAudioTrack(set: FilmTrackSet, programSpace: Timeline, track: AudioTrack): FilmTrackSet {
   return appendTrack(set, programSpace, track);
 }
 
 export function compileFilmComposition(
   program: FilmProgram,
   canvas: CanvasSpace,
-  programSpace: ProgramSpace,
+  programSpace: Timeline,
   set: FilmTrackSet,
 ): Composition {
   assertFilmProgramIdentity(program);

package/packages/film/src/recipe.ts

@@ -1,7 +1,8 @@
+import type { Timeline } from "@hypit/timeline";
 import type { SvsRecipe } from "@hypit/svs";
 
 /**
- * The Film Recipe owns Film appearance only. Canvas geometry and ProgramSpace
+ * The Film Recipe owns Film appearance only. Canvas geometry and Timeline
  * remain separate graph inputs and cannot be smuggled into a stylesheet.
  */
 

package/packages/film/src/surface.ts

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import { spatialTypes } from "@hypit/spatial";
 import { compositionTypes } from "@hypit/composition";
 import type { AudioTrack, Track, VisualTrack } from "@hypit/composition";
@@ -93,13 +93,13 @@ function trackKind(reference: SurfaceResolvedReference): "visual" | "audio" {
 }
 
 export const decodeFilmSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  exactAttributes(element, ["id", "canvas", element.attributes.space === undefined ? "semantic" : "space", "appearance"]);
+  exactAttributes(element, ["id", "canvas", "timeline", "appearance"]);
   const id = stringAttribute(element, "id");
   const canvas = requiredReference(element, "canvas", resolveReference);
   if (!sameType(canvas.type, spatialTypes.canvas)) {
     throw new Error(`${element.name}.canvas must reference CanvasSpace`);
   }
-  const time = createTemporalSpace({ id, element, ...resolveTemporalContext({ element, resolveReference }) });
+  const context = resolveTemporalContext({ element, resolveReference });
   const appearanceReference = requiredReference(element, "appearance", resolveReference);
   const appearance = filmAppearanceFromRecipe(
     recipe(appearanceReference, `${element.name}.appearance`).properties,
@@ -129,18 +129,18 @@ export const decodeFilmSurface: StructuredSurfaceHandler = ({ element, resolveRe
       value: { kind: "inline", value: program },
       range: element.range,
     }],
-    components: [...time.components, {
+    components: [{
       id,
       fragment: fragment.id,
       inputs: {
         program: { kind: "record", id: programId },
         canvas: canvas.ref,
-        space: time.space.ref,
+        timeline: context.timeline.ref,
         ...Object.fromEntries(tracks.map((track) => [track.name, track.source.ref])),
       },
       outputs: { composition: `${id}.composition` },
       range: element.range,
     }],
-    fragments: [...time.fragments, fragment],
+    fragments: [fragment],
   };
 };

package/packages/film-studio/package.json

@@ -9,7 +9,7 @@
   "dependencies": {
     "@hypit/composition": "workspace:*",
     "@hypit/film": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/studio-adapter": "workspace:*",
     "@hypit/program-space": "workspace:*"
   }

package/packages/film-studio/src/index.ts

@@ -2,13 +2,13 @@ import { programSpaceTypes } from "@hypit/program-space";
 import type { StudioFilmCompanion } from "@hypit/studio-adapter";
 import { compositionTypes } from "@hypit/composition";
 import { filmModuleRef } from "@hypit/film";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 
 /** Film owns the author vocabulary that selects its time source and peer Tracks. */
 export const filmStudioCompanions: readonly StudioFilmCompanion[] = [{
   id: "film",
   match: { module: filmModuleRef, surface: "film", outputType: compositionTypes.composition },
-  timeSources: [{ attribute: "semantic", type: semanticTrackTypes.track }, { attribute: "space", type: programSpaceTypes.programSpace }],
+  timeSources: [{ attribute: "timeline", type: timelineTypes.track }],
   tracks: {
     childSurface: "Track",
     sourceAttribute: "source",

package/packages/fishaudio-speech/README.md

@@ -0,0 +1,33 @@
+# `@hypit/fishaudio-speech`
+
+Exact model contracts and author Surfaces for Fish Audio Voice Design and Voice Clone.
+
+The package owns two distinct speech operations:
+
+- `voice-design-1` creates an ordinary audio voice reference from a natural-language description
+  and a short authored speech sample;
+- `voice-clone` uses one accepted audio voice reference to create independent speech.
+
+It contains no API URL, credential, retry, queue or Fish Audio wire encoding. Those belong to a
+Runtime Endpoint such as `@hypit/provider-hypihub`. Both models return the shared
+`GeneratedAudioSet`; the author Surfaces expose its primary member as an ordinary audio Resource.
+
+```xml
+<import as="fish" from="@hypit/fishaudio-speech@1"/>
+
+<fish:VoiceDesign id="host" speech={story.segment.voiceSample.speech}>
+  A clear young woman with a grounded, confident conversational delivery.
+</fish:VoiceDesign>
+
+<fish:VoiceClone id="narration" speech={story.segment.reveal.speech} voice={host.reference}/>
+```
+
+`host.reference` is not a special identity record. It is a normal audio Resource, so the same
+accepted reference can also feed an A-roll video model that accepts reference audio.
+`VoiceClone` takes spoken text and a voice reference. It has no separate natural-language delivery
+instruction input; the description in `VoiceDesign` establishes the reference voice.
+
+Official API reference: <https://docs.fish.audio/>
+
+The Source import selects author syntax and exact model semantics only. The Runtime Profile
+independently selects the Provider that fulfils either capability.

package/packages/fishaudio-speech/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@hypit/fishaudio-speech",
+  "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/model-kit": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/text": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  }
+}

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

@@ -0,0 +1,32 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeFishAudioVoiceCloneSurface,
+  decodeFishAudioVoiceDesignSurface,
+  fishAudioSpeechComponent,
+  fishAudioSpeechDefinition,
+  fishAudioSpeechManifest,
+  fishAudioSpeechMarkupSurfaces,
+  fishAudioSpeechModuleRef,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: fishAudioSpeechManifest }],
+  components: [fishAudioSpeechComponent],
+  hostFacets: [
+    fishAudioSpeechDefinition.hostFacet,
+    createMarkupSurfaceHostFacet({
+      module: fishAudioSpeechModuleRef,
+      declaration: fishAudioSpeechMarkupSurfaces.find((item) => item.name === "voiceDesign")!,
+      handler: decodeFishAudioVoiceDesignSurface,
+    }),
+    createMarkupSurfaceHostFacet({
+      module: fishAudioSpeechModuleRef,
+      declaration: fishAudioSpeechMarkupSurfaces.find((item) => item.name === "voiceClone")!,
+      handler: decodeFishAudioVoiceCloneSurface,
+    }),
+  ],
+};
+
+export default hypitPackage;

package/packages/fishaudio-speech/src/fragment.ts

@@ -0,0 +1,11 @@
+import { createExactModelPrimaryGenerationFragment } from "@hypit/model-kit";
+import type { ExactModelEndpoint, ExactModelMediaInput, ExactModelTextInput } from "@hypit/model-kit";
+
+/** Model result projection over the same graph-native request assembly as every exact model. */
+export function createFishAudioSpeechAudioFragment(
+  endpoint: ExactModelEndpoint,
+  mediaInputs: readonly ExactModelMediaInput[] = [],
+  textInputs: readonly ExactModelTextInput[] = [],
+) {
+  return createExactModelPrimaryGenerationFragment(endpoint, mediaInputs, textInputs);
+}

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

@@ -0,0 +1,156 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationRequestDraft, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const fishAudioSpeechModuleRef = { name: "@hypit/fishaudio-speech", version: "1" } as const;
+export const fishAudioSpeechModels = [
+  "voice-design-1",
+  "voice-clone",
+] as const;
+export type FishAudioSpeechModel = typeof fishAudioSpeechModels[number];
+
+// Fish Audio documents no fixed character ceiling. Service-side limits stay service-side
+// instead of becoming an invented model constraint in Author Source.
+const spokenText = { kind: "text" } as const;
+const voiceDescription = { kind: "text" } as const;
+
+function table(model: FishAudioSpeechModel): GenerationPortTable {
+  if (model === "voice-design-1") {
+    return sealGenerationPortTable({
+      model,
+      result: "audio",
+      ports: [
+        { name: "text", value: spokenText, minItems: 1, maxItems: 1 },
+        { name: "voiceDescription", value: voiceDescription, minItems: 1, maxItems: 1 },
+      ],
+      requires: [],
+    });
+  }
+  return sealGenerationPortTable({
+    model,
+    result: "audio",
+    ports: [
+      { name: "text", value: spokenText, minItems: 1, maxItems: 1 },
+      { name: "voiceReference", value: { kind: "media", accepts: ["audio"] }, minItems: 1, maxItems: 1 },
+    ],
+    requires: [],
+  });
+}
+
+export const fishAudioSpeechPorts: Readonly<Record<FishAudioSpeechModel, GenerationPortTable>> = {
+  "voice-design-1": table("voice-design-1"),
+  "voice-clone": table("voice-clone"),
+};
+
+export function sealFishAudioSpeechRequest(
+  model: FishAudioSpeechModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(fishAudioSpeechPorts[model], ports);
+}
+
+export function sealFishAudioSpeechRequestDraft(
+  model: FishAudioSpeechModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+) {
+  return sealGenerationRequestDraft(fishAudioSpeechPorts[model], ports);
+}
+
+const base = defineExactModelModule({
+  module: fishAudioSpeechModuleRef,
+  endpoints: ([
+    ["voiceDesign", "voice-design-1", "FishAudioVoiceDesignRequest"],
+    ["voiceClone", "voice-clone", "FishAudioVoiceCloneRequest"],
+  ] as const).map(([key, model, requestTypeName]) => ({
+    key,
+    requestTypeName,
+    producerName: `request-${model}`,
+    ports: fishAudioSpeechPorts[model],
+  })),
+});
+
+export const fishAudioSpeechEndpoints = base.endpoints;
+
+const spokenAttributes: readonly SurfaceAttributeVocabulary[] = [
+  {
+    name: "id",
+    kind: "identifier",
+    required: true,
+    summary: "Names this speech request and prefixes the binding it publishes.",
+  },
+  {
+    name: "speech",
+    kind: "reference",
+    required: true,
+    summary: "The Text edge whose exact words are spoken.",
+    accepts: [textTypes.text],
+  },
+];
+
+const referencePort: readonly SurfacePortVocabulary[] = [{
+  name: "reference",
+  type: artifactTypes.blob,
+  summary: "The designed voice reference, addressed as `<id>.reference`.",
+}];
+
+const audioPort: readonly SurfacePortVocabulary[] = [{
+  name: "audio",
+  type: artifactTypes.blob,
+  summary: "The independent speech, addressed as `<id>.audio`.",
+}];
+
+export const fishAudioSpeechMarkupSurfaces = [
+  {
+    name: "voiceDesign", tag: "VoiceDesign", mode: "structured",
+    outputs: [fishAudioSpeechEndpoints.voiceDesign.draftType],
+    vocabulary: {
+      summary: "Creates a reusable voice reference from a natural-language voice description.",
+      attributes: spokenAttributes,
+      ports: referencePort,
+      text: "The element's own text is the voice description and is required.",
+      example: `<fish:VoiceDesign id="host" speech={story.segment.voiceSample.speech}>
+  A clear young woman with a grounded, confident conversational delivery.
+</fish:VoiceDesign>`,
+      notes: [
+        "The element accepts no child elements; only its text is read.",
+        "The result is an ordinary audio Resource that can be supplied anywhere an audio reference is accepted.",
+      ],
+    },
+  },
+  {
+    name: "voiceClone", tag: "VoiceClone", mode: "structured",
+    outputs: [
+      fishAudioSpeechEndpoints.voiceClone.draftType,
+      ...Object.values(fishAudioSpeechEndpoints.voiceClone.mediaBindings).map((binding) => binding.type),
+    ],
+    vocabulary: {
+      summary: "Creates independent speech in the voice heard in one accepted audio reference.",
+      attributes: [
+        ...spokenAttributes,
+        {
+          name: "voice",
+          kind: "reference",
+          required: true,
+          summary: "The audio Resource carrying the voice identity to reproduce.",
+          accepts: [artifactTypes.blob],
+        },
+      ],
+      ports: audioPort,
+      example: `<fish:VoiceClone id="narration" speech={story.segment.reveal.speech} voice={host.reference}/>`,
+      notes: [
+        "The element takes its spoken words from speech and voice identity from voice; it has no body input.",
+        "The voice reference remains a normal audio Resource rather than a separate identity record.",
+      ],
+    },
+  },
+] as const;
+
+export const fishAudioSpeechManifest = { ...base.manifest } as const;
+export const fishAudioSpeechComponent = base.component;
+export const fishAudioSpeechDefinition = { ...base, manifest: fishAudioSpeechManifest };
+
+export { createFishAudioSpeechAudioFragment } from "./fragment.js";
+export { decodeFishAudioVoiceCloneSurface, decodeFishAudioVoiceDesignSurface } from "./surface.js";