wrplayer 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,9 @@
 
 WRPlayer 是一个统一的 Web 视频播放器 SDK，提供一致的 API 来播放多种流媒体协议（WebRTC、HLS、DASH、MP4 等），并可在原生 HTML、Next.js/React 与 Vue 3 环境中复用同一套核心代码。
 
+> **团队集成文档**（npm 安装、Vue/React 示例、PTZ/对讲、生产部署）：见 [docs/INTEGRATION.md](./docs/INTEGRATION.md)  
+> **npm 包**：https://www.npmjs.com/package/wrplayer
+
 ## 特性
 
 - **多协议支持**: WebRTC、HLS、DASH、MP4 等

package/adapters/vue/WRMonitorView.js

@@ -0,0 +1,303 @@
+import { reactive, ref, watch, computed, nextTick } from 'vue';
+import WRPlayer from '../../core/WRPlayer.js';
+import { useWRPlayer } from './useWRPlayer.js';
+
+/**
+ * 开箱即用的监控播放组件：内置加载态、错误提示、重连与基础工具栏
+ */
+export const WRMonitorView = {
+  name: 'WRMonitorView',
+  props: {
+    /** 播放地址，传入后自动开始连接 */
+    url: {
+      type: String,
+      default: ''
+    },
+    /** 流类型，默认 webrtc */
+    type: {
+      type: String,
+      default: 'webrtc'
+    },
+    /** 顶部标题 */
+    title: {
+      type: String,
+      default: '实时监控'
+    },
+    /** 是否显示底部工具栏（停止 / 重连 / 静音） */
+    showToolbar: {
+      type: Boolean,
+      default: true
+    },
+    /** 透传给 WRPlayer 的额外配置（ptz、voiceIntercom 等） */
+    playerOptions: {
+      type: Object,
+      default: () => ({})
+    }
+  },
+  emits: ['ready', 'error', 'stop', 'retry'],
+  setup(props, { emit, expose }) {
+    const isMuted = ref(true);
+    const playerConfig = reactive({
+      url: '',
+      type: props.type,
+      autoplay: true,
+      recvAudio: false,
+      recvVideo: true,
+      debug: false
+    });
+
+    const applyPlayerOptions = () => {
+      const { url, type, autoplay, recvAudio, recvVideo, debug, ...rest } = props.playerOptions || {};
+      Object.assign(playerConfig, {
+        type: type ?? props.type,
+        autoplay: autoplay ?? true,
+        recvAudio: recvAudio ?? false,
+        recvVideo: recvVideo ?? true,
+        debug: debug ?? false,
+        ...rest
+      });
+    };
+
+    const syncUrl = (value) => {
+      playerConfig.url = value || '';
+    };
+
+    applyPlayerOptions();
+    syncUrl(props.url);
+
+    watch(
+      () => props.url,
+      (value) => syncUrl(value)
+    );
+
+    watch(
+      () => props.type,
+      (value) => {
+        playerConfig.type = value;
+      }
+    );
+
+    watch(
+      () => props.playerOptions,
+      () => applyPlayerOptions(),
+      { deep: true }
+    );
+
+    const {
+      elementRef,
+      player,
+      isReady,
+      error,
+      stop: stopPlayer,
+      ptzAvailable,
+      voiceIntercomAvailable,
+      ptz,
+      voiceIntercom
+    } = useWRPlayer(playerConfig);
+
+    const status = computed(() => {
+      if (error.value) return 'error';
+      if (isReady.value) return 'playing';
+      if (playerConfig.url) return 'loading';
+      return 'idle';
+    });
+
+    const statusText = computed(() => {
+      switch (status.value) {
+        case 'loading': return '正在连接视频流…';
+        case 'playing': return '视频流接收正常';
+        case 'error': return '视频流连接失败';
+        default: return '等待播放地址';
+      }
+    });
+
+    watch(isReady, (ready) => {
+      if (ready) emit('ready', player.value);
+    });
+
+    watch(error, (err) => {
+      if (err) emit('error', err);
+    });
+
+    const handleStop = () => {
+      syncUrl('');
+      stopPlayer();
+      emit('stop');
+    };
+
+    const handleRetry = async () => {
+      const current = props.url;
+      if (!current) return;
+      syncUrl('');
+      emit('retry');
+      await nextTick();
+      syncUrl(current);
+    };
+
+    const toggleMute = () => {
+      isMuted.value = !isMuted.value;
+      if (elementRef.value) {
+        elementRef.value.muted = isMuted.value;
+      }
+    };
+
+    expose({
+      player,
+      ptz,
+      voiceIntercom,
+      ptzAvailable,
+      voiceIntercomAvailable,
+      stop: handleStop,
+      retry: handleRetry,
+      status
+    });
+
+    return {
+      elementRef,
+      isMuted,
+      status,
+      statusText,
+      error,
+      handleStop,
+      handleRetry,
+      toggleMute
+    };
+  },
+  template: `
+    <div class="wr-monitor">
+      <div class="wr-monitor__header" v-if="title">
+        <span class="wr-monitor__title">{{ title }}</span>
+        <span class="wr-monitor__badge" :class="'wr-monitor__badge--' + status">
+          {{ statusText }}
+        </span>
+      </div>
+
+      <div class="wr-monitor__viewport">
+        <video
+          ref="elementRef"
+          class="wr-monitor__video"
+          autoplay
+          playsinline
+          :muted="isMuted"
+        />
+
+        <div v-if="status === 'loading'" class="wr-monitor__overlay">
+          <div class="wr-monitor__spinner"></div>
+          <p>正在连接…</p>
+        </div>
+
+        <div v-else-if="status === 'error'" class="wr-monitor__overlay wr-monitor__overlay--error">
+          <p>无法连接视频流</p>
+          <button type="button" class="wr-monitor__btn" @click="handleRetry">重新连接</button>
+        </div>
+
+        <div v-else-if="status === 'idle'" class="wr-monitor__overlay">
+          <p>请传入 url 属性开始播放</p>
+        </div>
+      </div>
+
+      <div v-if="showToolbar" class="wr-monitor__toolbar">
+        <button type="button" class="wr-monitor__btn" @click="toggleMute">
+          {{ isMuted ? '取消静音' : '静音' }}
+        </button>
+        <button type="button" class="wr-monitor__btn" @click="handleRetry" :disabled="!status || status === 'idle'">
+          重连
+        </button>
+        <button type="button" class="wr-monitor__btn wr-monitor__btn--danger" @click="handleStop" :disabled="status === 'idle'">
+          停止
+        </button>
+      </div>
+    </div>
+  `,
+  styles: `
+    .wr-monitor {
+      font-family: system-ui, -apple-system, sans-serif;
+      background: #0f1419;
+      border-radius: 8px;
+      overflow: hidden;
+      color: #e6edf3;
+    }
+    .wr-monitor__header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 10px 14px;
+      background: #161b22;
+      border-bottom: 1px solid #30363d;
+    }
+    .wr-monitor__title { font-size: 14px; font-weight: 600; }
+    .wr-monitor__badge {
+      font-size: 12px;
+      padding: 2px 8px;
+      border-radius: 999px;
+      background: #21262d;
+      color: #8b949e;
+    }
+    .wr-monitor__badge--playing { background: #238636; color: #fff; }
+    .wr-monitor__badge--loading { background: #9e6a03; color: #fff; }
+    .wr-monitor__badge--error { background: #da3633; color: #fff; }
+    .wr-monitor__viewport {
+      position: relative;
+      aspect-ratio: 16 / 9;
+      background: #010409;
+    }
+    .wr-monitor__video {
+      width: 100%;
+      height: 100%;
+      object-fit: contain;
+      display: block;
+      background: #000;
+    }
+    .wr-monitor__overlay {
+      position: absolute;
+      inset: 0;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      gap: 12px;
+      background: rgba(1, 4, 9, 0.72);
+      color: #8b949e;
+      font-size: 14px;
+    }
+    .wr-monitor__overlay--error { color: #f85149; }
+    .wr-monitor__spinner {
+      width: 32px;
+      height: 32px;
+      border: 3px solid #30363d;
+      border-top-color: #58a6ff;
+      border-radius: 50%;
+      animation: wr-monitor-spin 0.8s linear infinite;
+    }
+    @keyframes wr-monitor-spin { to { transform: rotate(360deg); } }
+    .wr-monitor__toolbar {
+      display: flex;
+      gap: 8px;
+      padding: 10px 14px;
+      background: #161b22;
+      border-top: 1px solid #30363d;
+    }
+    .wr-monitor__btn {
+      padding: 6px 12px;
+      font-size: 13px;
+      border: 1px solid #30363d;
+      border-radius: 6px;
+      background: #21262d;
+      color: #e6edf3;
+      cursor: pointer;
+    }
+    .wr-monitor__btn:hover:not(:disabled) { background: #30363d; }
+    .wr-monitor__btn:disabled { opacity: 0.45; cursor: not-allowed; }
+    .wr-monitor__btn--danger { border-color: #da3633; color: #ff7b72; }
+  `
+};
+
+// 注入组件样式（仅一次）
+if (typeof document !== 'undefined' && !document.getElementById('wr-monitor-view-styles')) {
+  const style = document.createElement('style');
+  style.id = 'wr-monitor-view-styles';
+  style.textContent = WRMonitorView.styles;
+  document.head.appendChild(style);
+}
+
+export default WRMonitorView;

package/adapters/vue/index.js

@@ -1,5 +1,10 @@
-import { ref, onMounted, onUnmounted, watch, computed } from 'vue';
+import { watch } from 'vue';
 import WRPlayer from '../../core/WRPlayer.js';
+import { useWRPlayer } from './useWRPlayer.js';
+import { WRMonitorView } from './WRMonitorView.js';
+
+export { useWRPlayer } from './useWRPlayer.js';
+export { WRMonitorView } from './WRMonitorView.js';
 
 const PTZ_EVENTS = [
   'ptz:move', 'ptz:zoom', 'ptz:focus', 'ptz:iris', 'ptz:speed:change',
@@ -14,150 +19,6 @@ const VOICE_INTERCOM_EVENTS = [
   'voiceIntercom:localStream', 'voiceIntercom:remoteStream'
 ];
 
-/**
- * Vue 3 Composition API for WRPlayer with PTZ and Voice Intercom support
- * @param {Object} config - Player configuration
- * @returns {Object} Player instance and utilities
- */
-export function useWRPlayer(config) {
-  const elementRef = ref(null);
-  const player = ref(null);
-  const isReady = ref(false);
-  const error = ref(null);
-  const ptzAvailable = ref(false);
-  const voiceIntercomAvailable = ref(false);
-  const voiceIntercomStatus = ref(null);
-
-  const initPlayer = () => {
-    if (!elementRef.value || !config.url) return;
-
-    try {
-      const wrPlayer = new WRPlayer({
-        element: elementRef.value,
-        ...config
-      });
-
-      player.value = wrPlayer;
-      ptzAvailable.value = !!wrPlayer.ptz;
-      voiceIntercomAvailable.value = !!wrPlayer.voiceIntercom;
-
-      wrPlayer.on('ready', () => {
-        isReady.value = true;
-        error.value = null;
-      });
-
-      wrPlayer.on('error', (errorData) => {
-        error.value = errorData;
-        isReady.value = false;
-      });
-
-      if (wrPlayer.voiceIntercom) {
-        wrPlayer.on('voiceIntercom:statusChange', (data) => {
-          voiceIntercomStatus.value = data;
-        });
-      }
-
-    } catch (err) {
-      error.value = { type: 'init_error', details: err };
-    }
-  };
-
-  const destroyPlayer = () => {
-    if (player.value) {
-      player.value.stop();
-      player.value = null;
-    }
-    isReady.value = false;
-    error.value = null;
-    ptzAvailable.value = false;
-    voiceIntercomAvailable.value = false;
-    voiceIntercomStatus.value = null;
-  };
-
-  const play = () => {
-    if (player.value) {
-      player.value.play();
-    }
-  };
-
-  const pause = () => {
-    if (player.value) {
-      player.value.pause();
-    }
-  };
-
-  const stop = () => {
-    if (player.value) {
-      player.value.stop();
-    }
-  };
-
-  const ptz = computed(() => {
-    if (!ptzAvailable.value || !player.value?.ptz) return null;
-
-    return {
-      move: (direction, speed) => player.value.ptz.move(direction, speed),
-      zoom: (direction, speed) => player.value.ptz.zoom(direction, speed),
-      focus: (direction, speed) => player.value.ptz.focus(direction, speed),
-      iris: (direction, speed) => player.value.ptz.iris(direction, speed),
-      stop: () => player.value.ptz.stop(),
-      setSpeed: (speed) => player.value.ptz.setSpeed(speed),
-      getSpeed: () => player.value.ptz.getSpeed(),
-      preset: player.value.ptz.preset,
-      cruise: player.value.ptz.cruise,
-      scan: player.value.ptz.scan
-    };
-  });
-
-  const voiceIntercom = computed(() => {
-    if (!voiceIntercomAvailable.value || !player.value?.voiceIntercom) return null;
-
-    return {
-      start: (deviceId, channelId, mode) =>
-        player.value.voiceIntercom.startIntercom(deviceId, channelId, mode),
-      stop: () => player.value.voiceIntercom.stopIntercom(),
-      setMode: (mode) => player.value.voiceIntercom.setMode(mode),
-      getStatus: () => player.value.voiceIntercom.getStatus(),
-      status: voiceIntercomStatus.value
-    };
-  });
-
-  watch(
-    () => [config.url, config.type],
-    () => {
-      destroyPlayer();
-      if (config.url) {
-        initPlayer();
-      }
-    }
-  );
-
-  onMounted(() => {
-    if (config.url) {
-      initPlayer();
-    }
-  });
-
-  onUnmounted(() => {
-    destroyPlayer();
-  });
-
-  return {
-    elementRef,
-    player: computed(() => player.value),
-    isReady: computed(() => isReady.value),
-    error: computed(() => error.value),
-    ptzAvailable: computed(() => ptzAvailable.value),
-    voiceIntercomAvailable: computed(() => voiceIntercomAvailable.value),
-    voiceIntercomStatus: computed(() => voiceIntercomStatus.value),
-    play,
-    pause,
-    stop,
-    ptz,
-    voiceIntercom
-  };
-}
-
 /**
  * Vue 3 Component for WRPlayer with PTZ and Voice Intercom support
  */
@@ -375,4 +236,4 @@ export const WRPlayerVue2 = {
   `
 };
 
-export default { useWRPlayer, WRPlayerComponent, WRPlayerVue2 };
+export default { useWRPlayer, WRPlayerComponent, WRPlayerVue2, WRMonitorView };

package/adapters/vue/useWRPlayer.js

@@ -0,0 +1,148 @@
+import { ref, onMounted, onUnmounted, watch, computed } from 'vue';
+import WRPlayer from '../../core/WRPlayer.js';
+
+/**
+ * Vue 3 Composition API for WRPlayer with PTZ and Voice Intercom support
+ * @param {Object} config - Player configuration
+ * @returns {Object} Player instance and utilities
+ */
+export function useWRPlayer(config) {
+  const elementRef = ref(null);
+  const player = ref(null);
+  const isReady = ref(false);
+  const error = ref(null);
+  const ptzAvailable = ref(false);
+  const voiceIntercomAvailable = ref(false);
+  const voiceIntercomStatus = ref(null);
+
+  const initPlayer = () => {
+    if (!elementRef.value || !config.url) return;
+
+    try {
+      const wrPlayer = new WRPlayer({
+        element: elementRef.value,
+        ...config
+      });
+
+      player.value = wrPlayer;
+      ptzAvailable.value = !!wrPlayer.ptz;
+      voiceIntercomAvailable.value = !!wrPlayer.voiceIntercom;
+
+      wrPlayer.on('ready', () => {
+        isReady.value = true;
+        error.value = null;
+      });
+
+      wrPlayer.on('error', (errorData) => {
+        error.value = errorData;
+        isReady.value = false;
+      });
+
+      if (wrPlayer.voiceIntercom) {
+        wrPlayer.on('voiceIntercom:statusChange', (data) => {
+          voiceIntercomStatus.value = data;
+        });
+      }
+
+    } catch (err) {
+      error.value = { type: 'init_error', details: err };
+    }
+  };
+
+  const destroyPlayer = () => {
+    if (player.value) {
+      player.value.stop();
+      player.value = null;
+    }
+    isReady.value = false;
+    error.value = null;
+    ptzAvailable.value = false;
+    voiceIntercomAvailable.value = false;
+    voiceIntercomStatus.value = null;
+  };
+
+  const play = () => {
+    if (player.value) {
+      player.value.play();
+    }
+  };
+
+  const pause = () => {
+    if (player.value) {
+      player.value.pause();
+    }
+  };
+
+  const stop = () => {
+    if (player.value) {
+      player.value.stop();
+    }
+  };
+
+  const ptz = computed(() => {
+    if (!ptzAvailable.value || !player.value?.ptz) return null;
+
+    return {
+      move: (direction, speed) => player.value.ptz.move(direction, speed),
+      zoom: (direction, speed) => player.value.ptz.zoom(direction, speed),
+      focus: (direction, speed) => player.value.ptz.focus(direction, speed),
+      iris: (direction, speed) => player.value.ptz.iris(direction, speed),
+      stop: () => player.value.ptz.stop(),
+      setSpeed: (speed) => player.value.ptz.setSpeed(speed),
+      getSpeed: () => player.value.ptz.getSpeed(),
+      preset: player.value.ptz.preset,
+      cruise: player.value.ptz.cruise,
+      scan: player.value.ptz.scan
+    };
+  });
+
+  const voiceIntercom = computed(() => {
+    if (!voiceIntercomAvailable.value || !player.value?.voiceIntercom) return null;
+
+    return {
+      start: (deviceId, channelId, mode) =>
+        player.value.voiceIntercom.startIntercom(deviceId, channelId, mode),
+      stop: () => player.value.voiceIntercom.stopIntercom(),
+      setMode: (mode) => player.value.voiceIntercom.setMode(mode),
+      getStatus: () => player.value.voiceIntercom.getStatus(),
+      status: voiceIntercomStatus.value
+    };
+  });
+
+  watch(
+    () => [config.url, config.type],
+    () => {
+      destroyPlayer();
+      if (config.url) {
+        initPlayer();
+      }
+    }
+  );
+
+  onMounted(() => {
+    if (config.url) {
+      initPlayer();
+    }
+  });
+
+  onUnmounted(() => {
+    destroyPlayer();
+  });
+
+  return {
+    elementRef,
+    player: computed(() => player.value),
+    isReady: computed(() => isReady.value),
+    error: computed(() => error.value),
+    ptzAvailable: computed(() => ptzAvailable.value),
+    voiceIntercomAvailable: computed(() => voiceIntercomAvailable.value),
+    voiceIntercomStatus: computed(() => voiceIntercomStatus.value),
+    play,
+    pause,
+    stop,
+    ptz,
+    voiceIntercom
+  };
+}
+
+export default useWRPlayer;

package/core/streamUrl.js

@@ -0,0 +1,70 @@
+/**
+ * WVP / ZLM WebRTC 流地址拼接工具
+ */
+
+/**
+ * 拼接 WVP 设备+通道 stream 标识
+ * @param {string} deviceId
+ * @param {string} channelId
+ * @returns {string}
+ */
+export function buildWvpStreamKey(deviceId, channelId) {
+  return `${deviceId}_${channelId}`;
+}
+
+/**
+ * 拼接 WebRTC 播放地址（WVP / ZLM 标准格式）
+ * @param {Object} options
+ * @param {string} options.host - 媒体服务器地址，如 222.222.25.198:6080
+ * @param {string} options.stream - 流 ID
+ * @param {string} [options.app='rtp'] - app 名称
+ * @param {boolean} [options.useSsl=false] - 是否 https
+ * @returns {string}
+ */
+export function buildWebRtcUrl({ host, stream, app = 'rtp', useSsl = false }) {
+  if (!host || !stream) {
+    throw new Error('buildWebRtcUrl: host and stream are required');
+  }
+
+  const base = host.replace(/^https?:\/\//, '').replace(/\/$/, '');
+  const protocol = useSsl ? 'https' : 'http';
+  const params = new URLSearchParams({ app, stream });
+
+  return `${protocol}://${base}/index/api/webrtc?${params.toString()}`;
+}
+
+/**
+ * 根据国标 deviceId + channelId 拼接 WebRTC 地址
+ * @param {Object} options
+ * @param {string} options.host
+ * @param {string} options.deviceId
+ * @param {string} options.channelId
+ * @param {string} [options.app='rtp']
+ * @param {boolean} [options.useSsl=false]
+ * @returns {string}
+ */
+export function buildWebRtcUrlFromDevice({ host, deviceId, channelId, app = 'rtp', useSsl = false }) {
+  return buildWebRtcUrl({
+    host,
+    app,
+    useSsl,
+    stream: buildWvpStreamKey(deviceId, channelId)
+  });
+}
+
+/**
+ * 清理流地址（去除首尾空格、引号）
+ * @param {string} url
+ * @returns {string}
+ */
+export function normalizeStreamUrl(url) {
+  if (!url || typeof url !== 'string') return '';
+  return url.trim().replace(/^["']|["']$/g, '');
+}
+
+export default {
+  buildWvpStreamKey,
+  buildWebRtcUrl,
+  buildWebRtcUrlFromDevice,
+  normalizeStreamUrl
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wrplayer",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A unified web video player SDK supporting WebRTC, HLS, DASH and other formats with PTZ camera control",
   "main": "dist/wrplayer.umd.js",
   "module": "dist/wrplayer.esm.js",
@@ -49,6 +49,7 @@
     },
     "./core": "./core/WRPlayer.js",
     "./core/ptz": "./core/PTZController.js",
+    "./core/streamUrl": "./core/streamUrl.js",
     "./adapters/react": "./adapters/react/index.js",
     "./adapters/vue": "./adapters/vue/index.js",
     "./adapters/vanilla": "./adapters/vanilla/index.js"