im-rtc-call-engine 1.0.0

package/dist/media/videoProfile.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { VideoProfiles, defaultVideoProfile, videoConstraints } from './videoProfile.js';
+describe('画质档位', () => {
+    it('默认是 720p——1080p 在九宫格里只是白烧上行带宽', () => {
+        expect(defaultVideoProfile).toBe(VideoProfiles.p720);
+    });
+    /*
+      `exact` 会在不支持该分辨率的摄像头上抛 OverconstrainedError，通话直接打不出去。
+      画质是偏好不是硬条件，所以只能用 ideal。
+    */
+    it('约束用 ideal 不用 exact', () => {
+        const constraints = videoConstraints(VideoProfiles.p1080);
+        expect(constraints.width).toEqual({ ideal: 1920 });
+        expect(constraints.height).toEqual({ ideal: 1080 });
+        expect(constraints.frameRate).toEqual({ ideal: 30 });
+        expect(JSON.stringify(constraints)).not.toContain('exact');
+    });
+    /*
+      这个数字要和服务端 internal/sfu/bwe.go 的 bitrateHigh 对得上：
+      那边拿它做带宽预算，对不上的话降层判断是按一个错的数字做的。
+    */
+    it('720p 的码率与服务端 simulcast h 层的目标值一致', () => {
+        expect(VideoProfiles.p720.maxBitrateBps).toBe(1_500_000);
+    });
+});
+//# sourceMappingURL=videoProfile.test.js.map

package/dist/media/videoProfile.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"videoProfile.test.js","sourceRoot":"","sources":["../../src/media/videoProfile.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEzF,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE;IACpB,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH;;;MAGE;IACF,EAAE,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAC5B,MAAM,WAAW,GAAG,gBAAgB,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC1D,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QACrD,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH;;;MAGE;IACF,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/media/viewRegistry.d.ts

@@ -0,0 +1,75 @@
+/**
+ * uid ↔ 视频元素的挂载登记。
+ *
+ * # 为什么这层要存在
+ *
+ * CONVENTIONS §1：**uikit 禁止直接碰 `RTCPeerConnection`**，视频一律经
+ * `engine.attachView(uid, el)` 挂载。有了这条边界，换媒体实现时 uikit 一行不用改。
+ *
+ * # 为什么不能「收到轨道就挂上去」
+ *
+ * 轨道到达与「知道它是谁的」是**两个独立的时序**：`ontrack` 在第一个 RTP 包到达时触发，
+ * 而 `room.track_published`（带 uid）是信令帧，两者谁先到都可能。
+ * 所以这里按 track_id 收轨道、按 uid 认领，**认领可以迟到**——
+ * 迟到时把已经攒着的轨道补挂上去。漏掉这一步的表现是「有声音没画面」，
+ * 且只在网络较快时偶发。
+ */
+/**
+ * ViewElement 是能承载 MediaStream 的元素。取 DOM 的最小交集，便于在测试里做替身。
+ *
+ * `srcObject` 的类型跟 `HTMLMediaElement` 保持一致（`MediaProvider | null`）——
+ * 写成更窄的 `MediaStream | null` 的话，真正的 `<video>` 反而**赋不进来**：
+ * TS 的可变属性是不变的，窄类型不接受宽类型。
+ */
+export interface ViewElement {
+    srcObject: MediaProvider | null;
+}
+/** ViewRegistry 管「哪条轨道属于谁」与「谁挂在哪个元素上」。 */
+export declare class ViewRegistry {
+    /** uid → 该用户的媒体流（音视频合在一条流里，浏览器才会同步播放）。 */
+    private readonly streams;
+    /** uid → 已挂载的元素。 */
+    private readonly views;
+    /** track_id → 还没认领归属的轨道。 */
+    private readonly orphans;
+    /** track_id → uid，认领之后的记账，退订时按 track_id 摘轨道要用。 */
+    private readonly owners;
+    /**
+     * addTrack 收下一条下行轨道。
+     *
+     * uid 为空表示「还不知道是谁的」——先存进 orphans，等 claim 来认领。
+     */
+    addTrack(trackId: string, track: MediaStreamTrack, uid: string): void;
+    /**
+     * claim 认领一条之前不知道归属的轨道。
+     *
+     * engine 在 `room.track_published` 到达、或状态机补上 track_id → uid 之后调它。
+     * 认领不到（轨道还没来）时什么都不做——轨道到达时会走 addTrack 那条路。
+     */
+    claim(trackId: string, uid: string): void;
+    /** removeTrack 摘掉一条轨道（对方停发或退订）。 */
+    removeTrack(trackId: string): void;
+    /**
+     * attach 把某个 uid 的画面挂到元素上；`el` 传 null 表示卸载。
+     *
+     * **卸载必须做**：组件卸载时不清 `srcObject`，被卸掉的 <video> 会连着
+     * MediaStream 一起被引用，画面停了但解码器还占着（CONVENTIONS §5）。
+     */
+    attach(uid: string, el: ViewElement | null): void;
+    /**
+     * claimedTracks 列出**已认领**的 track_id → 归属。
+     *
+     * 给 `MediaBridge.syncRemoteTracks` 做对账用：状态机里已经没有的那些要摘掉。
+     * 返回快照而不是内部 Map——调用方要边遍历边 `removeTrack`。
+     */
+    claimedTracks(): [string, string][];
+    /** viewOf 取某人此刻挂着的元素（没挂为 undefined）。 */
+    viewOf(uid: string): ViewElement | undefined;
+    /** streamFor 取某人的流，宿主想自己挂载时用。 */
+    streamFor(uid: string): MediaStream | undefined;
+    /** clear 清空全部登记（通话结束 / logout）。 */
+    clear(): void;
+    private streamOf;
+    private refresh;
+}
+//# sourceMappingURL=viewRegistry.d.ts.map

package/dist/media/viewRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewRegistry.d.ts","sourceRoot":"","sources":["../../src/media/viewRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,aAAa,GAAG,IAAI,CAAC;CACjC;AAED,0CAA0C;AAC1C,qBAAa,YAAY;IACvB,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,oBAAoB;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,4BAA4B;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IAEpD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAWrE;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAMzC,mCAAmC;IACnC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAelC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI;IAWjD;;;;;OAKG;IACH,aAAa,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;IAInC,wCAAwC;IACxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAI5C,iCAAiC;IACjC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAI/C,mCAAmC;IACnC,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,OAAO;CAKhB"}

package/dist/media/viewRegistry.js

@@ -0,0 +1,130 @@
+/**
+ * uid ↔ 视频元素的挂载登记。
+ *
+ * # 为什么这层要存在
+ *
+ * CONVENTIONS §1：**uikit 禁止直接碰 `RTCPeerConnection`**，视频一律经
+ * `engine.attachView(uid, el)` 挂载。有了这条边界，换媒体实现时 uikit 一行不用改。
+ *
+ * # 为什么不能「收到轨道就挂上去」
+ *
+ * 轨道到达与「知道它是谁的」是**两个独立的时序**：`ontrack` 在第一个 RTP 包到达时触发，
+ * 而 `room.track_published`（带 uid）是信令帧，两者谁先到都可能。
+ * 所以这里按 track_id 收轨道、按 uid 认领，**认领可以迟到**——
+ * 迟到时把已经攒着的轨道补挂上去。漏掉这一步的表现是「有声音没画面」，
+ * 且只在网络较快时偶发。
+ */
+/** ViewRegistry 管「哪条轨道属于谁」与「谁挂在哪个元素上」。 */
+export class ViewRegistry {
+    /** uid → 该用户的媒体流（音视频合在一条流里，浏览器才会同步播放）。 */
+    streams = new Map();
+    /** uid → 已挂载的元素。 */
+    views = new Map();
+    /** track_id → 还没认领归属的轨道。 */
+    orphans = new Map();
+    /** track_id → uid，认领之后的记账，退订时按 track_id 摘轨道要用。 */
+    owners = new Map();
+    /**
+     * addTrack 收下一条下行轨道。
+     *
+     * uid 为空表示「还不知道是谁的」——先存进 orphans，等 claim 来认领。
+     */
+    addTrack(trackId, track, uid) {
+        if (uid === '') {
+            this.orphans.set(trackId, track);
+            return;
+        }
+        this.orphans.delete(trackId);
+        this.owners.set(trackId, uid);
+        this.streamOf(uid).addTrack(track);
+        this.refresh(uid);
+    }
+    /**
+     * claim 认领一条之前不知道归属的轨道。
+     *
+     * engine 在 `room.track_published` 到达、或状态机补上 track_id → uid 之后调它。
+     * 认领不到（轨道还没来）时什么都不做——轨道到达时会走 addTrack 那条路。
+     */
+    claim(trackId, uid) {
+        const track = this.orphans.get(trackId);
+        if (track === undefined || uid === '')
+            return;
+        this.addTrack(trackId, track, uid);
+    }
+    /** removeTrack 摘掉一条轨道（对方停发或退订）。 */
+    removeTrack(trackId) {
+        this.orphans.delete(trackId);
+        const uid = this.owners.get(trackId);
+        if (uid === undefined)
+            return;
+        this.owners.delete(trackId);
+        const stream = this.streams.get(uid);
+        if (stream === undefined)
+            return;
+        for (const track of stream.getTracks()) {
+            if (track.id === trackId)
+                stream.removeTrack(track);
+        }
+        if (stream.getTracks().length === 0)
+            this.streams.delete(uid);
+        this.refresh(uid);
+    }
+    /**
+     * attach 把某个 uid 的画面挂到元素上；`el` 传 null 表示卸载。
+     *
+     * **卸载必须做**：组件卸载时不清 `srcObject`，被卸掉的 <video> 会连着
+     * MediaStream 一起被引用，画面停了但解码器还占着（CONVENTIONS §5）。
+     */
+    attach(uid, el) {
+        if (el === null) {
+            const previous = this.views.get(uid);
+            if (previous !== undefined)
+                previous.srcObject = null;
+            this.views.delete(uid);
+            return;
+        }
+        this.views.set(uid, el);
+        this.refresh(uid);
+    }
+    /**
+     * claimedTracks 列出**已认领**的 track_id → 归属。
+     *
+     * 给 `MediaBridge.syncRemoteTracks` 做对账用：状态机里已经没有的那些要摘掉。
+     * 返回快照而不是内部 Map——调用方要边遍历边 `removeTrack`。
+     */
+    claimedTracks() {
+        return [...this.owners];
+    }
+    /** viewOf 取某人此刻挂着的元素（没挂为 undefined）。 */
+    viewOf(uid) {
+        return this.views.get(uid);
+    }
+    /** streamFor 取某人的流，宿主想自己挂载时用。 */
+    streamFor(uid) {
+        return this.streams.get(uid);
+    }
+    /** clear 清空全部登记（通话结束 / logout）。 */
+    clear() {
+        for (const [, el] of this.views)
+            el.srcObject = null;
+        this.views.clear();
+        this.streams.clear();
+        this.orphans.clear();
+        this.owners.clear();
+    }
+    streamOf(uid) {
+        let stream = this.streams.get(uid);
+        if (stream === undefined) {
+            stream = new MediaStream();
+            this.streams.set(uid, stream);
+        }
+        return stream;
+    }
+    refresh(uid) {
+        const el = this.views.get(uid);
+        if (el === undefined)
+            return;
+        el.srcObject = this.streams.get(uid) ?? null;
+    }
+}
+//# sourceMappingURL=viewRegistry.js.map

package/dist/media/viewRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewRegistry.js","sourceRoot":"","sources":["../../src/media/viewRegistry.ts"],"names":[],"mappings":"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"}

package/dist/media/webrtcAdapter.d.ts

@@ -0,0 +1,158 @@
+import type { PcRole } from '../signaling/enums.js';
+import type { LocalTrackInfo, MediaAdapter, MediaAdapterEvents, MediaSource } from './mediaAdapter.js';
+import type { VideoProfile } from './videoProfile.js';
+/**
+ * 浏览器 WebRTC 的媒体适配器。
+ *
+ * **两条 PeerConnection，各有固定 offerer**（协议 §3.3）：pub 由本端 offer、
+ * sub 由服务端 offer。固定 offerer 就没有 glare，所以这里**没有一行**
+ * perfect negotiation / rollback。
+ *
+ * **不配 iceServers**：SFU 有公网 IP，客户端直连它，不部署 TURN（拍板 §11-2）。
+ */
+export declare class WebRTCAdapter implements MediaAdapter {
+    private readonly source;
+    private pub;
+    private sub;
+    private events;
+    /** cid → 本端轨道。cid 就是轨道的 id（见 LocalTrackInfo）。 */
+    private readonly locals;
+    /** 候选缓存：PC 的远端描述还没设时收到的候选先存着（乱序是常态）。 */
+    private readonly pendingCandidates;
+    /** 采集画质档位。见 videoProfile.ts：**策略归宿主**，不是服务端下发的。 */
+    private readonly video;
+    /** 已经在预览的摄像头。发布时复用它，不重开设备。 */
+    private preview;
+    /** 预览那条轨道是否已经挂到 pub 上。`addTrack` 同一条轨道两次会抛异常。 */
+    private cameraPublished;
+    /**
+     * acquireCamera 已经认领了预览（发布中或已发布）。**进门就置位**，不等预览起完：
+     * 预览还在路上时来一句 `stopLocalPreview`，不能把马上要发布的这条停掉。
+     */
+    private cameraClaimed;
+    /** 摄像头挂上 pub 的 sender。通话中关了再开要靠它 `replaceTrack`，不重新协商。 */
+    private cameraSender;
+    /**
+     * 预览意图的序号：每次 start / stop 加一。
+     * `stopLocalPreview` 等完在起的那一次之后序号变了，说明这期间又有人要了预览——听后来的。
+     */
+    private previewIntent;
+    /** 通话中开关摄像头排成一队：连点时上一次的 getUserMedia 还没回来，下一次不能插队。 */
+    private cameraToggle;
+    /** 已经拿到并挂在 pub 上的麦克风轨道 cid；没有是 null。见 {@link publishedMicrophoneCid}。 */
+    private micCid;
+    /** 麦克风权限已经探过一次。见 `probeMicrophone`：探测不是免费的。 */
+    private micProbed;
+    /** 摄像头权限已经探过一次。见 `probeCamera`。 */
+    private cameraProbed;
+    /**
+     * 正在起的那次预览。**并发的 startLocalPreview / acquireCamera / probeCamera 共用这一次 getUserMedia**。
+     *
+     * 来电页的预览还没起完、用户就点了接听：接听路径要探权限、要起预览、进房后还要发布，
+     * 三处各自去 `getUserMedia` 就是把摄像头开两三次——多出来的那条流没人收，指示灯灭不掉。
+     */
+    private previewOpening;
+    /** close() 一次加一。起到一半被 close 掉的预览靠它认出自己已经作废。 */
+    private closeGeneration;
+    /** source 缺省时用 navigator.mediaDevices；端到端测试可以传合成源。 */
+    constructor(source?: MediaSource, videoProfile?: VideoProfile);
+    open(events: MediaAdapterEvents): void;
+    /** 下一个上行 offer 要不要带 ICE restart。见 restartPubICE()。 */
+    private pubICERestartPending;
+    private createPeer;
+    acquireMicrophone(): Promise<LocalTrackInfo>;
+    probeMicrophone(): Promise<void>;
+    probeCamera(): Promise<void>;
+    /**
+     * startLocalPreview 只起采集，不挂到 pub 上。
+     *
+     * **拨出中就该看得见自己**（草图 §03-E），可那时还没有房间、推不了流。
+     * 所以采集与发布拆成两步，`acquireCamera` 复用这条轨道——
+     * 不复用的话第二次 `getUserMedia` 会去抢同一个摄像头。
+     */
+    startLocalPreview(): Promise<LocalTrackInfo>;
+    /**
+     * stopLocalPreview 停掉**还没发布**的预览，摄像头指示灯随之熄灭（交互稿 §01 v3.7）。
+     *
+     * 进房前（来电页 / 拨出中）关摄像头原先只是把画面藏起来，采集一直开到通话结束。
+     * 已经发布（或正在发布）的不停：通话中关摄像头走 `setMuted`，发送器与协商要留着。
+     */
+    stopLocalPreview(): Promise<void>;
+    private openPreview;
+    acquireCamera(simulcast?: boolean): Promise<LocalTrackInfo>;
+    /**
+     * addVideoTrack 把一条上行视频挂到 pub 上。
+     *
+     * # 为什么不能用 addTrack
+     *
+     * `addTrack` 只会产生**一个 encoding**，浏览器里发 simulcast 必须在建
+     * transceiver 时就把 `sendEncodings` 给出来——协商之后再 `setParameters`
+     * 加层是加不上的（规范不允许改 encoding 的条数）。
+     *
+     * 这正是之前那个洞：`publishCamera(simulcast = true)` 的这个参数一路传进了
+     * `room.publish` 帧、**告诉服务端「我是 simulcast」**，可媒体面走的是裸
+     * `addTrack`，实际只发一层。服务端于是只看到空 RID 的单层（`ridToLayer("")`
+     * 当成 h），层选择无从谈起：订阅者报 `l` 也只能收到全速率的 h
+     * （`selectLayer` 的兜底），弱下行的那一方被自己的全速率流压死。
+     *
+     * `streams: [stream]` 不能省：msid 的第二段就是 cid，服务端靠它认领 m-line
+     * （协议 §3.2）。省掉它服务端永远认不回这条轨道。
+     */
+    private addVideoTrack;
+    /**
+     * acquire 拿一条本端轨道并挂到 pub PC 上。
+     *
+     * `getUserMedia` **只在 localhost / HTTPS 可用**；权限被拒要有明确的界面态与重试，
+     * **不弹 alert**（CONVENTIONS §8）——所以这里只抛结构化错误，界面怎么表现由 uikit 决定。
+     */
+    private acquire;
+    publishedMicrophoneCid(): string | null;
+    /** 摄像头「已发布」= 预览那条轨道真的挂上了 pub（`cameraPublished`），只在预览不算。 */
+    publishedCameraCid(): string | null;
+    /** getStreamOrThrow 取流，并把浏览器的异常收敛成结构化错误。 */
+    private getStreamOrThrow;
+    /**
+     * applyVideoBitrate 给上行视频压一个码率上限。
+     *
+     * **不设的话浏览器会自己往上飙**：Chrome 对 720p 的默认上限远高于我们给
+     * simulcast h 层定的目标值，服务端的带宽预算（`bwe.go` 的 `bitrateHigh`）
+     * 就成了一个对不上的数字，降层判断跟着不准。
+     *
+     * 失败只记日志：码率是画质偏好，`setParameters` 被拒不该让通话打不出去。
+     */
+    private applyVideoBitrate;
+    createPubOffer(): Promise<string>;
+    /**
+     * restartPubICE 让**下一个**上行 offer 带上 ICE restart（换一对新 ufrag/pwd 重新打洞）。
+     *
+     * `pub` 那条 PC 的 offerer 恒为本端（协议 §3.3），它 `failed` 了只能自己救；
+     * `sub` 那条由服务端救——**各自重启自己 offer 的那条**，不需要新的协议帧，也不会 glare。
+     * 做成「置一个位、下一个 offer 生效」而不是「立刻发帧」：发帧是 engine 的事，媒体层不认识信令。
+     */
+    restartPubICE(): void;
+    applyPubAnswer(sdp: string): Promise<void>;
+    answerSubOffer(sdp: string): Promise<string>;
+    /**
+     * addRemoteCandidate 加一个远端候选。
+     *
+     * 远端描述还没设时**缓存起来而不是报错**——trickle ICE 与 offer/answer 天然会赛跑，
+     * 协议要求容忍（§3.3）。
+     */
+    addRemoteCandidate(pc: PcRole, candidate: RTCIceCandidateInit): Promise<void>;
+    private drainCandidates;
+    setMuted(cid: string, muted: boolean): Promise<void>;
+    /**
+     * syncCameraCapture 让已发布摄像头的采集跟上开关（交互稿 §01 v3.7：通话中关摄像头也停采集）。
+     *
+     * 光 `enabled=false` 的话画面是黑了，**摄像头指示灯却一直亮着**。所以关 = `stop()` 掉轨道；
+     * 开 = 重新 getUserMedia，再用 `replaceTrack` 换到同一个 sender 上——
+     * transceiver、msid、cid 都不变，**不重新协商**，服务端只看到这条 Track 又有包了。
+     * 重新采集可能被拒（用户刚在浏览器里收回了权限），错误原样抛给调用方，轨道留在停着的状态。
+     */
+    private syncCameraCapture;
+    localTrack(cid: string): MediaStreamTrack | undefined;
+    close(): void;
+    private requirePub;
+    private requireSub;
+}
+//# sourceMappingURL=webrtcAdapter.d.ts.map

package/dist/media/webrtcAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webrtcAdapter.d.ts","sourceRoot":"","sources":["../../src/media/webrtcAdapter.ts"],"names":[],"mappings":"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"}