@mengine/medeo-tool 2.0.1-alpha.6 → 2.0.1-alpha.8

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-CzaUmSsS.mjs}

@@ -1,7 +1,62 @@
 import { applyFieldChanges, assertCanonicalEditorResources, assertFieldChanges, ensureEditorFoundation, importMediaAsset, readDocumentAudioScript } from "@mengine/medeo-client";
 //#region ../medeo-dsl/src/entities.ts
+/**
+* The declared trait set of every known kind.
+*
+* `caption` carries `sequence` on purpose: a Caption owns the display timing of
+* the one AudioScript segment it shows, which is what admits it into a Clip.
+* `voice` carries no media or sequence trait — it is a timbre identity, not
+* playable content; a rendered voiceover is an `audio` entity.
+*/
+const ENTITY_TRAIT_KINDS = Object.freeze({
+	axvideo: Object.freeze([
+		"container",
+		"sequence",
+		"visual",
+		"audible"
+	]),
+	timeline: Object.freeze(["container"]),
+	track: Object.freeze(["container", "sequence"]),
+	clip: Object.freeze(["container"]),
+	asset: Object.freeze([]),
+	video: Object.freeze([
+		"media-file",
+		"sequence",
+		"visual",
+		"audible"
+	]),
+	audio: Object.freeze([
+		"media-file",
+		"sequence",
+		"audible"
+	]),
+	image: Object.freeze([
+		"media-file",
+		"sequence",
+		"visual"
+	]),
+	voice: Object.freeze(["container", "ip-bound"]),
+	"sequence-marker": Object.freeze([]),
+	viewport: Object.freeze([]),
+	"audio-script": Object.freeze(["segment-text"]),
+	"phonetic-script": Object.freeze(["segment-text"]),
+	caption: Object.freeze(["segment-text", "sequence"])
+});
+/** Declared traits of a known kind; extension kinds declare none through this table. */
+function traitKindsOf(entityKind) {
+	return isKnownEntityKind(entityKind) ? ENTITY_TRAIT_KINDS[entityKind] : [];
+}
+function hasTraitKind(entityKind, trait) {
+	return traitKindsOf(entityKind).includes(trait);
+}
+/**
+* Sequence admission asks the declared traits first, so a kind that does not
+* declare `sequence` can never buy its way in by carrying the fields. Extension
+* kinds declare no traits 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) && !hasTraitKind(entity.entityKind, "sequence")) return false;
 	return isSequenceFields(entity);
 }
 function isSequenceFields(value) {
@@ -14,22 +69,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_TRAIT_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);
 }
@@ -608,12 +657,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 +772,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 +923,6 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 	if ([
 		"video",
 		"audio",
-		"voice",
 		"image",
 		"caption",
 		"axvideo"
@@ -920,7 +986,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 +1027,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 +1036,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 +1085,7 @@ const builtInRelationSpecs = Object.freeze([
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
 	phoneticScriptRenderRelationSpec,
+	voiceTimbreRelationSpec,
 	audioScriptSourceRelationSpec,
 	audioScriptMarkerRelationSpec
 ]);
@@ -1039,7 +1115,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;
@@ -1788,7 +1864,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 +2171,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-CzaUmSsS.mjs.map