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

package/dist/index.d.cts

@@ -627,6 +627,13 @@ interface IVIVolumeControlProps {
 }
 
 type IviSubtitleRole = IviRuntimeConversationItem["role"];
+type IviSubtitleSource = "conversation" | "response_audio_transcript";
+type IviSubtitleCompletedReason = "conversation_done" | "response_done";
+type IviCompletedSubtitleDecision = "keep" | "remove" | {
+    removeAfterMs: number;
+};
+type IviCompletedSubtitleDecisionResult = IviCompletedSubtitleDecision | void | Promise<IviCompletedSubtitleDecision | void>;
+declare const DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS = 3000;
 interface IviSubtitleItem {
     id: string;
     role: IviSubtitleRole;
@@ -637,16 +644,47 @@ interface IviSubtitleItem {
     displayText: string;
     content: IviRuntimeConversationItem["content"];
     item: IviRuntimeConversationItem["item"];
+    /** 字幕数据来源。 */
+    source?: IviSubtitleSource;
+    /** 关联的 response_id；仅 response_audio_transcript 来源有值。 */
+    responseId?: string;
+    /** 关联的 item_id；仅 response_audio_transcript 来源有值。 */
+    itemId?: string;
     /** 首次进入字幕队列的时间戳。 */
     timestamp: number;
     /** 最近一次字幕内容或状态更新的时间戳。 */
     updatedAt: number;
 }
+interface IviSubtitleCompletedContext {
+    /** 当前字幕队列快照。 */
+    entries: readonly IviSubtitleItem[];
+    /** 本次完成态来自 conversation 完成还是 response 完成。 */
+    reason: IviSubtitleCompletedReason;
+    /** 当字幕被移除、会话结束、配置变化或组件卸载时触发。 */
+    signal: AbortSignal;
+}
+type IviSubtitleCompletedHandler = (item: IviSubtitleItem, context: IviSubtitleCompletedContext) => IviCompletedSubtitleDecisionResult;
 interface IviUseSubtitlesOptions {
     /** 要收集的发言人角色，默认 ["user"]。传单个字符串或数组均可。 */
     roles?: IviSubtitleRole | IviSubtitleRole[];
     /** 最多保留的字幕条数，超过后自动清理最旧条目，默认 2。 */
     maxItems?: number;
+    /**
+     * 当 roles 包含 "model" 时，是否使用 response.output_audio_transcript.* 事件作为 model 字幕来源。
+     * 开启后 model 字幕不再从 conversation.* 聚合；response.output_audio_transcript.done 不视为结束，
+     * 只有 response.done 才会把这一轮 model 字幕标记为 done。
+     */
+    useModelStreamingTranscript?: boolean;
+    /**
+     * 字幕进入完成态后多久自动移除，默认 3000ms；传 false 可恢复为一直保留直到被 maxItems 裁剪。
+     * 自定义 onSubtitleCompleted 时，此配置仅作为未提供自定义策略时的默认策略。
+     */
+    hideCompletedAfterMs?: number | false;
+    /**
+     * 字幕进入完成态时调用一次。返回 "remove" 立即删除，返回 { removeAfterMs } 延迟删除，
+     * 返回 "keep" 或 undefined 则保留。异步策略可通过 context.signal 响应取消。
+     */
+    onSubtitleCompleted?: IviSubtitleCompletedHandler;
 }
 /**
  * 监听 runtime 中的 conversation/response 事件，并维护当前应展示的字幕队列。
@@ -672,6 +710,14 @@ interface IVISubtitleOverlayProps {
     maxItems?: number;
     /** @deprecated Use `maxItems` instead. */
     maxVisible?: number;
+    /**
+     * 当 roles 包含 "model" 时，是否使用 response.output_audio_transcript.* 事件作为 model 字幕来源。
+     */
+    useModelStreamingTranscript?: boolean;
+    /** 字幕进入完成态后多久自动移除，默认 3000ms；传 false 可关闭自动移除。 */
+    hideCompletedAfterMs?: IviUseSubtitlesOptions["hideCompletedAfterMs"];
+    /** 字幕进入完成态时的自定义保留/删除策略，优先于 hideCompletedAfterMs。 */
+    onSubtitleCompleted?: IviUseSubtitlesOptions["onSubtitleCompleted"];
     /** 样式配置 */
     subtitleStyle?: IVISubtitleOverlayStyle;
     /** 自定义类名 */
@@ -756,4 +802,4 @@ declare function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRunti
 
 declare function useIviStageView(): IviStageViewContextValue;
 
-export { EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleItem, type IviSubtitleRole, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };

package/dist/index.d.ts

@@ -627,6 +627,13 @@ interface IVIVolumeControlProps {
 }
 
 type IviSubtitleRole = IviRuntimeConversationItem["role"];
+type IviSubtitleSource = "conversation" | "response_audio_transcript";
+type IviSubtitleCompletedReason = "conversation_done" | "response_done";
+type IviCompletedSubtitleDecision = "keep" | "remove" | {
+    removeAfterMs: number;
+};
+type IviCompletedSubtitleDecisionResult = IviCompletedSubtitleDecision | void | Promise<IviCompletedSubtitleDecision | void>;
+declare const DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS = 3000;
 interface IviSubtitleItem {
     id: string;
     role: IviSubtitleRole;
@@ -637,16 +644,47 @@ interface IviSubtitleItem {
     displayText: string;
     content: IviRuntimeConversationItem["content"];
     item: IviRuntimeConversationItem["item"];
+    /** 字幕数据来源。 */
+    source?: IviSubtitleSource;
+    /** 关联的 response_id；仅 response_audio_transcript 来源有值。 */
+    responseId?: string;
+    /** 关联的 item_id；仅 response_audio_transcript 来源有值。 */
+    itemId?: string;
     /** 首次进入字幕队列的时间戳。 */
     timestamp: number;
     /** 最近一次字幕内容或状态更新的时间戳。 */
     updatedAt: number;
 }
+interface IviSubtitleCompletedContext {
+    /** 当前字幕队列快照。 */
+    entries: readonly IviSubtitleItem[];
+    /** 本次完成态来自 conversation 完成还是 response 完成。 */
+    reason: IviSubtitleCompletedReason;
+    /** 当字幕被移除、会话结束、配置变化或组件卸载时触发。 */
+    signal: AbortSignal;
+}
+type IviSubtitleCompletedHandler = (item: IviSubtitleItem, context: IviSubtitleCompletedContext) => IviCompletedSubtitleDecisionResult;
 interface IviUseSubtitlesOptions {
     /** 要收集的发言人角色，默认 ["user"]。传单个字符串或数组均可。 */
     roles?: IviSubtitleRole | IviSubtitleRole[];
     /** 最多保留的字幕条数，超过后自动清理最旧条目，默认 2。 */
     maxItems?: number;
+    /**
+     * 当 roles 包含 "model" 时，是否使用 response.output_audio_transcript.* 事件作为 model 字幕来源。
+     * 开启后 model 字幕不再从 conversation.* 聚合；response.output_audio_transcript.done 不视为结束，
+     * 只有 response.done 才会把这一轮 model 字幕标记为 done。
+     */
+    useModelStreamingTranscript?: boolean;
+    /**
+     * 字幕进入完成态后多久自动移除，默认 3000ms；传 false 可恢复为一直保留直到被 maxItems 裁剪。
+     * 自定义 onSubtitleCompleted 时，此配置仅作为未提供自定义策略时的默认策略。
+     */
+    hideCompletedAfterMs?: number | false;
+    /**
+     * 字幕进入完成态时调用一次。返回 "remove" 立即删除，返回 { removeAfterMs } 延迟删除，
+     * 返回 "keep" 或 undefined 则保留。异步策略可通过 context.signal 响应取消。
+     */
+    onSubtitleCompleted?: IviSubtitleCompletedHandler;
 }
 /**
  * 监听 runtime 中的 conversation/response 事件，并维护当前应展示的字幕队列。
@@ -672,6 +710,14 @@ interface IVISubtitleOverlayProps {
     maxItems?: number;
     /** @deprecated Use `maxItems` instead. */
     maxVisible?: number;
+    /**
+     * 当 roles 包含 "model" 时，是否使用 response.output_audio_transcript.* 事件作为 model 字幕来源。
+     */
+    useModelStreamingTranscript?: boolean;
+    /** 字幕进入完成态后多久自动移除，默认 3000ms；传 false 可关闭自动移除。 */
+    hideCompletedAfterMs?: IviUseSubtitlesOptions["hideCompletedAfterMs"];
+    /** 字幕进入完成态时的自定义保留/删除策略，优先于 hideCompletedAfterMs。 */
+    onSubtitleCompleted?: IviUseSubtitlesOptions["onSubtitleCompleted"];
     /** 样式配置 */
     subtitleStyle?: IVISubtitleOverlayStyle;
     /** 自定义类名 */
@@ -756,4 +802,4 @@ declare function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRunti
 
 declare function useIviStageView(): IviStageViewContextValue;
 
-export { EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleItem, type IviSubtitleRole, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };

package/dist/index.js

@@ -3078,20 +3078,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 = useMemo(
     () => new Set(roleKey.split("\0")),
     [roleKey]
   );
+  const useModelStreamingTranscript = options.useModelStreamingTranscript === true && roleSet.has("model");
   const [subtitles, setSubtitles] = useState([]);
   const seenIdsRef = useRef(/* @__PURE__ */ new Set());
   const initializedRef = useRef(false);
+  const completedSubtitleIdsRef = useRef(/* @__PURE__ */ new Set());
+  const completionControllersRef = useRef(/* @__PURE__ */ new Map());
+  const completionPolicyRef = useRef(null);
   useEffect(() => {
     seenIdsRef.current = /* @__PURE__ */ new Set();
     initializedRef.current = false;
+    completedSubtitleIdsRef.current = /* @__PURE__ */ new Set();
+    abortCompletedSubtitleTasks(completionControllersRef.current);
     setSubtitles([]);
     if (!runtime) {
       return;
@@ -3102,7 +3111,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);
           }
         }
@@ -3111,8 +3120,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(
@@ -3125,7 +3138,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)) {
@@ -3135,10 +3148,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);
@@ -3146,15 +3156,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]);
+  useEffect(() => {
+    return () => {
+      completedSubtitleIdsRef.current = /* @__PURE__ */ new Set();
+      abortCompletedSubtitleTasks(completionControllersRef.current);
+    };
+  }, []);
+  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) {
@@ -3166,6 +3258,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;
 }
@@ -3180,16 +3362,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 {
@@ -3197,13 +3472,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";
@@ -4294,6 +4575,6 @@ function getClientLogTag(category) {
   return "[IVI-CLIENT]";
 }
 
-export { EMPTY_RUNTIME_STATE, IVILivekitPlayer, IVIStageView, IVISubtitleOverlay, IVITrackSlot, IVITrtcPlayer, IviFrontendSdk, IviRuntimeCoordinator, IviRuntimeDispatcher, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, IVIStageView, IVISubtitleOverlay, IVITrackSlot, IVITrtcPlayer, IviFrontendSdk, IviRuntimeCoordinator, IviRuntimeDispatcher, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map