@vivix-ai/ivi-frontend-sdk 0.3.0 → 0.3.2

package/README.md

@@ -45,12 +45,6 @@ pnpm update @vivix-ai/ivi-frontend-sdk
 yarn up @vivix-ai/ivi-frontend-sdk
 ```
 
-### `dist` 与 npm 发布
-
-`package.json` 的 `main` / `module` / `types` / `exports` 均指向 `dist/`，且 npm 包通过 `"files": ["dist"]` 发布到 npm 官方仓库。因此发布前必须先完成构建，确保 npm 包包含可运行、可解析类型的产物。
-
-**协作约定**：修改 `src/` 后必须在本地执行 `npm run build`（或 `pnpm run build`），并将**与本次源码变更对应的一次完整 `dist/` 输出**一并提交：可与功能改动放在**同一提交**，或在必要时单独提交，提交信息示例：`chore: 重新构建 dist`。禁止只改源码而不更新 `dist/`，避免仓库内源码与产物不一致。
-
 ### Peer Dependencies
 
 React 为可选 peer dependency，仅使用 React 组件时需要：
@@ -161,12 +155,29 @@ const unlistenEvent = runtime.onEvent((event, state) => {
   console.log("event:", event.type, "runtime:", state.status);
 });
 
+const unlistenTrtcEvent = runtime.onTrtcEvent((event) => {
+  console.log("trtc event:", event.sourceId, event.type, event.payload);
+});
+
 // 业务结束时
 unlistenState();
 unlistenEvent();
+unlistenTrtcEvent();
 runtime.stop();
 ```
 
+也可以在创建 runtime 时通过 `onTrtcEvent` 配置项统一接收 TRTC SDK 原始事件：
+
+```ts
+const runtime = new IviRuntimeCoordinator(client, {
+  onTrtcEvent: (event) => {
+    // event.type: "remote_video_available" | "remote_video_unavailable" | "remote_audio_available" | "remote_audio_unavailable"
+    // event.rawType: TRTC SDK 原始事件名
+    // event.payload: TRTC SDK 原始事件 payload
+  }
+});
+```
+
 ### 3）发送用户文本并触发模型回复
 
 ```ts
@@ -514,7 +525,27 @@ HLS 流播放器（基于 `hls.js`），由 `IVITrackSlot` 内部用于 `.m3u8`
 >
 > 若需“保留播放/音量，仅隐藏进度条”，请在上层自行渲染自定义控制栏。
 
-### `IVIVolumeControl`（内部组件）
+### `IVIFlvVideo`
+
+FLV 流播放器（基于 `xgplayer` + `xgplayer-flv`），用于 `.flv` 地址播放。`IVITrackSlot` 会按 URL 后缀自动选用。辅助函数 `isFlvUrl(url)` 可判断 URL 是否为 flv。
+
+使用前需安装 peer 依赖：
+
+```bash
+npm install xgplayer xgplayer-flv
+```
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `url` | `string` | FLV 播放地址 |
+| `videoProps` | — | 透传 muted / controls / onEnded 等语义 |
+| `style` | — | 容器样式 |
+| `isLive` | `boolean` | 是否直播，默认 `true` |
+| `paused` | `boolean` | 是否暂停（standby 预加载） |
+
+> 直播 FLV 通常不会触发 `ended`，切换 source 时请使用定时模式而非「播放完毕」。
+
+### `IVIVolumeControl`
 
 音量控制浮层组件，由 `IVITrackSlot` 在 `showVolumeControl` 开启时内部使用；当前不从包根公开导出。
 

package/dist/index.cjs

@@ -1108,8 +1108,9 @@ var ConversationManager = class {
 // src/runtime/managers/trtc-source-manager.ts
 var TAG = "[IVI-TRTC]";
 var TrtcSourceManager = class {
-  constructor(onLog) {
+  constructor(onLog, onTrtcEvent) {
     this.onLog = onLog;
+    this.onTrtcEvent = onTrtcEvent;
     this.sessions = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Map();
   }
@@ -1345,6 +1346,7 @@ var TrtcSourceManager = class {
         session.views.forEach((binding) => {
           void this.startRemoteVideoForBinding(client, event.userId, event.streamType, binding, remoteVideoKey);
         });
+        this.emitTrtcEvent(session.sourceId, "remote_video_available", TRTC.EVENT.REMOTE_VIDEO_AVAILABLE, event);
       };
       const onRemoteVideoUnavailable = (event) => {
         this.log("info", `\u8FDC\u7AEF\u89C6\u9891\u4E0D\u53EF\u7528 source=${session.sourceId} userId=${event.userId} streamType=${event.streamType}`);
@@ -1358,16 +1360,19 @@ var TrtcSourceManager = class {
           userId: event.userId,
           streamType: event.streamType
         }).catch(() => void 0);
+        this.emitTrtcEvent(session.sourceId, "remote_video_unavailable", TRTC.EVENT.REMOTE_VIDEO_UNAVAILABLE, event);
       };
       const onRemoteAudioAvailable = (event) => {
         this.log("info", `\u8FDC\u7AEF\u97F3\u9891\u53EF\u7528 source=${session.sourceId} userId=${event.userId}`);
         session.remoteAudioUsers.add(event.userId);
         void this.applyAudioPolicy(session);
+        this.emitTrtcEvent(session.sourceId, "remote_audio_available", TRTC.EVENT.REMOTE_AUDIO_AVAILABLE, event);
       };
       const onRemoteAudioUnavailable = (event) => {
         this.log("info", `\u8FDC\u7AEF\u97F3\u9891\u4E0D\u53EF\u7528 source=${session.sourceId} userId=${event.userId}`);
         session.remoteAudioUsers.delete(event.userId);
         void this.applyAudioPolicy(session);
+        this.emitTrtcEvent(session.sourceId, "remote_audio_unavailable", TRTC.EVENT.REMOTE_AUDIO_UNAVAILABLE, event);
       };
       session.onRemoteVideoAvailable = onRemoteVideoAvailable;
       session.onRemoteVideoUnavailable = onRemoteVideoUnavailable;
@@ -1540,6 +1545,17 @@ var TrtcSourceManager = class {
       data: extra.length > 0 ? { message, extra } : { message }
     });
   }
+  emitTrtcEvent(sourceId, type, rawType, payload) {
+    const event = {
+      sourceId,
+      type,
+      rawType: String(rawType),
+      payload,
+      userId: payload.userId,
+      streamType: payload.streamType
+    };
+    this.onTrtcEvent?.(event);
+  }
 };
 function isRuntimeTrtcSource(source) {
   return source.status === "ready" && source.playback?.type === "trtc" && typeof source.playback.trtc === "object" && source.playback.trtc !== null;
@@ -2038,6 +2054,7 @@ var IviRuntimeCoordinator = class {
     this.conversationManager = new ConversationManager();
     this.stateListeners = /* @__PURE__ */ new Set();
     this.eventListeners = /* @__PURE__ */ new Set();
+    this.trtcEventListeners = /* @__PURE__ */ new Set();
     this.pendingUserTextToResponseFlows = /* @__PURE__ */ new Map();
     this.userTextFlowCounter = 0;
     this.waitingTracksListValidation = false;
@@ -2057,7 +2074,10 @@ var IviRuntimeCoordinator = class {
       syncStageOnSessionCreated: true,
       ...config
     };
-    this.trtcSourceManager = new TrtcSourceManager(this.config.onLog);
+    this.trtcSourceManager = new TrtcSourceManager(
+      this.config.onLog,
+      (event) => this.emitTrtcEvent(event)
+    );
     this.livekitSourceManager = new LivekitSourceManager(this.config.onLog);
     this.sessionHandler = new SessionEventHandler(this.sessionManager, {
       onSessionCreated: (event) => this.onSessionCreated(event),
@@ -2130,6 +2150,12 @@ var IviRuntimeCoordinator = class {
       this.eventListeners.delete(listener);
     };
   }
+  onTrtcEvent(listener) {
+    this.trtcEventListeners.add(listener);
+    return () => {
+      this.trtcEventListeners.delete(listener);
+    };
+  }
   emitLog(entry) {
     this.config.onLog?.(entry);
   }
@@ -2384,6 +2410,10 @@ var IviRuntimeCoordinator = class {
     this.progressUserTextToResponseFlows(event);
     this.eventListeners.forEach((listener) => listener(event, this.state));
   }
+  emitTrtcEvent(event) {
+    this.config.onTrtcEvent?.(event);
+    this.trtcEventListeners.forEach((listener) => listener(event));
+  }
   resetStoppedState() {
     this.rejectPendingUserTextToResponseFlows(
       new Error("Runtime stopped before user text to response flow completed.")
@@ -3292,6 +3322,132 @@ function IVILivekitPlayer(props) {
     }
   );
 }
+var loadModulesPromise = null;
+async function loadXgplayerModules() {
+  if (!loadModulesPromise) {
+    loadModulesPromise = (async () => {
+      try {
+        await import('xgplayer/dist/index.min.css');
+      } catch (err) {
+        console.warn("[IVIFlvVideo] \u52A0\u8F7D xgplayer \u6837\u5F0F\u5931\u8D25\uFF0C\u64AD\u653E\u5668\u63A7\u4EF6\u53EF\u80FD\u663E\u793A\u5F02\u5E38", err);
+      }
+      const [playerMod, flvMod] = await Promise.all([import('xgplayer'), import('xgplayer-flv')]);
+      const playerModule = playerMod;
+      const flvModule = flvMod;
+      const Player = playerModule.default ?? playerModule.Player;
+      const FlvPlugin = flvModule.default ?? flvModule.FlvPlugin;
+      if (!Player || !FlvPlugin) {
+        throw new Error("xgplayer \u6216 xgplayer-flv \u6A21\u5757\u5BFC\u51FA\u65E0\u6548");
+      }
+      return { Player, FlvPlugin };
+    })().catch((err) => {
+      loadModulesPromise = null;
+      throw err;
+    });
+  }
+  return loadModulesPromise;
+}
+function IVIFlvVideo(props) {
+  const { url, videoProps, style, isLive = true, paused = false } = props;
+  const containerRef = react.useRef(null);
+  const playerRef = react.useRef(null);
+  const pausedRef = react.useRef(paused);
+  const videoPropsRef = react.useRef(videoProps);
+  videoPropsRef.current = videoProps;
+  const reactId = react.useId();
+  const containerId = `ivi-flv-${reactId.replace(/:/g, "")}`;
+  react.useEffect(() => {
+    pausedRef.current = paused;
+    const player = playerRef.current;
+    if (!player) return;
+    if (paused) {
+      player.pause();
+    } else {
+      Promise.resolve(player.play()).catch((err) => {
+        console.warn(
+          "[IVIFlvVideo] paused\u2192active \u5207\u6362\u65F6 play() \u88AB\u6D4F\u89C8\u5668\u62D2\u7EDD\uFF08\u591A\u534A\u53D7\u81EA\u52A8\u64AD\u653E\u7B56\u7565\u9650\u5236\uFF09",
+          err
+        );
+      });
+    }
+  }, [paused]);
+  react.useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    let disposed = false;
+    let endedHandler = null;
+    let errorHandler = null;
+    const setup = async () => {
+      try {
+        const { Player, FlvPlugin } = await loadXgplayerModules();
+        if (disposed || !containerRef.current) return;
+        playerRef.current?.destroy();
+        playerRef.current = null;
+        container.innerHTML = "";
+        const shouldAutoplay = !pausedRef.current;
+        const currentVideoProps = videoPropsRef.current;
+        const muted = Boolean(currentVideoProps?.muted);
+        const player = new Player({
+          id: containerId,
+          el: containerRef.current,
+          url,
+          plugins: [FlvPlugin],
+          isLive,
+          autoplay: shouldAutoplay,
+          autoplayMuted: muted,
+          muted,
+          controls: currentVideoProps?.controls ?? true,
+          width: "100%",
+          height: "100%",
+          fluid: true,
+          videoFillMode: "contain",
+          flv: {
+            retryCount: Number.MAX_SAFE_INTEGER,
+            retryDelay: 500,
+            loadTimeout: 1e4
+          }
+        });
+        playerRef.current = player;
+        errorHandler = (...args) => {
+          console.warn("[IVIFlvVideo] \u64AD\u653E\u5668 error \u4E8B\u4EF6", { url, args });
+        };
+        player.on("error", errorHandler);
+        const onEnded = currentVideoProps?.onEnded;
+        if (onEnded) {
+          endedHandler = () => {
+            videoPropsRef.current?.onEnded?.({});
+          };
+          player.on("ended", endedHandler);
+        }
+        if (!pausedRef.current) {
+          Promise.resolve(player.play()).catch((err) => {
+            console.warn("[IVIFlvVideo] \u521D\u59CB play() \u88AB\u6D4F\u89C8\u5668\u62D2\u7EDD", err);
+          });
+        }
+      } catch (err) {
+        console.warn("[IVIFlvVideo] \u521D\u59CB\u5316 xgplayer-flv \u5931\u8D25", err);
+      }
+    };
+    void setup();
+    return () => {
+      disposed = true;
+      const player = playerRef.current;
+      if (player) {
+        if (endedHandler) player.off("ended", endedHandler);
+        if (errorHandler) player.off("error", errorHandler);
+        player.destroy();
+      }
+      playerRef.current = null;
+      if (containerRef.current) {
+        containerRef.current.innerHTML = "";
+      }
+    };
+  }, [url, isLive, containerId]);
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { id: containerId, ref: containerRef, style: { width: "100%", height: "100%", ...style } });
+}
+function isFlvUrl(url) {
+  return /\.flv(?:$|[?#])/i.test(url);
+}
 var RETRY_DELAY_MS = 500;
 var UNLIMITED_RETRIES = Number.MAX_SAFE_INTEGER;
 var HLS_LOG_TAG = "[IVI-HLS]";
@@ -3648,16 +3804,32 @@ function TrackSlotMediaContent(props) {
     ) : void 0
   };
   const shouldPause = !isActive;
-  return isM3u8Url(playbackUrl) ? /* @__PURE__ */ jsxRuntime.jsx(
-    IVIHlsVideo,
-    {
-      url: playbackUrl,
-      videoProps: mergedVideoProps,
-      style: videoStyle,
-      paused: shouldPause,
-      onLog
-    }
-  ) : /* @__PURE__ */ jsxRuntime.jsx(
+  if (isM3u8Url(playbackUrl)) {
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      IVIHlsVideo,
+      {
+        url: playbackUrl,
+        videoProps: mergedVideoProps,
+        style: videoStyle,
+        paused: shouldPause
+      }
+    );
+  }
+  if (isFlvUrl(playbackUrl)) {
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      IVIFlvVideo,
+      {
+        url: playbackUrl,
+        videoProps: {
+          ...mergedVideoProps,
+          controls: isActive ? videoProps?.controls ?? true : false
+        },
+        style: videoStyle,
+        paused: shouldPause
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxRuntime.jsx(
     SlotVideo,
     {
       src: playbackUrl,