@editframe/elements 0.20.4-beta.0 → 0.21.0-beta.0

package/src/elements/EFMedia/AssetMediaEngine.ts

@@ -1,5 +1,6 @@
 import type { TrackFragmentIndex } from "@editframe/assets";
 
+import { withSpan } from "../../otel/tracingHelpers.js";
 import type {
   AudioRendition,
   InitSegmentPaths,
@@ -121,23 +122,36 @@ export class AssetMediaEngine extends BaseMediaEngine implements MediaEngine {
     rendition: { trackId: number | undefined; src: string },
     signal: AbortSignal,
   ) {
-    if (!rendition.trackId) {
-      throw new Error(
-        "[fetchInitSegment] Track ID is required for asset metadata",
-      );
-    }
-    const url = this.buildInitSegmentUrl(rendition.trackId);
-    const initSegment = this.data[rendition.trackId]?.initSegment;
-    if (!initSegment) {
-      throw new Error("Init segment not found");
-    }
-
-    // Use unified fetch method with Range headers
-    const headers = {
-      Range: `bytes=${initSegment.offset}-${initSegment.offset + initSegment.size - 1}`,
-    };
-
-    return this.fetchMediaWithHeaders(url, headers, signal);
+    return withSpan(
+      "assetEngine.fetchInitSegment",
+      {
+        trackId: rendition.trackId || -1,
+        src: rendition.src,
+      },
+      undefined,
+      async (span) => {
+        if (!rendition.trackId) {
+          throw new Error(
+            "[fetchInitSegment] Track ID is required for asset metadata",
+          );
+        }
+        const url = this.buildInitSegmentUrl(rendition.trackId);
+        const initSegment = this.data[rendition.trackId]?.initSegment;
+        if (!initSegment) {
+          throw new Error("Init segment not found");
+        }
+
+        span.setAttribute("offset", initSegment.offset);
+        span.setAttribute("size", initSegment.size);
+
+        // Use unified fetch method with Range headers
+        const headers = {
+          Range: `bytes=${initSegment.offset}-${initSegment.offset + initSegment.size - 1}`,
+        };
+
+        return this.fetchMediaWithHeaders(url, headers, signal);
+      },
+    );
   }
 
   async fetchMediaSegment(
@@ -145,26 +159,40 @@ export class AssetMediaEngine extends BaseMediaEngine implements MediaEngine {
     rendition: { trackId: number | undefined; src: string },
     signal?: AbortSignal,
   ) {
-    if (!rendition.trackId) {
-      throw new Error(
-        "[fetchMediaSegment] Track ID is required for asset metadata",
-      );
-    }
-    if (segmentId === undefined) {
-      throw new Error("Segment ID is not available");
-    }
-    const url = this.buildMediaSegmentUrl(rendition.trackId, segmentId);
-    const mediaSegment = this.data[rendition.trackId]?.segments[segmentId];
-    if (!mediaSegment) {
-      throw new Error("Media segment not found");
-    }
-
-    // Use unified fetch method with Range headers
-    const headers = {
-      Range: `bytes=${mediaSegment.offset}-${mediaSegment.offset + mediaSegment.size - 1}`,
-    };
-
-    return this.fetchMediaWithHeaders(url, headers, signal);
+    return withSpan(
+      "assetEngine.fetchMediaSegment",
+      {
+        segmentId,
+        trackId: rendition.trackId || -1,
+        src: rendition.src,
+      },
+      undefined,
+      async (span) => {
+        if (!rendition.trackId) {
+          throw new Error(
+            "[fetchMediaSegment] Track ID is required for asset metadata",
+          );
+        }
+        if (segmentId === undefined) {
+          throw new Error("Segment ID is not available");
+        }
+        const url = this.buildMediaSegmentUrl(rendition.trackId, segmentId);
+        const mediaSegment = this.data[rendition.trackId]?.segments[segmentId];
+        if (!mediaSegment) {
+          throw new Error("Media segment not found");
+        }
+
+        span.setAttribute("offset", mediaSegment.offset);
+        span.setAttribute("size", mediaSegment.size);
+
+        // Use unified fetch method with Range headers
+        const headers = {
+          Range: `bytes=${mediaSegment.offset}-${mediaSegment.offset + mediaSegment.size - 1}`,
+        };
+
+        return this.fetchMediaWithHeaders(url, headers, signal);
+      },
+    );
   }
 
   /**

package/src/elements/EFMedia/BaseMediaEngine.ts

@@ -1,3 +1,4 @@
+import { withSpan } from "../../otel/tracingHelpers.js";
 import { RequestDeduplicator } from "../../transcoding/cache/RequestDeduplicator.js";
 import type {
   AudioRendition,
@@ -61,65 +62,122 @@ export abstract class BaseMediaEngine {
       signal?: AbortSignal;
     },
   ): Promise<any> {
-    const { responseType, headers, signal } = options;
-
-    // Create cache key that includes URL and headers for proper isolation
-    // Note: We don't include signal in cache key as it would prevent proper deduplication
-    const cacheKey = headers ? `${url}:${JSON.stringify(headers)}` : url;
-
-    // Check cache first
-    const cached = mediaCache.get(cacheKey);
-    if (cached) {
-      // If we have a cached promise, we need to handle the caller's abort signal
-      // without affecting the underlying request that other instances might be using
-      if (signal) {
-        return this.handleAbortForCachedRequest(cached, signal);
-      }
-      return cached;
-    }
-
-    // Use global deduplicator to prevent concurrent requests for the same resource
-    // Note: We do NOT pass the signal to the deduplicator - each caller manages their own abort
-    const promise = globalRequestDeduplicator.executeRequest(
-      cacheKey,
-      async () => {
-        try {
-          // Make the fetch request WITHOUT the signal - let each caller handle their own abort
-          // This prevents one instance's abort from affecting other instances using the shared cache
-          const response = await this.host.fetch(url, { headers });
-
-          if (responseType === "json") {
-            return response.json();
+    return withSpan(
+      "mediaEngine.fetchWithCache",
+      {
+        url: url.length > 100 ? `${url.substring(0, 100)}...` : url,
+        responseType: options.responseType,
+        hasHeaders: !!options.headers,
+      },
+      undefined,
+      async (span) => {
+        const t0 = performance.now();
+        const { responseType, headers, signal } = options;
+
+        // Create cache key that includes URL and headers for proper isolation
+        // Note: We don't include signal in cache key as it would prevent proper deduplication
+        const cacheKey = headers ? `${url}:${JSON.stringify(headers)}` : url;
+
+        // Check cache first
+        const t1 = performance.now();
+        const cached = mediaCache.get(cacheKey);
+        const t2 = performance.now();
+        span.setAttribute("cacheLookupMs", Math.round((t2 - t1) * 1000) / 1000);
+
+        if (cached) {
+          span.setAttribute("cacheHit", true);
+          // If we have a cached promise, we need to handle the caller's abort signal
+          // without affecting the underlying request that other instances might be using
+          if (signal) {
+            const t3 = performance.now();
+            const result = await this.handleAbortForCachedRequest(
+              cached,
+              signal,
+            );
+            const t4 = performance.now();
+            span.setAttribute(
+              "handleAbortMs",
+              Math.round((t4 - t3) * 100) / 100,
+            );
+            span.setAttribute(
+              "totalCacheHitMs",
+              Math.round((t4 - t0) * 100) / 100,
+            );
+            return result;
           }
-          return response.arrayBuffer();
-        } catch (error) {
-          // If the request was aborted, don't cache the error
+          span.setAttribute(
+            "totalCacheHitMs",
+            Math.round((t2 - t0) * 100) / 100,
+          );
+          return cached;
+        }
+
+        span.setAttribute("cacheHit", false);
+
+        // Use global deduplicator to prevent concurrent requests for the same resource
+        // Note: We do NOT pass the signal to the deduplicator - each caller manages their own abort
+        const promise = globalRequestDeduplicator.executeRequest(
+          cacheKey,
+          async () => {
+            const fetchStart = performance.now();
+            try {
+              // Make the fetch request WITHOUT the signal - let each caller handle their own abort
+              // This prevents one instance's abort from affecting other instances using the shared cache
+              const response = await this.host.fetch(url, { headers });
+              const fetchEnd = performance.now();
+              span.setAttribute("fetchMs", fetchEnd - fetchStart);
+
+              if (responseType === "json") {
+                return response.json();
+              }
+              const buffer = await response.arrayBuffer();
+              span.setAttribute("sizeBytes", buffer.byteLength);
+              return buffer;
+            } catch (error) {
+              // If the request was aborted, don't cache the error
+              if (
+                error instanceof DOMException &&
+                error.name === "AbortError"
+              ) {
+                // Remove from cache so other requests can retry
+                mediaCache.delete(cacheKey);
+              }
+              throw error;
+            }
+          },
+        );
+
+        // Cache the promise (not the result) to handle concurrent requests
+        mediaCache.set(cacheKey, promise);
+
+        // Handle the case where the promise might be aborted
+        promise.catch((error) => {
+          // If the request was aborted, remove it from cache to prevent corrupted data
           if (error instanceof DOMException && error.name === "AbortError") {
-            // Remove from cache so other requests can retry
             mediaCache.delete(cacheKey);
           }
-          throw error;
+        });
+
+        // If the caller has a signal, handle abort logic without affecting the underlying request
+        if (signal) {
+          const result = await this.handleAbortForCachedRequest(
+            promise,
+            signal,
+          );
+          const tEnd = performance.now();
+          span.setAttribute(
+            "totalFetchMs",
+            Math.round((tEnd - t0) * 100) / 100,
+          );
+          return result;
         }
+
+        const result = await promise;
+        const tEnd = performance.now();
+        span.setAttribute("totalFetchMs", Math.round((tEnd - t0) * 100) / 100);
+        return result;
       },
     );
-
-    // Cache the promise (not the result) to handle concurrent requests
-    mediaCache.set(cacheKey, promise);
-
-    // Handle the case where the promise might be aborted
-    promise.catch((error) => {
-      // If the request was aborted, remove it from cache to prevent corrupted data
-      if (error instanceof DOMException && error.name === "AbortError") {
-        mediaCache.delete(cacheKey);
-      }
-    });
-
-    // If the caller has a signal, handle abort logic without affecting the underlying request
-    if (signal) {
-      return this.handleAbortForCachedRequest(promise, signal);
-    }
-
-    return promise;
   }
 
   /**

package/src/elements/EFMedia/BufferedSeekingInput.ts

@@ -8,6 +8,7 @@ import {
   MP4,
   VideoSampleSink,
 } from "mediabunny";
+import { withSpan } from "../../otel/tracingHelpers.js";
 import { type MediaSample, SampleBuffer } from "../SampleBuffer";
 import { roundToMilliseconds } from "./shared/PrecisionUtils";
 
@@ -177,26 +178,39 @@ export class BufferedSeekingInput {
   }
 
   async seek(trackId: number, timeMs: number) {
-    // Apply timeline offset to map user timeline to media timeline
-    const mediaTimeMs = timeMs + this.startTimeOffsetMs;
-
-    // Round using consistent precision handling
-    const roundedMediaTimeMs = roundToMilliseconds(mediaTimeMs);
-
-    // Serialize seek operations per track (but don't block iterator creation)
-    const existingSeek = this.trackSeekPromises.get(trackId);
-    if (existingSeek) {
-      await existingSeek;
-    }
+    return withSpan(
+      "bufferedInput.seek",
+      {
+        trackId,
+        timeMs,
+        startTimeOffsetMs: this.startTimeOffsetMs,
+      },
+      undefined,
+      async (span) => {
+        // Apply timeline offset to map user timeline to media timeline
+        const mediaTimeMs = timeMs + this.startTimeOffsetMs;
+
+        // Round using consistent precision handling
+        const roundedMediaTimeMs = roundToMilliseconds(mediaTimeMs);
+        span.setAttribute("roundedMediaTimeMs", roundedMediaTimeMs);
+
+        // Serialize seek operations per track (but don't block iterator creation)
+        const existingSeek = this.trackSeekPromises.get(trackId);
+        if (existingSeek) {
+          span.setAttribute("waitedForExistingSeek", true);
+          await existingSeek;
+        }
 
-    const seekPromise = this.seekSafe(trackId, roundedMediaTimeMs);
-    this.trackSeekPromises.set(trackId, seekPromise);
+        const seekPromise = this.seekSafe(trackId, roundedMediaTimeMs);
+        this.trackSeekPromises.set(trackId, seekPromise);
 
-    try {
-      return await seekPromise;
-    } finally {
-      this.trackSeekPromises.delete(trackId);
-    }
+        try {
+          return await seekPromise;
+        } finally {
+          this.trackSeekPromises.delete(trackId);
+        }
+      },
+    );
   }
 
   private async resetIterator(track: InputTrack) {
@@ -224,90 +238,193 @@ export class BufferedSeekingInput {
   #seekLock?: PromiseWithResolvers<void>;
 
   private async seekSafe(trackId: number, timeMs: number) {
-    if (this.#seekLock) {
-      await this.#seekLock.promise;
-    }
-    const seekLock = Promise.withResolvers<void>();
-    this.#seekLock = seekLock;
-
-    try {
-      const track = await this.getTrack(trackId);
-      const trackBuffer = this.getTrackBuffer(track);
-
-      const roundedTimeMs = roundToMilliseconds(timeMs);
-      const firstTimestampMs = roundToMilliseconds(
-        (await track.getFirstTimestamp()) * 1000,
-      );
-
-      if (roundedTimeMs < firstTimestampMs) {
-        console.error("Seeking outside bounds of input", {
-          roundedTimeMs,
-          firstTimestampMs,
-        });
-        throw new NoSample(
-          `Seeking outside bounds of input ${roundedTimeMs} < ${firstTimestampMs}`,
-        );
-      }
-
-      // Check if we need to reset iterator for seeks outside current buffer range
-      const bufferContents = trackBuffer.getContents();
-      if (bufferContents.length > 0) {
-        const bufferStartMs = roundToMilliseconds(
-          trackBuffer.firstTimestamp * 1000,
-        );
-
-        if (roundedTimeMs < bufferStartMs) {
-          await this.resetIterator(track);
-        }
-      }
-
-      const alreadyInBuffer = trackBuffer.find(timeMs);
-      if (alreadyInBuffer) return alreadyInBuffer;
-
-      const iterator = this.getTrackIterator(track);
-      while (true) {
-        const { done, value: decodedSample } = await iterator.next();
-
-        if (decodedSample) {
-          trackBuffer.push(decodedSample);
-        }
-        const foundSample = trackBuffer.find(roundedTimeMs);
-        if (foundSample) {
-          return foundSample;
-        }
-        if (done) {
-          break;
+    return withSpan(
+      "bufferedInput.seekSafe",
+      {
+        trackId,
+        timeMs,
+      },
+      undefined,
+      async (span) => {
+        if (this.#seekLock) {
+          span.setAttribute("waitedForSeekLock", true);
+          await this.#seekLock.promise;
         }
-      }
-
-      // Check if we're seeking to the exact end of the track (legitimate use case)
-      const finalBufferContents = trackBuffer.getContents();
-      if (finalBufferContents.length > 0) {
-        const lastSample = finalBufferContents[finalBufferContents.length - 1];
-        const lastSampleEndMs = roundToMilliseconds(
-          ((lastSample?.timestamp || 0) + (lastSample?.duration || 0)) * 1000,
-        );
-
-        // Only return last sample if seeking to exactly the track duration
-        // (end of video) AND we have the final segment loaded
-        const trackDurationMs = (await track.computeDuration()) * 1000;
-        const isSeekingToTrackEnd =
-          roundToMilliseconds(timeMs) === roundToMilliseconds(trackDurationMs);
-        const isAtEndOfTrack = roundToMilliseconds(timeMs) >= lastSampleEndMs;
-
-        if (isSeekingToTrackEnd && isAtEndOfTrack) {
-          return lastSample;
+        const seekLock = Promise.withResolvers<void>();
+        this.#seekLock = seekLock;
+
+        try {
+          const track = await this.getTrack(trackId);
+          span.setAttribute("trackType", track.type);
+
+          const trackBuffer = this.getTrackBuffer(track);
+
+          const roundedTimeMs = roundToMilliseconds(timeMs);
+          const firstTimestampMs = roundToMilliseconds(
+            (await track.getFirstTimestamp()) * 1000,
+          );
+          span.setAttribute("firstTimestampMs", firstTimestampMs);
+
+          if (roundedTimeMs < firstTimestampMs) {
+            console.error("Seeking outside bounds of input", {
+              roundedTimeMs,
+              firstTimestampMs,
+            });
+            throw new NoSample(
+              `Seeking outside bounds of input ${roundedTimeMs} < ${firstTimestampMs}`,
+            );
+          }
+
+          // Check if we need to reset iterator for seeks outside current buffer range
+          const bufferContents = trackBuffer.getContents();
+          span.setAttribute("bufferContentsLength", bufferContents.length);
+
+          if (bufferContents.length > 0) {
+            const bufferStartMs = roundToMilliseconds(
+              trackBuffer.firstTimestamp * 1000,
+            );
+            span.setAttribute("bufferStartMs", bufferStartMs);
+
+            if (roundedTimeMs < bufferStartMs) {
+              span.setAttribute("resetIterator", true);
+              await this.resetIterator(track);
+            }
+          }
+
+          const alreadyInBuffer = trackBuffer.find(timeMs);
+          if (alreadyInBuffer) {
+            span.setAttribute("foundInBuffer", true);
+            span.setAttribute("bufferSize", trackBuffer.length);
+            const contents = trackBuffer.getContents();
+            if (contents.length > 0) {
+              span.setAttribute(
+                "bufferTimestamps",
+                contents
+                  .map((s) => Math.round((s.timestamp || 0) * 1000))
+                  .slice(0, 10)
+                  .join(","),
+              );
+            }
+            return alreadyInBuffer;
+          }
+
+          // Buffer miss - record buffer state
+          span.setAttribute("foundInBuffer", false);
+          span.setAttribute("bufferSize", trackBuffer.length);
+          span.setAttribute("requestedTimeMs", Math.round(timeMs));
+
+          const contents = trackBuffer.getContents();
+          if (contents.length > 0) {
+            const firstSample = contents[0];
+            const lastSample = contents[contents.length - 1];
+            if (firstSample && lastSample) {
+              const bufferStartMs = Math.round(
+                (firstSample.timestamp || 0) * 1000,
+              );
+              const bufferEndMs = Math.round(
+                ((lastSample.timestamp || 0) + (lastSample.duration || 0)) *
+                  1000,
+              );
+              span.setAttribute("bufferStartMs", bufferStartMs);
+              span.setAttribute("bufferEndMs", bufferEndMs);
+              span.setAttribute(
+                "bufferRangeMs",
+                `${bufferStartMs}-${bufferEndMs}`,
+              );
+            }
+          }
+
+          const iterator = this.getTrackIterator(track);
+          let iterationCount = 0;
+          const decodeStart = performance.now();
+
+          while (true) {
+            iterationCount++;
+            const iterStart = performance.now();
+            const { done, value: decodedSample } = await iterator.next();
+            const iterEnd = performance.now();
+
+            // Record individual iteration timing for first 5 iterations
+            if (iterationCount <= 5) {
+              span.setAttribute(
+                `iter${iterationCount}Ms`,
+                Math.round((iterEnd - iterStart) * 100) / 100,
+              );
+            }
+
+            if (decodedSample) {
+              trackBuffer.push(decodedSample);
+              if (iterationCount <= 5) {
+                span.setAttribute(
+                  `iter${iterationCount}Timestamp`,
+                  Math.round((decodedSample.timestamp || 0) * 1000),
+                );
+              }
+            }
+
+            const foundSample = trackBuffer.find(roundedTimeMs);
+            if (foundSample) {
+              const decodeEnd = performance.now();
+              span.setAttribute("iterationCount", iterationCount);
+              span.setAttribute(
+                "decodeMs",
+                Math.round((decodeEnd - decodeStart) * 100) / 100,
+              );
+              span.setAttribute(
+                "avgIterMs",
+                Math.round(((decodeEnd - decodeStart) / iterationCount) * 100) /
+                  100,
+              );
+              span.setAttribute("foundSample", true);
+              span.setAttribute(
+                "foundTimestamp",
+                Math.round((foundSample.timestamp || 0) * 1000),
+              );
+              return foundSample;
+            }
+            if (done) {
+              break;
+            }
+          }
+
+          span.setAttribute("iterationCount", iterationCount);
+          span.setAttribute("reachedEnd", true);
+
+          // Check if we're seeking to the exact end of the track (legitimate use case)
+          const finalBufferContents = trackBuffer.getContents();
+          if (finalBufferContents.length > 0) {
+            const lastSample =
+              finalBufferContents[finalBufferContents.length - 1];
+            const lastSampleEndMs = roundToMilliseconds(
+              ((lastSample?.timestamp || 0) + (lastSample?.duration || 0)) *
+                1000,
+            );
+
+            // Only return last sample if seeking to exactly the track duration
+            // (end of video) AND we have the final segment loaded
+            const trackDurationMs = (await track.computeDuration()) * 1000;
+            const isSeekingToTrackEnd =
+              roundToMilliseconds(timeMs) ===
+              roundToMilliseconds(trackDurationMs);
+            const isAtEndOfTrack =
+              roundToMilliseconds(timeMs) >= lastSampleEndMs;
+
+            if (isSeekingToTrackEnd && isAtEndOfTrack) {
+              span.setAttribute("returnedLastSample", true);
+              return lastSample;
+            }
+          }
+
+          // For all other cases (seeking within track but outside buffer range), throw error
+          // The caller should ensure the correct segment is loaded before seeking
+          throw new NoSample(
+            `Sample not found for time ${timeMs} in ${track.type} track ${trackId}`,
+          );
+        } finally {
+          this.#seekLock = undefined;
+          seekLock.resolve();
         }
-      }
-
-      // For all other cases (seeking within track but outside buffer range), throw error
-      // The caller should ensure the correct segment is loaded before seeking
-      throw new NoSample(
-        `Sample not found for time ${timeMs} in ${track.type} track ${trackId}`,
-      );
-    } finally {
-      this.#seekLock = undefined;
-      seekLock.resolve();
-    }
+      },
+    );
   }
 }

package/src/elements/EFMedia/audioTasks/makeAudioInputTask.ts

@@ -19,6 +19,8 @@ export const makeAudioInputTask = (host: EFMedia): InputTask => {
     onComplete: (_value) => {},
     task: async (_, { signal }) => {
       const mediaEngine = await host.mediaEngineTask.taskComplete;
+      if (signal.aborted) return undefined;
+
       const audioRendition = mediaEngine?.audioRendition;
 
       // Return undefined if no audio rendition available (video-only asset)
@@ -27,9 +29,10 @@ export const makeAudioInputTask = (host: EFMedia): InputTask => {
       }
 
       const initSegment = await host.audioInitSegmentFetchTask.taskComplete;
-      signal.throwIfAborted();
+      if (signal.aborted) return undefined;
+
       const segment = await host.audioSegmentFetchTask.taskComplete;
-      signal.throwIfAborted();
+      if (signal.aborted) return undefined;
 
       if (!initSegment || !segment) {
         return undefined;
@@ -38,7 +41,8 @@ export const makeAudioInputTask = (host: EFMedia): InputTask => {
       const startTimeOffsetMs = audioRendition.startTimeOffsetMs;
 
       const arrayBuffer = await new Blob([initSegment, segment]).arrayBuffer();
-      signal.throwIfAborted();
+      if (signal.aborted) return undefined;
+
       return new BufferedSeekingInput(arrayBuffer, {
         videoBufferSize: EFMedia.VIDEO_SAMPLE_BUFFER_SIZE,
         audioBufferSize: EFMedia.AUDIO_SAMPLE_BUFFER_SIZE,