@mengine/medeo-client 2.0.1-alpha.7 → 2.0.1-alpha.8

package/dist/{document-Bnxm1p5E.js → document-DdwzfZ1g.js}

@@ -1447,8 +1447,63 @@ function emptyLaneTracks() {
 }
 //#endregion
 //#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) {
@@ -1461,22 +1516,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);
 }
@@ -2059,12 +2108,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);
@@ -2171,11 +2223,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\"");
@@ -2307,7 +2374,6 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 	if ([
 		"video",
 		"audio",
-		"voice",
 		"image",
 		"caption",
 		"axvideo"
@@ -2371,7 +2437,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"
 	};
@@ -2412,7 +2478,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. */
@@ -2421,20 +2487,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
 });
 /**
@@ -2461,6 +2536,7 @@ const builtInRelationSpecs = Object.freeze([
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
 	phoneticScriptRenderRelationSpec,
+	voiceTimbreRelationSpec,
 	audioScriptSourceRelationSpec,
 	audioScriptMarkerRelationSpec
 ]);
@@ -2490,7 +2566,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;
@@ -2920,7 +2996,7 @@ function resolveGraphLayout(graph) {
 			if (clip.entityKind !== "clip" || graph.adjacent(clip.entityId, "track-clip").length !== 1) fail(`Clip ${clip.entityId} must belong to exactly one Track`);
 			const marker = graph.one(clip.entityId, "clip-marker", "sequence-marker");
 			const content = graph.one(marker.entityId, "marker-content");
-			if (!(typedRole === "video_clip" ? ["image", "video"] : typedRole === "speech" ? ["voice"] : typedRole === "caption" ? ["caption"] : ["audio"]).includes(content.entityKind)) fail(`unsupported compatibility content kind ${content.entityKind} on ${typedRole} Track`);
+			if (!(typedRole === "video_clip" ? ["image", "video"] : typedRole === "speech" ? ["audio"] : typedRole === "caption" ? ["caption"] : ["audio"]).includes(content.entityKind)) fail(`unsupported compatibility content kind ${content.entityKind} on ${typedRole} Track`);
 			const space = content.payload.coordinateSpace;
 			if (space !== "ms" && space !== "milliseconds" && (!object(space) || space.unit !== "ms" && space.unit !== "milliseconds")) fail(`media ${content.entityId} must state millisecond coordinates for this reader`);
 			const source = range(marker.payload.sourceRange, "sourceRange");
@@ -2999,7 +3075,7 @@ function resolveGraphLayout(graph) {
 		let start = fact.absoluteStart ?? 0;
 		if (fact.mode === "anchored") {
 			const host = resolve(fact.anchorId);
-			if (fact.role === "speech" && !["video_clip", "bgm"].includes(facts.get(host.clipEntityId).role)) fail("An anchored Voice must use a visual or BGM Clip as its host");
+			if (fact.role === "speech" && !["video_clip", "bgm"].includes(facts.get(host.clipEntityId).role)) fail("An anchored voiceover must use a visual or BGM Clip as its host");
 			start = host.start + fact.anchorOffset;
 		} else if (fact.predecessor !== void 0) {
 			const prior = resolve(fact.predecessor);
@@ -3083,8 +3159,11 @@ function projectEntityTimeline(rows) {
 			const asset = mediaAssetFacts(graph, content);
 			requireUntrimmedAudio(content, marker, placement);
 			const external = externalLocator(asset, "memota-speech");
-			const assembled = graph.adjacent(content.entityId, "phonetic-script-render").length > 0 || content.payload.voice !== void 0 ? assemblePhoneticScriptContent(rows, graph.one(content.entityId, "phonetic-script-render", "phonetic-script").entityId) : void 0;
-			const voice = content.payload.voice;
+			const renderEdges = graph.adjacent(content.entityId, "phonetic-script-render");
+			const timbreEdges = graph.adjacent(content.entityId, "voice-timbre");
+			const assembled = renderEdges.length > 0 || timbreEdges.length > 0 ? assemblePhoneticScriptContent(rows, graph.one(content.entityId, "phonetic-script-render", "phonetic-script").entityId) : void 0;
+			if (timbreEdges.length > 1) fail("A voiceover resolves at most one Voice identity");
+			const voice = timbreEdges.length === 0 ? void 0 : graph.one(content.entityId, "voice-timbre", "voice").payload.voice;
 			if (voice !== void 0 && (!object(voice) || voice.system !== "voice-library" || typeof voice.key !== "string")) fail("Voice must use an explicit voice-library locator");
 			const captionIds = layout.tracks.flatMap((candidate) => candidate.role === "caption" ? candidate.clips.filter((caption) => caption.anchorClipEntityId === clip.entityId).map((caption) => caption.clipEntityId) : []);
 			parts[clip.entityId] = { speech: {

package/dist/index.d.ts

@@ -272,17 +272,22 @@ interface AudioMediaAssetFact {
   readonly durationMs: number;
   readonly storageKey: string;
 }
-interface VoiceMediaAssetFact {
+/**
+ * A speech recording. It materializes as an `audio` entity like every other
+ * playable sound; `voice` names the timbre identity it was synthesized with,
+ * which becomes its own Voice entity linked by a `voice-timbre` Relation.
+ */
+interface VoiceoverMediaAssetFact {
   /** Stable external speech result id, independent of the placed Clip id. */
   readonly assetId: string;
-  readonly kind: 'voice';
+  readonly kind: 'voiceover';
   readonly durationMs: number;
   readonly storageKey: string;
-  /** Present for synthesized voice, absent for original recorded audio. */
+  /** Present for synthesized speech, absent for original recorded audio. */
   readonly voice?: VoiceDescriptor;
 }
 /** Facts resolved from media storage. A trim window never substitutes for intrinsic duration. */
-type MediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact | AudioMediaAssetFact | VoiceMediaAssetFact;
+type MediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact | AudioMediaAssetFact | VoiceoverMediaAssetFact;
 type ClipPlacement = {
   readonly kind: 'sequential';
   readonly order: number;
@@ -334,7 +339,7 @@ interface DeleteClipTreeInput {
 interface VoiceoverCaptionFact {
   /** Stable placed caption identity supplied by the materialized side effect. */
   readonly captionClipEntityId: string;
-  /** Directly held bases; includes the AudioScript used by the Voice. */
+  /** Directly held bases; includes the AudioScript the voiceover was rendered from. */
   readonly baseEntityIds: readonly string[];
   /** Ordered selection of AudioScript segments; caption text is never passed inline. */
   readonly selection: CaptionSegmentSelection;
@@ -345,7 +350,7 @@ interface VoiceoverCaptionFact {
 type VoiceoverTakeInput = {
   readonly timelineEntityId: string; /** Stable placed speech identity, distinct from media.assetId. */
   readonly voiceoverClipEntityId: string;
-  readonly media: VoiceMediaAssetFact; /** Existing pronunciation variant; its composed AudioScript stays the text owner. */
+  readonly media: VoiceoverMediaAssetFact; /** Existing pronunciation variant; its composed AudioScript stays the text owner. */
   readonly phoneticScriptEntityId: string;
   readonly volume: number;
   readonly captions: readonly VoiceoverCaptionFact[];
@@ -421,8 +426,11 @@ interface TrimClipInput {
 }
 interface VoiceoverTakeResult {
   readonly voiceoverClipEntityId: string;
-  readonly voiceEntityId: string;
-  /** The pronunciation variant the Voice was rendered from. */
+  /** The rendered voiceover Audio entity. */
+  readonly voiceoverAudioEntityId: string;
+  /** The timbre identity it was synthesized with, when the take declared one. */
+  readonly voiceEntityId?: string;
+  /** The pronunciation variant the voiceover was rendered from. */
   readonly phoneticScriptEntityId: string;
   /** The base-text owner resolved from the PhoneticScript baseEntityIds. */
   readonly audioScriptEntityId: string;
@@ -556,7 +564,7 @@ declare class EntityTimelineEditor {
   insertCaptionClip(input: InsertCaptionClipInput): ClipEntityId;
   private insertPlacedClipIntoDraft;
   private ensureRoleTrack;
-  /** The existing pronunciation variant a Voice consumes; composition is required. */
+  /** The existing pronunciation variant a voiceover consumes; composition is required. */
   private requireComposedPhoneticScript;
   /** Preserve the factual synthesis input, regardless of persisted endpoint positions. */
   private ensurePhoneticRender;
@@ -632,6 +640,8 @@ interface ImportedMediaAsset {
   readonly rows: EntityRelationRows;
   /** The single media variant identity for this asset id; it is its own Asset. */
   readonly contentEntityId: string;
+  /** The timbre identity of a synthesized voiceover; absent for recorded media. */
+  readonly voiceEntityId?: string;
 }
 /**
  * Import at the editor boundary, not at asset generation time. Existing
@@ -1716,4 +1726,4 @@ declare function hasAudioScriptAsset(payload: JsonObject): boolean;
 /** Internal fingerprint prevents a resource from silently describing an older text revision. */
 declare function audioScriptAssetFields(payload: JsonObject, assetId: string): JsonObject;
 //#endregion
-export { type Aggregation, type AssembledCaptionContent, type AssembledPhoneticScriptContent, type Attachment, type AudioMediaAssetFact, type BgmPart, type CaptionContentInput, type CaptionDisplayCue, type CaptionPart, type CaptionSegmentSelection, type CaptionStyle, type ClipEntityId, type ClipPlacement, type CommitOptions, DEFAULT_UNIT_TIME_MS, type DeleteBgmInput, type DeleteClipInput, type DeleteClipTreeInput, type DeleteVoiceoverInput, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, type DocumentAudioScript, type DocumentAudioScriptState, type EditorFoundation, EntityDocumentState, type EntityGraphCommitOptions, EntityGraphHttpClient, type EntityGraphState, EntityTimelineEditor, type EntityTimelineIdFactory, EntityTimelineProjectionError, type EntityTimelineTrackRole, type FieldChange, type FieldPath, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImageMediaAssetFact, type ImplementedSemanticOpKind, type ImportedMediaAsset, type InsertCaptionClipInput, type InsertClipInput, type InsertMediaClipInput, type InsertMediaClipsInput, type InsertPlacedClipInput, type JournalEntry, LANE_KINDS_IN_STACK_ORDER, LORO_ENTITY_SCHEMA, type LaneKind, type LinearClipSpeed, LoroEntityDocument, LoroEntityDraft, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, type MediaAssetFact, type MediaClipInsertion, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocSyncState, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUndoState, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type MoveClipInput, type MoveClipsToStartsInput, type MoveSequentialClipsInput, type MoveVoiceoverInput, type OpActor, type PartAggregation, type PartIdFactory, type PartKind, type PartUnion, type PatchCaptionStyleInput, PlainMemoryAdapter, type PlainMemoryAdapterOptions, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, type ReplaceClipContentInput, type ReplaceMediaClipInput, type ReplaceSequentialClipsInput, type ReplacementMediaClipInput, type ResolvedEntityClipPlacement, type ResolvedEntityTimelineLayout, type ResolvedEntityTrack, SchemaValidator, ScriptCompositionError, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SequentialClipAnchor, type SetBgmInput, type SetCaptionVisibilityInput, type SetClipPlacementInput, type SetClipSpeedInput, type SetClipVolumeInput, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, type TrimClipInput, type UpdateClipInput, type UpdateClipMarkerInput, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftContent, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type VideoMediaAssetFact, type VisualMediaAssetFact, type VoiceMediaAssetFact, type VoiceoverCaptionFact, type VoiceoverTakeInput, type VoiceoverTakeResult, type WaitForServerAckOptions, applyEntityRows, applyFieldChanges, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertFieldChanges, assertMediaAssetWritePolicy, assertValidVideoDocument, audioScriptAssetContent, audioScriptAssetFields, audioScriptAssetHash, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileEntityRows, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hasAudioScriptAsset, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, prepareCaptionContent, projectEntityTimeline, readDocumentAudioScript, readEntityDocument, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };
+export { type Aggregation, type AssembledCaptionContent, type AssembledPhoneticScriptContent, type Attachment, type AudioMediaAssetFact, type BgmPart, type CaptionContentInput, type CaptionDisplayCue, type CaptionPart, type CaptionSegmentSelection, type CaptionStyle, type ClipEntityId, type ClipPlacement, type CommitOptions, DEFAULT_UNIT_TIME_MS, type DeleteBgmInput, type DeleteClipInput, type DeleteClipTreeInput, type DeleteVoiceoverInput, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, type DocumentAudioScript, type DocumentAudioScriptState, type EditorFoundation, EntityDocumentState, type EntityGraphCommitOptions, EntityGraphHttpClient, type EntityGraphState, EntityTimelineEditor, type EntityTimelineIdFactory, EntityTimelineProjectionError, type EntityTimelineTrackRole, type FieldChange, type FieldPath, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImageMediaAssetFact, type ImplementedSemanticOpKind, type ImportedMediaAsset, type InsertCaptionClipInput, type InsertClipInput, type InsertMediaClipInput, type InsertMediaClipsInput, type InsertPlacedClipInput, type JournalEntry, LANE_KINDS_IN_STACK_ORDER, LORO_ENTITY_SCHEMA, type LaneKind, type LinearClipSpeed, LoroEntityDocument, LoroEntityDraft, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, type MediaAssetFact, type MediaClipInsertion, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocSyncState, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUndoState, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type MoveClipInput, type MoveClipsToStartsInput, type MoveSequentialClipsInput, type MoveVoiceoverInput, type OpActor, type PartAggregation, type PartIdFactory, type PartKind, type PartUnion, type PatchCaptionStyleInput, PlainMemoryAdapter, type PlainMemoryAdapterOptions, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, type ReplaceClipContentInput, type ReplaceMediaClipInput, type ReplaceSequentialClipsInput, type ReplacementMediaClipInput, type ResolvedEntityClipPlacement, type ResolvedEntityTimelineLayout, type ResolvedEntityTrack, SchemaValidator, ScriptCompositionError, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SequentialClipAnchor, type SetBgmInput, type SetCaptionVisibilityInput, type SetClipPlacementInput, type SetClipSpeedInput, type SetClipVolumeInput, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, type TrimClipInput, type UpdateClipInput, type UpdateClipMarkerInput, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftContent, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type VideoMediaAssetFact, type VisualMediaAssetFact, type VoiceoverCaptionFact, type VoiceoverMediaAssetFact, type VoiceoverTakeInput, type VoiceoverTakeResult, type WaitForServerAckOptions, applyEntityRows, applyFieldChanges, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertFieldChanges, assertMediaAssetWritePolicy, assertValidVideoDocument, audioScriptAssetContent, audioScriptAssetFields, audioScriptAssetHash, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileEntityRows, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hasAudioScriptAsset, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, prepareCaptionContent, projectEntityTimeline, readDocumentAudioScript, readEntityDocument, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as findLaneTrack, A as assemblePhoneticScriptContent, B as isMediaAssetVariantKind, C as EntityProjectionGraph, D as ScriptCompositionError, E as decodeEntityRelationRows, F as variantBaseEntityIds, G as toVideoDocument, H as buildSpeechHostMap, I as isJsonObject, J as validateVideoDocument, K as VideoDocumentValidationError, L as createEntityId, M as findComposedAudioScript, N as selectAudioScriptSegment, O as assembleCaptionContent, P as updateEntityFields, Q as ensureLaneTrack, R as createRelationId, S as projectEntityTimeline, St as bytesToBase64, T as EntityTimelineProjectionError, U as derivePositionFromAbs, V as buildInitialVideoDocument, W as fromVideoDocument, X as videoDocumentSchema, Y as partUnionSchema, Z as LANE_KINDS_IN_STACK_ORDER, _ as hasAudioScriptAsset, _t as speedOf, a as createMirrorVideoDocument, at as fillMainTrackTimeGaps, b as assertFieldChanges, bt as videoDocumentMirrorSchema, c as DocumentMutationGuard, ct as resolveAllSpeechOverlaps, d as LoroEntityDraft, dt as TIMELINE_SKELETON_DURATION_MS, et as hasResolvedPlacement, f as readEntityDocument, ft as isEmptyVideoClip, g as audioScriptAssetHash, gt as effectiveVideoClipDurationMs, h as audioScriptAssetFields, ht as DEFAULT_UNIT_TIME_MS, i as MirrorVideoDocumentAdapter, it as arrangeMainTrackSeamlessly, j as assembleScriptText, k as assembleEntityContent, l as LORO_ENTITY_SCHEMA, lt as resolveSpeechOverlapByShiftingVideos, m as audioScriptAssetContent, mt as safeDurationMs, n as createPlainMemoryAdapter, nt as solveVideoDocument, o as createMirrorVideoDocumentAdapter, ot as reassignSpeechesToVideoClipsByTime, p as entityOrderGroups, pt as partDurationMs, q as assertValidVideoDocument, r as generatePartId, rt as cascadeAfterVideoClipChanges, s as readVideoDocumentFromDraft, st as recalculateTimelineDuration, t as PlainMemoryAdapter, tt as laneTrackId, u as LoroEntityDocument, ut as syncAggregatedClipsTimePosition, v as equalJson, vt as partUnionToDraft, w as resolveEntityTimelineLayout, x as resolveFieldPath, xt as base64ToBytes, y as applyFieldChanges, yt as recordEntries, z as hasSequence } from "./document-Bnxm1p5E.js";
+import { $ as findLaneTrack, A as assemblePhoneticScriptContent, B as isMediaAssetVariantKind, C as EntityProjectionGraph, D as ScriptCompositionError, E as decodeEntityRelationRows, F as variantBaseEntityIds, G as toVideoDocument, H as buildSpeechHostMap, I as isJsonObject, J as validateVideoDocument, K as VideoDocumentValidationError, L as createEntityId, M as findComposedAudioScript, N as selectAudioScriptSegment, O as assembleCaptionContent, P as updateEntityFields, Q as ensureLaneTrack, R as createRelationId, S as projectEntityTimeline, St as bytesToBase64, T as EntityTimelineProjectionError, U as derivePositionFromAbs, V as buildInitialVideoDocument, W as fromVideoDocument, X as videoDocumentSchema, Y as partUnionSchema, Z as LANE_KINDS_IN_STACK_ORDER, _ as hasAudioScriptAsset, _t as speedOf, a as createMirrorVideoDocument, at as fillMainTrackTimeGaps, b as assertFieldChanges, bt as videoDocumentMirrorSchema, c as DocumentMutationGuard, ct as resolveAllSpeechOverlaps, d as LoroEntityDraft, dt as TIMELINE_SKELETON_DURATION_MS, et as hasResolvedPlacement, f as readEntityDocument, ft as isEmptyVideoClip, g as audioScriptAssetHash, gt as effectiveVideoClipDurationMs, h as audioScriptAssetFields, ht as DEFAULT_UNIT_TIME_MS, i as MirrorVideoDocumentAdapter, it as arrangeMainTrackSeamlessly, j as assembleScriptText, k as assembleEntityContent, l as LORO_ENTITY_SCHEMA, lt as resolveSpeechOverlapByShiftingVideos, m as audioScriptAssetContent, mt as safeDurationMs, n as createPlainMemoryAdapter, nt as solveVideoDocument, o as createMirrorVideoDocumentAdapter, ot as reassignSpeechesToVideoClipsByTime, p as entityOrderGroups, pt as partDurationMs, q as assertValidVideoDocument, r as generatePartId, rt as cascadeAfterVideoClipChanges, s as readVideoDocumentFromDraft, st as recalculateTimelineDuration, t as PlainMemoryAdapter, tt as laneTrackId, u as LoroEntityDocument, ut as syncAggregatedClipsTimePosition, v as equalJson, vt as partUnionToDraft, w as resolveEntityTimelineLayout, x as resolveFieldPath, xt as base64ToBytes, y as applyFieldChanges, yt as recordEntries, z as hasSequence } from "./document-DdwzfZ1g.js";
 import { addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, moveSpeechesInputSchema, moveVideoClipsByAnchorInputSchema, moveVideoClipsInputSchema, replaceVideoClipContentInputSchema, replaceVideoClipSequenceInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, t as schemas_exports } from "./schemas.js";
 import { LoroDoc, UndoManager, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
@@ -579,36 +579,55 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 		"image",
 		"video",
 		"audio",
-		"voice"
+		"voiceover"
 	].includes(fact.kind)) throw new Error("Unsupported media kind");
 	if (fact.kind !== "image" && (!Number.isFinite(fact.durationMs) || fact.durationMs <= 0)) throw new Error(`${fact.kind} ${fact.assetId} requires its factual positive duration`);
-	if ((fact.kind === "audio" || fact.kind === "voice") && fact.storageKey.trim() === "") throw new Error(`${fact.kind} ${fact.assetId} requires its physical storage key`);
+	if ((fact.kind === "audio" || fact.kind === "voiceover") && fact.storageKey.trim() === "") throw new Error(`${fact.kind} ${fact.assetId} requires its physical storage key`);
 	decodeEntityRelationRows(initial, numericCoordinates);
 	assertCanonicalEditorResources(initial);
 	const entities = structuredClone([...initial.entities]);
 	const relations = structuredClone([...initial.relations]);
-	const system = fact.kind === "voice" ? "memota-speech" : "memota";
+	const system = fact.kind === "voiceover" ? "memota-speech" : "memota";
+	const entityKind = fact.kind === "voiceover" ? "audio" : fact.kind;
+	const timbre = fact.kind === "voiceover" ? fact.voice : void 0;
 	const existing = entities.filter((row) => {
 		const external = row.payload.external;
 		return isMediaAssetVariantKind(row.entityKind) && isJsonObject(external) && external.system === system && external.key === fact.assetId;
 	});
+	const requireMatchingVariant = (row) => {
+		const extent = row.payload.extent;
+		if (row.entityKind !== entityKind || fact.kind !== "image" && (!isJsonObject(extent) || extent.start !== 0 || extent.end !== fact.durationMs)) throw new Error(`Media facts conflict with existing identity for ${fact.assetId}`);
+		if (fact.storageKey !== void 0 && row.payload.storageKey !== fact.storageKey) {
+			if (row.payload.storageKey !== void 0) throw new Error(`Media facts conflict with existing storage key for ${fact.assetId}`);
+			return {
+				...row,
+				payload: {
+					...row.payload,
+					storageKey: fact.storageKey
+				}
+			};
+		}
+		return row;
+	};
 	if (existing.length > 1) throw new Error(`Duplicate media identities for ${fact.assetId}; reuse ${existing[0].entityId}`);
 	if (existing[0] !== void 0) {
-		const variant = requireMatchingVariant(existing[0], fact);
+		const variant = requireMatchingVariant(existing[0]);
 		replaceEntity$1(entities, variant.entityId, variant);
+		const voiceEntityId = bindVoiceTimbre(entities, relations, variant.entityId, timbre, idFactory);
 		return {
 			rows: {
 				entities,
 				relations
 			},
-			contentEntityId: variant.entityId
+			contentEntityId: variant.entityId,
+			...voiceEntityId
 		};
 	}
 	const entityId = createEntityId(idFactory("entity"));
 	if (entities.some((row) => row.entityId === entityId)) throw new Error(`Duplicate entity id ${entityId}`);
 	const variant = {
 		entityId,
-		entityKind: fact.kind,
+		entityKind,
 		payload: {
 			extent: fact.kind === "image" ? {
 				kind: "unbounded",
@@ -624,15 +643,11 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 				system,
 				key: fact.assetId
 			},
-			...fact.storageKey === void 0 ? {} : { storageKey: fact.storageKey },
-			...fact.kind === "voice" && fact.voice !== void 0 ? { voice: {
-				system: fact.voice.system,
-				key: fact.voice.key,
-				...fact.voice.name === void 0 ? {} : { name: fact.voice.name }
-			} } : {}
+			...fact.storageKey === void 0 ? {} : { storageKey: fact.storageKey }
 		}
 	};
 	entities.push(variant);
+	const voiceEntityId = bindVoiceTimbre(entities, relations, entityId, timbre, idFactory);
 	const rows = {
 		entities,
 		relations
@@ -641,33 +656,58 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 	assertCanonicalEditorResources(rows);
 	return {
 		rows,
-		contentEntityId: entityId
+		contentEntityId: entityId,
+		...voiceEntityId
 	};
 }
-function requireMatchingVariant(row, fact) {
-	const extent = row.payload.extent;
-	if (row.entityKind !== fact.kind || fact.kind !== "image" && (!isJsonObject(extent) || extent.start !== 0 || extent.end !== fact.durationMs) || fact.kind === "voice" && !sameVoice(row.payload.voice, fact.voice)) throw new Error(`Media facts conflict with existing identity for ${fact.assetId}`);
-	if (fact.storageKey !== void 0 && row.payload.storageKey !== fact.storageKey) {
-		if (row.payload.storageKey !== void 0) throw new Error(`Media facts conflict with existing storage key for ${fact.assetId}`);
-		return {
-			...row,
-			payload: {
-				...row.payload,
-				storageKey: fact.storageKey
-			}
-		};
+/**
+* Attach the timbre a synthesized voiceover was rendered with. One Voice
+* identity is shared by every take naming the same library entry, so an
+* existing row is reused rather than duplicated. Recorded media declares no
+* timbre and keeps no link.
+*/
+function bindVoiceTimbre(entities, relations, audioEntityId, descriptor, idFactory) {
+	const linked = relations.filter((relation) => relation.relationKind === "voice-timbre" && (relation.endpoint0EntityId === audioEntityId || relation.endpoint1EntityId === audioEntityId));
+	if (linked.length > 1) throw new Error(`Voiceover ${audioEntityId} has multiple Voice timbre relations`);
+	if (descriptor === void 0) {
+		if (linked.length > 0) throw new Error(`Recorded media ${audioEntityId} cannot keep a synthesized Voice timbre`);
+		return {};
 	}
-	return row;
+	const voice = entities.find((row) => row.entityKind === "voice" && sameVoiceDescriptor(row.payload.voice, descriptor)) ?? appendVoiceIdentity(entities, descriptor, idFactory);
+	const existing = linked[0];
+	if (existing === void 0) relations.push({
+		relationId: createRelationId(idFactory("relation")),
+		relationKind: "voice-timbre",
+		endpoint0EntityId: createEntityId(audioEntityId),
+		endpoint1EntityId: createEntityId(voice.entityId),
+		metadata: {},
+		trace: {}
+	});
+	else if (existing.endpoint0EntityId !== audioEntityId || existing.endpoint1EntityId !== voice.entityId) throw new Error(`Voiceover ${audioEntityId} already carries a different Voice timbre`);
+	return { voiceEntityId: voice.entityId };
+}
+function appendVoiceIdentity(entities, descriptor, idFactory) {
+	const voice = {
+		entityId: createEntityId(idFactory("entity")),
+		entityKind: "voice",
+		payload: { voice: {
+			system: descriptor.system,
+			key: descriptor.key,
+			...descriptor.name === void 0 ? {} : { name: descriptor.name }
+		} }
+	};
+	entities.push(voice);
+	return voice;
+}
+/** Two takes share a Voice identity only when they name the same library entry. */
+function sameVoiceDescriptor(stored, descriptor) {
+	return isJsonObject(stored) && stored.system === descriptor.system && stored.key === descriptor.key && stored.name === descriptor.name;
 }
 function replaceEntity$1(entities, entityId, replacement) {
 	const index = entities.findIndex((row) => row.entityId === entityId);
 	if (index < 0) throw new Error(`Entity id ${entityId} does not exist`);
 	entities[index] = replacement;
 }
-function sameVoice(left, right) {
-	if (right === void 0) return left === void 0;
-	return isJsonObject(left) && left.system === right.system && left.key === right.key && left.name === right.name && Object.keys(left).every((key) => key === "system" || key === "key" || key === "name");
-}
 //#endregion
 //#region src/entity-editor/entity-timeline-editor.ts
 /**
@@ -1203,20 +1243,20 @@ var EntityTimelineEditor = class {
 				hostClipEntityId: input.hostClipEntityId,
 				anchorOffset: input.anchorOffset
 			};
-			if (input.placement !== void 0 && (input.hostClipEntityId !== void 0 || input.anchorOffset !== void 0)) throw new Error("Specify Voice placement or hostClipEntityId/anchorOffset, not both");
+			if (input.placement !== void 0 && (input.hostClipEntityId !== void 0 || input.anchorOffset !== void 0)) throw new Error("Specify voiceover placement or hostClipEntityId/anchorOffset, not both");
 			requireVolume(input.volume);
 			const imported = importMediaAsset(draft, input.media, this.idFactory);
 			replaceRows(draft, imported.rows);
-			const voice = requireEntityKind(draft, imported.contentEntityId, "voice");
+			const voiceover = requireEntityKind(draft, imported.contentEntityId, "audio");
 			const phonetic = this.requireComposedPhoneticScript(draft, input.phoneticScriptEntityId);
-			this.ensurePhoneticRender(draft, voice.entityId, phonetic.entityId);
+			this.ensurePhoneticRender(draft, voiceover.entityId, phonetic.entityId);
 			const speechTrack = this.ensureRoleTrack(draft, input.timelineEntityId, "speech");
 			const existing = draft.entities.find((row) => row.entityId === input.voiceoverClipEntityId);
 			let voiceoverClipEntityId;
 			if (existing === void 0) voiceoverClipEntityId = this.insertPlacedClipIntoDraft(draft, {
 				clipEntityId: input.voiceoverClipEntityId,
 				trackEntityId: speechTrack.entityId,
-				contentEntityId: voice.entityId,
+				contentEntityId: voiceover.entityId,
 				sourceRange: {
 					start: 0,
 					end: input.media.durationMs
@@ -1240,7 +1280,7 @@ var EntityTimelineEditor = class {
 				});
 				this.relinkRelation(draft, topology.markerContentRelation, {
 					endpoint0EntityId: topology.marker.entityId,
-					endpoint1EntityId: voice.entityId
+					endpoint1EntityId: voiceover.entityId
 				});
 				this.applyClipPlacement(draft, topology.clip.entityId, placement);
 				const placed = requireClipTopology(draft, topology.clip.entityId);
@@ -1259,11 +1299,12 @@ var EntityTimelineEditor = class {
 					}
 				});
 			}
-			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voice.entityId, phonetic.entityId, input.captions);
+			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceover.entityId, phonetic.entityId, input.captions);
 			this.resolveOneVoiceoverOverlap(draft);
 			return {
 				voiceoverClipEntityId,
-				voiceEntityId: voice.entityId,
+				voiceoverAudioEntityId: voiceover.entityId,
+				...imported.voiceEntityId === void 0 ? {} : { voiceEntityId: imported.voiceEntityId },
 				phoneticScriptEntityId: phonetic.entityId,
 				audioScriptEntityId: requireComposedAudioScript(draft, phonetic.entityId),
 				captionClipEntityIds: input.captions.map((caption) => caption.captionClipEntityId)
@@ -1469,23 +1510,23 @@ var EntityTimelineEditor = class {
 		draft.relations.push(this.createRelation(draft, "timeline-track", timeline.entityId, track.entityId));
 		return track;
 	}
-	/** The existing pronunciation variant a Voice consumes; composition is required. */
+	/** The existing pronunciation variant a voiceover consumes; composition is required. */
 	requireComposedPhoneticScript(draft, phoneticScriptEntityId) {
 		const phonetic = requireEntityKind(draft, phoneticScriptEntityId, "phonetic-script");
 		requireComposedAudioScript(draft, phonetic.entityId);
 		return phonetic;
 	}
 	/** Preserve the factual synthesis input, regardless of persisted endpoint positions. */
-	ensurePhoneticRender(draft, voiceEntityId, phoneticScriptEntityId) {
-		const renders = draft.relations.filter((relation) => relation.relationKind === "phonetic-script-render" && (relation.endpoint0EntityId === voiceEntityId || relation.endpoint1EntityId === voiceEntityId));
-		if (renders.length > 1) throw new Error(`Voice "${voiceEntityId}" has multiple PhoneticScript render relations`);
+	ensurePhoneticRender(draft, voiceoverAudioEntityId, phoneticScriptEntityId) {
+		const renders = draft.relations.filter((relation) => relation.relationKind === "phonetic-script-render" && (relation.endpoint0EntityId === voiceoverAudioEntityId || relation.endpoint1EntityId === voiceoverAudioEntityId));
+		if (renders.length > 1) throw new Error(`Voiceover "${voiceoverAudioEntityId}" has multiple PhoneticScript render relations`);
 		if (renders[0] !== void 0) {
-			if (otherEndpoint(renders[0], voiceEntityId) === phoneticScriptEntityId) return;
-			throw new Error(`Voice "${voiceEntityId}" already has a different PhoneticScript synthesis input`);
+			if (otherEndpoint(renders[0], voiceoverAudioEntityId) === phoneticScriptEntityId) return;
+			throw new Error(`Voiceover "${voiceoverAudioEntityId}" already has a different PhoneticScript synthesis input`);
 		}
-		draft.relations.push(this.createRelation(draft, "phonetic-script-render", voiceEntityId, phoneticScriptEntityId));
+		draft.relations.push(this.createRelation(draft, "phonetic-script-render", voiceoverAudioEntityId, phoneticScriptEntityId));
 	}
-	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceEntityId, phoneticScriptEntityId, captions) {
+	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceoverAudioEntityId, phoneticScriptEntityId, captions) {
 		const audioScriptEntityId = requireComposedAudioScript(draft, phoneticScriptEntityId);
 		const requested = new Set(captions.map((caption) => caption.captionClipEntityId));
 		if (requested.size !== captions.length) throw new Error("Caption Clip ids must be unique within a voiceover take");
@@ -1516,7 +1557,7 @@ var EntityTimelineEditor = class {
 				};
 				draft.entities.push(content);
 				assertCaptionScript(draft, content.entityId, audioScriptEntityId);
-				draft.relations.push(this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
+				draft.relations.push(this.createRelation(draft, "caption-alignment", content.entityId, voiceoverAudioEntityId, { alignment: {
 					start: startMs,
 					end: startMs + durationMs
 				} }));
@@ -1573,7 +1614,7 @@ var EntityTimelineEditor = class {
 					}
 				}
 			});
-			this.replaceCaptionAlignment(draft, content.entityId, voiceEntityId, startMs, durationMs);
+			this.replaceCaptionAlignment(draft, content.entityId, voiceoverAudioEntityId, startMs, durationMs);
 		}
 	}
 	ensureRoleTrackForClip(draft, clipEntityId, role) {
@@ -1582,10 +1623,10 @@ var EntityTimelineEditor = class {
 		const timeline = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, track.entityId, "timeline-track"), track.entityId), "timeline");
 		return this.ensureRoleTrack(draft, timeline.entityId, role);
 	}
-	replaceCaptionAlignment(draft, captionEntityId, voiceEntityId, startMs, durationMs) {
+	replaceCaptionAlignment(draft, captionEntityId, voiceoverAudioEntityId, startMs, durationMs) {
 		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment").map((relation) => relation.relationId));
 		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
-		draft.relations.push(this.createRelation(draft, "caption-alignment", captionEntityId, voiceEntityId, { alignment: {
+		draft.relations.push(this.createRelation(draft, "caption-alignment", captionEntityId, voiceoverAudioEntityId, { alignment: {
 			start: startMs,
 			end: startMs + durationMs
 		} }));
@@ -2048,7 +2089,7 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 				relations
 			}, {
 				assetId: speech.origin_speech_id,
-				kind: "voice",
+				kind: "voiceover",
 				durationMs: speech.media_duration_ms,
 				storageKey: speech.audio_storage_key,
 				voice: {
@@ -2136,8 +2177,8 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 			} else if (part.caption !== void 0) {
 				const caption = part.caption;
 				duration = caption.initial_duration_ms;
-				const voice = contentByPartId.get(caption.speech_part_id);
-				const render = relations.find((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voice);
+				const voiceover = contentByPartId.get(caption.speech_part_id);
+				const render = relations.find((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceover);
 				const phonetic = entities.find((entity) => entity.entityId === render?.endpoint1EntityId);
 				const script = phonetic === void 0 ? void 0 : composedAudioScript(phonetic, entities);
 				if (script === void 0) fail("Legacy Caption has no composed AudioScript");
@@ -2164,7 +2205,7 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 					selection,
 					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
 				});
-				link("caption-alignment", content, voice, { alignment: {
+				link("caption-alignment", content, voiceover, { alignment: {
 					start: caption.start_ms,
 					end: caption.start_ms + duration
 				} });
@@ -2503,21 +2544,21 @@ function requirePart(document, partId) {
 	if (part === void 0) fail(`Placed Clip ${partId} has no part payload`);
 	return part;
 }
-function ensureSpeechPhoneticChain(voiceEntityId, audioScriptText, phonemeScript, entities, relations, addEntity, link, documentAudioScriptEntityId) {
-	const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceEntityId);
-	if (renders.length > 1) fail(`Voice ${voiceEntityId} has ambiguous PhoneticScript provenance`);
+function ensureSpeechPhoneticChain(voiceoverAudioEntityId, audioScriptText, phonemeScript, entities, relations, addEntity, link, documentAudioScriptEntityId) {
+	const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceoverAudioEntityId);
+	if (renders.length > 1) fail(`Voiceover ${voiceoverAudioEntityId} has ambiguous PhoneticScript provenance`);
 	if (renders.length === 1) {
 		const phonetic = entities.find((entity) => entity.entityId === renders[0].endpoint1EntityId && entity.entityKind === "phonetic-script");
-		if (phonetic === void 0) fail(`Voice ${voiceEntityId} has a dangling PhoneticScript render`);
+		if (phonetic === void 0) fail(`Voiceover ${voiceoverAudioEntityId} has a dangling PhoneticScript render`);
 		const script = composedAudioScript(phonetic, entities);
-		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
+		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voiceover ${voiceoverAudioEntityId} conflicts with the legacy Speech script`);
 		return phonetic.entityId;
 	}
 	const script = entities.find((entity) => entity.entityId === documentAudioScriptEntityId);
 	if (script === void 0 || script.entityKind !== "audio-script") fail("Migration must carry the fixed document AudioScript");
 	const segments = script.payload.segments;
 	if (Array.isArray(segments) && segments.length > 0) {
-		if (scriptText(script) !== audioScriptText) fail(`Voice ${voiceEntityId} conflicts with the project AudioScript text`);
+		if (scriptText(script) !== audioScriptText) fail(`Voiceover ${voiceoverAudioEntityId} conflicts with the project AudioScript text`);
 	} else {
 		const scriptIndex = entities.findIndex((row) => row.entityId === script.entityId);
 		entities[scriptIndex] = {
@@ -2532,7 +2573,7 @@ function ensureSpeechPhoneticChain(voiceEntityId, audioScriptText, phonemeScript
 		baseEntityIds: [script.entityId],
 		...phonemeScript === void 0 ? {} : { phonemeScript }
 	});
-	link("phonetic-script-render", voiceEntityId, phonetic);
+	link("phonetic-script-render", voiceoverAudioEntityId, phonetic);
 	return phonetic;
 }
 function composedAudioScript(phonetic, entities) {

package/dist/testing.js

@@ -1,4 +1,4 @@
-import { St as bytesToBase64, o as createMirrorVideoDocumentAdapter, xt as base64ToBytes } from "./document-Bnxm1p5E.js";
+import { St as bytesToBase64, o as createMirrorVideoDocumentAdapter, xt as base64ToBytes } from "./document-DdwzfZ1g.js";
 import { t as classifyUpdate } from "./loro-relay-doc-cJSY-uau.js";
 import { LoroDoc, VersionVector, encodeFrontiers } from "loro-crdt";
 //#region src/testing/in-memory-mengine-server.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mengine/medeo-client",
-  "version": "2.0.1-alpha.7",
+  "version": "2.0.1-alpha.8",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -28,9 +28,9 @@
     "immer": "^10.2.0",
     "loro-mirror": "^2.3.3",
     "zod": "^4.4.3",
-    "@mengine/storage": "2.0.1-alpha.7",
-    "@mengine/sync": "2.0.1-alpha.7",
-    "@mengine/utils": "2.0.1-alpha.7"
+    "@mengine/sync": "2.0.1-alpha.8",
+    "@mengine/utils": "2.0.1-alpha.8",
+    "@mengine/storage": "2.0.1-alpha.8"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",