@mengine/medeo-tool 2.0.1-alpha.7 → 2.0.1-alpha.9

package/dist/{entity-contract-G4HxwNXl.d.mts → entity-contract-Bpe6NRIQ.d.mts}

@@ -8,8 +8,8 @@ interface JsonObject {
 }
 type KnownEntityKind = 'axvideo' | 'timeline' | 'track' | 'clip' | 'asset' | 'video' | 'audio' | 'voice' | 'image' | 'sequence-marker' | 'viewport' | 'audio-script' | 'phonetic-script' | 'caption';
 /** Asset identity, either an old physical-only row or a directly composed media variant. */
-type ResourceEntityKind = 'image' | 'video' | 'audio' | 'voice';
-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';
+type ResourceEntityKind = 'image' | 'video' | 'audio';
+type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'caption-alignment' | 'clip-anchor' | 'phonetic-script-render' | 'voice-timbre' | 'audio-script-source' | 'audio-script-marker';
 type AuthorableRelationKind = KnownRelationKind;
 interface BoundedNativeSequencePayload extends JsonObject {
   /** Factual coordinates from recalled media metadata; never invent an end/duration. */
@@ -50,6 +50,14 @@ type MediaAssetPayload = JsonObject & {
   };
   storageKey?: string;
 };
+/** The voice-library timbre a synthesized Audio was rendered with. */
+type VoiceIdentityPayload = JsonObject & {
+  voice: {
+    system: 'voice-library';
+    key: string;
+    name?: string;
+  };
+};
 type CaptionTextSelection = JsonObject & {
   segmentId: string; /** Half-open Unicode code-point range within the selected source segment. */
   textRange?: {
@@ -68,8 +76,10 @@ interface EntityPayloadByKind {
   /** Physical resource fields; never a copy of Caption content. */
   asset: JsonObject;
   video: BoundedNativeSequencePayload & MediaAssetPayload;
+  /** Every playable sound, including video original audio and synthesized voiceovers. */
   audio: BoundedNativeSequencePayload & MediaAssetPayload;
-  voice: BoundedNativeSequencePayload & MediaAssetPayload;
+  /** A timbre identity, never playable content; the rendered take is an `audio` entity. */
+  voice: VoiceIdentityPayload;
   image: UnboundedConstantSequencePayload & MediaAssetPayload;
   'sequence-marker': JsonObject & {
     sourceRange: {
@@ -115,8 +125,15 @@ interface EntityPayloadByKind {
     }[];
   };
 }
-/** Stored own fields; a variant may obtain required content fields from its declared bases. */
-type StoredEntityPayload<K extends KnownEntityKind> = EntityPayloadByKind[K] | (K extends 'caption' | 'voice' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never) | (JsonObject & Partial<EntityPayloadByKind[K]> & {
+/**
+ * Stored own fields; a variant may obtain required content fields from its
+ * declared bases.
+ *
+ * Caption and Audio may also be declared resource-only: the ASR transcript and
+ * the synthesized voiceover are attached by the host, which then fills in the
+ * remaining factual fields.
+ */
+type StoredEntityPayload<K extends KnownEntityKind> = EntityPayloadByKind[K] | (K extends 'caption' | 'audio' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never) | (JsonObject & Partial<EntityPayloadByKind[K]> & {
   baseEntityIds: string[];
 });
 interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {
@@ -238,4 +255,4 @@ interface BusinessRelationFacade {
 }
 //#endregion
 export { UpdateEntityInput as C, UnlinkRelationInput as S, LinkRelationInput as _, DeleteEntityInput as a, SandboxEntity as b, EntitySandboxCheckpoint as c, JsonObject as d, JsonPrimitive as f, LinkGeneratedRelationInput as g, KnownRelationKind as h, CreateEntityInput as i, EntityStoreSnapshot as l, KnownEntityKind as m, BusinessEntityFacade as n, EntityCommand as o, JsonValue as p, BusinessRelationFacade as r, EntityPlanState as s, AuthorableRelationKind as t, EntityUpdateInput as u, RelationUpdateInput as v, SandboxRelation as x, ResourceEntityKind as y };
-//# sourceMappingURL=entity-contract-G4HxwNXl.d.mts.map
+//# sourceMappingURL=entity-contract-Bpe6NRIQ.d.mts.map

package/dist/{entity-sandbox-DSFbfybl.mjs → entity-sandbox-CJeLcNcx.mjs}

@@ -1,7 +1,84 @@
 import { applyFieldChanges, assertCanonicalEditorResources, assertFieldChanges, ensureEditorFoundation, importMediaAsset, readDocumentAudioScript } from "@mengine/medeo-client";
 //#region ../medeo-dsl/src/entities.ts
+/**
+* What every known entity kind declares.
+*
+* `kinds` is a multi-declaration: every entry holds at the same time, the first
+* naming the object and the rest the properties it shares with others. The
+* order carries no priority, endpoint role, or edit sequence — an operation
+* asks whether the entity declares the kind it needs, never what its "main
+* type" is.
+*
+* `Caption` declares `Sequence` on purpose: it owns the display timing of the
+* one AudioScript segment it shows, which is what admits it into a Clip.
+* `Voice` declares neither `MediaFile` nor `Sequence` — it is a timbre
+* identity, not playable content; a rendered voiceover is an `audio` entity.
+*/
+const ENTITY_KINDS = Object.freeze({
+	axvideo: Object.freeze([
+		"AXVideo",
+		"Container",
+		"Sequence",
+		"Visual",
+		"Audible"
+	]),
+	timeline: Object.freeze(["Timeline", "Container"]),
+	track: Object.freeze([
+		"Track",
+		"Container",
+		"Sequence"
+	]),
+	clip: Object.freeze(["Clip", "Container"]),
+	asset: Object.freeze(["Asset"]),
+	video: Object.freeze([
+		"Video",
+		"MediaFile",
+		"Sequence",
+		"Visual",
+		"Audible"
+	]),
+	audio: Object.freeze([
+		"Audio",
+		"MediaFile",
+		"Sequence",
+		"Audible"
+	]),
+	image: Object.freeze([
+		"Image",
+		"MediaFile",
+		"Sequence",
+		"Visual"
+	]),
+	voice: Object.freeze([
+		"Voice",
+		"Container",
+		"IPBound"
+	]),
+	"sequence-marker": Object.freeze(["SequenceMarker"]),
+	viewport: Object.freeze(["Viewport"]),
+	"audio-script": Object.freeze(["AudioScript", "SegmentText"]),
+	"phonetic-script": Object.freeze(["PhoneticScript", "SegmentText"]),
+	caption: Object.freeze([
+		"Caption",
+		"SegmentText",
+		"Sequence"
+	])
+});
+/** What a known kind declares; extension kinds declare nothing through this table. */
+function kindsOf(entityKind) {
+	return isKnownEntityKind(entityKind) ? ENTITY_KINDS[entityKind] : [];
+}
+function declaresKind(entityKind, kind) {
+	return kindsOf(entityKind).includes(kind);
+}
+/**
+* Sequence admission asks `kinds` first, so an entity that does not declare
+* `Sequence` can never buy its way in by carrying the fields. Extension kinds
+* declare nothing and stay structurally detected.
+*/
 function hasSequence(entity) {
-	if (isKnownNonSequenceKind(entity.entityKind) || isReservedEntityKind(entity.entityKind)) return false;
+	if (isReservedEntityKind(entity.entityKind)) return false;
+	if (isKnownEntityKind(entity.entityKind) && !declaresKind(entity.entityKind, "Sequence")) return false;
 	return isSequenceFields(entity);
 }
 function isSequenceFields(value) {
@@ -14,22 +91,16 @@ function isSequenceFields(value) {
 	if (value.sampling !== "native" && value.sampling !== "constant" && value.sampling !== "derived") return false;
 	return "coordinateSpace" in value && value.coordinateSpace !== void 0;
 }
-function isKnownSequenceKind(kind) {
-	return isMediaAssetVariantKind(kind) || kind === "caption" || kind === "axvideo";
-}
 function isMediaAssetVariantKind(kind) {
-	return kind === "video" || kind === "image" || kind === "audio" || kind === "voice";
+	return kind === "video" || kind === "image" || kind === "audio";
 }
 function isKnownEntityKind(kind) {
-	return isKnownSequenceKind(kind) || isKnownNonSequenceKind(kind);
+	return Object.hasOwn(ENTITY_KINDS, kind);
 }
 function isReservedEntityKind(kind) {
 	const normalized = kind.toLowerCase().replaceAll("-", "").replaceAll("_", "");
 	return normalized === "speech" || normalized === "videodocument";
 }
-function isKnownNonSequenceKind(kind) {
-	return kind === "timeline" || kind === "track" || kind === "clip" || kind === "asset" || kind === "sequence-marker" || kind === "viewport" || kind === "audio-script" || kind === "phonetic-script";
-}
 function isRecord$1(value) {
 	return typeof value === "object" && value != null && !Array.isArray(value);
 }
@@ -209,14 +280,17 @@ function assembleCaptionContent(rows, captionEntityId) {
 	requireEntityKind(rows, captionEntityId, "caption");
 	const caption = assembleEntityContent(rows, captionEntityId);
 	const script = findComposedAudioScript(rows, captionEntityId, "caption");
-	const segment = selectAudioScriptSegment({
+	const selection = captionSelection(caption);
+	const composed = {
 		...script,
 		payload: caption.payload
-	}, captionSelection(caption));
+	};
+	const segment = selectAudioScriptSegment(composed, selection);
 	return {
 		caption,
 		audioScript: script,
 		segments: [segment],
+		segmentIndex: scriptSegments(composed).findIndex((entry) => entry.segmentId === selection.segmentId),
 		text: segment.text
 	};
 }
@@ -608,12 +682,15 @@ function validateKnownEntityPayload(entity) {
 			break;
 		case "video":
 		case "audio":
-		case "voice":
+			validateSequencePayload(value, "bounded", "native", problems);
+			validateMediaAssetFields(value, problems);
+			break;
 		case "caption":
 			validateSequencePayload(value, "bounded", "native", problems);
-			if (entity.entityKind !== "caption") validateMediaAssetFields(value, problems);
-			if (entity.entityKind === "voice") validateVoicePayload(value, problems);
-			if (entity.entityKind === "caption") validateCaptionPayload(value, problems);
+			validateCaptionPayload(value, problems);
+			break;
+		case "voice":
+			validateVoicePayload(value, problems);
 			break;
 		case "image":
 			validateSequencePayload(value, "unbounded", "constant", problems);
@@ -720,11 +797,26 @@ function validateExternalLocator(value, problems) {
 function validateStorageKey(value, problems) {
 	if (value.storageKey !== void 0 && (typeof value.storageKey !== "string" || value.storageKey.trim() === "")) problems.push("storageKey must be a non-empty string when present");
 }
+/**
+* Voice is a timbre identity, not playable content: it owns the voice-library
+* descriptor and nothing that would make it look like media or a Sequence. The
+* rendered voiceover is an `audio` entity bound by a `voice-timbre` Relation.
+*/
 function validateVoicePayload(value, problems) {
+	for (const key of [
+		"extent",
+		"sampling",
+		"coordinateSpace",
+		"external",
+		"storageKey"
+	]) if (Object.hasOwn(value, key)) problems.push(`${key} belongs to the rendered Audio, not to the Voice identity`);
 	const voice = value.voice;
-	if (voice === void 0) return;
+	if (voice === void 0) {
+		problems.push("voice is required; a Voice entity is its voice-library identity");
+		return;
+	}
 	if (!isRecord(voice)) {
-		problems.push("voice must be an object when present");
+		problems.push("voice must be an object");
 		return;
 	}
 	if (voice.system !== "voice-library") problems.push("voice.system must be \"voice-library\"");
@@ -856,7 +948,6 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 	if ([
 		"video",
 		"audio",
-		"voice",
 		"image",
 		"caption",
 		"axvideo"
@@ -920,7 +1011,7 @@ function collectRelatedEntities(entityRefs, index) {
 	};
 }
 function expectedSequenceShape(kind) {
-	if (kind === "video" || kind === "audio" || kind === "voice" || kind === "caption") return {
+	if (kind === "video" || kind === "audio" || kind === "caption") return {
 		extent: "bounded",
 		sampling: "native"
 	};
@@ -961,7 +1052,7 @@ const generatedRelationSpec = Object.freeze({
 });
 const captionAlignmentRelationSpec = Object.freeze({
 	kind: "caption-alignment",
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["caption"]), new Set(["audio", "voice"])),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["caption"]), new Set(["audio"])),
 	validateMetadata: isCaptionAlignmentMetadata
 });
 /** `clip-anchor(child, host)` means endpoint 0 follows endpoint 1. */
@@ -970,20 +1061,29 @@ const clipAnchorRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => endpoints[0].current().entityKind === "clip" && endpoints[1].current().entityKind === "clip",
 	validateMetadata: isEmptyMetadata
 });
-/** Voice is generated from PhoneticScript; kinds determine roles regardless of endpoint positions. */
+/**
+* The rendered voiceover Audio and the PhoneticScript it was synthesized from;
+* kinds determine roles regardless of endpoint positions.
+*/
 const phoneticScriptRenderRelationSpec = Object.freeze({
 	kind: "phonetic-script-render",
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["voice"]), new Set(["phonetic-script"])),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio"]), new Set(["phonetic-script"])),
+	validateMetadata: isEmptyMetadata
+});
+/**
+* The timbre identity a rendered voiceover Audio was synthesized with. Voice
+* stays an identity: it never carries the audio itself, so the link between the
+* two is a Relation rather than one shared entity.
+*/
+const voiceTimbreRelationSpec = Object.freeze({
+	kind: "voice-timbre",
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio"]), new Set(["voice"])),
 	validateMetadata: isEmptyMetadata
 });
 /** AudioScript was transcribed from Audio, Video, or recorded Voice; kinds determine roles. */
 const audioScriptSourceRelationSpec = Object.freeze({
 	kind: "audio-script-source",
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set([
-		"audio",
-		"video",
-		"voice"
-	])),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set(["audio", "video"])),
 	validateMetadata: isEmptyMetadata
 });
 /**
@@ -1010,6 +1110,7 @@ const builtInRelationSpecs = Object.freeze([
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
 	phoneticScriptRenderRelationSpec,
+	voiceTimbreRelationSpec,
 	audioScriptSourceRelationSpec,
 	audioScriptMarkerRelationSpec
 ]);
@@ -1039,7 +1140,7 @@ function hasAssetAndSequence(endpoints) {
 	return first.entityKind === "asset" && hasSequence(second) || second.entityKind === "asset" && hasSequence(first);
 }
 function isGeneratedMedia(entity) {
-	return entity.entityKind === "video" || entity.entityKind === "image" || entity.entityKind === "audio" || entity.entityKind === "voice";
+	return entity.entityKind === "video" || entity.entityKind === "image" || entity.entityKind === "audio";
 }
 function isEmptyMetadata(value) {
 	return isJsonObject(value) && Object.keys(value).length === 0;
@@ -1599,6 +1700,7 @@ var EntitySandbox = class {
 				const assembled = assembleCaptionContent(toDslRows(this.state), createEntityId(entityId));
 				return clone({
 					audio_script_entity_id: assembled.audioScript.entityId,
+					segment_index: assembled.segmentIndex,
 					text: assembled.text,
 					segments: assembled.segments.map((segment) => ({ ...segment }))
 				});
@@ -1788,7 +1890,7 @@ var EntitySandbox = class {
 		}
 		for (const row of rows.relations) {
 			if (this.state.relations.some((relation) => relation.relation_id === row.relationId)) continue;
-			if (row.relationKind !== "timeline-track") throw new Error(`Unexpected resource Relation ${row.relationKind}`);
+			if (row.relationKind !== "timeline-track" && row.relationKind !== "voice-timbre") throw new Error(`Unexpected resource Relation ${row.relationKind}`);
 			this.link({
 				relation_id: row.relationId,
 				relation_kind: row.relationKind,
@@ -2095,4 +2197,4 @@ const numericMarkerComparators = { compareMarkerPoints: (_marker, _range, left,
 //#endregion
 export { isJsonObject as a, isMediaAssetVariantKind as c, businessState as i, toDslRows as n, createEntityId as o, businessFacades as r, createRelationId as s, EntitySandbox as t };
 
-//# sourceMappingURL=entity-sandbox-DSFbfybl.mjs.map
+//# sourceMappingURL=entity-sandbox-CJeLcNcx.mjs.map