原始轨道 (Source Track)
        │
        ├── clone() ──▶ 克隆体 A (独立 ID、独立事件、独立 enabled 状态)
        │
        └── clone() ──▶ 克隆体 B (共享同一编码器/摄像头缓冲区)

interface RenderContext {
  element: HTMLVideoElement | HTMLAudioElement;
  track: MediaStreamTrack;
  cleanup: () => void;
}

class TrackSyncManager {
  private source: MediaStreamTrack;
  private clones: Map<string, MediaStreamTrack> = new Map();
  private contexts: Map<string, RenderContext> = new Map();
  private stateSubscribers: Set<(enabled: boolean) => void> = new Set();

  constructor(sourceTrack: MediaStreamTrack) {
    this.source = sourceTrack;
    this.bindSourceEvents();
  }

  /** 创建并注册新渲染上下文 */
  createRenderContext(id: string, element: HTMLVideoElement): RenderContext {
    const clone = this.source.clone();
    this.clones.set(id, clone);

    element.srcObject = new MediaStream([clone]);
    element.play().catch(console.warn);

    const ctx: RenderContext = {
      element,
      track: clone,
      cleanup: () => this.destroyContext(id)
    };
    this.contexts.set(id, ctx);
    return ctx;
  }

  /** 统一控制启用/禁用 */
  setEnabled(enabled: boolean) {
    this.source.enabled = enabled;
    this.clones.forEach(c => c.enabled = enabled);
    this.stateSubscribers.forEach(cb => cb(enabled));
  }

  /** 订阅全局状态变更 */
  onStateChange(cb: (enabled: boolean) => void) {
    this.stateSubscribers.add(cb);
    return () => this.stateSubscribers.delete(cb);
  }

  private bindSourceEvents() {
    this.source.addEventListener('ended', () => this.teardownAll());
    this.source.addEventListener('mute', () => this.broadcastMute(true));
    this.source.addEventListener('unmute', () => this.broadcastMute(false));
  }

  private broadcastMute(muted: boolean) {
    this.contexts.forEach(ctx => {
      ctx.element.muted = muted; // 或触发自定义事件
    });
  }

  private destroyContext(id: string) {
    const clone = this.clones.get(id);
    clone?.stop();
    this.clones.delete(id);
    this.contexts.delete(id);
  }

  private teardownAll() {
    this.clones.forEach(c => c.stop());
    this.clones.clear();
    this.contexts.clear();
  }
}

flowchart LR
    SourceTrack -->|clone()| CloneA[渲染器 A]
    SourceTrack -->|clone()| Processor[MediaStreamTrackProcessor]
    Processor -->|ReadableStream| Transform[TransformStream<br/>AI/水印/录制]
    Transform -->|WritableStream| Generator[MediaStreamTrackGenerator]
    Generator -->|新轨道| CloneB[渲染器 B / MediaRecorder]

// hooks/useTrackRenderer.ts
import { useSyncExternalStore, useRef, useEffect } from 'react';
import { TrackSyncManager } from './TrackSyncManager'; // 上篇核心管理器

interface TrackRendererProps {
  manager: TrackSyncManager;
  renderId: string;          // 业务唯一标识，如 "local-preview" / "remote-user-123-main"
  className?: string;
  onError?: (err: Error) => void;
}

export const VideoTrackRenderer = React.memo(({ manager, renderId, className, onError }: TrackRendererProps) => {
  const videoRef = useRef<HTMLVideoElement>(null);
  const contextRef = useRef<ReturnType<TrackSyncManager['createRenderContext']>>();

  // 1. 订阅轨道启用状态，驱动 UI 禁用态（如静音图标、占位图）
  const isEnabled = useSyncExternalStore(
    manager.onStateChange.bind(manager),
    () => manager.getSourceTrack().enabled,
    () => true // SSR 回退
  );

  // 2. 生命周期绑定：仅在 DOM 挂载时创建上下文，卸载自动清理
  useEffect(() => {
    if (!videoRef.current) return;
    try {
      contextRef.current = manager.createRenderContext(renderId, videoRef.current);
    } catch (e) {
      onError?.(e as Error);
    }
    return () => contextRef.current?.cleanup();
  }, [manager, renderId, onError]);

  // 3. 可见性优化：IntersectionObserver 控制克隆体 enabled，节省解码资源
  useEffect(() => {
    const el = videoRef.current;
    if (!el) return;
    const io = new IntersectionObserver(([entry]) => {
      contextRef.current?.track.enabled = entry.isIntersecting;
    }, { rootMargin: '200px' }); // 提前 200px 解码
    io.observe(el);
    return () => io.disconnect();
  }, []);

  return (
    <video
      ref={videoRef}
      className={className}
      playsInline
      muted={!isEnabled} // 受控静音，避免自动播放策略拦截
      style={{ opacity: isEnabled ? 1 : 0.4, transition: 'opacity 0.2s' }}
      aria-label={`视频流：${renderId}`}
    />
  );
});

<!-- components/VideoTrackRenderer.vue -->
<script setup lang="ts">
import { shallowRef, onMounted, onUnmounted, watchEffect } from 'vue';
import type { TrackSyncManager } from '@/core/TrackSyncManager';

const props = defineProps<{
  manager: TrackSyncManager;
  renderId: string;
}>();
const emit = defineEmits<{ error: [Error] }>();

const videoEl = shallowRef<HTMLVideoElement>();
let ctx: ReturnType<TrackSyncManager['createRenderContext']> | null = null;

onMounted(() => {
  if (!videoEl.value) return;
  try {
    ctx = props.manager.createRenderContext(props.renderId, videoEl.value);
  } catch (e) {
    emit('error', e as Error);
  }
});

onUnmounted(() => ctx?.cleanup());

// 响应式同步 enabled 状态到克隆体（双向绑定示例）
watchEffect(() => {
  if (ctx) ctx.track.enabled = props.manager.getSourceTrack().enabled;
});
</script>

<template>
  <video
    ref="videoEl"
    playsinline
    :muted="!manager.getSourceTrack().enabled"
    class="w-full h-full object-cover"
  />
</template>

sequenceDiagram
    participant Main as 主线程
    participant SW as Service Worker / SharedWorker
    participant MW as Media Worker (Dedicated)
    Main->>SW: getUserMedia() 获取源轨道
    SW->>MW: postMessage({track: sourceTrack}, [sourceTrack]) // Transferable
    MW->>MW: track.clone() x N -> Processor/Generator 管线
    MW->>MW: WebCodecs VideoDecoder/Encoder 硬编硬解
    MW->>Main: postMessage({outputTrack: generator}, [generator])
    Main->>Main: new MediaStream([outputTrack]) -> <video>

// media-worker.ts (Dedicated Worker)
self.onmessage = async (e: MessageEvent<{ track: MediaStreamTrack }>) => {
  const { track } = e.data;
  const processor = new MediaStreamTrackProcessor({ track });
  const generator = new MediaStreamTrackGenerator({ kind: 'video' });

  // 可读流 -> Transform -> 可写流
  const transform = new TransformStream<VideoFrame, VideoFrame>({
    async transform(frame, controller) {
      // 此处接入 WebCodecs / WebNN / WASM 推理
      const processed = await heavyProcessing(frame); // 返回新 VideoFrame
      controller.enqueue(processed);
      frame.close(); // 手动释放引用，关键！
    }
  });

  processor.readable.pipeThrough(transform).pipeTo(generator.writable);

  // 将生成器轨道传回主线程
  self.postMessage({ outputTrack: generator }, [generator]);
};

// main-thread.ts
const worker = new Worker(new URL('./media-worker.ts', import.meta.url));
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [sourceTrack] = stream.getVideoTracks();

worker.postMessage({ track: sourceTrack }, [sourceTrack]);

worker.onmessage = (e: MessageEvent<{ outputTrack: MediaStreamTrack }>) => {
  const { outputTrack } = e.data;
  // outputTrack 可直接赋值给 video.srcObject 或再次 clone 给多渲染器
  videoEl.srcObject = new MediaStream([outputTrack]);
};

async function setupHardwareTranscodePipeline(sourceTrack: MediaStreamTrack) {
  // 1. 克隆源轨道接入 Processor
  const clone = sourceTrack.clone();
  const processor = new MediaStreamTrackProcessor({ track: clone });
  const reader = processor.readable.getReader();

  // 2. 硬件解码器（浏览器自动选择 GPU）
  const decoder = new VideoDecoder({
    output: (frame) => {
      // 业务处理：AI 推理、水印、截图
      handleFrame(frame);
      frame.close();
    },
    error: (e) => console.error('Decoder error:', e)
  });

  // 3. 配置解码器：优先硬件、低延迟
  const config = sourceTrack.getSettings();
  decoder.configure({
    codec: 'avc1.42001f', // H.264 Baseline，根据 getCapabilities 动态选型
    codedWidth: config.width,
    codedHeight: config.height,
    optimizeForLatency: true,
    hardwareAcceleration: 'prefer-hardware'
  });

  // 4. 泵送循环
  try {
    while (true) {
      const { done, value: chunk } = await reader.read();
      if (done) break;
      decoder.decode(chunk);
    }
  } finally {
    await decoder.flush();
    decoder.close();
    clone.stop();
  }
}

// __tests__/TrackSyncManager.test.ts
import { TrackSyncManager } from '../TrackSyncManager';

class MockTrack implements MediaStreamTrack {
  id = crypto.randomUUID();
  kind: 'video' = 'video';
  enabled = true;
  readyState: MediaStreamTrackState = 'live';
  clone() { return new MockTrack(); }
  stop() { this.readyState = 'ended'; this.dispatchEvent(new Event('ended')); }
  addEventListener() {} removeEventListener() {} dispatchEvent() { return true; }
  // ... 其余必选成员存根
}

describe('TrackSyncManager', () => {
  it('should create independent clones with shared source', () => {
    const source = new MockTrack();
    const mgr = new TrackSyncManager(source);
    const ctxA = mgr.createRenderContext('a', document.createElement('video'));
    const ctxB = mgr.createRenderContext('b', document.createElement('video'));

    expect(ctxA.track.id).not.toBe(ctxB.track.id);
    expect(ctxA.track.id).not.toBe(source.id);

    source.enabled = false;
    expect(ctxA.track.enabled).toBe(false);
    expect(ctxB.track.enabled).toBe(false);

    ctxA.cleanup();
    expect(ctxA.track.readyState).toBe('ended');
    expect(ctxB.track.readyState).toBe('live'); // 互不影响
  });

  it('should teardown all on source ended', () => {
    const source = new MockTrack();
    const mgr = new TrackSyncManager(source);
    mgr.createRenderContext('a', document.createElement('video'));
    source.stop(); // 触发 ended
    // 断言内部 clones Map 已清空
  });
});

# .github/workflows/e2e.yml
jobs:
  webrtc-clone:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        browser: [chromium, firefox, webkit]
        device: [desktop, 'iPhone 14', 'Pixel 7']
    steps:
      - uses: actions/checkout@v4
      - uses: microsoft/playwright-github-action@v1
      - run: npm ci && npm run build
      - run: npx playwright test --project=${{ matrix.browser }}-${{ matrix.device }}

// metrics/rtcVitals.ts
export function observeTrackHealth(track: MediaStreamTrack, report: (m: TrackMetrics) => void) {
  let lastFrames = 0, lastTime = performance.now();
  const observer = new PerformanceObserver((list) => {
    for (const entry of list.getEntriesByType('frame')) {
      lastFrames++;
    }
  });
  observer.observe({ type: 'frame', buffered: true });

  setInterval(() => {
    const now = performance.now();
    const fps = (lastFrames / (now - lastTime)) * 1000;
    report({ trackId: track.id, fps, timestamp: now });
    lastFrames = 0; lastTime = now;
  }, 5000);
}

stateDiagram-v2
    [*] --> HEALTHY
    HEALTHY --> DEGRADED: onmute / fps < 5 持续 10s
    DEGRADED --> HEALTHY: onunmute / fps 恢复
    DEGRADED --> REBUILDING: onended / 连续 3 次 decode error
    REBUILDING --> HEALTHY: 重新 getUserMedia / renegotiate 成功
    REBUILDING --> FAILED: 重试 3 次失败
    FAILED --> [*]: 上报告警、展示降级 UI

// Client -> SFU (DataChannel / WebSocket)
{
  "type": "track.clone.request",
  "sourceTrackId": "camera-track-123",
  "cloneId": "preview-renderer-456",
  "constraints": { "width": 320, "height": 180, "frameRate": 15 }
}
// SFU 返回新的 trackId 或直接在现有 Simulcast 流上增加订阅者