googlevideo 3.0.0 → 4.0.1

package/README.md

@@ -1,19 +1,11 @@
-# What Is This?
+# GoogleVideo
 [![JSR](https://jsr.io/badges/@luanrt/googlevideo)](https://jsr.io/@luanrt/googlevideo)
 [![NPM](https://img.shields.io/npm/v/googlevideo)](https://www.npmjs.com/package/googlevideo)
 [![License](https://img.shields.io/github/license/LuanRT/googlevideo)](./LICENSE)
 
-This is a collection of utilities for working with Google Video APIs, with a primary focus on UMP.
+A collection of modules for working with YouTube's proprietary video streaming protocols (UMP/SABR). It can be used to build clients or to integrate with existing media players (e.g., [Shaka Player](https://shaka-player-demo.appspot.com/docs/api/index.html)).
 
-
-* [Video Streaming Protos](./protos/video_streaming/)
-* [UMP (Parser)](./src/core/UMP.ts)
-* [ServerAbrStream (SABR Client)](./src/core/ServerAbrStream.ts)
-* [ChunkedDataBuffer (Buffer Manager)](./src/core/ChunkedDataBuffer.ts)
-
-The protobuf definitions were extracted from YouTube's Android and iOS clients, and the UMP parser and buffer manager are based on the implementation currently found on youtube.com.
-
-Usage examples can be found [here](./examples/).
+[API Reference →](https://ytjs.dev/googlevideo/api)
 
 ## Installation
 
@@ -30,46 +22,102 @@ npm install LuanRT/googlevideo
 ```
 
 ## Basic Usage
+Below is a basic example using the UMP modules to create a buffer, write parts, and process them:
+
+> [!NOTE] 
+> More advanced usage examples can be found in the [/examples](./examples/) directory.
 
 ```typescript
-import GoogleVideo, { PART, Protos } from 'googlevideo';
-
-const streamingUrl = 'https://abcd--a.googlevideo.com/videoplayback?...';
-
-const response = await fetch(streamingUrl, { method: 'POST' });
-
-const arrayBuffer = await response.arrayBuffer();
-
-const dataBuffer = new GoogleVideo.ChunkedDataBuffer();
-dataBuffer.append(new Uint8Array(arrayBuffer));
-
-const googUmp = new GoogleVideo.UMP(dataBuffer);
-
-googUmp.parse((part) => {
-  switch (part.type) {
-    case PART.MEDIA_HEADER: {
-      console.log('[MediaHeader]:', Protos.MediaHeader.decode(part.data.chunks[0]));
-      break;
-    }
-    case PART.MEDIA: {
-      const headerId = part.data.getUint8(0);
-      const streamData = part.data.split(1).remainingBuffer;
-      console.log('[Media]:', `Header ID: ${headerId}`, `length: ${streamData.getLength()}`);
-      break;
-    }
-    case PART.MEDIA_END: {
-      const headerId = part.data.getUint8(0);
-      console.log('[MediaEnd]:', `Header ID: ${headerId}`);
-      break;
-    }
-    default:
-      console.log('Unhandled part:', part.type);
-      break;
+import { CompositeBuffer, UmpReader, UmpWriter } from 'googlevideo/ump';
+import { MediaHeader, UMPPartId } from 'googlevideo/protos';
+import { concatenateChunks } from 'googlevideo/utils';
+import { Part } from 'googlevideo/shared-types';
+
+function handleMediaHeader(part: Part) {
+  const mediaHeader = MediaHeader.decode(concatenateChunks(part.data.chunks));
+  console.log('Media Header:', mediaHeader);
+}
+
+function handleMedia(part: Part) {
+  const headerId = part.data.getUint8(0);
+  console.log(`Media Part (Associated Header ID: ${headerId}):`, part.data.split(1).remainingBuffer.getLength(), 'bytes');
+}
+
+function handleMediaEnd(part: Part) {
+  const headerId = part.data.getUint8(0);
+  console.log(`Media End Part (Associated Header ID: ${headerId}):`, part.data.split(1).remainingBuffer.getLength(), 'bytes');
+}
+
+const umpPartHandlers = new Map<UMPPartId, (part: Part) => void>([
+  [ UMPPartId.MEDIA_HEADER, handleMediaHeader ],
+  [ UMPPartId.MEDIA, handleMedia ],
+  [ UMPPartId.MEDIA_END, handleMediaEnd ]
+]);
+
+const buffer = mockUmpData();
+const reader = new UmpReader(buffer);
+
+reader.read((part) => {
+  const handler = umpPartHandlers.get(part.type);
+  if (handler) {
+    handler(part);
+  } else {
+    console.warn(`No handler for part type: ${part.type}`);
   }
 });
+
+/**
+ * Generates a mock UMP data buffer containing a MEDIA_HEADER, and respective MEDIA and MEDIA_END parts.
+ * This group represents a single audio segment, which is what you would typically see
+ * in a real UMP stream.
+ */
+function mockUmpData(): CompositeBuffer {
+  const buffer = new CompositeBuffer();
+  const writer = new UmpWriter(buffer);
+
+  const audioHeaderId = 0;
+
+  const partsToWrite: [UMPPartId, Uint8Array][] = [
+    [
+      UMPPartId.MEDIA_HEADER,
+      MediaHeader.encode({
+        headerId: audioHeaderId,
+        videoId: "sOa4VVlI9tE",
+        itag: 141,
+        lmt: 1645502668395260,
+        xtags: "",
+        startRange: 5463800,
+        isInitSeg: false,
+        sequenceNumber: 0,
+        durationMs: 0,
+        formatId: {
+          itag: 141,
+          lastModified: 1645502668395260,
+          xtags: ""
+        },
+        contentLength: 963966,
+      }).finish()
+    ],
+    [ UMPPartId.MEDIA, new Uint8Array([ audioHeaderId, ...new Uint8Array(827609).fill(0) ]) ],
+    [ UMPPartId.MEDIA, new Uint8Array([ audioHeaderId, ...new Uint8Array(136357).fill(0) ]) ],
+    [ UMPPartId.MEDIA_END, new Uint8Array([ audioHeaderId ]) ]
+  ];
+
+  for (const [type, data] of partsToWrite) {
+    writer.write(type, data);
+  }
+
+  return buffer;
+}
 ```
 
-For more advanced examples, including scenarios beyond just parsing responses, check out the [examples](./examples/).
+Expected output:
+```
+Media Header: { ... }
+Media Part (Associated Header ID: 0): 827609 bytes
+Media Part (Associated Header ID: 0): 136357 bytes
+Media End Part (Associated Header ID: 0): 0 bytes
+```
 
 ## License
 Distributed under the [MIT](./LICENSE) License.

package/dist/protos/generated/misc/common.d.ts

@@ -1,5 +1,167 @@
 import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
 export declare const protobufPackage = "misc";
+export declare enum CompressionType {
+    UNKNOWN = 0,
+    GZIP = 1,
+    BROTLI = 2,
+    UNRECOGNIZED = -1
+}
+export declare enum AudioQuality {
+    UNKNOWN = 0,
+    ULTRALOW = 5,
+    LOW = 10,
+    MEDIUM = 20,
+    HIGH = 30,
+    UNRECOGNIZED = -1
+}
+export declare enum VideoQualitySetting {
+    UNKNOWN = 0,
+    HIGHER_QUALITY = 1,
+    DATA_SAVER = 2,
+    ADVANCED_MENU = 3,
+    UNRECOGNIZED = -1
+}
+export declare enum PlaybackAudioRouteOutputType {
+    UNKNOWN = 0,
+    LINE_OUT = 1,
+    HEADPHONES = 2,
+    BLUETOOTH_A2DP = 3,
+    BUILT_IN_RECEIVER = 4,
+    BUILT_IN_SPEAKER = 5,
+    HDMI = 6,
+    AIR_PLAY = 7,
+    BLUETOOTH_LE = 8,
+    BLUETOOTH_HFP = 9,
+    USB_AUDIO = 10,
+    CAR_PLAY = 11,
+    ANDROID_AUDIO = 12,
+    UNRECOGNIZED = -1
+}
+export declare enum NetworkMeteredState {
+    UNKNOWN = 0,
+    UNMETERED = 1,
+    METERED = 2,
+    UNRECOGNIZED = -1
+}
+export declare enum SeekSource {
+    UNKNOWN = 0,
+    TIMESTAMP_IN_COMMENTS = 1,
+    TIMESTAMP_IN_DESCRIPTION = 2,
+    MACRO_MARKER_LIST_ITEM = 3,
+    DOUBLE_TAP_TO_SEEK = 4,
+    DOUBLE_TAP_TO_SKIP_CHAPTER = 5,
+    PICK_UP_PLAY_HEAD = 6,
+    SLIDE_ON_SCRUBBER_BAR = 7,
+    SLIDE_ON_PLAYER = 8,
+    SABR_PARTIAL_CHUNK = 9,
+    SABR_SEEK_TO_HEAD = 10,
+    SABR_LIVE_DVR_USER_SEEK = 11,
+    SABR_SEEK_TO_DVR_LOWER_BOUND = 12,
+    SABR_SEEK_TO_DVR_UPPER_BOUND = 13,
+    SSDAI_INTERNAL = 14,
+    START_PLAYBACK = 15,
+    SABR_ACCURATE_SEEK = 17,
+    START_PLAYBACK_SEEK_TO_END = 18,
+    IOS_PLAYER_REMOVED_SEGMENTS = 19,
+    IOS_PLAYER_SEGMENT_LIST = 20,
+    IOS_PLAYER_ITEM_SEEK = 21,
+    IOS_PLAYER_ITEM_SEEK_TO_END = 22,
+    IOS_PLAYER_SEEK_TO_END_TO_RESYNC = 23,
+    IOS_SEEK_ACCESSIBILITY_BUTTON = 24,
+    FINE_SCRUBBER_SLIDE_ON_FILMSTRIP = 25,
+    FINE_SCRUBBER_TAP_ON_FILMSTRIP = 26,
+    FINE_SCRUBBER_SLIDE_ON_SCRUBBER_BAR = 27,
+    SEEK_BUTTON_ON_PLAYER_CONTROL = 28,
+    SABR_INGESTION_WALL_TIME_SEEK = 29,
+    PLAYER_VIEW_REPARENT_INTERNAL = 30,
+    PRESS_REWIND_PLAY_BACK_CONTROL = 31,
+    PRESS_FAST_FORWARD_PLAY_BACK_CONTROL = 32,
+    PRESS_LIVE_SYNC_ICON = 33,
+    PEG_TO_LIVE = 34,
+    ANDROID_MEDIA_SESSION = 35,
+    TAP_ON_REPLAY_ACTION = 36,
+    AUTOMATIC_REPLAY_ACTION = 37,
+    NON_USER_SEEK_TO_PREVIOUS = 38,
+    NON_USER_SEEK_TO_NEXT = 39,
+    HIGHLIGHTS_TAP_PREVIOUS_PLAY = 66,
+    HIGHLIGHTS_TAP_NEXT_PLAY = 40,
+    HIGHLIGHTS_TAP_HIDDEN_NEXT_PLAY = 41,
+    HIGHLIGHTS_TAP_LIST_ITEM = 42,
+    HIGHLIGHTS_AUTOMATIC_NEXT_PLAY = 43,
+    HIGHLIGHTS_SEEK_TO_FIRST_PLAY = 44,
+    HIGHLIGHTS_SEEK_TO_END = 45,
+    SEGMENTS_TAP_LIST_ITEM = 46,
+    PIP_FAST_FORWARD_BUTTON = 47,
+    PIP_REWIND_BUTTON = 48,
+    PIP_RESUME_ON_HEAD = 49,
+    MOVING_CLIP_FRAME = 50,
+    RESUME_CLIP_PREVIOUS_POSITION = 51,
+    SEEK_TO_NEXT_CHAPTER = 52,
+    SEEK_TO_PREVIOUS_CHAPTER = 53,
+    IOS_SHAREPLAY_PAUSE = 54,
+    IOS_SHAREPLAY_SEEK = 55,
+    IOS_SHAREPLAY_SYNC_RESPONSE = 56,
+    SEEK_TO_HEAD_IMMERSIVE_LIVE_VIDEO = 57,
+    SEEK_TO_START_OF_LOOPING_RANGE_OF_SHORTS = 58,
+    SABR_SEEK_TO_CLOSEST_KEYFRAME = 59,
+    SEEK_TO_END_OF_LOOPING_RANGE_OF_SHORTS = 60,
+    CLIP_SLIDE_ON_FLIMSTRIP = 61,
+    PICK_UP_CLIP_SLIDER = 62,
+    FINE_SCRUBBER_CANCELLED = 63,
+    INLINE_PLAYER_SEEK_CHAPTER = 64,
+    INLINE_PLAYER_SEEK_SECONDS = 65,
+    HIGHLIGHTS_PLAYER_EXIT_FULLSCREEN = 67,
+    LARGE_CONTROLS_FORWARD_BUTTON = 68,
+    LARGE_CONTROLS_REWIND_BUTTON = 69,
+    LARGE_CONTROLS_SCRUBBER_BAR = 70,
+    SEEK_BACKWARD_5S = 71,
+    SEEK_FORWARD_5S = 72,
+    SEEK_BACKWARD_10S = 73,
+    SEEK_FORWARD_10S = 74,
+    SEEK_FORWARD_60S = 75,
+    SEEK_BACKWARD_60S = 76,
+    SEEK_TO_NEXT_FRAME = 77,
+    SEEK_TO_PREV_FRAME = 78,
+    KEYBOARD_SEEK_TO_BEGINNING = 79,
+    KEYBOARD_SEEK_TO_END = 80,
+    SEEK_PERCENT_OF_VIDEO = 81,
+    HIDDEN_FAST_FORWARD_BUTTON = 82,
+    HIDDEN_REWIND_BUTTON = 83,
+    TIMESTAMP = 84,
+    LR_MEDIA_SESSION_SEEK = 87,
+    MIDROLLS_WITH_TIME_RANGE = 88,
+    SKIP_AD = 89,
+    SEEK_TO_PREVIOUS = 90,
+    SEEK_TO_NEXT = 91,
+    LR_QUICK_SEEK = 92,
+    ONESIE_LIVE = 93,
+    LR_PLAYER_CONTROL_ACTION = 94,
+    UNPLUGGED_LENS_START_CLIP = 95,
+    LR_KEY_PLAYS = 96,
+    SSAP_AD_FMT_FATAL = 97,
+    TVHTML5_INPUT_SOURCE_KEY_EVENT = 98,
+    TVHTML5_INPUT_SOURCE_CONTROLS = 99,
+    TVHTML5_INPUT_SOURCE_TOUCH = 100,
+    TVHTML5_INPUT_SOURCE_TOUCHPAD = 101,
+    SEEK_TO_HEAD = 102,
+    AUTOMATIC_PREVIEW_REPLAY_ACTION = 103,
+    H5_MEDIA_ELEMENT_EVENT = 104,
+    H5_WORKAROUND_SEEK = 105,
+    MINIPLAYER_REWIND_BUTTON = 106,
+    MINIPLAYER_FAST_FORWARD_BUTTON = 107,
+    SABR_RELOAD_PLAYER_RESPONSE_TOKEN_SEEK = 108,
+    SLIDE_ON_SCRUBBER_BAR_CHAPTER = 109,
+    ANDROID_CLEAR_BUFFER = 110,
+    UNRECOGNIZED = -1
+}
+export declare enum OnesieRequestTarget {
+    UNKNOWN = 0,
+    ENCRYPTED_PLAYER_SERVICE = 1,
+    ENCRYPTED_WATCH_SERVICE_DEPRECATED = 2,
+    ENCRYPTED_WATCH_SERVICE = 3,
+    INNERTUBE_ENCRYPTED_SERVICE = 4,
+    UNRECOGNIZED = -1
+}
 export interface HttpHeader {
     name?: string | undefined;
     value?: string | undefined;
@@ -9,23 +171,35 @@ export interface FormatId {
     lastModified?: number | undefined;
     xtags?: string | undefined;
 }
-export interface InitRange {
+export interface Range {
+    legacyStart?: number | undefined;
+    legacyEnd?: number | undefined;
     start?: number | undefined;
     end?: number | undefined;
 }
-export interface IndexRange {
-    start?: number | undefined;
-    end?: number | undefined;
+export interface IdentifierToken {
+    requestNumber?: number | undefined;
+    field5?: number | undefined;
 }
 export interface KeyValuePair {
     key?: string | undefined;
     value?: string | undefined;
 }
+export interface AuthorizedFormat {
+    trackType?: number | undefined;
+    isHdr?: boolean | undefined;
+}
+export interface PlaybackAuthorization {
+    authorizedFormats: AuthorizedFormat[];
+    sabrLicenseConstraint?: Uint8Array | undefined;
+}
 export declare const HttpHeader: MessageFns<HttpHeader>;
 export declare const FormatId: MessageFns<FormatId>;
-export declare const InitRange: MessageFns<InitRange>;
-export declare const IndexRange: MessageFns<IndexRange>;
+export declare const Range: MessageFns<Range>;
+export declare const IdentifierToken: MessageFns<IdentifierToken>;
 export declare const KeyValuePair: MessageFns<KeyValuePair>;
+export declare const AuthorizedFormat: MessageFns<AuthorizedFormat>;
+export declare const PlaybackAuthorization: MessageFns<PlaybackAuthorization>;
 export interface MessageFns<T> {
     encode(message: T, writer?: BinaryWriter): BinaryWriter;
     decode(input: BinaryReader | Uint8Array, length?: number): T;