@vivix-ai/ivi-frontend-sdk 0.3.5 → 0.3.7

package/README.md

@@ -380,20 +380,27 @@ function useIviSubtitles(
 ): IviSubtitleItem[];
 ```
 
-基于 runtime 的 conversation / response 事件维护字幕队列，不负责渲染，也不按时间自动消失。
+基于 runtime 的 conversation / response 事件维护字幕队列，不负责渲染。字幕进入完成态后默认 3000ms 自动移除，可通过 `hideCompletedAfterMs={false}` 关闭，或通过 `onSubtitleCompleted` 自定义保留/删除策略。默认从 conversation 条目聚合字幕；当 `roles` 包含 `"model"` 且开启 `useModelStreamingTranscript` 时，model 字幕改为使用 `response.output_audio_transcript.*` 事件，`response.output_audio_transcript.done` 只更新文本，只有 `response.done` 才表示这一轮 model 字幕结束。
 
 | Option | 类型 | 默认值 | 说明 |
 |--------|------|--------|------|
 | `roles` | `IviSubtitleRole \| IviSubtitleRole[]` | `"user"` | 要收集的发言人角色 |
 | `maxItems` | `number` | `2` | 最多保留的字幕条数，超过后清理最旧条目 |
+| `useModelStreamingTranscript` | `boolean` | `false` | 当 `roles` 包含 `"model"` 时，model 字幕是否改用 `response.output_audio_transcript.*` 事件 |
+| `hideCompletedAfterMs` | `number \| false` | `3000` | 字幕进入完成态后多久自动移除；传 `false` 保留到被 `maxItems` 裁剪 |
+| `onSubtitleCompleted` | `(item, context) => "keep" \| "remove" \| { removeAfterMs } \| void \| Promise<...>` | — | 自定义完成态清理策略，优先于 `hideCompletedAfterMs` |
 
-`IviSubtitleItem` 包含 `id`、`role`、`lifecycle`、`status`、`text`、`transcript`、`displayText`、`timestamp`、`updatedAt`、`content`、`item`。
+`IviSubtitleItem` 包含 `id`、`role`、`lifecycle`、`status`、`text`、`transcript`、`displayText`、`timestamp`、`updatedAt`、`content`、`item`、`source`、`responseId`、`itemId`。
 
 ```tsx
 function CustomSubtitles({ runtime }: { runtime: IviRuntimeCoordinator | null }) {
   const subtitles = useIviSubtitles(runtime, {
     roles: ["user", "model"],
-    maxItems: 5
+    maxItems: 5,
+    useModelStreamingTranscript: true,
+    onSubtitleCompleted: (item) => (
+      item.role === "model" ? { removeAfterMs: 4000 } : { removeAfterMs: 2500 }
+    )
   });
 
   return (
@@ -464,7 +471,7 @@ function useApplyVolumeToSlot(
 | `showVolumeControl` | `boolean` | — | 是否显示音量控制浮层 |
 | `volumeControlProps` | — | — | 音量控制自定义配置 |
 | `showSubtitle` | `boolean` | — | 是否显示字幕浮层 |
-| `subtitleProps` | `Omit<IVISubtitleOverlayProps, "runtime">` | — | 字幕自定义配置 |
+| `subtitleProps` | `Omit<IVISubtitleOverlayProps, "runtime">` | — | 字幕自定义配置，可传 `roles`、`maxItems`、`useModelStreamingTranscript`、`hideCompletedAfterMs`、`onSubtitleCompleted` 等 |
 | `trtcPlayerProps` | — | — | TRTC 播放器自定义配置 |
 | `livekitPlayerProps` | — | — | LiveKit 播放器自定义配置 |
 | `videoProps` / `imageProps` | — | — | 透传给原生 `<video>` / `<img>` |
@@ -574,6 +581,9 @@ npm install xgplayer xgplayer-flv
 | `roles` | `IviSubtitleRole \| IviSubtitleRole[]` | `"user"` | 要展示的发言人角色 |
 | `maxItems` | `number` | `2` | 最多保留的字幕条数，超过后清理最旧条目 |
 | `maxVisible` | `number` | — | 已废弃，兼容旧字段；请使用 `maxItems` |
+| `useModelStreamingTranscript` | `boolean` | `false` | 当 `roles` 包含 `"model"` 时，model 字幕是否改用 `response.output_audio_transcript.*` 事件 |
+| `hideCompletedAfterMs` | `number \| false` | `3000` | 字幕进入完成态后多久自动移除；传 `false` 关闭自动移除 |
+| `onSubtitleCompleted` | `(item, context) => "keep" \| "remove" \| { removeAfterMs } \| void \| Promise<...>` | — | 自定义完成态清理策略，优先于 `hideCompletedAfterMs` |
 | `subtitleStyle` | `IVISubtitleOverlayStyle` | — | 样式配置 |
 | `className` / `style` | — | — | 样式 |
 

package/dist/index.cjs

@@ -3080,20 +3080,29 @@ function useApplyVolumeToSlot(containerRef, volume, enabled, activeSourceId) {
     return () => observer.disconnect();
   }, [containerRef, volume, enabled, activeSourceId]);
 }
+var DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS = 3e3;
 function useIviSubtitles(runtime, options = {}) {
   const roles = options.roles ?? "user";
   const maxItems = normalizeMaxItems(options.maxItems);
+  const hideCompletedAfterMs = normalizeHideCompletedAfterMs(options.hideCompletedAfterMs);
+  const onSubtitleCompleted = options.onSubtitleCompleted;
   const roleKey = Array.isArray(roles) ? roles.join("\0") : roles;
   const roleSet = react.useMemo(
     () => new Set(roleKey.split("\0")),
     [roleKey]
   );
+  const useModelStreamingTranscript = options.useModelStreamingTranscript === true && roleSet.has("model");
   const [subtitles, setSubtitles] = react.useState([]);
   const seenIdsRef = react.useRef(/* @__PURE__ */ new Set());
   const initializedRef = react.useRef(false);
+  const completedSubtitleIdsRef = react.useRef(/* @__PURE__ */ new Set());
+  const completionControllersRef = react.useRef(/* @__PURE__ */ new Map());
+  const completionPolicyRef = react.useRef(null);
   react.useEffect(() => {
     seenIdsRef.current = /* @__PURE__ */ new Set();
     initializedRef.current = false;
+    completedSubtitleIdsRef.current = /* @__PURE__ */ new Set();
+    abortCompletedSubtitleTasks(completionControllersRef.current);
     setSubtitles([]);
     if (!runtime) {
       return;
@@ -3104,7 +3113,7 @@ function useIviSubtitles(runtime, options = {}) {
       if (!initializedRef.current) {
         initializedRef.current = true;
         for (const item of conversations) {
-          if (item.lifecycle === "done" || !getDisplayText(item) || !roleSet.has(item.role)) {
+          if (item.lifecycle === "done" || !getDisplayText(item) || !shouldUseConversationRole(item.role, roleSet, useModelStreamingTranscript)) {
             seenIds.add(item.id);
           }
         }
@@ -3113,8 +3122,12 @@ function useIviSubtitles(runtime, options = {}) {
         const conversationMap = new Map(conversations.map((item) => [item.id, item]));
         const nextById = /* @__PURE__ */ new Map();
         for (const previousItem of previous) {
+          if (previousItem.source === "response_audio_transcript") {
+            nextById.set(previousItem.id, previousItem);
+            continue;
+          }
           const conversation = conversationMap.get(previousItem.id);
-          if (!conversation || !roleSet.has(conversation.role) || !getDisplayText(conversation)) {
+          if (!conversation || !shouldUseConversationRole(conversation.role, roleSet, useModelStreamingTranscript) || !getDisplayText(conversation)) {
             continue;
           }
           nextById.set(
@@ -3127,7 +3140,7 @@ function useIviSubtitles(runtime, options = {}) {
           );
         }
         for (const conversation of conversations) {
-          if (!roleSet.has(conversation.role) || !getDisplayText(conversation)) {
+          if (!shouldUseConversationRole(conversation.role, roleSet, useModelStreamingTranscript) || !getDisplayText(conversation)) {
             continue;
           }
           if (seenIds.has(conversation.id)) {
@@ -3137,10 +3150,7 @@ function useIviSubtitles(runtime, options = {}) {
           nextById.set(conversation.id, buildSubtitleItem(conversation, now, now));
         }
         const next = Array.from(nextById.values());
-        if (maxItems === 0) {
-          return [];
-        }
-        return next.length > maxItems ? next.slice(next.length - maxItems) : next;
+        return trimSubtitleItems(next, maxItems);
       });
     };
     syncConversations(runtime.getState().conversations);
@@ -3148,15 +3158,97 @@ function useIviSubtitles(runtime, options = {}) {
       if (event.type === "session.ended") {
         seenIdsRef.current = /* @__PURE__ */ new Set();
         initializedRef.current = false;
+        completedSubtitleIdsRef.current = /* @__PURE__ */ new Set();
+        abortCompletedSubtitleTasks(completionControllersRef.current);
         setSubtitles([]);
         return;
       }
+      if (useModelStreamingTranscript && isModelStreamingTranscriptEvent(event)) {
+        setSubtitles((previous) => trimSubtitleItems(upsertModelStreamingSubtitle(previous, event), maxItems));
+        return;
+      }
+      if (useModelStreamingTranscript && isResponseDoneEvent(event)) {
+        setSubtitles((previous) => trimSubtitleItems(markModelStreamingSubtitleDone(previous, event), maxItems));
+        return;
+      }
       if (!isSubtitleRelatedEvent(event.type)) {
         return;
       }
       syncConversations(state.conversations);
     });
-  }, [runtime, roleSet, maxItems]);
+  }, [runtime, roleSet, maxItems, useModelStreamingTranscript]);
+  react.useEffect(() => {
+    return () => {
+      completedSubtitleIdsRef.current = /* @__PURE__ */ new Set();
+      abortCompletedSubtitleTasks(completionControllersRef.current);
+    };
+  }, []);
+  react.useEffect(() => {
+    const previousPolicy = completionPolicyRef.current;
+    const policyChanged = Boolean(
+      previousPolicy && (previousPolicy.hideCompletedAfterMs !== hideCompletedAfterMs || previousPolicy.onSubtitleCompleted !== onSubtitleCompleted)
+    );
+    completionPolicyRef.current = { hideCompletedAfterMs, onSubtitleCompleted };
+    if (policyChanged) {
+      completedSubtitleIdsRef.current = /* @__PURE__ */ new Set();
+      abortCompletedSubtitleTasks(completionControllersRef.current);
+    }
+    const subtitleById = new Map(subtitles.map((item) => [item.id, item]));
+    const completedIds = completedSubtitleIdsRef.current;
+    const controllers = completionControllersRef.current;
+    for (const [id, controller] of Array.from(controllers)) {
+      const item = subtitleById.get(id);
+      if (!item || !isCompletedSubtitle(item)) {
+        controller.abort();
+        controllers.delete(id);
+        completedIds.delete(id);
+      }
+    }
+    for (const id of Array.from(completedIds)) {
+      const item = subtitleById.get(id);
+      if (!item || !isCompletedSubtitle(item)) {
+        completedIds.delete(id);
+      }
+    }
+    for (const item of subtitles) {
+      if (!isCompletedSubtitle(item) || completedIds.has(item.id)) {
+        continue;
+      }
+      completedIds.add(item.id);
+      const controller = new AbortController();
+      controllers.set(item.id, controller);
+      const context = {
+        entries: subtitles,
+        reason: getSubtitleCompletedReason(item),
+        signal: controller.signal
+      };
+      let decisionResult;
+      try {
+        decisionResult = onSubtitleCompleted ? onSubtitleCompleted(item, context) : getDefaultCompletedSubtitleDecision(hideCompletedAfterMs);
+      } catch {
+        decisionResult = "keep";
+      }
+      void Promise.resolve(decisionResult).then((decision) => {
+        applyCompletedSubtitleDecision(
+          item.id,
+          decision,
+          controller,
+          controllers,
+          completedIds,
+          (id) => setSubtitles((previous) => removeSubtitleById(previous, id))
+        );
+      }).catch(() => {
+        applyCompletedSubtitleDecision(
+          item.id,
+          "keep",
+          controller,
+          controllers,
+          completedIds,
+          (id) => setSubtitles((previous) => removeSubtitleById(previous, id))
+        );
+      });
+    }
+  }, [subtitles, hideCompletedAfterMs, onSubtitleCompleted]);
   return subtitles;
 }
 function normalizeMaxItems(maxItems) {
@@ -3168,6 +3260,96 @@ function normalizeMaxItems(maxItems) {
   }
   return Math.max(0, Math.floor(maxItems));
 }
+function normalizeHideCompletedAfterMs(hideCompletedAfterMs) {
+  if (hideCompletedAfterMs === false) {
+    return false;
+  }
+  if (hideCompletedAfterMs === void 0 || !Number.isFinite(hideCompletedAfterMs)) {
+    return DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS;
+  }
+  return Math.max(0, Math.floor(hideCompletedAfterMs));
+}
+function getDefaultCompletedSubtitleDecision(hideCompletedAfterMs) {
+  if (hideCompletedAfterMs === false) {
+    return "keep";
+  }
+  return hideCompletedAfterMs === 0 ? "remove" : { removeAfterMs: hideCompletedAfterMs };
+}
+function normalizeCompletedSubtitleDecision(decision) {
+  if (decision === "keep" || decision === "remove") {
+    return decision;
+  }
+  if (decision && typeof decision === "object" && "removeAfterMs" in decision) {
+    const removeAfterMs = Number(decision.removeAfterMs);
+    if (!Number.isFinite(removeAfterMs)) {
+      return "keep";
+    }
+    const normalized = Math.max(0, Math.floor(removeAfterMs));
+    return normalized === 0 ? "remove" : { removeAfterMs: normalized };
+  }
+  return "keep";
+}
+function shouldUseConversationRole(role, roleSet, useModelStreamingTranscript) {
+  if (!roleSet.has(role)) {
+    return false;
+  }
+  return !(useModelStreamingTranscript && role === "model");
+}
+function trimSubtitleItems(items, maxItems) {
+  if (maxItems === 0) {
+    return [];
+  }
+  const sorted = [...items].sort((a, b) => a.timestamp - b.timestamp);
+  return sorted.length > maxItems ? sorted.slice(sorted.length - maxItems) : sorted;
+}
+function isCompletedSubtitle(item) {
+  return item.lifecycle === "done" || item.status === "completed" || item.status === "incomplete";
+}
+function getSubtitleCompletedReason(item) {
+  return item.source === "response_audio_transcript" || item.role === "model" ? "response_done" : "conversation_done";
+}
+function abortCompletedSubtitleTasks(controllers) {
+  for (const controller of controllers.values()) {
+    controller.abort();
+  }
+  controllers.clear();
+}
+function applyCompletedSubtitleDecision(itemId, decision, controller, controllers, completedIds, removeSubtitle) {
+  if (controller.signal.aborted) {
+    return;
+  }
+  const normalizedDecision = normalizeCompletedSubtitleDecision(decision);
+  if (normalizedDecision === "keep") {
+    controllers.delete(itemId);
+    return;
+  }
+  const remove = () => {
+    if (controller.signal.aborted) {
+      return;
+    }
+    controllers.delete(itemId);
+    completedIds.delete(itemId);
+    removeSubtitle(itemId);
+  };
+  if (normalizedDecision === "remove") {
+    remove();
+    return;
+  }
+  const timeout = setTimeout(remove, normalizedDecision.removeAfterMs);
+  controller.signal.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(timeout);
+    },
+    { once: true }
+  );
+}
+function removeSubtitleById(items, itemId) {
+  if (!items.some((item) => item.id === itemId)) {
+    return items;
+  }
+  return items.filter((item) => item.id !== itemId);
+}
 function getDisplayText(item) {
   return item.text || item.transcript;
 }
@@ -3182,16 +3364,109 @@ function buildSubtitleItem(item, timestamp, updatedAt) {
     displayText: getDisplayText(item),
     content: item.content,
     item: item.item,
+    source: "conversation",
     timestamp,
     updatedAt
   };
 }
+function upsertModelStreamingSubtitle(previous, event, now = Date.now()) {
+  const responseId = getEventString(event, "responseId", "response_id");
+  if (!responseId) {
+    return previous;
+  }
+  const displayText = event.type === "response.output_audio_transcript.done" ? event.transcript : event.delta;
+  if (typeof displayText !== "string" || displayText.length === 0) {
+    return previous;
+  }
+  const id = buildModelStreamingSubtitleId(responseId);
+  const itemId = getEventString(event, "itemId", "item_id");
+  const existing = previous.find((item) => item.id === id);
+  const nextItem = {
+    id,
+    role: "model",
+    lifecycle: "added",
+    status: "in_progress",
+    text: "",
+    transcript: displayText,
+    displayText,
+    content: [],
+    item: {
+      id: itemId ?? id,
+      type: "message",
+      role: "model",
+      status: "in_progress",
+      content: [{ type: "audio", transcript: displayText }]
+    },
+    source: "response_audio_transcript",
+    responseId,
+    itemId,
+    timestamp: existing?.timestamp ?? now,
+    updatedAt: hasStreamingSubtitleChanged(existing, displayText) ? now : existing?.updatedAt ?? now
+  };
+  return replaceSubtitleItem(previous, nextItem);
+}
+function markModelStreamingSubtitleDone(previous, event, now = Date.now()) {
+  const responseId = event.response?.id;
+  if (!responseId) {
+    return previous;
+  }
+  const id = buildModelStreamingSubtitleId(responseId);
+  const status = mapResponseStatusToConversationStatus(event.response?.status);
+  return previous.map((item) => {
+    if (item.id !== id || item.source !== "response_audio_transcript") {
+      return item;
+    }
+    return {
+      ...item,
+      lifecycle: "done",
+      status,
+      item: {
+        ...item.item,
+        status
+      },
+      updatedAt: now
+    };
+  });
+}
+function replaceSubtitleItem(previous, nextItem) {
+  const replaced = previous.map((item) => item.id === nextItem.id ? nextItem : item);
+  if (replaced.some((item) => item.id === nextItem.id)) {
+    return replaced;
+  }
+  return [...previous, nextItem];
+}
+function hasStreamingSubtitleChanged(previous, nextDisplayText) {
+  return !previous || previous.displayText !== nextDisplayText || previous.lifecycle !== "added" || previous.status !== "in_progress";
+}
+function buildModelStreamingSubtitleId(responseId) {
+  return `model-response:${responseId}`;
+}
+function getEventString(event, camelKey, snakeKey) {
+  const record = event;
+  const value = record[camelKey] ?? record[snakeKey];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function mapResponseStatusToConversationStatus(status) {
+  if (status === "completed") {
+    return "completed";
+  }
+  if (status === "in_progress") {
+    return "in_progress";
+  }
+  return "incomplete";
+}
 function hasSubtitleChanged(previous, next) {
   return previous.text !== next.text || previous.transcript !== next.transcript || previous.lifecycle !== next.lifecycle || previous.status !== next.status || previous.role !== next.role;
 }
 function isSubtitleRelatedEvent(type) {
   return type.startsWith("conversation.") || type.startsWith("response.");
 }
+function isModelStreamingTranscriptEvent(event) {
+  return event.type === "response.output_audio_transcript.delta" || event.type === "response.output_audio_transcript.done";
+}
+function isResponseDoneEvent(event) {
+  return event.type === "response.done";
+}
 var BREATHE_KEYFRAMES = `@keyframes ivi-subtitle-breathe{0%,100%{opacity:1}50%{opacity:.55}}`;
 function IVISubtitleOverlay(props) {
   const {
@@ -3199,13 +3474,19 @@ function IVISubtitleOverlay(props) {
     roles = "user",
     maxItems,
     maxVisible,
+    useModelStreamingTranscript,
+    hideCompletedAfterMs,
+    onSubtitleCompleted,
     subtitleStyle,
     className,
     style
   } = props;
   const entries = useIviSubtitles(runtime, {
     roles,
-    maxItems: maxItems ?? maxVisible
+    maxItems: maxItems ?? maxVisible,
+    useModelStreamingTranscript,
+    hideCompletedAfterMs,
+    onSubtitleCompleted
   });
   if (entries.length === 0) return null;
   const fontFamily = subtitleStyle?.fontFamily ?? "system-ui, -apple-system, sans-serif";
@@ -4296,6 +4577,7 @@ function getClientLogTag(category) {
   return "[IVI-CLIENT]";
 }
 
+exports.DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS = DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS;
 exports.EMPTY_RUNTIME_STATE = EMPTY_RUNTIME_STATE;
 exports.IVILivekitPlayer = IVILivekitPlayer;
 exports.IVIStageView = IVIStageView;