@observertc/observer-js 1.0.0-beta.5 → 1.0.0-beta.6

package/README.md

@@ -104,9 +104,8 @@ import { Observer, ClientSample } from '@observertc/observer-js';
 
 // 1. Create an observer.
 const observer = new Observer({
-  // how often the observer aggregates call/client metrics:
-  updatePolicy: 'update-on-interval',
-  updateIntervalInMs: 5000,
+  // when the observer aggregates call/client metrics:
+  updatePolicy: 'update-when-all-call-updated',
   // default policy applied to calls created automatically by accept():
   defaultCallUpdatePolicy: 'update-on-any-client-updated',
   // optional auto-teardown:
@@ -177,7 +176,7 @@ client getStats()  ──►  ClientSample  ──►  observer.accept(sample, c
 |-------|-----------|------------------------|-------|
 | `Observer` | `new Observer(config?)` | — (root) | `observedCalls: Map<string, ObservedCall>`, global counters, the event bus |
 | `ObservedCall` | `observer.createObservedCall(settings)` / lazily by `accept` | `observedCalls` | `observedClients: Map<string, ObservedClient>`, call-wide metrics, `detectors`, `scoreCalculator` |
-| `ObservedClient` | `call.createObservedClient(settings)` / lazily | `observedClients` | `observedPeerConnections: Map<string, ObservedPeerConnection>`, per-client metrics, `report` |
+| `ObservedClient` | `call.createObservedClient(settings)` / lazily | `observedClients` | `observedPeerConnections: Map<string, ObservedPeerConnection>`, per-client metrics |
 | `ObservedPeerConnection` | lazily, from `sample.peerConnections[]` | `observedPeerConnections` | the 15 sub-stat maps below, transport/RTT/bitrate metrics |
 | Sub-stats | lazily, from the `PeerConnectionSample` | maps on the PC | individual WebRTC stat objects |
 
@@ -206,12 +205,49 @@ fields from the schema plus derived fields (deltas, bitrates).
 
 The single entry point. It:
 
-1. drops + emits `sample-rejected` if the observer is closed, or `callId`/`clientId` is missing;
-2. gets or lazily creates the `ObservedCall` and `ObservedClient`;
-3. shallow-merges `context` into the created/looked-up entity `appData`;
-4. delegates to `client.accept(sample, context)`, which fans out to each
+1. drops + emits `sample-rejected` if the observer is closed;
+2. runs the sample through the **global accept-middleware chain** (see below);
+3. (chain terminal) drops + emits `sample-rejected` if `callId`/`clientId` is missing;
+4. gets or lazily creates the `ObservedCall` and `ObservedClient` (their `appData` comes from the
+   configured factories, never from `context`);
+5. delegates to `client.accept(sample, context)`, which fans out to each
    `ObservedPeerConnection.accept(pcSample, context)`.
 
+### Accept middlewares (global pre-dispatch hook)
+
+`observer.addAcceptMiddleware(...)` registers middlewares run on **every** sample inside
+`accept()`, in order, **before** the sample is dispatched to any call or client. Each middleware
+gets a `{ sample, context }` payload; it can inspect or mutate the sample (set/normalize
+`callId`/`clientId`, enrich, redact) or the context, then call `next(payload)` to continue.
+**Not calling `next` drops the sample** — nothing is created and no event fires. A throwing
+middleware is caught and warns (the sample is dropped), never crashing `accept()`.
+
+```ts
+import { Observer, AcceptMiddleware } from '@observertc/observer-js';
+
+const observer = new Observer();
+
+// derive callId/clientId from the app's own attachment, before dispatch
+const route: AcceptMiddleware = ({ sample }, next) => {
+  sample.callId ??= sample.attachments?.roomId as string;
+  sample.clientId ??= sample.attachments?.peerId as string;
+  next({ sample });
+};
+
+// drop samples from a blocklisted client (never dispatched)
+const filter: AcceptMiddleware = (payload, next) => {
+  if (blocked.has(payload.sample.clientId)) return;   // no next() => dropped
+  next(payload);
+};
+
+observer.addAcceptMiddleware(route, filter);
+// observer.removeAcceptMiddleware(route);
+```
+
+This is a lightweight global injection point, distinct from the larger (not-yet-built)
+`ClientSampleProcessor` pipeline in the roadmap. When no middleware is registered, `accept()`
+dispatches directly with no overhead.
+
 ### `context` (the `AcceptContext`)
 
 ```ts
@@ -259,9 +295,9 @@ These return `undefined` (and warn) when the parent is closed; `createObservedCa
 ## Update policies
 
 "Update" means *recompute aggregated metrics and emit the `*-updated` event* at that level.
-Both the observer and each call have a configurable trigger. The `update-on-interval` policy
-**requires** an interval and this is enforced at compile time (a discriminated union); at
-runtime a missing interval warns and falls back rather than throwing.
+Both the observer and each call have a configurable trigger. Updates are **event-driven** — there
+is no built-in timer. An app that wants a fixed cadence can call `observer.update()` /
+`call.update()` from its own `setInterval`.
 
 **Observer-level** (`ObserverConfig.updatePolicy`, default `update-when-all-call-updated`):
 
@@ -269,7 +305,6 @@ runtime a missing interval warns and falls back rather than throwing.
 |--------|-------------------------------------|
 | `update-on-any-call-updated` | any call updates |
 | `update-when-all-call-updated` | every call has updated since the last observer update |
-| `update-on-interval` | a timer fires (`updateIntervalInMs` required) |
 
 **Call-level** (`ObservedCallSettings.updatePolicy`, defaulted from
 `ObserverConfig.defaultCallUpdatePolicy`):
@@ -278,7 +313,6 @@ runtime a missing interval warns and falls back rather than throwing.
 |--------|--------------------------------|
 | `update-on-any-client-updated` | any client in the call updates |
 | `update-when-all-client-updated` | every client has updated since the last call update |
-| `update-on-interval` | a timer fires (`updateIntervalInMs` required) |
 
 ---
 
@@ -353,7 +387,6 @@ additional field(s) on top of that scope.
 | `client-metadata` | `{ metaData: ClientMetaData }` | a client meta item arrived |
 | `client-extension-stats` | `{ extensionStats: ExtensionStat }` | an app-defined extension stat arrived |
 | `client-event` | `{ event: ClientEvent }` | any client event was processed |
-| `client-track-report` | `{ report: TrackReport }` | a track was removed; final per-track report |
 
 #### Peer-connection level — scope `{ observer, observedCall, observedClient, observedPeerConnection }`
 
@@ -403,12 +436,9 @@ listen to them, but prefer the bus equivalents above for application logic.
 ```ts
 new Observer<AppData>(config?: ObserverConfig<AppData>)
 
-type ObserverConfig<AppData = Record<string, unknown>> =
-  ( { updatePolicy: 'update-on-interval'; updateIntervalInMs: number }
-  | { updatePolicy?: 'update-on-any-call-updated' | 'update-when-all-call-updated'; updateIntervalInMs?: number }
-  ) & {
+type ObserverConfig<AppData = Record<string, unknown>> = {
+    updatePolicy?: 'update-on-any-call-updated' | 'update-when-all-call-updated';
     defaultCallUpdatePolicy?: ObservedCallSettings['updatePolicy'];
-    defaultCallUpdateIntervalInMs?: number;
     appData?: AppData;
     closeClientIfIdleForMs?: number;
     closeCallIfEmptyForMs?: number;
@@ -418,6 +448,8 @@ type ObserverConfig<AppData = Record<string, unknown>> =
     createClientAppData?: (p: { clientId: string; observedCall: ObservedCall }) => Record<string, unknown>;
     // sink factory — produces a per-client sink that receives every accepted sample (see Sinks).
     createClientSink?: (p: { clientId: string; observedCall: ObservedCall }) => ClientSampleSink | undefined;
+    // track-resolver factory — produces a call's RemoteTrackResolver (see Remote track resolution).
+    createTrackResolver?: (observedCall: ObservedCall) => RemoteTrackResolver | undefined;
   };
 ```
 
@@ -438,6 +470,7 @@ const observer = new Observer({
 Key members:
 
 - `accept(sample: ClientSample, context?: AcceptContext): void`
+- `addAcceptMiddleware(...mw: AcceptMiddleware[]): this` / `removeAcceptMiddleware(...mw): this` — global pre-dispatch sample hooks (see [Accept middlewares](#accept-middlewares-global-pre-dispatch-hook))
 - `getObservedCall<T>(callId): ObservedCall<T> | undefined`
 - `createObservedCall<T>(settings): ObservedCall<T> | undefined`
 - `getOrCreateObservedCall<T>(settings): ObservedCall<T> | undefined`
@@ -454,13 +487,10 @@ Key members:
 ### `ObservedCall`
 
 ```ts
-type ObservedCallSettings<AppData = Record<string, unknown>> =
-  ( { updatePolicy: 'update-on-interval'; updateIntervalInMs: number }
-  | { updatePolicy?: 'update-on-any-client-updated' | 'update-when-all-client-updated'; updateIntervalInMs?: number }
-  ) & {
+type ObservedCallSettings<AppData = Record<string, unknown>> = {
+    updatePolicy?: 'update-on-any-client-updated' | 'update-when-all-client-updated';
     callId: string;
     appData?: AppData;
-    remoteTrackResolvePolicy?: 'p2p' | 'mediasoup-sfu' | 'none';
     closeCallIfEmptyForMs?: number;
   };
 ```
@@ -473,7 +503,7 @@ Key members:
 - `addIssue(issue: ClientIssue): void` — raise a **call-level** issue → emits `call-issue`
 - `readonly detectors: Detectors` — server-side detector registry (empty by default; see [Detectors](#detectors-server-side-extension-point))
 - `scoreCalculator: ScoreCalculator`, `get score()`, `readonly calculatedScore`
-- `remoteTrackResolver?: RemoteTrackResolver`
+- `remoteTrackResolver?: RemoteTrackResolver` — set from `ObserverConfig.createTrackResolver` at call creation (see [Remote track resolution](#remote-track-resolution-mediasoup--sfu))
 - aggregates: `numberOfIssues`, `numberOfPeerConnections`, `numberOfInboundRtpStreams`,
   `numberOfOutboundRtpStreams`, `numberOfDataChannels`, `maxNumberOfClients`,
   `clientsUsedTurn: Set<string>`, `startedAt?`, `endedAt?`, `closedAt?`, `closed`
@@ -507,7 +537,6 @@ Key members:
 - Per-tick deltas: `deltaReceivedAudioBytes`, `deltaSentAudioBytes`, … (see source for the full set)
 - Lifecycle: `joinedAt?`, `leftAt?`, `closedAt?`, `closed`, `get score()`
 - Metadata: `browser?`, `engine?`, `platform?`, `operationSystem?`, `mediaDevices`, `mediaConstraints`
-- `readonly report: ClientReport` — cumulative report (byte/packet totals + RTT & score distributions)
 - `accept(sample, context?)`, `close()`
 
 ### `ObservedPeerConnection`
@@ -588,9 +617,6 @@ mediasoup set `PRODUCER_*` / `CONSUMER_*` / `DATA_PRODUCER_*` / `DATA_CONSUMER_*
 `MEDIA_DEVICES_SUPPORTED_CONSTRAINTS`, `USER_MEDIA_ERROR`, `LOCAL_SDP`, `OPERATION_SYSTEM`,
 `ENGINE`, `PLATFORM`, `BROWSER`.
 
-`Reports` exported: `ClientReport` (cumulative per-client totals + RTT/score distributions) and
-`TrackReport` (per-track final report, delivered on `client-track-report`).
-
 ---
 
 ## Detectors (server-side extension point)
@@ -643,29 +669,47 @@ class Detectors {
 ## Remote track resolution (mediasoup / SFU)
 
 In an SFU, one participant's **outbound** track is delivered to other participants as **inbound**
-tracks. To correlate them server-side, set `remoteTrackResolvePolicy: 'mediasoup-sfu'` on the
-call settings. The built-in `MediasoupRemoteTrackResolver` subscribes to the bus (filtered to
-its call) and maps producer↔consumer using track `attachments` (`producerId`, `consumerId`):
+tracks (one **publisher** → many **subscribers**). Correlation is **opt-in** per observer: set
+`ObserverConfig.createTrackResolver`, a factory invoked when each call is created that returns the
+call's `RemoteTrackResolver` (or `undefined` for none).
+
+`RemoteTrackResolver` is a generic, strategy-driven class. It subscribes to the bus (filtered to
+its call) and links tracks by **publisher id** — the link key — maintaining the links directly on
+the tracks: `inboundTrack.remoteOutboundTrack` and `outboundTrack.remoteInboundTracks: Set`.
 
 ```ts
-const call = observer.createObservedCall({ callId, remoteTrackResolvePolicy: 'mediasoup-sfu' });
-// later, given an inbound track:
-const source = inboundTrack.getRemoteOutboundTrack();     // the producing ObservedOutboundTrack
-const consumers = outboundTrack.getRemoteInboundTracks(); // the consuming ObservedInboundTrack[]
+import { Observer, createDefaultMediasoupRemoteTrackResolverFactory } from '@observertc/observer-js';
+
+const observer = new Observer({
+  createTrackResolver: createDefaultMediasoupRemoteTrackResolverFactory(),
+});
+
+// later, given tracks (links are kept up to date as tracks come and go):
+const source    = inboundTrack.remoteOutboundTrack;       // the publishing ObservedOutboundTrack
+const receivers = [ ...outboundTrack.remoteInboundTracks ]; // the subscribing ObservedInboundTrack[]
 ```
 
-Custom topologies can implement the `RemoteTrackResolver` interface and assign
-`call.remoteTrackResolver`:
+Two built-in factories ship: `createDefaultMediasoupRemoteTrackResolverFactory()` (publisher =
+`attachments.producerId`, subscriber = `attachments.consumerId`) and
+`createP2pRemoteTrackResolverFactory()` (matches by RTP **SSRC**, preserved end-to-end in p2p).
+
+For any other topology, build a `RemoteTrackResolver` with your own key resolvers — the publisher
+id is just whatever links a subscribed track to the published one:
 
 ```ts
-interface RemoteTrackResolver {
-  resolveRemoteOutboundTrack(inboundTrack: ObservedInboundTrack): ObservedOutboundTrack | undefined;
-  resolveRemoteInboundTracks(outboundTrack: ObservedOutboundTrack): ObservedInboundTrack[] | undefined;
-}
+import { Observer, RemoteTrackResolver } from '@observertc/observer-js';
+
+const observer = new Observer({
+  createTrackResolver: (observedCall) => new RemoteTrackResolver(observedCall, {
+    resolveOutboundTrackPublisherId: (out) => out.attachments?.mediaId as string | undefined,
+    resolveInboundTrackPublisherId:  (inb) => inb.attachments?.mediaId as string | undefined,
+    resolveInboundTrackSubscriberId: (inb) => inb.attachments?.subId  as string | undefined, // optional
+  }),
+});
 ```
 
-The application is expected to put `direction` (`'send'`/`'recv'`), `producerId`, `consumerId`,
-and `label` into `PeerConnectionSample.attachments` / track `attachments`.
+For the mediasoup factory, the application puts `producerId` / `consumerId` (and optionally
+`direction`, `label`) into the track `attachments`.
 
 ---
 
@@ -819,14 +863,15 @@ filtering, per-module routing, and full silencing.
 
 The library **warns and degrades; it does not throw** on operational problems:
 
-- Bad config (`update-on-interval` without an interval) → warn + safe fallback policy.
 - `createObservedCall` / `createObservedClient` on a closed parent → warn + return `undefined`.
 - Duplicate id → warn + return the **existing** instance.
 - `accept()` on a closed client → warn + no-op.
 - Sample missing `callId`/`clientId`, or observer closed → `sample-rejected` event.
+- A throwing accept-middleware → warn + drop that sample (never crashes `accept()`).
 
-Therefore `create*` and `getOrCreate*` return `T | undefined`; **guard the result.** The only
-remaining `throw`s are internal invariants in the unused `Middleware` utility.
+Therefore `create*` and `getOrCreate*` return `T | undefined`; **guard the result.** The
+`Middleware` utility's internal invariants (e.g. calling `next()` twice) throw, but those throws
+are caught by `accept()` and surfaced as a warning.
 
 ---
 
@@ -863,7 +908,11 @@ export type { JsonlFileSinkOptions, JsonlFileSinkFactoryOptions } from './sinks/
 export { InMemorySink, createInMemorySink } from './sinks/InMemorySink';
 
 export { Middleware } from './common/Middleware';
-export type { TrackReport, ClientReport } from './Reports';
+
+// remote track correlation
+export { RemoteTrackResolver } from './utils/RemoteTrackResolver';
+export type { RemoteTrackResolvers, RemoteTrackResolverFactory } from './utils/RemoteTrackResolver';
+export { createDefaultMediasoupRemoteTrackResolverFactory, createP2pRemoteTrackResolverFactory } from './utils/RemoteTrackResolverFactories';
 ```
 
 ---

package/dist/index.d.mts

@@ -1340,6 +1340,25 @@ type CalculatedScore = {
 
 type MediaKind = 'audio' | 'video';
 
+declare class ObservedMediaPlayout implements MediaPlayoutStats {
+    timestamp: number;
+    id: string;
+    kind: MediaKind;
+    private readonly _peerConnection;
+    private _visited;
+    appData?: Record<string, unknown>;
+    synthesizedSamplesDuration?: number | undefined;
+    synthesizedSamplesEvents?: number | undefined;
+    totalSamplesDuration?: number | undefined;
+    totalPlayoutDelay?: number | undefined;
+    totalSamplesCount?: number | undefined;
+    attachments?: Record<string, unknown> | undefined;
+    constructor(timestamp: number, id: string, kind: MediaKind, _peerConnection: ObservedPeerConnection);
+    get visited(): boolean;
+    getPeerConnection(): ObservedPeerConnection;
+    update(stats: MediaPlayoutStats): void;
+}
+
 declare class ObservedMediaSource implements MediaSourceStats {
     timestamp: number;
     id: string;
@@ -1579,91 +1598,6 @@ declare class ObservedOutboundRtp implements OutboundRtpStats {
     update(stats: OutboundRtpStats): void;
 }
 
-type InboundAudioTrackReport = {
-    trackId: string;
-    fractionLostDistribution: {
-        lt001: number;
-        lt005: number;
-        lt010: number;
-        lt020: number;
-        lt050: number;
-        gtOrEq050: number;
-        count: number;
-        sum: number;
-    };
-};
-type InboundVideoTrackReport = {
-    trackId: string;
-    fractionLostDistribution: {
-        lt001: number;
-        lt005: number;
-        lt010: number;
-        lt020: number;
-        lt050: number;
-        gtOrEq050: number;
-        count: number;
-        sum: number;
-    };
-};
-type OutboundAudioTrackReport = {
-    trackId: string;
-};
-type OutboundVideoTrackReport = {
-    trackId: string;
-};
-type InboundTrackReport = ({
-    kind: 'audio';
-} & InboundAudioTrackReport) | ({
-    kind: 'video';
-} & InboundVideoTrackReport);
-type OutboundTrackReport = ({
-    kind: 'audio';
-} & OutboundAudioTrackReport) | ({
-    kind: 'video';
-} & OutboundVideoTrackReport);
-type TrackReport = ({
-    direction: 'inbound';
-} & InboundTrackReport) | ({
-    direction: 'outbound';
-} & OutboundTrackReport);
-type ClientReport = {
-    callId: string;
-    clientId: string;
-    totalDataChannelBytesReceived: number;
-    totalDataChannelBytesSent: number;
-    totalDataChannelMessagesReceived: number;
-    totalDataChannelMessagesSent: number;
-    totalInboundRtpPacketsReceived: number;
-    totalInboundRtpPacketsLost: number;
-    totalInboundRtpBytesReceived: number;
-    totalOutboundRtpPacketsSent: number;
-    totalOutboundRtpBytesSent: number;
-    totalAudioBytesReceived: number;
-    totalVideoBytesReceived: number;
-    totalAudioBytesSent: number;
-    totalVideoBytesSent: number;
-    totalNumberOfIssues: number;
-    issues: Record<string, number>;
-    rttDistribution: {
-        lt50ms: number;
-        lt150ms: number;
-        lt300ms: number;
-        gtOrEq300ms: number;
-        count: number;
-        sum: number;
-    };
-    scoreDistribution: {
-        '0': number;
-        '1': number;
-        '2': number;
-        '3': number;
-        '4': number;
-        '5': number;
-        count: number;
-        sum: number;
-    };
-};
-
 declare class ObservedOutboundTrack implements OutboundTrackSample {
     timestamp: number;
     readonly id: string;
@@ -1673,7 +1607,7 @@ declare class ObservedOutboundTrack implements OutboundTrackSample {
     private readonly _mediaSource?;
     private _visited;
     appData?: Record<string, unknown>;
-    readonly report: OutboundTrackReport;
+    readonly remoteInboundTracks: Set<ObservedInboundTrack>;
     readonly calculatedScore: CalculatedScore;
     addedAt?: number | undefined;
     removedAt?: number | undefined;
@@ -1685,29 +1619,9 @@ declare class ObservedOutboundTrack implements OutboundTrackSample {
     getPeerConnection(): ObservedPeerConnection;
     getOutboundRtps(): ObservedOutboundRtp[] | undefined;
     getMediaSource(): ObservedMediaSource | undefined;
-    getRemoteInboundTracks(): ObservedInboundTrack[] | undefined;
     update(stats: OutboundTrackSample): void;
 }
 
-declare class ObservedMediaPlayout implements MediaPlayoutStats {
-    timestamp: number;
-    id: string;
-    kind: MediaKind;
-    private readonly _peerConnection;
-    private _visited;
-    appData?: Record<string, unknown>;
-    synthesizedSamplesDuration?: number | undefined;
-    synthesizedSamplesEvents?: number | undefined;
-    totalSamplesDuration?: number | undefined;
-    totalPlayoutDelay?: number | undefined;
-    totalSamplesCount?: number | undefined;
-    attachments?: Record<string, unknown> | undefined;
-    constructor(timestamp: number, id: string, kind: MediaKind, _peerConnection: ObservedPeerConnection);
-    get visited(): boolean;
-    getPeerConnection(): ObservedPeerConnection;
-    update(stats: MediaPlayoutStats): void;
-}
-
 declare class ObservedInboundTrack implements InboundTrackSample {
     timestamp: number;
     readonly id: string;
@@ -1717,7 +1631,7 @@ declare class ObservedInboundTrack implements InboundTrackSample {
     private readonly _mediaPlayout?;
     readonly calculatedScore: CalculatedScore;
     appData?: Record<string, unknown>;
-    report: InboundTrackReport;
+    remoteOutboundTrack?: ObservedOutboundTrack | undefined;
     private _visited;
     addedAt?: number | undefined;
     removedAt?: number | undefined;
@@ -1729,7 +1643,6 @@ declare class ObservedInboundTrack implements InboundTrackSample {
     getPeerConnection(): ObservedPeerConnection;
     getInboundRtp(): ObservedInboundRtp | undefined;
     getMediaPlayout(): ObservedMediaPlayout | undefined;
-    getRemoteOutboundTrack(): ObservedOutboundTrack | undefined;
     update(stats: InboundTrackSample): void;
 }
 
@@ -2237,9 +2150,6 @@ type ObserverEvents = {
     'client-event': [ObservedClientScope & {
         event: ClientEvent;
     }];
-    'client-track-report': [ObservedClientScope & {
-        report: TrackReport;
-    }];
     'peer-connection-added': [ObservedPeerConnectionScope];
     'peer-connection-updated': [ObservedPeerConnectionScope];
     'peer-connection-closed': [ObservedPeerConnectionScope];
@@ -2479,7 +2389,6 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     deltaNumberOfIssues: number;
     totalScoreSum: number;
     numberOfScoreMeasurements: number;
-    readonly report: ClientReport;
     readonly mediaDevices: MediaDeviceInfo[];
     issues: ClientIssue[];
     private _injections;
@@ -2508,9 +2417,49 @@ interface ScoreCalculator {
     update(): void;
 }
 
-interface RemoteTrackResolver {
+type RemoteTrackResolverFactory = (observedCall: ObservedCall) => RemoteTrackResolver;
+/**
+ * Strategy functions that map a track to its publish/subscribe identity. Two tracks are linked
+ * when a subscribed (inbound) track's **publisher id** equals a published (outbound) track's
+ * **publisher id** — one publisher → many subscribers. The **subscriber id** is optional and is
+ * only used to look an inbound track up via `getInboundTrackBySubscriberId`.
+ *
+ * The "publisher id" is whatever a strategy uses as the link key: mediasoup passes its producerId,
+ * a p2p strategy the SSRC, a generic strategy a shared attachment value.
+ */
+type RemoteTrackResolvers = {
+    /** The publisher id a subscribed (inbound) track receives. Required — this is the link key. */
+    resolveInboundTrackPublisherId: (inboundTrack: ObservedInboundTrack) => string | undefined;
+    /** The publisher id a published (outbound) track represents. Required — this is the link key. */
+    resolveOutboundTrackPublisherId: (outboundTrack: ObservedOutboundTrack) => string | undefined;
+    /** Optional: the inbound track's own subscription id (enables `getInboundTrackBySubscriberId`). */
+    resolveInboundTrackSubscriberId?: (inboundTrack: ObservedInboundTrack) => string | undefined;
+};
+/**
+ * Generic, strategy-driven base resolver. It subscribes to the Observer bus (filtered to one call),
+ * links subscribed↔published tracks by publisher id, and maintains the links directly on the tracks
+ * (`inboundTrack.remoteOutboundTrack`, `outboundTrack.remoteInboundTracks`).
+ *
+ * Concrete strategies (mediasoup, p2p-by-SSRC, generic attachment) are just different
+ * {@link RemoteTrackResolvers} passed to this class. Ids are re-resolved on demand rather than
+ * cached, so the only state kept is the two lookup indexes that back the public getters.
+ */
+declare class RemoteTrackResolver {
+    readonly observedCall: ObservedCall;
+    private readonly resolvers;
+    private readonly _publisherIdToOutboundTrack;
+    private readonly _subscriberIdToInboundTrack;
+    constructor(observedCall: ObservedCall, resolvers: RemoteTrackResolvers);
+    /** The published (outbound) track for a publisher id, if any. */
+    getOutboundTrackByPublisherId(publisherId: string): ObservedOutboundTrack | undefined;
+    /** The subscribed (inbound) track for a subscriber id, if the strategy resolves subscriber ids. */
+    getInboundTrackBySubscriberId(subscriberId: string): ObservedInboundTrack | undefined;
     resolveRemoteOutboundTrack(inboundTrack: ObservedInboundTrack): ObservedOutboundTrack | undefined;
     resolveRemoteInboundTracks(outboundTrack: ObservedOutboundTrack): ObservedInboundTrack[] | undefined;
+    private _addInboundTrack;
+    private _removeInboundTrack;
+    private _addOutboundTrack;
+    private _removeOutboundTrack;
 }
 
 interface Updater {
@@ -2536,16 +2485,11 @@ declare class Detectors {
 }
 
 type ObservedCallUpdateConfig = {
-    updatePolicy: 'update-on-interval';
-    updateIntervalInMs: number;
-} | {
     updatePolicy?: 'update-on-any-client-updated' | 'update-when-all-client-updated';
-    updateIntervalInMs?: number;
 };
 type ObservedCallSettings<AppData extends Record<string, unknown> = Record<string, unknown>> = ObservedCallUpdateConfig & {
     callId: string;
     appData?: AppData;
-    remoteTrackResolvePolicy?: 'p2p' | 'mediasoup-sfu' | 'none';
     closeCallIfEmptyForMs?: number;
 };
 type ObservedCallEvents = {
@@ -2606,6 +2550,22 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
     private _notify;
 }
 
+type Middleware<T> = (input: T, next: (nextInput: T) => void) => void;
+interface Processor<T> {
+    finalCallback?: Callback<T>;
+    process(value: T): void;
+    addMiddleware(...middlewares: Middleware<T>[]): Processor<T>;
+    removeMiddleware(...middlewares: Middleware<T>[]): Processor<T>;
+}
+type Callback<T> = (input: T) => void;
+declare class MiddlewareProcessor<T> implements Processor<T> {
+    private stack;
+    finalCallback?: Callback<T>;
+    addMiddleware(...middlewares: Middleware<T>[]): Processor<T>;
+    removeMiddleware(...middlewares: Middleware<T>[]): Processor<T>;
+    process(value: T): void;
+}
+
 type SampleRejectedReason = 'observer-closed' | 'missing-callId' | 'missing-clientId';
 
 /**
@@ -2614,12 +2574,20 @@ type SampleRejectedReason = 'observer-closed' | 'missing-callId' | 'missing-clie
  * merged into the `appData` of entities created during the accept pass.
  */
 type AcceptContext = Record<string, unknown>;
+/** The payload threaded through `accept()` middlewares: the sample and its optional context. */
+type AcceptMiddlewarePayload = {
+    sample: ClientSample;
+    context?: AcceptContext;
+};
+/**
+ * A global middleware run on every sample passed to `observer.accept()`, in registration order,
+ * **before** the sample is dispatched to any call/client. It may inspect or mutate the sample
+ * (e.g. set/normalize `callId`/`clientId`, enrich, redact) or the context, then call
+ * `next(payload)` to continue the chain. Not calling `next` **drops** the sample.
+ */
+type AcceptMiddleware = Middleware<AcceptMiddlewarePayload>;
 type ObserverUpdateConfig = {
-    updatePolicy: 'update-on-interval';
-    updateIntervalInMs: number;
-} | {
     updatePolicy?: 'update-on-any-call-updated' | 'update-when-all-call-updated';
-    updateIntervalInMs?: number;
 };
 /** Produces the initial `appData` for a call created without an explicit `appData`. */
 type CallAppDataFactory = (params: {
@@ -2633,7 +2601,6 @@ type ClientAppDataFactory = (params: {
 }) => Record<string, unknown>;
 type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unknown>> = ObserverUpdateConfig & {
     defaultCallUpdatePolicy?: ObservedCallSettings['updatePolicy'];
-    defaultCallUpdateIntervalInMs?: number;
     appData?: AppData;
     closeClientIfIdleForMs?: number;
     closeCallIfEmptyForMs?: number;
@@ -2651,6 +2618,13 @@ type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unk
      * can be derived from `callId` / `clientId`.
      */
     createClientSink?: ClientSampleSinkFactory;
+    /**
+     * Optional factory invoked when a call is created, producing the call's `RemoteTrackResolver`
+     * (or `undefined` for none). Use the built-ins
+     * (`createDefaultMediasoupRemoteTrackResolverFactory()` / `createP2pRemoteTrackResolverFactory()`)
+     * or build a `RemoteTrackResolver` with custom publisher/subscriber id resolvers.
+     */
+    createTrackResolver?: RemoteTrackResolverFactory;
 };
 declare interface Observer {
     on<U extends keyof ObserverEvents>(event: U, listener: (...args: ObserverEvents[U]) => void): this;
@@ -2674,7 +2648,8 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
     numberOfOutboundRtpStreams: number;
     numberOfDataChannels: number;
     numberOfPeerConnections: number;
-    private _timer?;
+    /** Global, pre-dispatch middleware chain run on every accepted sample. */
+    readonly acceptMiddlewares: MiddlewareProcessor<AcceptMiddlewarePayload>;
     constructor(config?: ObserverConfig<AppData>);
     get numberOfCalls(): number;
     get appData(): AppData | undefined;
@@ -2790,6 +2765,7 @@ declare class InMemorySink extends ClientSampleSink {
 }
 declare function createInMemorySink(samples?: ClientSample[]): InMemorySink;
 
-type Middleware<T> = (input: T, next: (nextInput: T) => void) => void;
+declare function createDefaultMediasoupRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
+declare function createP2pRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 
-export { type AcceptContext, type CallAppDataFactory, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientIssue, type ClientMetaData, ClientMetaTypes, type ClientReport, type ClientSample, ClientSampleSink, type ClientSampleSinkEvents, type ClientSampleSinkFactory, type Detector, Detectors, InMemorySink, JsonlFileSink, type JsonlFileSinkFactoryOptions, type JsonlFileSinkOptions, type Logger, type Middleware, ObservedCall, type ObservedCallScope, ObservedCertificate, ObservedClient, type ObservedClientScope, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, Observer, type ObserverEventBase, type ObserverEvents, type ObserverLogger, type SampleRejectedReason, type ScoreCalculator, type TrackReport, createInMemorySink, createJsonlFileSink, createJsonlFileSinkFactory, createLogger, setObserverLogger };
+export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type CallAppDataFactory, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientIssue, type ClientMetaData, ClientMetaTypes, type ClientSample, ClientSampleSink, type ClientSampleSinkEvents, type ClientSampleSinkFactory, type Detector, Detectors, InMemorySink, JsonlFileSink, type JsonlFileSinkFactoryOptions, type JsonlFileSinkOptions, type Logger, type Middleware, ObservedCall, type ObservedCallScope, ObservedCertificate, ObservedClient, type ObservedClientScope, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, Observer, type ObserverEventBase, type ObserverEvents, type ObserverLogger, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolvers, type SampleRejectedReason, type ScoreCalculator, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createJsonlFileSinkFactory, createLogger, createP2pRemoteTrackResolverFactory, setObserverLogger };