@amazon/vinyl 4.0.1-next.20261017024550 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,8 +3,8 @@ import { ReadonlyPlaybackController } from './ReadonlyPlaybackController';
3
3
  import { StallEndedReason } from './ReadonlyPlaybackController';
4
4
  export interface StallMonitorOptions {
5
5
  /**
6
- * Seconds the play head must be frozen (no `timeUpdate`) while playing before a stall is
7
- * reported. Default: 1
6
+ * Seconds the play head must be frozen (`currentTime` not advancing) while playing before a
7
+ * stall is reported. Default: 1
8
8
  */
9
9
  readonly stallThreshold?: number;
10
10
  /**
@@ -13,7 +13,7 @@ export interface StallMonitorOptions {
13
13
  readonly pollInterval?: number;
14
14
  }
15
15
  export interface StallEndedInfo {
16
- /** Time of the last `timeUpdate` observed before the play head froze. */
16
+ /** Time of the last progress observed before the play head froze. */
17
17
  readonly started: Timestamp;
18
18
  /** Time the stall ended. */
19
19
  readonly ended: Timestamp;
@@ -30,14 +30,19 @@ export interface StallMonitorCallbacks {
30
30
  }
31
31
  /**
32
32
  * Watches a {@link ReadonlyPlaybackController} for stalls while playing: the play head freezing
33
- * (no `timeUpdate`) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
33
+ * (`currentTime` not advancing) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
34
+ *
35
+ * Progress is observed both from `timeUpdate` events and by reading `currentTime` on each poll. A
36
+ * late `timeUpdate` alone is not a stall: when the main thread is busy (a long task, a GC pause) or
37
+ * event delivery is delayed, the play head keeps advancing while no `timeUpdate` reaches script,
38
+ * and the poll sees that advance rather than reporting a freeze.
34
39
  *
35
40
  * Detection only runs once playback has actually been observed (a `playing` event) and is
36
41
  * suspended on `pause`/`seeking`/`emptied` until playback is observed again — so a stall is never
37
42
  * reported during initial loading or while awaiting a seek. A detected stall ends when the play
38
43
  * head advances again (`playing`) or playback stops for another reason (`pause`/`seeking`/
39
- * `emptied`); {@link StallEndedInfo.duration} is measured from the last `timeUpdate` before the
40
- * freeze, so it reflects the full frozen time rather than only the time past the threshold.
44
+ * `emptied`); {@link StallEndedInfo.duration} is measured from the last observed progress before
45
+ * the freeze, so it reflects the full frozen time rather than only the time past the threshold.
41
46
  *
42
47
  * Returns a function that stops the monitor.
43
48
  */
@@ -3,8 +3,8 @@ import type { ReadonlyPlaybackController } from './ReadonlyPlaybackController';
3
3
  import { StallEndedReason } from './ReadonlyPlaybackController';
4
4
  export interface StallMonitorOptions {
5
5
  /**
6
- * Seconds the play head must be frozen (no `timeUpdate`) while playing before a stall is
7
- * reported. Default: 1
6
+ * Seconds the play head must be frozen (`currentTime` not advancing) while playing before a
7
+ * stall is reported. Default: 1
8
8
  */
9
9
  readonly stallThreshold?: number;
10
10
  /**
@@ -13,7 +13,7 @@ export interface StallMonitorOptions {
13
13
  readonly pollInterval?: number;
14
14
  }
15
15
  export interface StallEndedInfo {
16
- /** Time of the last `timeUpdate` observed before the play head froze. */
16
+ /** Time of the last progress observed before the play head froze. */
17
17
  readonly started: Timestamp;
18
18
  /** Time the stall ended. */
19
19
  readonly ended: Timestamp;
@@ -30,14 +30,19 @@ export interface StallMonitorCallbacks {
30
30
  }
31
31
  /**
32
32
  * Watches a {@link ReadonlyPlaybackController} for stalls while playing: the play head freezing
33
- * (no `timeUpdate`) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
33
+ * (`currentTime` not advancing) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
34
+ *
35
+ * Progress is observed both from `timeUpdate` events and by reading `currentTime` on each poll. A
36
+ * late `timeUpdate` alone is not a stall: when the main thread is busy (a long task, a GC pause) or
37
+ * event delivery is delayed, the play head keeps advancing while no `timeUpdate` reaches script,
38
+ * and the poll sees that advance rather than reporting a freeze.
34
39
  *
35
40
  * Detection only runs once playback has actually been observed (a `playing` event) and is
36
41
  * suspended on `pause`/`seeking`/`emptied` until playback is observed again — so a stall is never
37
42
  * reported during initial loading or while awaiting a seek. A detected stall ends when the play
38
43
  * head advances again (`playing`) or playback stops for another reason (`pause`/`seeking`/
39
- * `emptied`); {@link StallEndedInfo.duration} is measured from the last `timeUpdate` before the
40
- * freeze, so it reflects the full frozen time rather than only the time past the threshold.
44
+ * `emptied`); {@link StallEndedInfo.duration} is measured from the last observed progress before
45
+ * the freeze, so it reflects the full frozen time rather than only the time past the threshold.
41
46
  *
42
47
  * Returns a function that stops the monitor.
43
48
  */
@@ -3,8 +3,8 @@ import type { ReadonlyPlaybackController } from './ReadonlyPlaybackController';
3
3
  import { StallEndedReason } from './ReadonlyPlaybackController';
4
4
  export interface StallMonitorOptions {
5
5
  /**
6
- * Seconds the play head must be frozen (no `timeUpdate`) while playing before a stall is
7
- * reported. Default: 1
6
+ * Seconds the play head must be frozen (`currentTime` not advancing) while playing before a
7
+ * stall is reported. Default: 1
8
8
  */
9
9
  readonly stallThreshold?: number;
10
10
  /**
@@ -13,7 +13,7 @@ export interface StallMonitorOptions {
13
13
  readonly pollInterval?: number;
14
14
  }
15
15
  export interface StallEndedInfo {
16
- /** Time of the last `timeUpdate` observed before the play head froze. */
16
+ /** Time of the last progress observed before the play head froze. */
17
17
  readonly started: Timestamp;
18
18
  /** Time the stall ended. */
19
19
  readonly ended: Timestamp;
@@ -30,14 +30,19 @@ export interface StallMonitorCallbacks {
30
30
  }
31
31
  /**
32
32
  * Watches a {@link ReadonlyPlaybackController} for stalls while playing: the play head freezing
33
- * (no `timeUpdate`) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
33
+ * (`currentTime` not advancing) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
34
+ *
35
+ * Progress is observed both from `timeUpdate` events and by reading `currentTime` on each poll. A
36
+ * late `timeUpdate` alone is not a stall: when the main thread is busy (a long task, a GC pause) or
37
+ * event delivery is delayed, the play head keeps advancing while no `timeUpdate` reaches script,
38
+ * and the poll sees that advance rather than reporting a freeze.
34
39
  *
35
40
  * Detection only runs once playback has actually been observed (a `playing` event) and is
36
41
  * suspended on `pause`/`seeking`/`emptied` until playback is observed again — so a stall is never
37
42
  * reported during initial loading or while awaiting a seek. A detected stall ends when the play
38
43
  * head advances again (`playing`) or playback stops for another reason (`pause`/`seeking`/
39
- * `emptied`); {@link StallEndedInfo.duration} is measured from the last `timeUpdate` before the
40
- * freeze, so it reflects the full frozen time rather than only the time past the threshold.
44
+ * `emptied`); {@link StallEndedInfo.duration} is measured from the last observed progress before
45
+ * the freeze, so it reflects the full frozen time rather than only the time past the threshold.
41
46
  *
42
47
  * Returns a function that stops the monitor.
43
48
  */
@@ -5,6 +5,10 @@
5
5
  import { createStallMonitor, StallEndedReason, } from '@amazon/vinyl';
6
6
  import { EventHostImpl } from '@amazon/vinyl-util';
7
7
  import { useMockTime } from '@amazon/vinyl-util/browserTestUtil';
8
+ /** A controller stand-in: events plus a play head position the test moves by hand. */
9
+ class MockController extends EventHostImpl {
10
+ currentTime = 0;
11
+ }
8
12
  describe('createStallMonitor', () => {
9
13
  const clock = useMockTime();
10
14
  let host;
@@ -12,7 +16,7 @@ describe('createStallMonitor', () => {
12
16
  let onStallEnded;
13
17
  let stop;
14
18
  beforeEach(() => {
15
- host = new EventHostImpl();
19
+ host = new MockController();
16
20
  onStallEntered = jasmine.createSpy('onStallEntered');
17
21
  onStallEnded = jasmine.createSpy('onStallEnded');
18
22
  });
@@ -152,6 +156,44 @@ describe('createStallMonitor', () => {
152
156
  await poll(3); // 0.75s < 1s threshold
153
157
  expect(onStallEntered).toHaveBeenCalledTimes(1);
154
158
  });
159
+ it('does not report a stall when the play head advances but timeUpdates are delayed', async () => {
160
+ // A long task (or delayed event delivery) holds back `timeUpdate` while the media keeps
161
+ // playing. When the main thread frees up, the poll can run before the queued timeUpdate;
162
+ // the advanced currentTime shows it's progress, not a freeze.
163
+ monitor();
164
+ host.dispatch('playing', {});
165
+ // 3s of playback with the play head advancing but no timeUpdate delivered.
166
+ for (let i = 0; i < 12; i++) {
167
+ host.currentTime += 0.25;
168
+ await poll(1);
169
+ }
170
+ expect(onStallEntered).not.toHaveBeenCalled();
171
+ expect(onStallEnded).not.toHaveBeenCalled();
172
+ });
173
+ it('still reports a stall when the play head is frozen and no timeUpdate arrives', async () => {
174
+ monitor();
175
+ host.currentTime = 3;
176
+ host.dispatch('playing', {});
177
+ await poll(4); // currentTime unchanged for 1s
178
+ expect(onStallEntered).toHaveBeenCalledTimes(1);
179
+ });
180
+ it('ends a stall when the play head advances before a timeUpdate is delivered', async () => {
181
+ monitor();
182
+ host.dispatch('playing', {});
183
+ await poll(4); // frozen 1s -> stallEntered
184
+ expect(onStallEntered).toHaveBeenCalledTimes(1);
185
+ await poll(4); // frozen another 1s (total 2s)
186
+ host.currentTime = 0.25; // resumed; the next poll sees it before any timeUpdate
187
+ await poll(1);
188
+ expect(onStallEnded).toHaveBeenCalledTimes(1);
189
+ const info = onStallEnded.calls.mostRecent().args[0];
190
+ expect(info.reason).toBe(StallEndedReason.PLAYING);
191
+ expect(info.duration).toBeCloseTo(2.25, 1);
192
+ // The late timeUpdate for the same advance doesn't end or start another stall.
193
+ host.dispatch('timeUpdate', { previous: 0, current: 0.25 });
194
+ expect(onStallEnded).toHaveBeenCalledTimes(1);
195
+ expect(onStallEntered).toHaveBeenCalledTimes(1);
196
+ });
155
197
  it('stops reporting after disposal', async () => {
156
198
  monitor();
157
199
  host.dispatch('playing', {});