live-start-bug: updating new fn name to alignMediaPlaylistByPDT, addi…

…ng further description, and updating subtitle-track-controller to also use for initial load, per PR feedback.

src/controller/audio-stream-controller.ts

@@ -9,7 +9,7 @@ import ChunkCache from '../demux/chunk-cache';
 import TransmuxerInterface from '../demux/transmuxer-interface';
 import { ChunkMetadata } from '../types/transmuxer';
 import { fragmentWithinToleranceTest } from './fragment-finders';
-import { alignByPDT } from '../utils/discontinuities';
+import { alignMediaPlaylistByPDT } from '../utils/discontinuities';
 import { ErrorDetails } from '../errors';
 import { logger } from '../utils/logger';
 import type { NetworkComponentAPI } from '../types/component-api';
@@ -443,7 +443,7 @@ class AudioStreamController
       ) {
         // Make sure our audio rendition is aligned with the "main" rendition, using
         // pdt as our reference times.
-        alignByPDT(newDetails, mainDetails);
+        alignMediaPlaylistByPDT(newDetails, mainDetails);
         sliding = newDetails.fragments[0].start;
       } else {
         sliding = this.alignPlaylists(newDetails, track.details);

src/controller/subtitle-stream-controller.ts

@@ -2,7 +2,7 @@ import { Events } from '../events';
 import { logger } from '../utils/logger';
 import { BufferHelper } from '../utils/buffer-helper';
 import { findFragmentByPDT, findFragmentByPTS } from './fragment-finders';
-import { alignPDT } from '../utils/discontinuities';
+import { alignMediaPlaylistByPDT } from '../utils/discontinuities';
 import { addSliding } from './level-helper';
 import { FragmentState } from './fragment-tracker';
 import BaseStreamController, { State } from './base-stream-controller';
@@ -251,7 +251,7 @@ export class SubtitleStreamController
       const mainSlidingStartFragment = mainDetails.fragments[0];
       if (!track.details) {
         if (newDetails.hasProgramDateTime && mainDetails.hasProgramDateTime) {
-          alignPDT(newDetails, mainDetails);
+          alignMediaPlaylistByPDT(newDetails, mainDetails);
         } else if (mainSlidingStartFragment) {
           // line up live playlist with main so that fragments in range are loaded
           addSliding(newDetails, mainSlidingStartFragment.start);

src/utils/discontinuities.ts

@@ -183,11 +183,22 @@ export function alignFragmentByPDTDelta(frag: Fragment, delta: number) {
 }
 
 /**
- * Ensures appropriate time-alignment between renditions based on PDT.
+ * Ensures appropriate time-alignment between renditions based on PDT. Unlike `alignPDT`, which adjusts
+ * the timeline based on the delta between PDTs of the 0th fragment of two playlists/`LevelDetails`,
+ * this function assumes the timelines represented in `refDetails` are accurate, including the PDTs,
+ * and uses the "wallclock"/PDT timeline as a cross-reference to `details`, adjusting the presentation
+ * times/timelines of `details` accordingly.
+ * Given the asynchronous nature of fetches and initial loads of live `main` and audio/subtitle tracks,
+ * the primary purpose of this function is to ensure the "local timelines" of audio/subtitle tracks
+ * are aligned to the main/video timeline, using PDT as the cross-reference/"anchor" that should
+ * be consistent across playlists, per the HLS spec.
  * @param details - The details of the rendition you'd like to time-align (e.g. an audio rendition).
  * @param refDetails - The details of the reference rendition with start and PDT times for alignment.
  */
-export function alignByPDT(details: LevelDetails, refDetails: LevelDetails) {
+export function alignMediaPlaylistByPDT(
+  details: LevelDetails,
+  refDetails: LevelDetails
+) {
   // This check protects the unsafe "!" usage below for null program date time access.
   if (
     !refDetails.fragments.length ||

tests/unit/utils/discontinuities.js

@@ -3,7 +3,7 @@ import {
   findDiscontinuousReferenceFrag,
   adjustSlidingStart,
   alignPDT,
-  alignByPDT,
+  alignMediaPlaylistByPDT,
 } from '../../../src/utils/discontinuities';
 
 const mockReferenceFrag = {
@@ -163,7 +163,7 @@ describe('level-helper', function () {
       alignedSliding: true,
       hasProgramDateTime: true,
     };
-    alignByPDT(lastLevel.details, refDetails);
+    alignMediaPlaylistByPDT(lastLevel.details, refDetails);
     expect(
       lastLevel.details,
       `actual:\n\n${JSON.stringify(