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

package/README.md

@@ -380,13 +380,15 @@ function useIviSubtitles(
 ): IviSubtitleItem[];
 ```
 
-基于 runtime 的 conversation / response 事件维护字幕队列，不负责渲染，也不按时间自动消失。默认从 conversation 条目聚合字幕；当 `roles` 包含 `"model"` 且开启 `useModelStreamingTranscript` 时，model 字幕改为使用 `response.output_audio_transcript.*` 事件，`response.output_audio_transcript.done` 只更新文本，只有 `response.done` 才表示这一轮 model 字幕结束。
+基于 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`、`source`、`responseId`、`itemId`。
 
@@ -395,7 +397,10 @@ function CustomSubtitles({ runtime }: { runtime: IviRuntimeCoordinator | null })
   const subtitles = useIviSubtitles(runtime, {
     roles: ["user", "model"],
     maxItems: 5,
-    useModelStreamingTranscript: true
+    useModelStreamingTranscript: true,
+    onSubtitleCompleted: (item) => (
+      item.role === "model" ? { removeAfterMs: 4000 } : { removeAfterMs: 2500 }
+    )
   });
 
   return (
@@ -466,7 +471,7 @@ function useApplyVolumeToSlot(
 | `showVolumeControl` | `boolean` | — | 是否显示音量控制浮层 |
 | `volumeControlProps` | — | — | 音量控制自定义配置 |
 | `showSubtitle` | `boolean` | — | 是否显示字幕浮层 |
-| `subtitleProps` | `Omit<IVISubtitleOverlayProps, "runtime">` | — | 字幕自定义配置，可传 `roles`、`maxItems`、`useModelStreamingTranscript` 等 |
+| `subtitleProps` | `Omit<IVISubtitleOverlayProps, "runtime">` | — | 字幕自定义配置，可传 `roles`、`maxItems`、`useModelStreamingTranscript`、`hideCompletedAfterMs`、`onSubtitleCompleted` 等 |
 | `trtcPlayerProps` | — | — | TRTC 播放器自定义配置 |
 | `livekitPlayerProps` | — | — | LiveKit 播放器自定义配置 |
 | `videoProps` / `imageProps` | — | — | 透传给原生 `<video>` / `<img>` |
@@ -577,6 +582,8 @@ npm install xgplayer xgplayer-flv
 | `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,9 +3080,12 @@ 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")),
@@ -3092,9 +3095,14 @@ function useIviSubtitles(runtime, options = {}) {
   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;
@@ -3150,6 +3158,8 @@ 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;
       }
@@ -3167,6 +3177,78 @@ function useIviSubtitles(runtime, options = {}) {
       syncConversations(state.conversations);
     });
   }, [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) {
@@ -3178,6 +3260,35 @@ 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;
@@ -3191,6 +3302,54 @@ function trimSubtitleItems(items, maxItems) {
   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;
 }
@@ -3316,6 +3475,8 @@ function IVISubtitleOverlay(props) {
     maxItems,
     maxVisible,
     useModelStreamingTranscript,
+    hideCompletedAfterMs,
+    onSubtitleCompleted,
     subtitleStyle,
     className,
     style
@@ -3323,7 +3484,9 @@ function IVISubtitleOverlay(props) {
   const entries = useIviSubtitles(runtime, {
     roles,
     maxItems: maxItems ?? maxVisible,
-    useModelStreamingTranscript
+    useModelStreamingTranscript,
+    hideCompletedAfterMs,
+    onSubtitleCompleted
   });
   if (entries.length === 0) return null;
   const fontFamily = subtitleStyle?.fontFamily ?? "system-ui, -apple-system, sans-serif";
@@ -4414,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;