track/access audio ref remove caption description

.changeset/polite-cougars-cheer.md

@@ -0,0 +1,5 @@
+---
+"react-audio-tracks": patch
+---
+
+allow accessing audioref on track stream interface and remove a built-in caption property ('description') which should be accessed from the custom 'metadata' property. Keep it less heavy in boilerplate.

src/AudioItem.ts

@@ -131,6 +131,10 @@ class AudioItem {
     }
   }
 
+  public unsafe_getInnerAudio(): Readonly<HTMLAudioElement> | null {
+    return this.#innerAudio ?? null
+  }
+
   public getInnerAudioState(): T.InnerAudioState | null {
     if (!this.#innerAudio) return null
     return {

src/Track.ts

@@ -32,6 +32,7 @@ class Track {
     audioItemState: null,
     caption: null,
     innerAudioState: null,
+    innerAudioRef: null,
   }
   private stream_listeners: T.Listener<T.TrackStream>[] = []
   updateTrackCallback: (trackState: T.TrackState) => void = () => {}
@@ -91,13 +92,15 @@ class Track {
         caption: null,
         audioItemState: null,
         innerAudioState: null,
+        innerAudioRef: null,
       })
     } else if (!this.#State.autoPlay) {
       Statepayload.isPlaying = false
       this.#updateStream({
         trackIsPlaying: false,
         audioItemState: this.#queue[0]?.getState() ?? null,
         innerAudioState: this.#queue[0]?.getInnerAudioState() ?? null,
+        innerAudioRef: this.#queue[0]?.unsafe_getInnerAudio() ?? null,
       })
     }
     this.#updateState(Statepayload)
@@ -340,6 +343,7 @@ class Track {
           trackIsPlaying: true,
           audioItemState: audioItem.getState(),
           innerAudioState: audioItem.getInnerAudioState(),
+          innerAudioRef: audioItem.unsafe_getInnerAudio(),
         }
         if (_subtitles?.length) {
           payload.caption = U.getCurrentCaption(_subtitles, 0, _locale)
@@ -356,6 +360,7 @@ class Track {
         const payload: Partial<T.TrackStream> = {
           audioItemState: audioItem.getState(),
           innerAudioState: audioItem.getInnerAudioState(),
+          innerAudioRef: audioItem.unsafe_getInnerAudio(),
         }
         if (_subtitles?.length) {
           payload.caption = U.getCurrentCaption(
@@ -377,6 +382,7 @@ class Track {
           trackIsPlaying: false,
           audioItemState: audioItem.getState(),
           innerAudioState: audioItem.getInnerAudioState(),
+          innerAudioRef: audioItem.unsafe_getInnerAudio(),
         })
       },
       onEnd: () => {
@@ -387,6 +393,7 @@ class Track {
         this.#updateStream({
           audioItemState: null,
           innerAudioState: null,
+          innerAudioRef: null,
           caption: null,
         })
       },
@@ -406,6 +413,7 @@ class Track {
         this.#updateStream({
           audioItemState: null,
           innerAudioState: null,
+          innerAudioRef: null,
           caption: null,
         })
       },

src/types.ts

@@ -35,19 +35,6 @@ export type Subtitle = {
     | {
         [locale: string]: string
       }
-
-  /**
-   *  Extra metadata: Description of the scene
-   *
-   *  Supporting internationalization
-   *
-   *  Example: { "en":"(Footsteps approaching)", "fr": "(Des pas approchent)" }
-   */
-  description?:
-    | string
-    | {
-        [langID: string]: string
-      }
   /**
    * Extra metadata based on the timeline of the audio
    */
@@ -157,15 +144,6 @@ export type CaptionState = {
    */
   text: string
 
-  /**
-   *  Extra metadata: Description of the scene
-   *
-   *  This has to be given in the subtitles option.
-   *
-   *  Example: "Footsteps approaching"
-   */
-  description?: string
-
   /**
    * Extra metadata based on the timeline of the audio
    *
@@ -334,6 +312,8 @@ export type TrackStream = {
   readonly audioItemState: AudioItemState | null
   caption: CaptionState | null
   readonly innerAudioState: InnerAudioState | null
+  /** directly accessing audio element's ref */
+  readonly innerAudioRef: HTMLAudioElement | null
 }
 
 /**
@@ -363,5 +343,5 @@ export type RegistrationArgTuple = [
   options?: AudioCallbacks &
     AudioOptions & {
       trackIdx?: number
-    }
+    },
 ]