@arraypress/waveform-player 1.29.0 → 1.29.1

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.
package/src/js/core.js CHANGED
@@ -18,7 +18,9 @@ import {
18
18
  formatCssLength,
19
19
  toFiniteNumber,
20
20
  toNumberArray,
21
- DEFAULT_SAMPLES
21
+ DEFAULT_SAMPLES,
22
+ inTimeRanges,
23
+ coversDuration,
22
24
  } from './utils.js';
23
25
 
24
26
  import {
@@ -64,6 +66,9 @@ export class WaveformPlayer {
64
66
  /** @type {WaveformPlayer|null} */
65
67
  static currentlyPlaying = null;
66
68
 
69
+ /** Audio URLs already warned about lacking byte-range support. @private */
70
+ static _noRangeWarned = new Set();
71
+
67
72
  /**
68
73
  * Create a new WaveformPlayer instance.
69
74
  *
@@ -1122,7 +1127,8 @@ export class WaveformPlayer {
1122
1127
  this.audio.addEventListener('seeked', () => this._updatePositionState());
1123
1128
  this.audio.addEventListener('ratechange', () => this._updatePositionState());
1124
1129
  this.audio.addEventListener('timeupdate', () => {
1125
- if (this.isPlaying && Date.now() - this._frameAt > 500) this.updateProgress();
1130
+ // Not mid cache-reload: currentTime reads 0 until the seek lands.
1131
+ if (this.isPlaying && !this._seekReload && Date.now() - this._frameAt > 500) this.updateProgress();
1126
1132
  });
1127
1133
  }
1128
1134
 
@@ -1388,6 +1394,9 @@ export class WaveformPlayer {
1388
1394
  * @private
1389
1395
  */
1390
1396
  _resetTrack() {
1397
+ // A seek waiting on / reloading the previous file no longer applies.
1398
+ this._cancelCacheSeek?.();
1399
+ this._seekReload = null;
1391
1400
  this.progress = 0;
1392
1401
  this.waveformData = [];
1393
1402
  this._extDuration = 0;
@@ -2005,8 +2014,9 @@ export class WaveformPlayer {
2005
2014
  * @fires WaveformPlayer#waveformplayer:play
2006
2015
  */
2007
2016
  onPlay() {
2008
- // Ignore during destruction
2009
- if (this.isDestroying) return;
2017
+ // Ignore during destruction, and during a seek's cache reload (an
2018
+ // internal pause/play pair consumers shouldn't see; see _reloadForSeek).
2019
+ if (this.isDestroying || this._seekReload) return;
2010
2020
 
2011
2021
  this.isPlaying = true;
2012
2022
 
@@ -2035,8 +2045,8 @@ export class WaveformPlayer {
2035
2045
  * @fires WaveformPlayer#waveformplayer:pause
2036
2046
  */
2037
2047
  onPause() {
2038
- // Ignore during destruction
2039
- if (this.isDestroying) return;
2048
+ // Ignore during destruction, and during a seek's cache reload.
2049
+ if (this.isDestroying || this._seekReload) return;
2040
2050
 
2041
2051
  this.isPlaying = false;
2042
2052
 
@@ -2512,6 +2522,126 @@ export class WaveformPlayer {
2512
2522
  }
2513
2523
  }
2514
2524
 
2525
+ /**
2526
+ * Move the owned `<audio>` to `time`. The single path every self-mode seek
2527
+ * takes ({@link WaveformPlayer#seekTo}, {@link WaveformPlayer#seekToPercent},
2528
+ * so clicks, drags, keys and the slider too).
2529
+ *
2530
+ * Some hosts ignore HTTP byte ranges: they answer a `Range` request with
2531
+ * `200` and the whole file (Cloudflare Pages and Workers static assets, and
2532
+ * plenty of plain servers). Chromium then can't seek the media at all —
2533
+ * `seekable` stays `0–0` even once every byte has arrived — which is the
2534
+ * "long tracks snap back to 0" symptom. The copy in the browser's HTTP
2535
+ * cache *is* seekable (why a page refresh "fixes" it), so when the target
2536
+ * isn't seekable this reloads the element from cache and seeks there; see
2537
+ * {@link WaveformPlayer#_seekViaCache}. Detection is by the element's own
2538
+ * `seekable`, not the browser, so engines that can already seek (WebKit,
2539
+ * Firefox) never take that path; it runs at most once per file.
2540
+ * @param {number} time - Target position in seconds.
2541
+ * @private
2542
+ */
2543
+ _seekAudio(time) {
2544
+ const audio = this.audio;
2545
+ // Only divert when the element positively reports ranges that exclude
2546
+ // the target (Chromium's `0–0` on these hosts). No ranges at all means
2547
+ // "unknown" (no metadata yet, some engines, test DOMs): seek as always.
2548
+ const seekable = audio.seekable;
2549
+ if (!Number.isFinite(audio.duration)
2550
+ || !seekable || seekable.length === 0
2551
+ || inTimeRanges(seekable, time)
2552
+ || this._seekReloadedUrl === this.options.url) {
2553
+ audio.currentTime = time;
2554
+ return;
2555
+ }
2556
+ this._seekViaCache(time);
2557
+ }
2558
+
2559
+ /**
2560
+ * Seek on a host without byte-range support: once the whole file is
2561
+ * downloaded (raising `preload` to `auto` until it is, then restoring it),
2562
+ * reload the element from the browser cache and seek there. Repeated seeks
2563
+ * while waiting just update the target. Warns once per URL, since the
2564
+ * real fix is serving audio from a range-capable host.
2565
+ * @param {number} time - Target position in seconds.
2566
+ * @private
2567
+ */
2568
+ _seekViaCache(time) {
2569
+ const audio = this.audio;
2570
+ const url = this.options.url;
2571
+ this._cacheSeekTime = time;
2572
+
2573
+ if (!WaveformPlayer._noRangeWarned.has(url)) {
2574
+ WaveformPlayer._noRangeWarned.add(url);
2575
+ console.warn(`[WaveformPlayer] ${url}: the host ignores HTTP Range requests, so seeking waits for the download and reloads from cache. Serve audio with Range support for instant seeks.`);
2576
+ }
2577
+
2578
+ if (this._cancelCacheSeek) return; // Already waiting; the target is updated.
2579
+ if (coversDuration(audio.buffered, audio.duration)) {
2580
+ this._reloadForSeek(url);
2581
+ return;
2582
+ }
2583
+
2584
+ const preload = audio.preload;
2585
+ audio.preload = 'auto';
2586
+ this.setLoading(true);
2587
+ const stop = () => {
2588
+ audio.removeEventListener('progress', check);
2589
+ audio.removeEventListener('canplaythrough', check);
2590
+ audio.preload = preload;
2591
+ this._cancelCacheSeek = null;
2592
+ };
2593
+ const check = () => {
2594
+ if (this.audio !== audio || this.options.url !== url) return stop();
2595
+ if (!coversDuration(audio.buffered, audio.duration)) return;
2596
+ stop();
2597
+ this._reloadForSeek(url);
2598
+ };
2599
+ this._cancelCacheSeek = stop;
2600
+ audio.addEventListener('progress', check, {signal: this._ac.signal});
2601
+ audio.addEventListener('canplaythrough', check, {signal: this._ac.signal});
2602
+ }
2603
+
2604
+ /**
2605
+ * Reload the fully-downloaded file from cache, seek to the pending target
2606
+ * and resume. The element's own pause/play events during the reload are
2607
+ * internal plumbing, so onPause/onPlay ignore them while `_seekReload` is
2608
+ * set: consumers (the bar, waveform-tracker) see a seek, not a pause and a
2609
+ * new play, and the button doesn't flicker.
2610
+ * @param {string} url - The file being reloaded.
2611
+ * @private
2612
+ */
2613
+ _reloadForSeek(url) {
2614
+ const audio = this.audio;
2615
+ const wasPlaying = !audio.paused && !audio.ended;
2616
+ const rate = audio.playbackRate;
2617
+ this._seekReloadedUrl = url;
2618
+ this._seekReload = {wasPlaying};
2619
+
2620
+ const finish = () => {
2621
+ this._seekReload = null;
2622
+ this.setLoading(false);
2623
+ this.updateProgress();
2624
+ };
2625
+ audio.addEventListener('loadedmetadata', () => {
2626
+ if (this.audio !== audio || this.options.url !== url) return;
2627
+ audio.playbackRate = rate; // load() resets it to the default
2628
+ audio.currentTime = this._cacheSeekTime;
2629
+ if (!wasPlaying) {
2630
+ finish();
2631
+ return;
2632
+ }
2633
+ audio.play().then(() => {
2634
+ finish();
2635
+ this.startSmoothUpdate();
2636
+ }, () => {
2637
+ // Playback refused after the reload: show the true state.
2638
+ finish();
2639
+ this.onPause();
2640
+ });
2641
+ }, {once: true, signal: this._ac.signal});
2642
+ audio.load();
2643
+ }
2644
+
2515
2645
  /**
2516
2646
  * Seek the owned `<audio>` element to an absolute time, clamped to
2517
2647
  * `[0, duration]`, and refresh progress. Self mode only — a no-op when
@@ -2524,7 +2654,7 @@ export class WaveformPlayer {
2524
2654
  // Coerce + guard like setVolume(): `audio.currentTime = NaN` throws.
2525
2655
  const s = Number(seconds);
2526
2656
  if (this.audio && this.audio.duration && Number.isFinite(s)) {
2527
- this.audio.currentTime = clamp(s, 0, this.audio.duration);
2657
+ this._seekAudio(clamp(s, 0, this.audio.duration));
2528
2658
  this.updateProgress();
2529
2659
  }
2530
2660
  }
@@ -2538,7 +2668,7 @@ export class WaveformPlayer {
2538
2668
  seekToPercent(percent) {
2539
2669
  const p = Number(percent);
2540
2670
  if (this.audio && this.audio.duration && Number.isFinite(p)) {
2541
- this.audio.currentTime = this.audio.duration * clamp(p);
2671
+ this._seekAudio(this.audio.duration * clamp(p));
2542
2672
  this.updateProgress();
2543
2673
  }
2544
2674
  }
package/src/js/utils.js CHANGED
@@ -680,4 +680,36 @@ export function resampleData(data, targetLength) {
680
680
  }
681
681
 
682
682
  return result;
683
- }
683
+ }
684
+
685
+ /**
686
+ * Whether a time falls inside a `TimeRanges` (e.g. `audio.seekable`), with a
687
+ * little slack for float rounding at the edges.
688
+ *
689
+ * @param {Pick<TimeRanges, 'length'|'start'|'end'>} ranges - The ranges.
690
+ * @param {number} time - Seconds.
691
+ * @returns {boolean}
692
+ */
693
+ export function inTimeRanges(ranges, time) {
694
+ for (let i = 0; i < ranges.length; i++) {
695
+ if (ranges.start(i) - 0.05 <= time && time <= ranges.end(i) + 0.05) return true;
696
+ }
697
+ return false;
698
+ }
699
+
700
+ /**
701
+ * Whether one range of a `TimeRanges` (e.g. `audio.buffered`) spans the whole
702
+ * track: the file is fully downloaded, and so in the browser's HTTP cache.
703
+ *
704
+ * @param {Pick<TimeRanges, 'length'|'start'|'end'>} ranges - The ranges.
705
+ * @param {number} duration - Track length in seconds.
706
+ * @returns {boolean}
707
+ */
708
+ export function coversDuration(ranges, duration) {
709
+ if (!Number.isFinite(duration) || duration <= 0) return false;
710
+ for (let i = 0; i < ranges.length; i++) {
711
+ if (ranges.start(i) <= 0.05 && ranges.end(i) >= duration - 0.1) return true;
712
+ }
713
+ return false;
714
+ }
715
+