feat: Add sound-position-timestamp helper to get current time from HLS streams, or approximate the time from startsAt if currentTime is not available

Author: jkeen

.github/actions/assert-build/action.yml

@@ -35,6 +35,7 @@ runs:
             helpers/sound-is-seekable.js
             helpers/sound-metadata.js
             helpers/sound-position.js
+            helpers/sound-position-timestamp.js
             helpers/stereo-volume-is-adjustable.js
             helpers/stereo-volume.js
             helpers/stop-sound.js

docs/app/components/docs/custom-position-control.js

@@ -2,11 +2,10 @@ import Component from '@glimmer/component';
 import { action } from '@ember/object';
 import { tracked } from '@glimmer/tracking';
 export default class DocsCustomPositionControlComponent extends Component {
-
   @tracked lastSelectedPosition;
 
   @action
-  onChangePosition(position, event) {
+  onChangePosition(position /* event */) {
     this.lastSelectedPosition = position;
   }
 }

docs/app/components/docs/manual-position-control.js

@@ -2,7 +2,6 @@ import Component from '@glimmer/component';
 import { action } from '@ember/object';
 import { tracked } from '@glimmer/tracking';
 export default class DocsCustomPositionControlComponent extends Component {
-
   @tracked lastSelectedPosition;
 
   @action

docs/app/components/docs/queued.js

@@ -14,7 +14,7 @@ export default class Queued extends Component {
     this.queue = [
       '/sounds/attention.mp3',
       '/sounds/internet-on-computers.mp3',
-      'https://streaming.koop.org/stream.aac';,
+      'https://streaming.koop.org/stream.aac',
     ];
 
     let sound = await this.playNext();

ember-stereo/src/helpers/sound-position-timestamp.js

@@ -0,0 +1,52 @@
+import StereoBaseIsHelper from '../-private/helpers/is-helper';
+import { add } from 'date-fns';
+
+/**
+  A helper to get a sound's position timestamp based on the playingDate property in an HLS file, or from the position + a startsAt parameter.
+  ```hbs
+
+  this.startsAt = new Date('2024-10-01T00:00:00Z');
+  {{sound-position-timestamp @identifier}} #=> playingDate property from HLS
+  {{sound-position-timestamp @identifier startsAt=this.startsAt}} #=> new Date('2024-10-01T00:00:00Z')
+   ```
+
+  @class {{sound-position-timestamp}}
+  @type {Helper}
+*/
+
+/**
+  @method compute
+  @param {Any} identifier url, urls, url objects, promise that resolves to a url
+  @param {Float} position
+  @param {Date} currentTime
+  @param {Date} startsAt
+  @return {Date}
+*/
+export default class SoundPositionTimestamp extends StereoBaseIsHelper {
+  name = 'sound-position-timestamp';
+
+  get result() {
+    let result;
+    let position = this.options?.position || this.sound?.position || 0;
+    let currentTime = this.sound?.currentTime;
+    let startsAt = this.options?.startsAt;
+
+    if (startsAt && !this.sound?.isLoaded) {
+      return new Date(startsAt);
+    }
+
+    if (currentTime) {
+      result = new Date(currentTime);
+    } else if (startsAt) {
+      result = add(new Date(startsAt), {
+        seconds: position / 1000,
+      });
+    }
+
+    if (result instanceof Date && !isNaN(result)) {
+      return result;
+    } else {
+      return undefined;
+    }
+  }
+}