chore: Added RFC for stitcher API

Author: matvp91

apps/stitcher/src/interstitials.ts

@@ -8,7 +8,7 @@ import type { Asset, TimedEvent } from "./types";
 
 interface Group {
   showTimeline: boolean;
-  inlineDuration?: number;
+  duration?: number;
 }
 
 export function getStaticDateRanges(
@@ -36,18 +36,22 @@ export function getStaticDateRanges(
     const assetListUrl = createUrl(context, "out/asset-list.json", {
       dt: dateTime.toISO(),
       sid: session.id,
-      mdur: group.inlineDuration,
+      mdur: group.duration,
     });
 
     const clientAttributes: Record<string, number | string> = {
       RESTRICT: "SKIP,JUMP",
       "ASSET-LIST": assetListUrl,
       "CONTENT-MAY-VARY": "YES",
       "TIMELINE-STYLE": group.showTimeline ? "HIGHLIGHT" : "PRIMARY",
-      "TIMELINE-OCCUPIES": group.inlineDuration ? "RANGE" : "POINT",
-      "RESUME-OFFSET": group.inlineDuration ?? 0,
+      "TIMELINE-OCCUPIES": group.duration ? "RANGE" : "POINT",
+      "RESUME-OFFSET": group.duration ?? 0,
     };
 
+    if (group.duration) {
+      clientAttributes["PLAYOUT-LIMIT"] = group.duration;
+    }
+
     const cue: string[] = [];
     if (dateTime.equals(session.startTime)) {
       cue.push("PRE");
@@ -61,7 +65,7 @@ export function getStaticDateRanges(
       classId: "com.apple.hls.interstitial",
       id: `sprs.${dateTime.toMillis()}`,
       startDate: dateTime,
-      duration: group.inlineDuration,
+      duration: group.duration,
       clientAttributes,
     });
   });
@@ -80,8 +84,10 @@ function groupEvent(groups: Map<number, Group>, event: TimedEvent) {
     groups.set(ts, group);
   }
 
-  if (event.inlineDuration) {
-    group.inlineDuration = event.inlineDuration;
+  // If we have another event with a duration, we'll take the largest one to cover
+  // the entire interstitial.
+  if (event.duration && (!group.duration || event.duration > group.duration)) {
+    group.duration = event.duration;
   }
 
   if (event.vast) {
@@ -99,7 +105,7 @@ function getTimedEventsFromSegments(segments: Segment[]) {
 
     events.push({
       dateTime: segment.programDateTime,
-      inlineDuration: segment.spliceInfo.duration,
+      duration: segment.spliceInfo.duration,
     });
   }
 

apps/stitcher/src/routes/sessions.ts

@@ -36,6 +36,7 @@ export const sessionsApp = new Hono().post(
           z.intersection(
             z.object({
               time: z.union([z.number(), z.string()]),
+              duration: z.number().optional(),
             }),
             z.discriminatedUnion("type", [
               z.object({
@@ -46,18 +47,13 @@ export const sessionsApp = new Hono().post(
                 type: z.literal("vast"),
                 url: z.string(),
               }),
+              z.object({
+                type: z.literal("metadata"),
+              }),
             ]),
           ),
         )
         .optional(),
-      regions: z
-        .array(
-          z.object({
-            time: z.union([z.number(), z.string()]),
-            inlineDuration: z.number().optional(),
-          }),
-        )
-        .optional(),
       filter: z
         .object({
           resolution: z.string().optional(),

apps/stitcher/src/session.ts

@@ -28,6 +28,7 @@ export interface Session {
 
 type InterstitialInput = {
   time: string | number;
+  duration?: number;
 } & (
   | {
       type: "asset";
@@ -39,11 +40,6 @@ type InterstitialInput = {
     }
 );
 
-interface RegionInput {
-  time: string | number;
-  inlineDuration?: number;
-}
-
 interface CreateSessionParams {
   uri: string;
   expiry: number;
@@ -54,7 +50,6 @@ interface CreateSessionParams {
     url?: string;
   };
   interstitials?: InterstitialInput[];
-  regions?: RegionInput[];
 }
 
 export async function createSession(
@@ -84,13 +79,6 @@ export async function createSession(
     session.events.push(...events);
   }
 
-  if (params.regions) {
-    const events = params.regions.map((region) =>
-      mapRegionToTimedEvent(startTime, region),
-    );
-    session.events.push(...events);
-  }
-
   const value = JSON.stringify(session);
   await context.kv.set(`session:${id}`, value, session.expiry);
 
@@ -119,6 +107,7 @@ export async function mapInterstitialToTimedEvent(
 
   const event: TimedEvent = {
     dateTime,
+    duration: interstitial.duration,
   };
 
   if (interstitial.type === "asset") {
@@ -138,18 +127,6 @@ export async function mapInterstitialToTimedEvent(
   return event;
 }
 
-export function mapRegionToTimedEvent(
-  startTime: DateTime,
-  region: RegionInput,
-): TimedEvent {
-  const dateTime = toDateTime(startTime, region.time);
-
-  return {
-    dateTime,
-    inlineDuration: region.inlineDuration,
-  };
-}
-
 function toDateTime(startTime: DateTime, time: string | number) {
   return typeof time === "string"
     ? DateTime.fromISO(time)

apps/stitcher/src/types.ts

@@ -18,5 +18,5 @@ export interface TimedEvent {
   dateTime: DateTime;
   vast?: VastParams;
   asset?: Asset;
-  inlineDuration?: number;
+  duration?: number;
 }

packages/player/src/hls-player.ts

@@ -49,7 +49,7 @@ export class HlsPlayer {
 
     this.state_ = new State({
       onEvent: (event: Events) => this.emit_(event),
-      getTiming: () => hls.interstitialsManager?.primary,
+      getTiming: () => hls.interstitialsManager?.integrated,
     });
 
     hls.attachMedia(this.media_);

rfc/001_Stitcher_API.md

@@ -0,0 +1,47 @@
+# Stitcher API
+
+For VOD, without replacement (ad insertion)
+
+```
+|-------X-------|
+0       20
+```
+
+The interstitial structure is:
+
+- No DURATION
+- RESUME-OFFSET: 0
+- No PLAYOUT-LIMIT (ad server decides)
+
+For VOD, with replacement (ad replacement)
+
+```
+|-------X####----|
+0       20  30
+```
+
+The interstitial structure is:
+
+- DURATION: 10
+- RESUME-OFFSET: 10 (equal to the duration)
+- No PLAYOUT-LIMIT (ad server decides)
+
+Due to the DURATION tag, HLS.js treats the linear ad breaks as if they are not there in the first place. Unless we add CUE=ONCE.
+
+For live, with replacement (ad replacement)
+
+```
+|-------X####---->
+0       20  30
+```
+
+The interstitial structure is:
+
+- No DURATION
+- RESUME-OFFSET: 10 (equal to the duration)
+- PLAYOUT-LIMIT: 10 (equal to the duration)
+
+## Questions
+
+- What when we seek over an interstitial, and we want to end up to the original seek target time? How does a dynamic resume offset work? Can this be a seek when the interstitial ended?
+- What with (pre)buffering of the primary content in the case above?