@mengine/medeo-tool 1.2.1-alpha.9 → 1.3.1-alpha.8

package/dist/sandbox-api.d.mts

@@ -29,6 +29,18 @@ interface CaptionFontDescriptor {
   readonly system: 'font-library';
   readonly key: string;
 }
+/**
+ * One ordered entry of the Caption's segment selection. `segmentId` quotes the
+ * composed AudioScript's own stable segment identity — a local id quoted by the
+ * variant, never a peer Entity reference. Text itself is never copied here;
+ * complete Caption content is assembled through its direct baseEntityIds.
+ * The optional `textRange` narrows one Segment to an intra-Segment sub-span
+ * (intra-segment re-segmentation); without it the whole Segment text is selected.
+ */
+type CaptionSegmentSelection = JsonObject & {
+  readonly segmentId: string;
+  readonly textRange?: CaptionTextRange;
+};
 interface CaptionStyleFields {
   readonly font?: CaptionFontDescriptor;
   readonly fontSize?: number;
@@ -41,6 +53,23 @@ interface CaptionStyleFields {
   readonly positionX?: number;
   readonly positionY?: number;
 }
+/**
+ * Half-open `[start, end)` position window inside one Segment's text, counted
+ * in Unicode code points (not UTF-16 code units), so a boundary never splits a
+ * surrogate pair. Positions are non-negative safe integers with `start < end`;
+ * `end` must not exceed the Segment's code-point length.
+ */
+interface CaptionTextRange extends JsonObject {
+  readonly start: number;
+  readonly end: number;
+}
+type CaptionTextSelection = JsonObject & {
+  segmentId: string; /** Half-open Unicode code-point range within the selected source segment. */
+  textRange?: {
+    start: number;
+    end: number;
+  };
+};
 type ClipEntityId = EntityId;
 type ClipPlacement = {
   readonly kind: 'sequential';
@@ -53,10 +82,20 @@ type ClipPlacement = {
   readonly hostClipEntityId: string;
   readonly anchorOffset: number;
 };
+interface ComposedPhoneticContent extends ComposedScriptContent {
+  phonemeScript?: string;
+  prosody?: JsonObject;
+}
+/** Read result only: base text is assembled from the real AudioScript row. */
+interface ComposedScriptContent {
+  audio_script_entity_id: string;
+  text: string;
+  segments: ScriptTextSegment[];
+}
 type CreateEntityInput = { [K in KnownEntityKind]: {
   entity_id?: string;
   entity_kind: K;
-  payload: EntityPayloadByKind[K];
+  payload: StoredEntityPayload<K>;
 } }[KnownEntityKind];
 interface DeleteBgmInput {
   readonly timelineEntityId: string;
@@ -74,19 +113,28 @@ interface DeleteEntityInput {
 interface DeleteVoiceoverInput {
   readonly voiceoverClipEntityIds: readonly string[];
 }
-type EmptyRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline';
+type EmptyRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'audio-script-marker';
 interface EntityFacade {
+  /** Read complete assembled fields; returned objects are snapshots. Use update to persist edits. */
   list(): SandboxEntity[];
   get(entityId: string): SandboxEntity | null;
-  /** Return every explicitly imported Asset entity for a Memota asset id. */
-  findByAssetId(assetId: string): SandboxEntity<'asset'>[];
+  /** Find document resources by external Memota asset id, including directly composed media variants. */
+  findByAssetId(assetId: string): SandboxEntity<ResourceEntityKind>[];
+  /** Assemble selected Caption text; missing composition is an error. */
+  readCaptionContent(entityId: string): ComposedScriptContent;
+  /** Assemble base text and pronunciation fields before generating Voice. */
+  readPhoneticScriptContent(entityId: string): ComposedPhoneticContent;
   create(input: CreateEntityInput): string;
-  /** Replace one Entity's owned payload without changing its identity or kind. */
+  /** Patch assembled fields, routing inherited fields to their declaring entity. */
   update(input: UpdateEntityInput): void;
+  /** Explicitly declare own fields, overriding unambiguous bases without modifying them. Ordinary edits use update. */
+  declareFields(input: UpdateEntityInput): void;
   /** Delete an Entity only after all of its incident Relations have been explicitly unlinked. */
   delete(input: DeleteEntityInput): void;
-  /** Import one physical asset without implying a one-to-one media Entity mapping. */
-  importAsset(input: ImportAssetInput): string;
+  /** Get or create one typed Asset by factual external id and return its single content identity. Never creates a Clip. */
+  ensureMedia(fact: MediaAssetFact): {
+    contentEntityId: string;
+  };
 }
 type EntityId = string;
 interface EntityPayloadByKind {
@@ -97,12 +145,12 @@ interface EntityPayloadByKind {
     role?: string;
   };
   clip: JsonObject;
-  /** Asset-owned metadata. Peer media associations belong in physical-asset Relations. */
+  /** Physical resource fields; never a copy of Caption content. */
   asset: JsonObject;
-  video: BoundedNativeSequencePayload;
-  audio: BoundedNativeSequencePayload;
-  voice: BoundedNativeSequencePayload;
-  image: UnboundedConstantSequencePayload;
+  video: BoundedNativeSequencePayload & MediaAssetPayload;
+  audio: BoundedNativeSequencePayload & MediaAssetPayload;
+  voice: BoundedNativeSequencePayload & MediaAssetPayload;
+  image: UnboundedConstantSequencePayload & MediaAssetPayload;
   'sequence-marker': JsonObject & {
     sourceRange: {
       start: number;
@@ -120,19 +168,31 @@ interface EntityPayloadByKind {
     };
     timeRemapping?: JsonValue;
     anchorOffset?: number;
-    durationPolicy?: 'timeline';
+    durationPolicy?: 'timeline'; /** Directly assigned AudioScript annotation times; annotation Markers only. */
+    segmentRanges?: {
+      segmentId: string;
+      startMs: number;
+      endMs: number;
+    }[];
   };
   viewport: JsonObject;
   'audio-script': JsonObject & {
     segments: ScriptTextSegment[];
   };
   'phonetic-script': JsonObject & {
-    segments: ScriptTextSegment[];
+    baseEntityIds: string[];
+    phonemeScript?: string;
+    prosody?: JsonObject;
+  };
+  caption: BoundedNativeSequencePayload & {
+    baseEntityIds: string[];
+    selections: CaptionTextSelection[];
+    style?: JsonObject;
   };
-  caption: BoundedNativeSequencePayload;
 }
 interface EntityStoreSnapshot {
   revision: number;
+  audioScriptEntityId: string | null;
   entities: SandboxEntity[];
   relations: SandboxRelation[];
 }
@@ -141,10 +201,18 @@ interface ImageMediaAssetFact {
   readonly kind: 'image';
   readonly storageKey?: string;
 }
-interface ImportAssetInput {
-  asset_id: string;
-  entity_id?: string;
-  payload?: JsonObject;
+interface InsertCaptionClipInput {
+  readonly timelineEntityId: string;
+  /** Stable placed caption identity, distinct from the Caption content identity. */
+  readonly captionClipEntityId?: string;
+  /** Existing bases composed by this variant; includes an AudioScript text owner. */
+  readonly baseEntityIds: readonly string[];
+  /** Ordered selection of the AudioScript segments this Caption displays. */
+  readonly selections: readonly CaptionSegmentSelection[];
+  /** Intrinsic cue length of the Caption entity itself; display comes from the placement. */
+  readonly durationMs: number;
+  readonly style?: CaptionStyleFields;
+  readonly placement: ClipPlacement;
 }
 interface InsertClipInput {
   readonly trackEntityId: string;
@@ -186,16 +254,17 @@ interface JsonObject {
 type JsonPrimitive = string | number | boolean | null;
 type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
 type KnownEntityKind = 'axvideo' | 'timeline' | 'track' | 'clip' | 'asset' | 'video' | 'audio' | 'voice' | 'image' | 'sequence-marker' | 'viewport' | 'audio-script' | 'phonetic-script' | 'caption';
-type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'phonetic-script-provenance' | 'caption-provenance' | 'caption-alignment' | 'clip-anchor' | 'audio-script-render';
+type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'caption-alignment' | 'clip-anchor' | 'phonetic-script-render' | 'audio-script-source' | 'audio-script-marker';
 interface LinearClipSpeed {
   readonly kind: 'linear';
   readonly rate: number;
   readonly mode?: string;
 }
-interface LinkAudioScriptRenderRelationInput {
+/** `audio-script-source(script, source)`; the script was transcribed from the source media. */
+interface LinkAudioScriptSourceRelationInput {
   relation_id?: string;
-  output_entity_id: string;
   script_entity_id: string;
+  source_entity_id: string;
   trace?: JsonObject;
 }
 interface LinkClipAnchorRelationInput {
@@ -210,6 +279,12 @@ interface LinkGeneratedRelationInput {
   input_entity_id: string;
   trace?: JsonObject;
 }
+interface LinkPhoneticScriptRenderRelationInput {
+  relation_id?: string;
+  output_entity_id: string;
+  phonetic_script_entity_id: string;
+  trace?: JsonObject;
+}
 interface LinkRelationBase {
   relation_id?: string;
   endpoint_0_entity_id: string;
@@ -224,17 +299,21 @@ type LinkRelationInput = (LinkRelationBase & {
 }) | (LinkRelationBase & {
   relation_kind: 'physical-asset';
   metadata?: JsonObject;
-}) | (LinkRelationBase & {
-  relation_kind: 'phonetic-script-provenance' | 'caption-provenance';
-  metadata: JsonObject & {
-    segmentAlignment: JsonValue;
-  };
 }) | (LinkRelationBase & {
   relation_kind: 'caption-alignment';
   metadata: JsonObject & {
     alignment: JsonValue;
   };
 });
+/** Facts resolved from media storage. A trim window never substitutes for intrinsic duration. */
+type MediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact | AudioMediaAssetFact | VoiceMediaAssetFact;
+type MediaAssetPayload = JsonObject & {
+  external: {
+    system: 'memota' | 'memota-speech';
+    key: string;
+  };
+  storageKey?: string;
+};
 type MediaClipInsertion = {
   readonly kind: 'before';
   readonly clipEntityId: string;
@@ -275,14 +354,16 @@ interface RelationFacade {
   list(): SandboxRelation[];
   /** Incident lookup is endpoint-agnostic; persisted endpoint positions stay unchanged. */
   of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];
-  /** For physical-asset use sequence media as endpoint 0 and Asset as endpoint 1. */
+  /** Link existing entities through ordinary associations; variant bases are stored directly on the variant. */
   link(input: LinkRelationInput): string;
   /** Author ordered generated(output,input); generic link() deliberately rejects this kind. */
   linkGenerated(input: LinkGeneratedRelationInput): string;
   /** Author ordered clip-anchor(child,host) without positional endpoint ambiguity. */
   linkClipAnchor(input: LinkClipAnchorRelationInput): string;
-  /** Author ordered audio-script-render(output,script) without positional endpoint ambiguity. */
-  linkAudioScriptRender(input: LinkAudioScriptRenderRelationInput): string;
+  /** Author ordered phonetic-script-render(output,script) without positional endpoint ambiguity. */
+  linkPhoneticScriptRender(input: LinkPhoneticScriptRenderRelationInput): string;
+  /** Author ordered audio-script-source(script,source) without positional endpoint ambiguity. */
+  linkAudioScriptSource(input: LinkAudioScriptSourceRelationInput): string;
   /** Remove a Relation by identity; endpoint replacement is an explicit unlink plus link. */
   unlink(input: UnlinkRelationInput): void;
 }
@@ -312,10 +393,12 @@ interface ReplacementMediaClipInput {
   readonly sourceRange: SequenceRange<number>;
   readonly volume?: number;
 }
+/** Asset identity, either an old physical-only row or a directly composed media variant. */
+type ResourceEntityKind = 'image' | 'video' | 'audio' | 'voice';
 interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {
   entity_id: string;
   entity_kind: K;
-  payload: EntityPayloadByKind[K];
+  payload: StoredEntityPayload<K>;
 }
 interface SandboxRelation {
   relation_id: string;
@@ -369,6 +452,10 @@ interface SetClipVolumeInput {
   /** Playback gain in decibels. */
   readonly volume: number;
 }
+/** Stored own fields; a variant may obtain required content fields from its declared bases. */
+type StoredEntityPayload<K extends KnownEntityKind> = EntityPayloadByKind[K] | (JsonObject & Partial<EntityPayloadByKind[K]> & {
+  baseEntityIds: string[];
+});
 interface TrimClipInput {
   readonly clipEntityId: string;
   readonly sourceRange: SequenceRange<number>;
@@ -398,6 +485,7 @@ interface UpdateClipMarkerInput {
   /** Passing `undefined` explicitly removes the optional remapping value. */
   readonly timeRemapping?: JsonValue | undefined;
 }
+/** Patch supplied fields on the assembled entity; omitted fields remain unchanged. */
 interface UpdateEntityInput {
   entity_id: string;
   payload: JsonObject;
@@ -420,36 +508,49 @@ interface VoiceMediaAssetFact {
   readonly kind: 'voice';
   readonly durationMs: number;
   readonly storageKey: string;
-  readonly voice: VoiceDescriptor;
+  /** Present for synthesized voice, absent for original recorded audio. */
+  readonly voice?: VoiceDescriptor;
 }
 interface VoiceoverCaptionFact {
   /** Stable placed caption identity supplied by the materialized side effect. */
   readonly captionClipEntityId: string;
-  readonly text: string;
+  /** Directly held bases; includes the AudioScript used by the Voice. */
+  readonly baseEntityIds: readonly string[];
+  /** Ordered selection of AudioScript segments; caption text is never passed inline. */
+  readonly selections: readonly CaptionSegmentSelection[];
   readonly startMs: number;
   readonly durationMs: number;
   readonly style?: CaptionStyleFields;
 }
-interface VoiceoverTakeInput {
-  readonly timelineEntityId: string;
-  /** Stable placed speech identity, distinct from media.assetId. */
+type VoiceoverTakeInput = {
+  readonly timelineEntityId: string; /** Stable placed speech identity, distinct from media.assetId. */
   readonly voiceoverClipEntityId: string;
-  readonly hostClipEntityId: string;
-  readonly anchorOffset: number;
-  readonly media: VoiceMediaAssetFact;
-  /** Complete spoken text; the editor owns the deterministic local script segment identity. */
-  readonly scriptText: string;
+  readonly media: VoiceMediaAssetFact; /** Existing pronunciation variant; its composed AudioScript stays the text owner. */
+  readonly phoneticScriptEntityId: string;
   readonly volume: number;
   readonly captions: readonly VoiceoverCaptionFact[];
-}
+} & ({
+  readonly placement: ClipPlacement;
+  readonly hostClipEntityId?: never;
+  readonly anchorOffset?: never;
+} | {
+  readonly placement?: never;
+  readonly hostClipEntityId: string;
+  readonly anchorOffset: number;
+});
 interface VoiceoverTakeResult {
   readonly voiceoverClipEntityId: string;
   readonly voiceEntityId: string;
+  /** The pronunciation variant the Voice was rendered from. */
+  readonly phoneticScriptEntityId: string;
+  /** The base-text owner resolved from the PhoneticScript baseEntityIds. */
   readonly audioScriptEntityId: string;
   readonly captionClipEntityIds: readonly string[];
 }
 /** Timeline writes accept existing media Entity ids, never Memota asset ids or URLs. */
 interface EditApi {
+  /** Select the document AudioScript, or clear the optional association with null. */
+  setDocumentAudioScript(entityId: string | null): void;
   insertClip(input: InsertClipInput): ClipEntityId;
   insertPlacedClip(input: InsertPlacedClipInput): ClipEntityId;
   updateClipMarker(input: UpdateClipMarkerInput): void;
@@ -475,6 +576,7 @@ interface EditApi {
   deleteBgm(input: DeleteBgmInput): void;
   setCaptionVisibility(input: SetCaptionVisibilityInput): void;
   patchCaptionStyle(input: PatchCaptionStyleInput): void;
+  insertCaptionClip(input: InsertCaptionClipInput): ClipEntityId;
 }
 interface TimelineApi {
   snapshot(): EntityStoreSnapshot;
@@ -490,5 +592,5 @@ declare function checkpoint(): SandboxCheckpoint;
 declare function rollbackTo(cp: SandboxCheckpoint): void;
 declare const inputs: Readonly<Record<string, unknown>>;
 //#endregion
-export type { AudioMediaAssetFact, BoundedDerivedSequencePayload, BoundedNativeSequencePayload, CaptionFontDescriptor, CaptionStyleFields, ClipEntityId, ClipPlacement, CreateEntityInput, DeleteBgmInput, DeleteClipInput, DeleteClipTreeInput, DeleteEntityInput, DeleteVoiceoverInput, EditApi, EmptyRelationKind, EntityFacade, EntityId, EntityPayloadByKind, EntityStoreSnapshot, ImageMediaAssetFact, ImportAssetInput, InsertClipInput, InsertMediaClipInput, InsertMediaClipsInput, InsertPlacedClipInput, JsonObject, JsonPrimitive, JsonValue, KnownEntityKind, KnownRelationKind, LinearClipSpeed, LinkAudioScriptRenderRelationInput, LinkClipAnchorRelationInput, LinkGeneratedRelationInput, LinkRelationInput, MediaClipInsertion, MoveClipInput, MoveClipsToStartsInput, MoveSequentialClipsInput, MoveVoiceoverInput, PatchCaptionStyleInput, RelationFacade, ReplaceClipContentInput, ReplaceMediaClipInput, ReplaceSequentialClipsInput, ReplacementMediaClipInput, SandboxCheckpoint, SandboxEntity, SandboxRelation, ScriptTextSegment, SequenceDuration, SequenceRange, SequentialClipAnchor, SetBgmInput, SetCaptionVisibilityInput, SetClipPlacementInput, SetClipSpeedInput, SetClipVolumeInput, TimelineApi, TrimClipInput, UnboundedConstantSequencePayload, UnlinkRelationInput, UpdateClipInput, UpdateClipMarkerInput, UpdateEntityInput, VideoMediaAssetFact, VisualMediaAssetFact, VoiceDescriptor, VoiceMediaAssetFact, VoiceoverCaptionFact, VoiceoverTakeInput, VoiceoverTakeResult, checkpoint, edit, entities, inputs, relations, rollbackTo, timeline };
+export type { AudioMediaAssetFact, BoundedDerivedSequencePayload, BoundedNativeSequencePayload, CaptionFontDescriptor, CaptionSegmentSelection, CaptionStyleFields, CaptionTextRange, CaptionTextSelection, ClipEntityId, ClipPlacement, ComposedPhoneticContent, ComposedScriptContent, CreateEntityInput, DeleteBgmInput, DeleteClipInput, DeleteClipTreeInput, DeleteEntityInput, DeleteVoiceoverInput, EditApi, EmptyRelationKind, EntityFacade, EntityId, EntityPayloadByKind, EntityStoreSnapshot, ImageMediaAssetFact, InsertCaptionClipInput, InsertClipInput, InsertMediaClipInput, InsertMediaClipsInput, InsertPlacedClipInput, JsonObject, JsonPrimitive, JsonValue, KnownEntityKind, KnownRelationKind, LinearClipSpeed, LinkAudioScriptSourceRelationInput, LinkClipAnchorRelationInput, LinkGeneratedRelationInput, LinkPhoneticScriptRenderRelationInput, LinkRelationInput, MediaAssetFact, MediaAssetPayload, MediaClipInsertion, MoveClipInput, MoveClipsToStartsInput, MoveSequentialClipsInput, MoveVoiceoverInput, PatchCaptionStyleInput, RelationFacade, ReplaceClipContentInput, ReplaceMediaClipInput, ReplaceSequentialClipsInput, ReplacementMediaClipInput, ResourceEntityKind, SandboxCheckpoint, SandboxEntity, SandboxRelation, ScriptTextSegment, SequenceDuration, SequenceRange, SequentialClipAnchor, SetBgmInput, SetCaptionVisibilityInput, SetClipPlacementInput, SetClipSpeedInput, SetClipVolumeInput, StoredEntityPayload, TimelineApi, TrimClipInput, UnboundedConstantSequencePayload, UnlinkRelationInput, UpdateClipInput, UpdateClipMarkerInput, UpdateEntityInput, VideoMediaAssetFact, VisualMediaAssetFact, VoiceDescriptor, VoiceMediaAssetFact, VoiceoverCaptionFact, VoiceoverTakeInput, VoiceoverTakeResult, checkpoint, edit, entities, inputs, relations, rollbackTo, timeline };
 //# sourceMappingURL=sandbox-api.d.mts.map