From b9516a2759b8d2670a548d747422f92f33d089a5 Mon Sep 17 00:00:00 2001
From: Justin Halsall <Juice10@users.noreply.github.com>
Date: Wed, 1 Apr 2026 12:00:00 +0800
Subject: [PATCH] re-use live mode config - and improve docs on how to start
 liveMode (#1003)

* Use config.liveMode to turn on liveMode in the timer

* Discussion of `startLive(1500)` was incorrect as startLive is based on timestamps, not playback offsets.  Also reorder to introduce `addEvent` earlier

Co-authored-by: Eoghan Murray <eoghan@getthere.ie>
---
 docs/recipes/live-mode.md          | 25 +++++++++++++++----------
 packages/rrweb/src/replay/index.ts |  5 ++++-
 packages/rrweb/src/replay/timer.ts | 11 +++++++++--
 3 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/docs/recipes/live-mode.md b/docs/recipes/live-mode.md
index d415e856..921918e6 100644
--- a/docs/recipes/live-mode.md
+++ b/docs/recipes/live-mode.md
@@ -5,23 +5,28 @@ If you want to replay the events in a real-time way, you can use the live mode A
 When you are using rrweb's Replayer to do a real-time replay, you need to configure `liveMode: true` and call the `startLive` API to enable the live mode.
 
 ```js
-const replayer = new rrweb.Replayer([], {
+const ANY_OLD_EVENTS = [];
+const replayer = new rrweb.Replayer(ANY_OLD_EVENTS, {
   liveMode: true,
 });
-
-replayer.startLive(FIRST_EVENT.timestamp - BUFFER);
+replayer.startLive();
 ```
 
-When calling the `startLive` API, there is an optional parameter to set the baseline time. This is quite useful when you live scenario needs a buffer time.
+Later when you receive new events (e.g. over websockets), you can add them using:
 
-For example, you have an event recorded at timestamp 1500. Calling `startLive(1500)` will set the baseline time to 1500 and all the timing calculation will be based on this.
+```
+function onReceive(event) {
+  replayer.addEvent(event);
+}
+```
 
-But this may cause your replay to look laggy. Because data transportation needs time(such as the delay of the network). And some events have been throttled(such as mouse movements) which has a delay by default.
+When calling the `startLive` API, there is an optional parameter to set the baseline time. By default, this is `Date.now()` so that events are applied as soon as they come in, however this may cause your replay to look laggy. Because data transportation needs time(such as the delay of the network). And some events have been throttled(such as mouse movements) which has a delay by default.
 
-So we can configure a smaller baseline time to the `startLive` API, like `startLive(500)`. This will let the replay always delay 1 second than the source. If the time of data transportation is not longer than 1 second, the user will not feel laggy.
-
-When live mode is on, we can call `addEvent` API to add the latest events into the replayer:
+Here is how you introduce a buffer:
 
 ```js
-replayer.addEvent(NEW_EVENT);
+const BUFFER_MS = 1000;
+replayer.startLive(Date.now() - BUFFER_MS);
 ```
+
+This will let the replay always delay 1 second than the source. If the time of data transportation is not longer than 1 second, the user will not feel laggy.
diff --git a/packages/rrweb/src/replay/index.ts b/packages/rrweb/src/replay/index.ts
index 234360ff..8e1948e3 100644
--- a/packages/rrweb/src/replay/index.ts
+++ b/packages/rrweb/src/replay/index.ts
@@ -262,7 +262,10 @@ export class Replayer {
       this.mirror.reset();
     });
 
-    const timer = new Timer([], config?.speed || defaultConfig.speed);
+    const timer = new Timer([], {
+      speed: this.config.speed,
+      liveMode: this.config.liveMode,
+    });
     this.service = createPlayerService(
       {
         events: events
diff --git a/packages/rrweb/src/replay/timer.ts b/packages/rrweb/src/replay/timer.ts
index 4eefca80..6cfa95e0 100644
--- a/packages/rrweb/src/replay/timer.ts
+++ b/packages/rrweb/src/replay/timer.ts
@@ -13,9 +13,16 @@ export class Timer {
   private raf: number | null = null;
   private liveMode: boolean;
 
-  constructor(actions: actionWithDelay[] = [], speed: number) {
+  constructor(
+    actions: actionWithDelay[] = [],
+    config: {
+      speed: number;
+      liveMode: boolean;
+    },
+  ) {
     this.actions = actions;
-    this.speed = speed;
+    this.speed = config.speed;
+    this.liveMode = config.liveMode;
   }
   /**
    * Add an action after the timer starts.