@mengine/medeo-tool 1.4.1-alpha.4 → 2.0.1-alpha.2

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as createEntityId, i as businessState, o as createRelationId, s as isMediaAssetVariantKind, t as EntitySandbox } from "./entity-sandbox-OArq9NSH.mjs";
+import { c as isMediaAssetVariantKind, i as businessState, o as createEntityId, s as createRelationId, t as EntitySandbox } from "./entity-sandbox-TaUVT3on.mjs";
 import { LoroEntityDocument, ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, base64ToBytes, bytesToBase64, compileEntityRows, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, replayJournal, solveVideoDocument, speedOf, toVideoDocument } from "@mengine/medeo-client";
 import { Worker } from "node:worker_threads";
 import { createHash, randomUUID } from "node:crypto";
@@ -854,7 +854,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  };",
 	"  caption: BoundedNativeSequencePayload & {",
 	"    baseEntityIds: string[];",
-	"    selections: CaptionTextSelection[];",
+	"    selection: CaptionTextSelection;",
 	"    style?: JsonObject;",
 	"    segmentRanges?: {",
 	"      segmentId: string;",
@@ -985,7 +985,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"/** Stored own fields; a variant may obtain required content fields from its declared bases. */",
 	"export type StoredEntityPayload<K extends KnownEntityKind> =",
 	"  | EntityPayloadByKind[K]",
-	"  | (K extends 'caption' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never)",
+	"  | (K extends 'caption' | 'voice' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never)",
 	"  | (JsonObject &",
 	"      Partial<EntityPayloadByKind[K]> & {",
 	"        baseEntityIds: string[];",
@@ -1008,7 +1008,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"}",
 	"export declare const entities: BusinessEntityFacade;",
 	"export declare const relations: BusinessRelationFacade;",
-	"/** Resolve this Entity's attached resource through the host; await before using an uninitialized Caption. */",
+	"/** Resolve this Entity's attached resource through the host; await before using an uninitialized Caption or Voice. */",
 	"export declare function rgetAssetFromEntity(entityId: string): Promise<EntityAssetContent>;",
 	"export declare function checkpoint(): EntitySandboxCheckpoint;",
 	"export declare function rollbackTo(cp: EntitySandboxCheckpoint): void;",
@@ -1038,15 +1038,17 @@ The host supplies the current document. Do not invent or request a document id.
 
 Entity reads return assembled snapshots. Mutating returned objects has no persistence effect. Create declares own fields. Update requires a nonempty changes array and atomically applies its ordered operations to assembled fields, routing each to its declaring owner. DeclareFields explicitly establishes own fields or an override; it is not the normal way to edit inherited content. Deletion requires explicitly handling incident relations, variant references and protected project attachments; it never deletes external resources or cascades business entities.
 
-FieldChange paths start at payload for an entity, and at metadata or trace for a relation. Use strings for fields and {elementId:'...'} for list members, never numeric indices. Segment identity is segmentId; reference identity is the referenced id. set writes scalars or schema-declared atomic values, including complete sourceRange, targetRange, extent, duration, timeRemapping, textRange and external. It cannot replace collaborative text, lists or maps. Edit text with text.splice (Unicode code-point index and deleteCount), and segments/selections/segmentRanges with list.insert, list.move or list.remove. beforeElementId:null means append; moving before itself, duplicate identity or an absent anchor is an error. Unset removes optional fields only. Map fields are edited through leaf paths; initialize a new own map via declareFields. baseEntityIds is unordered composition membership: insert/remove are supported, moving bases cannot resolve field conflicts. Independent fields and list-item text edits retain native Loro identities.
+FieldChange paths start at payload for an entity, and at metadata or trace for a relation. Use strings for fields and {elementId:'...'} for list members, never numeric indices. Segment identity is segmentId; reference identity is the referenced id. set writes scalars or schema-declared atomic values, including complete sourceRange, targetRange, extent, duration, timeRemapping, selection, textRange and external. It cannot replace collaborative text, lists or maps. Edit text with text.splice (Unicode code-point index and deleteCount), and segments/segmentRanges with list.insert, list.move or list.remove. beforeElementId:null means append; moving before itself, duplicate identity or an absent anchor is an error. Unset removes optional fields only. Map fields are edited through leaf paths; initialize a new own map via declareFields. baseEntityIds is unordered composition membership: insert/remove are supported, moving bases cannot resolve field conflicts. Independent fields and list-item text edits retain native Loro identities.
 
 Entities own data. Relations associate two existing entities; endpoint_0 and endpoint_1 retain their declared positions. Each relation kind defines direction and meaning; neither relation listing order nor endpoint storage order implies a global business order. Relations.update changes metadata/trace fields only; kind/endpoints require explicit unlink plus link with a new identity. Generated relations use generated(output,input). Ordinary associations do not implement composition.
 
 Variants directly hold baseEntityIds. Assembly validates every base before applying explicit own overrides: two bases supplying the same field are an error even if values match or the variant declares that field. Missing/cyclic bases fail. Consumers operate assembled fields without copying inherited content or resolving owners themselves. An owned-field edit creates a new immutable entity version. Base changes automatically advance variant base references and project attachments without versioning an unchanged variant. A variant-owned change versions the variant and retains unchanged bases. Do not manually clone entities for versioning. Use the current plan's ids throughout that execution; refresh after commit.
 
-Generation tools return resource references. An asset id may be passed in an entity's external:{system:'memota',key:assetId}; it is never an entity id, baseEntityId or relation endpoint. Physical resources are host infrastructure. The sandbox has no direct resource lookup/CRUD by asset id. rgetAssetFromEntity takes only an existing business entity id and returns {assetId,content} for its attached resource. For output_caption, create a Caption with payload:{external:{system:'memota',key:assetId}}, then await rgetAssetFromEntity(captionId). The host initializes Caption intrinsic timing and its composed AudioScript text in the same causal plan; Without explicit bases, the host creates an independent AudioScript for that resource. With bases, it resolves their unique AudioScript text owner and preserves other nonconflicting bases. It never routes text through the panel selection. Read the editable fields with entities.get afterwards. Repeated reads preserve edited text and return the original immutable resource content. Unawaited initialization is completed before validation; failure prevents publication. Resource-free Caption composition from AudioScript is also valid.
+Generation tools return resource references. An asset id may be passed in an entity's external:{system:'memota',key:assetId}; it is never an entity id, baseEntityId or relation endpoint. Physical resources are host infrastructure. The sandbox has no direct resource lookup/CRUD by asset id. rgetAssetFromEntity takes only an existing business entity id and returns {assetId,content} for its attached resource. For output_caption, create a Caption with payload:{external:{system:'memota',key:assetId}}, then await rgetAssetFromEntity(captionId). The host initializes the complete AudioScript and one Caption per resource segment in the same causal plan when selection is omitted. The requested Caption represents the first segment; additional Caption entities share that same script and external reference. After awaiting, discover ALL resource Captions with entities.list filtered by entity_kind and payload.external.key, inspect each singular selection/extent, and place each in its own Clip/SequenceMarker. An explicit selection initializes only that selected Caption. Never place the first Caption over the whole transcript; Without explicit bases, the host creates an independent AudioScript for that resource. With bases, it resolves their unique AudioScript text owner and preserves other nonconflicting bases. It never routes text through the panel selection. Read the editable fields with entities.get afterwards. Repeated reads preserve edited text and return the original immutable resource content. Unawaited initialization is completed before validation; failure prevents publication. Resource-free Caption composition from AudioScript is also valid.
 
-Project initialization creates one current Timeline, the four standard Tracks and one attached AudioScript with segments:[]. A project may contain multiple independent complete AudioScripts (for example a generated script and an uploaded video transcript). The project AudioScript attachment selects only the panel view; it is not a singleton or membership constraint. Locate scripts with entities.list and choose the appropriate source. AudioScript owns independent multi-segment text; each can have multiple Caption variants. Caption and PhoneticScript compose it through baseEntityIds. Caption owns selections ({segmentId,textRange?}), intrinsic segmentRanges and style; segmentId is a stable script-local identity, not an entity reference or transient array index; selection textRange is a half-open code-point range and can split display text without rewriting the script. PhoneticScript owns pronunciation/prosody; Voice is generated from it and related by phonetic-script-render(voice,phoneticScript). Speech and caption occupy separate Clips. Subtitles normally accompany sound; use source media or generate Voice from PhoneticScript when the request requires narration. Do not fabricate a sound resource.
+Project initialization creates one current Timeline, the four standard Tracks and one attached AudioScript with segments:[]. A project may contain multiple independent complete AudioScripts (for example a generated script and an uploaded video transcript). The project AudioScript attachment selects only the panel view; it is not a singleton or membership constraint. Locate scripts with entities.list and choose the appropriate source. AudioScript owns independent multi-segment text; each can have multiple Caption variants. Caption and PhoneticScript compose it through baseEntityIds. Caption owns exactly one selection object ({segmentId,textRange?}), never an array or the legacy selections field. It selects one script segment or a contiguous substring, and owns only that selection's intrinsic timing and style; segmentId is a stable script-local identity, not an entity reference or transient array index; selection textRange is a half-open code-point range and can split display text without rewriting the script. PhoneticScript owns pronunciation/prosody; Voice is generated from it and related by phonetic-script-render(voice,phoneticScript). Speech and caption occupy separate Clips. Subtitles normally accompany sound; use source media or generate Voice from PhoneticScript when the request requires narration. Do not fabricate a sound resource.
+
+For Speech resources, create a Voice with external:{system:'memota-speech',key:speechId}, then await rgetAssetFromEntity(voiceId) before linking its placement. The host supplies full extent and optional voice-library identity, and assembles physical storage facts internally. Read the visible fields through entities.get; never invent them or use a Speech ID as a Memota media ID. TTS Voice still requires its real PhoneticScript relation; resource loading does not invent script content.
 
 AudioScript has no intrinsic time and cannot be Clip content. ASR input Audio/Video/Voice associates via audio-script-source(script,source). Its external annotation SequenceMarker associates via audio-script-marker(script,marker) and receives assigned segmentRanges, not references to another marker. Caption intrinsic timing and its Clip's display SequenceMarker are distinct. Move/stretch display by editing only the placement marker.
 
@@ -1802,10 +1804,10 @@ async function materializeResources(options, resources) {
 			ids.push(sandbox.entities.ensureMedia(resource).contentEntityId);
 			continue;
 		}
-		const existingCaption = sandbox.entities.list().find((row) => row.entity_kind === "caption" && row.payload.external?.key === resource.assetId);
-		if (existingCaption) {
-			if (existingCaption.payload.storageKey !== resource.storageKey) throw new Error("Conflicting Caption resource identity");
-			ids.push(existingCaption.entity_id);
+		const existingCaptions = sandbox.entities.list().filter((row) => row.entity_kind === "caption" && row.payload.external?.key === resource.assetId);
+		if (existingCaptions.length) {
+			if (existingCaptions.some((caption) => caption.payload.storageKey !== resource.storageKey)) throw new Error("Conflicting Caption resource identity");
+			ids.push(...existingCaptions.map((caption) => caption.entity_id));
 			continue;
 		}
 		if (!resource.assetId.trim() || !resource.storageKey.trim() || !resource.segments.length) throw new Error("Caption resource requires a physical locator and timed segments");
@@ -1830,28 +1832,31 @@ async function materializeResources(options, resources) {
 			startMs: segment.startMs,
 			endMs: segment.endMs
 		}));
-		const captionId = stableId("entity", "caption", resource.assetId);
-		sandbox.entities.create({
-			entity_id: captionId,
-			entity_kind: "caption",
-			payload: {
-				baseEntityIds: [scriptId],
-				external: {
-					system: "memota",
-					key: resource.assetId
-				},
-				storageKey: resource.storageKey,
-				segmentRanges: ranges,
-				selections: segments.map(({ segmentId }) => ({ segmentId })),
-				extent: {
-					kind: "bounded",
-					start,
-					end
-				},
-				sampling: "native",
-				coordinateSpace: "milliseconds"
-			}
-		});
+		for (const range of ranges) {
+			const captionId = stableId("entity", "caption", resource.assetId, range.segmentId);
+			sandbox.entities.create({
+				entity_id: captionId,
+				entity_kind: "caption",
+				payload: {
+					baseEntityIds: [scriptId],
+					external: {
+						system: "memota",
+						key: resource.assetId
+					},
+					storageKey: resource.storageKey,
+					selection: { segmentId: range.segmentId },
+					segmentRanges: [range],
+					extent: {
+						kind: "bounded",
+						start: range.startMs,
+						end: range.endMs
+					},
+					sampling: "native",
+					coordinateSpace: "milliseconds"
+				}
+			});
+			ids.push(captionId);
+		}
 		const markerId = sandbox.entities.create({
 			entity_id: stableId("entity", "asr-marker", resource.assetId),
 			entity_kind: "sequence-marker",
@@ -1878,7 +1883,6 @@ async function materializeResources(options, resources) {
 			endpoint_0_entity_id: scriptId,
 			endpoint_1_entity_id: markerId
 		});
-		ids.push(captionId);
 	}
 	const candidate = sandbox.buildPlan();
 	if (candidate.commands.length && options.loadGenerationFacts) {