feat: add controlled quality switching

Author: Priveetee

README.md

@@ -38,6 +38,8 @@ const engine = new TypeTypeMsePlayer(videoElement, {
 engine.on("state", (event) => console.log(event.state));
 await engine.load();
 await engine.play();
+
+await engine.setQuality({ videoItag: 248 });
 ```
 
 ## Diagnostics

src/index.ts

@@ -6,5 +6,6 @@ export type {
   TypeTypeMseEvent,
   TypeTypeMseEventType,
   TypeTypeMseListener,
+  TypeTypeMseQuality,
   TypeTypeMseState,
 } from "./types";

src/playback-client.ts

@@ -17,6 +17,12 @@ export type CreatePlaybackRequest = {
   startTimeMs: number;
 };
 
+export type SeekPlaybackOptions = {
+  videoItag?: number;
+  audioItag?: number;
+  audioTrackId?: string | null;
+};
+
 function field(value: object, key: string): unknown {
   return Reflect.get(value, key);
 }
@@ -65,12 +71,16 @@ export class PlaybackClient {
   async seek(
     sessionId: string,
     positionMs: number,
+    options: SeekPlaybackOptions = {},
     signal?: AbortSignal,
   ): Promise<PlaybackResponse> {
     const session = encodeURIComponent(sessionId);
     const params = new URLSearchParams({
       playerTimeMs: String(Math.max(0, Math.round(positionMs))),
     });
+    if (options.videoItag) params.set("videoItag", String(options.videoItag));
+    if (options.audioItag) params.set("audioItag", String(options.audioItag));
+    if (options.audioTrackId) params.set("audioTrackId", options.audioTrackId);
     const init = signal ? { method: "POST", signal } : { method: "POST" };
     const response = await this.http.json(`/sabr/playback/${session}/seek?${params}`, init);
     return parsePlaybackResponse(response);

src/player-deps.ts

@@ -0,0 +1,59 @@
+import { resolveBufferPolicy } from "./buffer-policy";
+import type { EventEmitter } from "./event-emitter";
+import { HttpClient } from "./http-client";
+import { MediaElementObserver } from "./media-element-observer";
+import { MediaSourceController } from "./media-source-controller";
+import { PlaybackClient } from "./playback-client";
+import { PlaybackLoop } from "./playback-loop";
+import { bufferedEndMs } from "./player-snapshot";
+import { SegmentScheduler } from "./segment-scheduler";
+import type { LoadedSession } from "./session-loader";
+import type { TypeTypeMseConfig, TypeTypeMseState } from "./types";
+
+export type PlayerDeps = {
+  http: HttpClient;
+  playback: PlaybackClient;
+  mediaEvents: MediaElementObserver;
+  media: MediaSourceController;
+  scheduler: SegmentScheduler;
+  loop: PlaybackLoop;
+};
+
+type Args = {
+  video: HTMLVideoElement;
+  config: TypeTypeMseConfig;
+  emitter: EventEmitter;
+  session: () => LoadedSession | null;
+  signal: () => AbortSignal;
+  state: (state: TypeTypeMseState) => void;
+  error: (error: Error) => void;
+};
+
+export function createPlayerDeps(args: Args): PlayerDeps {
+  const http = new HttpClient(
+    args.config.headers
+      ? { endpoint: args.config.endpoint, headers: args.config.headers }
+      : { endpoint: args.config.endpoint },
+  );
+  const playback = new PlaybackClient(http);
+  const mediaEvents = new MediaElementObserver({
+    video: args.video,
+    state: args.state,
+    error: args.error,
+  });
+  const media = new MediaSourceController(args.video);
+  const scheduler = new SegmentScheduler(http, media, args.emitter);
+  const loop = new PlaybackLoop({
+    video: args.video,
+    http,
+    media,
+    scheduler,
+    emitter: args.emitter,
+    policy: resolveBufferPolicy(args.config),
+    session: args.session,
+    signal: args.signal,
+    bufferedEndMs: () => bufferedEndMs(args.video),
+    error: args.error,
+  });
+  return { http, playback, mediaEvents, media, scheduler, loop };
+}

src/type-type-mse-player.ts

@@ -1,29 +1,19 @@
-import { resolveBufferPolicy } from "./buffer-policy";
 import { EventEmitter } from "./event-emitter";
-import { HttpClient } from "./http-client";
-import { MediaElementObserver } from "./media-element-observer";
-import { MediaSourceController } from "./media-source-controller";
-import { PlaybackClient } from "./playback-client";
-import { PlaybackLoop } from "./playback-loop";
+import { createPlayerDeps, type PlayerDeps } from "./player-deps";
 import { bufferedEndMs, createSnapshot, type TypeTypeMseSnapshot } from "./player-snapshot";
 import { SeekController } from "./seek-controller";
-import { SegmentScheduler } from "./segment-scheduler";
 import { type LoadedSession, loadPlaybackSession } from "./session-loader";
 import type {
   TypeTypeMseConfig,
   TypeTypeMseEventType,
   TypeTypeMseListener,
+  TypeTypeMseQuality,
   TypeTypeMseState,
 } from "./types";
 
 export class TypeTypeMsePlayer {
   private readonly emitter = new EventEmitter();
-  private readonly http: HttpClient;
-  private readonly playback: PlaybackClient;
-  private readonly mediaEvents: MediaElementObserver;
-  private readonly media: MediaSourceController;
-  private readonly scheduler: SegmentScheduler;
-  private readonly loop: PlaybackLoop;
+  private readonly deps: PlayerDeps;
   private readonly seekController = new SeekController();
   private session: LoadedSession | null = null;
   private operation = new AbortController();
@@ -35,32 +25,16 @@ export class TypeTypeMsePlayer {
     private readonly video: HTMLVideoElement,
     private readonly config: TypeTypeMseConfig,
   ) {
-    this.http = new HttpClient(
-      config.headers
-        ? { endpoint: config.endpoint, headers: config.headers }
-        : { endpoint: config.endpoint },
-    );
-    this.playback = new PlaybackClient(this.http);
-    this.mediaEvents = new MediaElementObserver({
+    this.deps = createPlayerDeps({
       video,
-      state: (state) => this.setState(state),
-      error: (error) => this.handleError(error),
-    });
-    this.mediaEvents.start();
-    this.media = new MediaSourceController(video);
-    this.scheduler = new SegmentScheduler(this.http, this.media, this.emitter);
-    this.loop = new PlaybackLoop({
-      video,
-      http: this.http,
-      media: this.media,
-      scheduler: this.scheduler,
+      config,
       emitter: this.emitter,
-      policy: resolveBufferPolicy(config),
       session: () => this.session,
       signal: () => this.operation.signal,
-      bufferedEndMs: () => bufferedEndMs(this.video),
+      state: (state) => this.setState(state),
       error: (error) => this.handleError(error),
     });
+    this.deps.mediaEvents.start();
   }
 
   on(type: TypeTypeMseEventType, listener: TypeTypeMseListener): () => void {
@@ -73,7 +47,7 @@ export class TypeTypeMsePlayer {
     const signal = this.operation.signal;
     this.setState("loading");
     const startTimeMs = Math.max(0, Math.round(this.config.startTimeMs ?? 0));
-    const response = await this.playback.create(
+    const response = await this.deps.playback.create(
       {
         videoId: this.config.videoId,
         videoItag: this.config.videoItag,
@@ -102,6 +76,13 @@ export class TypeTypeMsePlayer {
     return this.seekController.seek(positionMs, (targetMs) => this.performSeek(targetMs));
   }
 
+  async setQuality(quality: TypeTypeMseQuality): Promise<void> {
+    this.operation.abort();
+    return this.seekController.seek(this.currentTimeMs(), (targetMs) =>
+      this.performSeek(targetMs, quality),
+    );
+  }
+
   snapshot(): TypeTypeMseSnapshot {
     return createSnapshot(this.video, this.state, this.session, bufferedEndMs(this.video));
   }
@@ -111,25 +92,37 @@ export class TypeTypeMsePlayer {
     this.destroyed = true;
     this.operation.abort();
     this.seekController.reset();
-    this.loop.stop();
-    this.mediaEvents.stop();
-    this.media.detach();
+    this.deps.loop.stop();
+    this.deps.mediaEvents.stop();
+    this.deps.media.detach();
     this.emitter.clear();
     this.state = "destroyed";
   }
 
-  private async performSeek(positionMs: number): Promise<void> {
+  private async performSeek(positionMs: number, quality?: TypeTypeMseQuality): Promise<void> {
     this.ensureAlive();
     const current = this.session;
     if (!current) throw new Error("Player is not loaded");
     const revision = this.nextRevision();
     const signal = this.operation.signal;
     const targetMs = Math.max(0, Math.round(positionMs));
-    this.loop.stop();
+    this.deps.loop.stop();
     this.setState("seeking");
     this.emitter.emit({ type: "seek", positionMs: targetMs });
-    const response = await this.playback.seek(current.response.sessionId, targetMs, signal);
+    const response = await this.deps.playback.seek(
+      current.response.sessionId,
+      targetMs,
+      quality,
+      signal,
+    );
     await this.switchSession(response, targetMs, revision, signal);
+    if (quality) {
+      this.emitter.emit({
+        type: "quality",
+        videoItag: quality.videoItag,
+        audioItag: quality.audioItag ?? null,
+      });
+    }
   }
 
   private async switchSession(
@@ -139,19 +132,19 @@ export class TypeTypeMsePlayer {
     signal: AbortSignal,
   ): Promise<void> {
     const session = await loadPlaybackSession({
-      http: this.http,
-      playback: this.playback,
-      media: this.media,
-      scheduler: this.scheduler,
+      http: this.deps.http,
+      playback: this.deps.playback,
+      media: this.deps.media,
+      scheduler: this.deps.scheduler,
       video: this.video,
       response,
       startTimeMs,
       signal,
     });
     if (!this.isCurrent(revision)) return;
     this.session = session;
-    await this.loop.fillOnce();
-    this.loop.start();
+    await this.deps.loop.fillOnce();
+    this.deps.loop.start();
     this.emitter.emit({
       type: "manifest",
       generation: response.generation,
@@ -176,6 +169,10 @@ export class TypeTypeMsePlayer {
     if (this.destroyed) throw new Error("Player is destroyed");
   }
 
+  private currentTimeMs(): number {
+    return Math.max(0, Math.round(this.video.currentTime * 1000));
+  }
+
   private nextRevision(): number {
     this.operation.abort();
     this.operation = new AbortController();

src/types.ts

@@ -25,9 +25,16 @@ export type TypeTypeMseConfig = {
   manifestRefreshMs?: number;
 };
 
+export type TypeTypeMseQuality = {
+  videoItag: number;
+  audioItag?: number;
+  audioTrackId?: string | null;
+};
+
 export type TypeTypeMseEvent =
   | { type: "state"; state: TypeTypeMseState }
   | { type: "manifest"; generation: number | null; segmentCount: number }
+  | { type: "quality"; videoItag: number; audioItag: number | null }
   | { type: "segment"; kind: TrackKind; url: string; startMs: number; durationMs: number }
   | { type: "buffer"; bufferedEndMs: number; currentTimeMs: number }
   | { type: "seek"; positionMs: number }