smsmslib 1.0.38 → 1.0.41

package/javascr/av_controller/AvControllerState_t.js

@@ -0,0 +1,66 @@
+/**
+ * @file
+ * Implementation of the AvControllerState_t class.
+ *
+ * @description
+ * This module defines the data structure representing the playback state 
+ * of an AV controller. It encapsulates essential properties from the 
+ * HTMLMediaElement to be used as the shared state within the Observer 
+ * pattern, facilitating synchronization between the media element and 
+ * its associated UI components.
+ *
+ * @module src/av_controller/AvControllerState_t
+ */
+
+
+/**
+ * Av controller status.
+ */
+export class AvControllerState_t
+{
+  /** The initial start time of the media in seconds. */
+  d_start_sec;
+
+  /** The initial end time of the media in seconds. 
+   * A negative value indicates that the end time is invalid or indefinite
+   * (e.g., live streaming).
+   */
+  d_end_sec;
+
+  /** The total duration of the media in seconds.
+   * A negative value indicates that the duration is unavailable or infinite.
+   */
+  duration;
+
+  /** HTMLMediaElement.paused (Read only)
+   * A boolean that indicates whether the media element is paused. */
+  paused;
+
+  /** HTMLMediaElement.playbackRate
+   * A double that indicates the rate at which the media is being played back. */
+  playbackRate;
+
+  /** HTMLMediaElement.currentTime
+   * A double-precision floating-point value indicating the current playback
+   * time in seconds. */
+  currentTime;
+
+  /** Element.clientWidth (of the outer container)
+   * The maximum width of the progress bar background in pixels. 
+   * This represents the total length of the seek bar. */
+  i_bar_px_max;
+
+  constructor()
+  {
+    this.d_start_sec  = 0.0;
+    this.d_end_sec    = 10.0;
+    this.duration     = 10.0;
+    this.paused       = true;
+    this.playbackRate = 1.0;
+    this.currentTime  = this.d_start_sec;
+    this.i_bar_px_max = 10;
+  }
+
+}
+
+

package/javascr/av_controller/HtmlControl_t.js

@@ -0,0 +1,56 @@
+/**
+ * @file
+ * Implementation of the HtmlControl_t class.
+ *
+ * @description
+ * This module provides the HtmlControl_t class, which manages the
+ * visibility of the AV custom control container. It acts as an 
+ * observer linked to a specific DOM element and 
+ * ensures the UI is revealed only when the media state is initialized.
+ *
+ * @module src/HtmlControl_t
+ */
+
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+import {HtmlElement_t} from "../system/index.js";
+
+
+/** ---------------------------------------------------------------------------
+ * Class.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Manages the visibility and lifecycle of the custom AV control interface.
+ *
+ * This class serves as the container for custom playback UI elements.
+ */
+export class HtmlControl_t extends HtmlElement_t
+{
+  /**
+   * @see HtmlElement_t#constructor
+   */
+  constructor(s_selector)
+  {
+    super(s_selector);
+  }
+
+  /**
+   * Synchronizes the initial state to display the custom controls.
+   *
+   * @param {AvControllerState_t} o_state [in]
+   * The initial data state provided by the subject.
+   *
+   * @see Observer_t#handle_initial_update
+   */
+  handle_initial_update(o_state)
+  {
+    this._o_element.style.visibility = "visible"; /* Show custom UI for playback. */
+  }
+  
+}
+
+

package/javascr/av_controller/HtmlMedia_t.js

@@ -0,0 +1,515 @@
+/**
+ * @file
+ * Implementation of the HtmlMedia_t class and its associated helper functions.
+ *
+ * @description
+ * This module provides the HtmlMedia_t class, which serves as a specialized 
+ * observer for HTMLMediaElements (e.g., <video> or <audio>). It facilitates 
+ * bidirectional synchronization: 
+ *
+ * @module src/av_controller/HtmlMedia_t
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+import
+{
+  sj_is_number,
+  sj_is_object,
+  sj_prop_chg_own,
+  HtmlElement_t,
+  sj_element_key_get,
+  sj_Subject_get,
+  Subject_t
+}
+from "../system/index.js";
+
+import {AvControllerState_t} from "./AvControllerState_t.js"
+
+
+/** ---------------------------------------------------------------------------
+ * Class.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Synchronizes a media element (e.g., <video> or <audio>) with the application
+ * state.
+ *
+ * @extends HtmlElement_t
+ */
+export class HtmlMedia_t extends HtmlElement_t
+{
+  /**
+   * @see HtmlElement_t#constructor
+   */
+  constructor(s_selector)
+  {
+    super(s_selector);
+
+    const b_valid = this.is_valid();
+
+    if (b_valid)
+    {
+      const o_element = this._o_element;
+
+      o_element.addEventListener("durationchange", HtmlMedia_on_durationchange);
+      o_element.addEventListener("timeupdate"    , HtmlMedia_on_timeupdate);
+      o_element.addEventListener("ended"         , HtmlMedia_on_ended);
+      o_element.addEventListener("loadedmetadata", HtmlMedia_on_loadedmetadata);
+    }
+  }
+
+  /**
+   * @see HtmlMedia_loadedmetadata_manual
+   */
+  loadedmetadata_manual()
+  {
+    const i_exe = HtmlMedia_loadedmetadata_manual(this._o_element);
+
+    return i_exe;
+  }
+
+  /**
+   * @see Observer_t#handle_retrieve
+   * @see HtmlMedia_handle_retrieve
+   */
+  handle_retrieve(o_state)
+  {
+    HtmlMedia_handle_retrieve(this._o_element, o_state);
+  }
+
+  /**
+   * @see Observer_t#handle_initial_update
+   * @see HtmlMedia_handle_initial_update
+   */
+  handle_initial_update(o_state)
+  {
+    HtmlMedia_handle_initial_update(this._o_element, o_state)
+  }
+
+  /**
+   * @see Observer_t#handle_update
+   * @see HtmlMedia_handle_update
+   */
+  handle_update(o_state, o_chg, o_src)
+  {
+    HtmlMedia_handle_update(this._o_element, o_state, o_chg, o_src);
+  }
+
+}
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Event handler for the media element's 'loadedmetadata' event.
+ *
+ * @param {Event} o_event [in]
+ * The event object dispatched by the media element.
+ *
+ * @see HtmlMedia_loadedmetadata
+ */
+function HtmlMedia_on_loadedmetadata(o_event)
+{
+  HtmlMedia_loadedmetadata(o_event.currentTarget);
+}
+
+
+/**
+ * Event handler for the media element's 'timeupdate' event.
+ *
+ * This function synchronizes the current playback time of the media element 
+ * with the application state. 
+ *
+ * @param {Event} o_event [in]
+ * The event object dispatched by the media element.
+ */
+function HtmlMedia_on_timeupdate(o_event)
+{
+  const o_element = o_event.currentTarget;
+  const s_key     = sj_element_key_get(o_element);
+  const o_Subject = sj_Subject_get(s_key);
+  let   o_state   = undefined;
+
+  if (o_Subject instanceof Subject_t)
+  {
+    o_state = o_Subject.data_get();
+  }
+
+  if (o_state instanceof AvControllerState_t)
+  {
+    const d_start_sec = HtmlMedia_start_sec(o_element);
+    const d_end_sec   = HtmlMedia_end_sec(o_element);
+    const o_chg       = {};
+
+    sj_prop_chg_own(o_state, "currentTime", o_element.currentTime, o_chg);
+    sj_prop_chg_own(o_state, "d_start_sec", d_start_sec          , o_chg);
+    sj_prop_chg_own(o_state, "d_end_sec"  , d_end_sec            , o_chg);
+
+    if (0 < Object.keys(o_chg).length)
+    {
+      o_Subject.observer_update(o_chg, o_element);
+    }
+  }
+}
+
+
+/**
+ * Handles the 'ended' event of the media element.
+ * This handler synchronizes the application state when the media reaches the end.
+ * Since browsers automatically pause the video/audio element when it finishes, 
+ * this function explicitly updates the `paused` state to `true` in the subject's 
+ * data to ensure consistency between the UI and the media element.
+ *
+ * @param {Event} o_event [in]
+ * The event object dispatched by the media element (HTMLMediaElement).
+ */
+function HtmlMedia_on_ended(o_event)
+{
+  const o_element = o_event.currentTarget;
+  const s_key     = sj_element_key_get(o_element);
+  const o_Subject = sj_Subject_get(s_key);
+  let   o_state   = undefined;
+
+  if (o_Subject instanceof Subject_t)
+  {
+    o_state = o_Subject.data_get();
+  }
+
+  if (o_state instanceof AvControllerState_t)
+  {
+    const o_chg = {};
+
+    sj_prop_chg_own(o_state, "paused", true, o_chg);
+
+    if (0 < Object.keys(o_chg).length)
+    {
+      o_Subject.observer_update(o_chg, o_element);
+    }
+  }
+}
+
+
+/**
+ * Handles the 'durationchange' event for an HTML media element.
+ *
+ * @description
+ * This event handler synchronizes the state of an `AvControllerState_t` object with 
+ * the updated timing information of the media element. 
+ *
+ * @param {Event} o_event [in]
+ * The 'durationchange' event object. `o_event.currentTarget` is expected to be 
+ * an `HTMLMediaElement`.
+ *
+ * @returns {void}
+ */
+function HtmlMedia_on_durationchange(o_event)
+{
+  const o_element = o_event.currentTarget;
+  const s_key     = sj_element_key_get(o_element);
+  const o_Subject = sj_Subject_get(s_key);
+  let   o_state   = undefined;
+
+  if (o_Subject instanceof Subject_t)
+  {
+    o_state = o_Subject.data_get();
+  }
+
+  if (o_state instanceof AvControllerState_t)
+  {
+    const duration    = HtmlMedia_duration(o_element);
+    const d_start_sec = HtmlMedia_start_sec(o_element);
+    const d_end_sec   = HtmlMedia_end_sec(o_element);
+    const o_chg       = {};
+
+    sj_prop_chg_own(o_state, "duration"   , duration   , o_chg);
+    sj_prop_chg_own(o_state, "d_start_sec", d_start_sec, o_chg);
+    sj_prop_chg_own(o_state, "d_end_sec"  , d_end_sec  , o_chg);
+
+    if (0 < Object.keys(o_chg).length)
+    {
+      o_Subject.observer_update(o_chg, o_element);
+    }
+  }
+}
+
+
+/**
+ * Retrieves the initial timing information from the media element.
+ *
+ * @param {HTMLMediaElement} o_element [in]
+ * The source media element to read timing data from.
+ *
+ * @param {AvControllerState_t} o_state [out]
+ * The state object to be populated with the retrieved timing values.
+ */
+function HtmlMedia_handle_retrieve(o_element, o_state)
+{
+  if (o_element && (o_state instanceof AvControllerState_t))
+  {
+    o_state.duration     = HtmlMedia_duration(o_element);
+    o_state.d_start_sec  = HtmlMedia_start_sec(o_element);
+    o_state.d_end_sec    = HtmlMedia_end_sec(o_element);
+    o_state.currentTime  = o_state.d_start_sec;
+    o_state.playbackRate = 1.0;
+  }
+}
+
+
+/**
+ * Performs the initial setup and state synchronization for the media element.
+ *
+ * @param {HTMLMediaElement} o_element [in/out]
+ * The target media element to be initialized.
+ *
+ * @param {AvControllerState_t} o_state [in]
+ * The initial state object containing the desired playback configuration.
+ */
+function HtmlMedia_handle_initial_update(o_element, o_state)
+{
+  if (o_element && (o_state instanceof AvControllerState_t))
+  {
+    o_element.removeAttribute("controls");  /* Hide default UI for playback */
+
+    if (o_state.paused)
+    {
+      o_element.pause();
+    }
+    else
+    {
+      o_element.play();
+    }
+
+    o_element.playbackRate = o_state.playbackRate;
+    o_element.currentTime  = o_state.d_start_sec;
+  }
+}
+
+
+/**
+ * Synchronizes the media element's playback state and rate based on state changes.
+ *
+ * @param {HTMLMediaElement} o_element [in/out]
+ * The target media element (video or audio) to be controlled.
+ *
+ * @param {AvControllerState_t} o_state [in]
+ * The current state of the AV controller.
+ *
+ * @param {Object} o_chg [in]
+ * An object containing only the properties that have changed since the last update.
+ * If a property is undefined here, no action is taken for that property.
+ *
+ * @param {Object} [o_src] [in]
+ * The object that originally triggered the update.
+ */
+function HtmlMedia_handle_update(o_element, o_state, o_chg, o_src)
+{
+  const b_chg_obj = sj_is_object(o_chg);
+
+  if (o_element && (o_state instanceof AvControllerState_t) && b_chg_obj)
+  {
+    const b_self_update = Object.is(o_element, o_src);
+
+    if ("paused" in o_chg)
+    {
+      if (o_state.paused)
+      {
+        o_element.pause();
+      }
+      else
+      {
+        o_element.play();
+      }
+    }
+
+    if ("playbackRate" in o_chg)
+    {
+      o_element.playbackRate = o_state.playbackRate;
+    }
+
+    if ((!b_self_update) && ("currentTime" in o_chg))
+    {
+      o_element.currentTime = o_state.currentTime;
+    }
+  }
+}
+
+
+/**
+ * Manually triggers the metadata loading logic if the media element is already
+ * initialized.
+ *
+ * This function checks the 'readyState' of the media element. If the metadata has 
+ * already been loaded (i.e., readyState > HAVE_NOTHING), it manually invokes 
+ * the 'HtmlMedia_loadedmetadata' handler to ensure state synchronization. 
+ * This prevents initialization failures when the browser loads media before 
+ * event listeners are attached.
+ *
+ * @param {HTMLMediaElement} o_element [in]
+ * The media element to check.
+ *
+ * @returns {number}
+ * 1 : Success. Metadata was already available, and the handler was executed.
+ * 0 : Pending. Metadata is not yet available; the system must wait for the event.
+ * -1 : Error. The provided element is invalid.
+ */
+function HtmlMedia_loadedmetadata_manual(o_element)
+{
+  let i_exe = - 1;
+
+  if (o_element)
+  {
+    if (HTMLMediaElement.HAVE_NOTHING < o_element.readyState)
+    {
+      HtmlMedia_loadedmetadata(o_element);
+      i_exe = 1;
+    }
+    else
+    {
+      i_exe = 0;
+    }
+  }
+
+  return i_exe;
+}
+
+
+/**
+ * Synchronizes the subject state and notifies observers when media metadata is loaded.
+ *
+ * This function acts as the core initialization logic for media-related state. 
+ * It retrieves the current properties (e.g., duration, seekable ranges) from the 
+ * media element to populate the Subject's data, and then triggers an initial 
+ * update to synchronize all registered observers with this state.
+ *
+ * @param {HTMLMediaElement} o_element [in]
+ * The HTML media element (video or audio) that has loaded its metadata.
+ */
+function HtmlMedia_loadedmetadata(o_element)
+{
+  const s_key     = sj_element_key_get(o_element);
+  const o_Subject = sj_Subject_get(s_key);
+
+  if (o_Subject instanceof Subject_t)
+  {
+    o_Subject.observer_retrieve();
+    o_Subject.observer_initial_update();
+  }
+}
+
+
+/**
+ * Retrieves the starting time (in seconds) of the first seekable range of a media
+ * element.
+ *
+ * @description
+ * This function checks the `seekable` property of the provided HTMLMediaElement.
+ * If at least one seekable range exists and contains a valid finite number, 
+ * it returns the start time of the first range. Otherwise, it defaults to 0. 
+ * This ensures a safe numeric fallback even if the media is in an unstable 
+ * state or is a live stream where the start point has shifted.
+ *
+ * @param {HTMLMediaElement} o_element [in]
+ * The HTML media element (e.g., <video> or <audio>) to check.
+ *
+ * @returns {number}
+ * The start time of the first seekable range in seconds, or 0 if no range 
+ * is available or the value is non-finite (Infinity/NaN).
+ */
+function HtmlMedia_start_sec(o_element)
+{
+  let d_start_sec;
+
+  if (0 < o_element.seekable.length)
+  {
+    d_start_sec = o_element.seekable.start(0);
+
+    const b_num = sj_is_number(d_start_sec);
+
+    if (!b_num)
+    {
+      d_start_sec = 0
+    }
+  }
+  else
+  {
+    d_start_sec = 0;
+  }
+
+   return d_start_sec;
+}
+
+
+/**
+ * Retrieves the ending time (in seconds) of the last seekable range of a media element.
+ *
+ * @description
+ * This function determines the effectively playable end point of the media.
+ * If seekable time ranges are available, it returns the end time of the very last range.
+ * If the duration is indefinite (Infinity), such as in live streams, it returns -1.
+ *
+ * @param {HTMLMediaElement} o_element [in]
+ * The HTML media element (e.g., <video> or <audio>) to inspect.
+ *
+ * @returns {number}
+ * The end time in seconds, or -1 if the duration is infinite/indefinite.
+ */
+function HtmlMedia_end_sec(o_element)
+{
+  let d_end_sec;
+
+  if (0 < o_element.seekable.length)
+  {
+    d_end_sec = o_element.seekable.end(o_element.seekable.length - 1);
+
+    const b_num = sj_is_number(d_end_sec);
+
+    if (!b_num)
+    {
+      d_end_sec = - 1.0;
+    }
+  }
+  else
+  {
+    d_end_sec = HtmlMedia_duration(o_element);
+  }
+
+   return d_end_sec;
+}
+
+
+/**
+ * Retrieves the duration of the media element in seconds.
+ *
+ * @description
+ * This function returns the total length of the media. If the duration is 
+ * unavailable (NaN) or represents an infinite stream (Infinity), such as 
+ * a live broadcast, it returns -1 to indicate an indefinite duration. 
+ * This ensures the returned value is always a finite number, making it 
+ * safe for serialization and consistent state management.
+ *
+ * @param {HTMLMediaElement} o_element [in]
+ * The HTML media element to inspect.
+ *
+ * @returns {number}
+ * The duration in seconds, or -1 if the duration is infinite or unavailable.
+ */
+function HtmlMedia_duration(o_element)
+{
+  let duration = o_element.duration;
+
+  const b_num = sj_is_number(duration);
+
+  if (!b_num)
+  {
+    duration = - 1.0;
+  }
+
+   return duration;
+}
+
+