@postfetch/core 0.9.1 → 0.9.3

package/README.md

@@ -13,9 +13,11 @@ for (const item of result.items) {
 
 `postfetch(url, options?)` detects the platform and resolves its media into a typed `PostfetchResult` (URLs plus the headers needed to fetch them). It performs no side effects beyond the lookup — `download`, `downloadBlob`, `archive` and `toResponse` materialize the result.
 
-`downloadBlob(url, options?)` materializes an already-resolved media URL for
-clients that need an uploadable `Blob`. Pass the resolved item's headers for
-protected CDN URLs: `downloadBlob(item.url, { headers: item.headers })`. Set
+`downloadBlob(itemOrUrl, options?)` materializes resolved media for clients that
+need an uploadable `Blob`. Prefer `downloadBlob(item, { remux: true })` to
+include separate audio, assemble HLS playlists and use the item's headers.
+Passing only `item.url` fetches that URL alone and may omit separate audio;
+for direct URLs, pass `{ headers: item.headers }` when needed. Set
 `remux: true` to return `{ blob, thumbnail, width, height, duration }`: a
 normalized MP4, upload thumbnail and calculated presentation metadata. Remuxing
 defaults to off, uses `ffmpeg` and `ffprobe` from `PATH` unless their paths are

package/dist/download.d.ts

@@ -50,31 +50,32 @@ export type Archive = {
  */
 export declare function download(item: MediaItem, options?: DownloadOptions): Promise<Response>;
 /**
- * Download an already-resolved media URL as a Blob.
+ * Download a resolved media item or direct media URL as a Blob.
  *
  * This is useful for consumers that need to upload media themselves instead of
- * passing its URL to a third party. When the resolved {@link MediaItem} carries
- * required CDN headers, pass them in the options object. Set `remux: true` to
+ * passing its URL to a third party. Pass the full {@link MediaItem} to include
+ * separate audio, HLS playlists and required headers. A direct URL only fetches
+ * that URL; pass its required CDN headers in the options object. Set `remux: true` to
  * normalize an MP4 with an FFmpeg stream copy; if FFmpeg is unavailable or the
  * remux or metadata extraction fails, the operation throws.
  *
- * @param url A direct media URL returned by a resolver.
+ * @param input A resolved media item (recommended) or direct media URL.
  * @param options Headers, fetch implementation and opt-in remux behavior.
  * @returns A Blob, or with `remux: true`, the normalized video and its metadata.
  *
  * @example Upload a video with FormData
  * ```ts
  * const [media] = (await postfetch(sourceUrl)).items;
- * const video = await downloadBlob(media.url, { headers: media.headers, remux: true });
+ * const video = await downloadBlob(media, { remux: true });
  * form.append("video", video.blob, media.filename);
  * form.append("thumbnail", video.thumbnail, "thumbnail.jpg");
  * ```
  */
-export declare function downloadBlob(url: string, options: DownloadBlobOptions & {
+export declare function downloadBlob(input: string | MediaItem, options: DownloadBlobOptions & {
     remux: true;
 }): Promise<RemuxedVideo>;
 /** Download without remuxing and return the upstream media Blob. */
-export declare function downloadBlob(url: string, options?: DownloadBlobOptions & {
+export declare function downloadBlob(input: string | MediaItem, options?: DownloadBlobOptions & {
     remux?: false;
 }): Promise<Blob>;
 /** @deprecated Pass headers and fetch in a single {@link DownloadBlobOptions} object. */

package/dist/hls.d.ts

@@ -5,6 +5,7 @@ export type HlsVariant = {
     bandwidth: number;
     url: string;
     audioGroup: string | null;
+    codecs?: string;
 };
 export type HlsMaster = {
     variants: HlsVariant[];

package/dist/index.js

@@ -1038,6 +1038,175 @@ function boxVersion(data, box) {
   return data[box.dataStart];
 }
 
+// src/packed-aac.ts
+var sampleRates = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350];
+var encoder = new TextEncoder;
+function packedAacToMp4(segments) {
+  const first = segments[0];
+  if (!first || !id3(first, 0) && !adts(first, 0)) {
+    return null;
+  }
+  let config;
+  let nextTimestamp = 0;
+  const fragments = [];
+  for (const segment of segments) {
+    let offset = 0;
+    let timestamp;
+    while (id3(segment, offset)) {
+      const tag = readId3(segment, offset);
+      timestamp ??= tag.timestamp;
+      offset = tag.end;
+    }
+    const samples = [];
+    while (offset < segment.length) {
+      if (offset + 7 > segment.length || !adts(segment, offset)) {
+        throw new Error("Invalid packed AAC frame");
+      }
+      const profile = (segment[offset + 2] >> 6) + 1;
+      const frequencyIndex = segment[offset + 2] >> 2 & 15;
+      const sampleRate = sampleRates[frequencyIndex];
+      const channels = (segment[offset + 2] & 1) << 2 | segment[offset + 3] >> 6;
+      if (profile !== 2 || !sampleRate || sampleRate > 65535 || channels === 0 || (segment[offset + 6] & 3) !== 0) {
+        throw new Error("Unsupported packed AAC configuration (expected AAC-LC)");
+      }
+      if (config && (config.frequencyIndex !== frequencyIndex || config.channels !== channels)) {
+        throw new Error("Packed AAC configuration changed between frames");
+      }
+      config ??= { frequencyIndex, sampleRate, channels };
+      const length = (segment[offset + 3] & 3) << 11 | segment[offset + 4] << 3 | segment[offset + 5] >> 5;
+      const headerLength = segment[offset + 1] & 1 ? 7 : 9;
+      if (length <= headerLength || offset + length > segment.length) {
+        throw new Error("Truncated packed AAC frame");
+      }
+      samples.push(segment.subarray(offset + headerLength, offset + length));
+      offset += length;
+    }
+    if (!config || samples.length === 0) {
+      throw new Error("Packed AAC segment has no audio frames");
+    }
+    const start = timestamp === undefined ? nextTimestamp : Math.round(timestamp * config.sampleRate / 90000);
+    fragments.push({ samples, timestamp: start });
+    nextTimestamp = start + samples.length * 1024;
+  }
+  return concat([initSegment(config), ...fragments.flatMap((fragment, index) => mediaFragment(fragment, index + 1))]);
+}
+function id3(bytes, offset) {
+  return bytes[offset] === 73 && bytes[offset + 1] === 68 && bytes[offset + 2] === 51;
+}
+function adts(bytes, offset) {
+  return bytes[offset] === 255 && (bytes[offset + 1] & 246) === 240;
+}
+function synchsafe(bytes, offset) {
+  if (offset + 4 > bytes.length || bytes.subarray(offset, offset + 4).some((byte) => byte & 128)) {
+    throw new Error("Invalid packed AAC ID3 size");
+  }
+  return bytes[offset] * 2 ** 21 + bytes[offset + 1] * 2 ** 14 + bytes[offset + 2] * 128 + bytes[offset + 3];
+}
+function readId3(bytes, offset) {
+  const version = bytes[offset + 3];
+  if (offset + 10 > bytes.length || version !== 3 && version !== 4 || bytes[offset + 5] & 192) {
+    throw new Error("Unsupported packed AAC ID3 tag");
+  }
+  const end = offset + 10 + synchsafe(bytes, offset + 6);
+  if (end > bytes.length) {
+    throw new Error("Truncated packed AAC ID3 tag");
+  }
+  const owner = encoder.encode("com.apple.streaming.transportStreamTimestamp\x00");
+  let timestamp;
+  for (let cursor = offset + 10;cursor + 10 <= end && bytes[cursor] !== 0; ) {
+    const size = version === 4 ? synchsafe(bytes, cursor + 4) : readU32(bytes, cursor + 4);
+    const body = cursor + 10;
+    if (body + size > end) {
+      throw new Error("Truncated packed AAC ID3 frame");
+    }
+    if (String.fromCharCode(...bytes.subarray(cursor, cursor + 4)) === "PRIV" && size === owner.length + 8 && owner.every((byte, index) => bytes[body + index] === byte)) {
+      if (bytes[cursor + 8] !== 0 || bytes[cursor + 9] !== 0) {
+        throw new Error("Unsupported packed AAC timestamp encoding");
+      }
+      timestamp = Number(new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getBigUint64(body + owner.length) & 0x1ffffffffn);
+    }
+    cursor = body + size;
+  }
+  const footer = version === 4 && bytes[offset + 5] & 16 ? 10 : 0;
+  if (end + footer > bytes.length) {
+    throw new Error("Truncated packed AAC ID3 footer");
+  }
+  return { end: end + footer, timestamp };
+}
+function u32(...values) {
+  const bytes = new Uint8Array(values.length * 4);
+  values.forEach((value, index) => writeU32(bytes, index * 4, value));
+  return bytes;
+}
+function fullBox(type, version, flags, payload) {
+  return buildBox(type, concat([u32(version * 16777216 + flags), payload]));
+}
+function matrix(bytes, offset) {
+  bytes.set(u32(65536, 0, 0, 0, 65536, 0, 0, 0, 1073741824), offset);
+}
+function initSegment(config) {
+  const mvhd = new Uint8Array(96);
+  writeU32(mvhd, 8, 1000);
+  writeU32(mvhd, 16, 65536);
+  new DataView(mvhd.buffer).setUint16(20, 256);
+  matrix(mvhd, 32);
+  writeU32(mvhd, 92, 2);
+  const tkhd = new Uint8Array(80);
+  writeU32(tkhd, 8, 1);
+  new DataView(tkhd.buffer).setUint16(32, 256);
+  matrix(tkhd, 36);
+  const mdhd = concat([u32(0, 0, config.sampleRate, 0), Uint8Array.of(85, 196, 0, 0)]);
+  const hdlr = concat([u32(0), encoder.encode("soun"), u32(0, 0, 0), encoder.encode("SoundHandler\x00")]);
+  const stbl = buildBox("stbl", concat([
+    fullBox("stsd", 0, 0, concat([u32(1), sampleEntry(config)])),
+    ...["stts", "stsc", "stco"].map((type) => fullBox(type, 0, 0, u32(0))),
+    fullBox("stsz", 0, 0, u32(0, 0))
+  ]));
+  const minf = buildBox("minf", concat([
+    fullBox("smhd", 0, 0, u32(0)),
+    buildBox("dinf", fullBox("dref", 0, 0, concat([u32(1), fullBox("url ", 0, 1, new Uint8Array)]))),
+    stbl
+  ]));
+  const trak = buildBox("trak", concat([
+    fullBox("tkhd", 0, 7, tkhd),
+    buildBox("mdia", concat([fullBox("mdhd", 0, 0, mdhd), fullBox("hdlr", 0, 0, hdlr), minf]))
+  ]));
+  return concat([
+    buildBox("ftyp", concat([encoder.encode("isom"), u32(512), encoder.encode("isomiso6mp41")])),
+    buildBox("moov", concat([
+      fullBox("mvhd", 0, 0, mvhd),
+      trak,
+      buildBox("mvex", fullBox("trex", 0, 0, u32(1, 1, 1024, 0, 33554432)))
+    ]))
+  ]);
+}
+function descriptor(tag, payload) {
+  return concat([Uint8Array.of(tag, payload.length), payload]);
+}
+function sampleEntry(config) {
+  const entry = new Uint8Array(28);
+  const view = new DataView(entry.buffer);
+  view.setUint16(6, 1);
+  view.setUint16(16, config.channels === 7 ? 8 : config.channels);
+  view.setUint16(18, 16);
+  view.setUint32(24, config.sampleRate * 65536);
+  const asc = Uint8Array.of(2 << 3 | config.frequencyIndex >> 1, (config.frequencyIndex & 1) << 7 | config.channels << 3);
+  const decoder = descriptor(4, concat([Uint8Array.of(64, 21, 0, 0, 0), u32(0, 0), descriptor(5, asc)]));
+  const esds = descriptor(3, concat([Uint8Array.of(0, 1, 0), decoder, descriptor(6, Uint8Array.of(2))]));
+  return buildBox("mp4a", concat([entry, fullBox("esds", 0, 0, esds)]));
+}
+function mediaFragment(fragment, sequence) {
+  const timestamp = new Uint8Array(8);
+  new DataView(timestamp.buffer).setBigUint64(0, BigInt(fragment.timestamp));
+  const trun = fullBox("trun", 0, 513, concat([u32(fragment.samples.length, 0), u32(...fragment.samples.map((sample) => sample.length))]));
+  const moof = buildBox("moof", concat([
+    fullBox("mfhd", 0, 0, u32(sequence)),
+    buildBox("traf", concat([fullBox("tfhd", 0, 131072, u32(1)), fullBox("tfdt", 1, 0, timestamp), trun]))
+  ]));
+  writeU32(moof, moof.length - trun.length + 16, moof.length + 8);
+  return [moof, buildBox("mdat", concat(fragment.samples))];
+}
+
 // src/hls.ts
 function isMasterPlaylist(text) {
   return text.includes("#EXT-X-STREAM-INF");
@@ -1046,25 +1215,31 @@ function parseMaster(text, baseUrl) {
   const lines = text.split(`
 `).map((line) => line.trim());
   const audio = {};
+  const defaultAudio = new Set;
   const variants = [];
   for (let index = 0;index < lines.length; index += 1) {
     const line = lines[index];
     if (line.startsWith("#EXT-X-MEDIA:") && /TYPE=AUDIO/.test(line)) {
       const group = line.match(/GROUP-ID="([^"]+)"/)?.[1];
       const uri = line.match(/URI="([^"]+)"/)?.[1];
-      if (group && uri) {
+      const isDefault = /(?:^|,)DEFAULT=YES(?:,|$)/.test(line);
+      if (group && uri && (!audio[group] || isDefault && !defaultAudio.has(group))) {
         audio[group] = new URL(uri, baseUrl).href;
+        if (isDefault)
+          defaultAudio.add(group);
       }
     } else if (line.startsWith("#EXT-X-STREAM-INF:")) {
       const target = lines[index + 1];
       if (target && !target.startsWith("#")) {
         const resolution = line.match(/RESOLUTION=(\d+)x(\d+)/);
+        const codecs = line.match(/CODECS="([^"]+)"/)?.[1];
         variants.push({
           width: resolution ? Number(resolution[1]) : 0,
           height: resolution ? Number(resolution[2]) : 0,
           bandwidth: Number(line.match(/BANDWIDTH=(\d+)/)?.[1] ?? 0),
           url: new URL(target, baseUrl).href,
-          audioGroup: line.match(/AUDIO="([^"]+)"/)?.[1] ?? null
+          audioGroup: line.match(/AUDIO="([^"]+)"/)?.[1] ?? null,
+          ...codecs ? { codecs } : {}
         });
       }
     }
@@ -1080,7 +1255,8 @@ async function assembleHls(net, playlistUrl, headers) {
   if (segments.length === 0) {
     throw new Error("HLS playlist has no segments");
   }
-  return concat(await fetchSegments(net, segments, headers));
+  const bytes = await fetchSegments(net, segments, headers);
+  return packedAacToMp4(bytes) ?? concat(bytes);
 }
 function mediaSegments(text, baseUrl) {
   const segments = [];
@@ -2229,16 +2405,45 @@ var androidVrClient = {
   userAgent: "com.google.android.apps.youtube.vr.oculus/1.65.10 (Linux; U; Android 12L; eureka-user Build/SQ3A.220605.009.A1) gzip",
   version: "1.65.10"
 };
+var visionOsClient = {
+  clientName: "VISIONOS",
+  clientVersion: "1.02",
+  deviceMake: "Apple",
+  deviceModel: "RealityDevice17,1",
+  userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_7_3) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/605.1.15",
+  osName: "visionOS",
+  osVersion: "26.5.23O471"
+};
 var browserCookie = "PREF=hl=en&tz=UTC; SOCS=CAI";
 async function resolveYoutube(input) {
   const id = youtubeVideoId(input.url);
   if (!id) {
     throw new Error("YouTube video id not found");
   }
-  const session = await youtubeSession(input.net, id);
-  const response = await input.net("https://www.youtube.com/youtubei/v1/player?prettyPrint=false", {
-    body: JSON.stringify(playerBody(id, session)),
-    headers: playerHeaders(session),
+  let session;
+  try {
+    session = await youtubeSession(input.net, id);
+    const payload = await youtubePlayer(input.net, playerBody(id, session), playerHeaders(session));
+    const streams = selectStreams(payload, input.preferredWidth);
+    if (!streams) {
+      throw new Error("YouTube mp4 stream not found");
+    }
+    const headers = { "user-agent": androidVrClient.userAgent };
+    await Promise.all([streams.video, streams.audio].filter((url) => url !== null).map((url) => probeStream(input.net, url, headers)));
+    return youtubeResult(id, payload, streams, headers);
+  } catch (primaryError) {
+    try {
+      return await resolveVisionOs(input, id, session?.visitorData);
+    } catch (fallbackError) {
+      const message = (error) => error instanceof Error ? error.message : String(error);
+      throw new Error(`YouTube resolution failed: ${message(primaryError)}; visionOS HLS: ${message(fallbackError)}`, { cause: fallbackError });
+    }
+  }
+}
+async function youtubePlayer(net, body, headers) {
+  const response = await net("https://www.youtube.com/youtubei/v1/player?prettyPrint=false", {
+    body: JSON.stringify(body),
+    headers,
     method: "POST"
   });
   if (!response.ok) {
@@ -2250,12 +2455,10 @@ async function resolveYoutube(input) {
     const reason = object(payload) && object(payload.playabilityStatus) ? string(payload.playabilityStatus.reason) : null;
     throw new Error(reason ?? "YouTube video unavailable");
   }
-  const streams = selectStreams(payload, input.preferredWidth);
-  if (!streams) {
-    throw new Error("YouTube mp4 stream not found");
-  }
+  return payload;
+}
+function youtubeResult(id, payload, streams, headers) {
   const title = object(payload) && object(payload.videoDetails) ? string(payload.videoDetails.title) : null;
-  const headers = { "user-agent": androidVrClient.userAgent };
   const media = {
     filename: filename(`youtube_${title ?? id}_${id}.mp4`),
     headers,
@@ -2264,10 +2467,56 @@ async function resolveYoutube(input) {
     mime: "video/mp4",
     platform: "youtube",
     url: streams.video,
+    ...streams.hls ? { hls: true } : {},
     ...streams.audio ? { audio: { headers, url: streams.audio } } : {}
   };
   return { archiveFilename: filename(`youtube_${id}.zip`), id, items: [media], metadata: youtubeMetadata(payload), platform: "youtube" };
 }
+async function probeStream(net, url, headers) {
+  const response = await net(url, { headers }, 1);
+  await response.body?.cancel();
+  if (!response.ok) {
+    throw new Error(`YouTube stream failed: ${response.status}`);
+  }
+}
+async function resolveVisionOs(input, id, visitorData) {
+  const headers = { "user-agent": visionOsClient.userAgent };
+  const payload = await youtubePlayer(input.net, {
+    videoId: id,
+    contentCheckOk: true,
+    racyCheckOk: true,
+    context: { client: { ...visionOsClient, hl: "en", gl: "US", ...visitorData ? { visitorData } : {} } }
+  }, {
+    ...headers,
+    "content-type": "application/json",
+    "x-youtube-client-name": "101",
+    "x-youtube-client-version": visionOsClient.clientVersion,
+    ...visitorData ? { "x-goog-visitor-id": visitorData } : {}
+  });
+  const streaming = object(payload) && object(payload.streamingData) ? payload.streamingData : null;
+  const manifestUrl = streaming ? string(streaming.hlsManifestUrl) : null;
+  if (!manifestUrl) {
+    throw new Error("YouTube HLS manifest not found");
+  }
+  const response = await input.net(manifestUrl, { headers });
+  if (!response.ok) {
+    throw new Error(`YouTube HLS manifest failed: ${response.status}`);
+  }
+  const master = parseMaster(await response.text(), manifestUrl);
+  const variants = master.variants.filter((variant2) => /(?:^|,)(?:vp09|av01)\./i.test(variant2.codecs ?? "") && /(?:^|,)mp4a\.40\.2(?:,|$)/i.test(variant2.codecs ?? "") && variant2.audioGroup && master.audio[variant2.audioGroup]).sort((left, right) => Math.abs(left.width - input.preferredWidth) - Math.abs(right.width - input.preferredWidth) || right.bandwidth - left.bandwidth);
+  const variant = variants[0];
+  if (!variant?.audioGroup) {
+    throw new Error("YouTube fragmented MP4 HLS video with AAC audio not found");
+  }
+  const playlist = await input.net(variant.url, { headers });
+  if (!playlist.ok) {
+    throw new Error(`YouTube HLS playlist failed: ${playlist.status}`);
+  }
+  if (!(await playlist.text()).includes("#EXT-X-MAP:")) {
+    throw new Error("YouTube HLS video is not fragmented MP4");
+  }
+  return youtubeResult(id, payload, { video: variant.url, audio: master.audio[variant.audioGroup], hls: true }, headers);
+}
 function youtubeMetadata(payload) {
   const details = object(payload) && object(payload.videoDetails) ? payload.videoDetails : null;
   const renderer = object(payload) && object(payload.microformat) && object(payload.microformat.playerMicroformatRenderer) ? payload.microformat.playerMicroformatRenderer : null;
@@ -2840,7 +3089,7 @@ function rewriteMoof(data, moofBox, trackId2, sequence) {
 }
 
 // src/zip.ts
-var encoder = new TextEncoder;
+var encoder2 = new TextEncoder;
 var table = new Uint32Array(256);
 for (let value = 0;value < table.length; value += 1) {
   let crc = value;
@@ -2851,7 +3100,7 @@ for (let value = 0;value < table.length; value += 1) {
 }
 function zip(entries) {
   const files = entries.map((entry) => {
-    const name = encoder.encode(entry.name);
+    const name = encoder2.encode(entry.name);
     const crc = crc32(entry.data);
     return { ...entry, crc, name };
   });
@@ -2947,12 +3196,12 @@ async function download(item, options = {}) {
   }
   return response;
 }
-async function downloadBlob(url, optionsOrHeaders = {}, legacyOptions = {}) {
+async function downloadBlob(input, optionsOrHeaders = {}, legacyOptions = {}) {
   const modern = isDownloadBlobOptions(optionsOrHeaders);
   const options = modern ? optionsOrHeaders : legacyOptions;
   const headers = modern ? optionsOrHeaders.headers ?? {} : optionsOrHeaders;
   const net = createNet(options.fetch ?? globalThis.fetch);
-  const response = await net(url, { headers });
+  const response = typeof input === "string" ? await net(input, { headers }) : await download({ ...input, headers: modern ? optionsOrHeaders.headers ?? input.headers : input.headers }, options);
   if (!response.ok || !response.body) {
     throw new PostfetchError(502, `download failed: ${response.status}`);
   }

package/dist/internal.d.ts

@@ -20,8 +20,8 @@ export type MediaItem = {
     headers: HeadersInit;
     /**
      * When `true`, {@link MediaItem.url} (and `audio.url`, if set) are HLS media
-     * playlists rather than direct files: {@link download} assembles their segments
-     * into a fragmented MP4 before serving — and merges video with audio when both
+     * playlists rather than direct files: {@link download} assembles their fMP4
+     * segments (or packages packed AAC audio) before serving, and merges tracks when both
      * are present. Callers that read `url` directly get the playlist, not the media.
      */
     hls?: boolean;

package/dist/packed-aac.d.ts

@@ -0,0 +1 @@
+export declare function packedAacToMp4(segments: Uint8Array[]): Uint8Array | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postfetch/core",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Zero-dependency typed core that turns Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube post URLs into media files.",
   "license": "MIT",
   "type": "module",

package/src/download.ts

@@ -77,39 +77,40 @@ export async function download(item: MediaItem, options: DownloadOptions = {}):
 }
 
 /**
- * Download an already-resolved media URL as a Blob.
+ * Download a resolved media item or direct media URL as a Blob.
  *
  * This is useful for consumers that need to upload media themselves instead of
- * passing its URL to a third party. When the resolved {@link MediaItem} carries
- * required CDN headers, pass them in the options object. Set `remux: true` to
+ * passing its URL to a third party. Pass the full {@link MediaItem} to include
+ * separate audio, HLS playlists and required headers. A direct URL only fetches
+ * that URL; pass its required CDN headers in the options object. Set `remux: true` to
  * normalize an MP4 with an FFmpeg stream copy; if FFmpeg is unavailable or the
  * remux or metadata extraction fails, the operation throws.
  *
- * @param url A direct media URL returned by a resolver.
+ * @param input A resolved media item (recommended) or direct media URL.
  * @param options Headers, fetch implementation and opt-in remux behavior.
  * @returns A Blob, or with `remux: true`, the normalized video and its metadata.
  *
  * @example Upload a video with FormData
  * ```ts
  * const [media] = (await postfetch(sourceUrl)).items;
- * const video = await downloadBlob(media.url, { headers: media.headers, remux: true });
+ * const video = await downloadBlob(media, { remux: true });
  * form.append("video", video.blob, media.filename);
  * form.append("thumbnail", video.thumbnail, "thumbnail.jpg");
  * ```
  */
 export async function downloadBlob(
-  url: string,
+  input: string | MediaItem,
   options: DownloadBlobOptions & { remux: true },
 ): Promise<RemuxedVideo>;
 /** Download without remuxing and return the upstream media Blob. */
 export async function downloadBlob(
-  url: string,
+  input: string | MediaItem,
   options?: DownloadBlobOptions & { remux?: false },
 ): Promise<Blob>;
 /** @deprecated Pass headers and fetch in a single {@link DownloadBlobOptions} object. */
 export async function downloadBlob(url: string, headers?: HeadersInit, options?: DownloadOptions): Promise<Blob>;
 export async function downloadBlob(
-  url: string,
+  input: string | MediaItem,
   optionsOrHeaders: DownloadBlobOptions | HeadersInit = {},
   legacyOptions: DownloadOptions = {},
 ): Promise<Blob | RemuxedVideo> {
@@ -117,7 +118,9 @@ export async function downloadBlob(
   const options = modern ? optionsOrHeaders : legacyOptions;
   const headers = modern ? optionsOrHeaders.headers ?? {} : optionsOrHeaders;
   const net = createNet(options.fetch ?? globalThis.fetch);
-  const response = await net(url, { headers });
+  const response = typeof input === "string"
+    ? await net(input, { headers })
+    : await download({ ...input, headers: modern ? optionsOrHeaders.headers ?? input.headers : input.headers }, options);
   if (!response.ok || !response.body) {
     throw new PostfetchError(502, `download failed: ${response.status}`);
   }

package/src/hls.ts

@@ -1,14 +1,15 @@
 import { concat } from "./isobmff";
 import type { Net } from "./internal";
+import { packedAacToMp4 } from "./packed-aac";
 
 // HLS support for the fMP4/CMAF playlists reddit-style muxing already covers:
 // a media playlist is an EXT-X-MAP init plus media segments (often byte ranges of
-// one CMAF file), so assembling it is just fetching those byte ranges in order and
-// concatenating them into a fragmented MP4. No MPEG-TS demuxing is involved.
+// one CMAF file). Packed AAC audio is also packaged into fMP4 for merging with
+// YouTube's HLS video. No MPEG-TS demuxing is involved.
 
 type Segment = { url: string; range: { length: number; offset: number } | null };
 
-export type HlsVariant = { width: number; height: number; bandwidth: number; url: string; audioGroup: string | null };
+export type HlsVariant = { width: number; height: number; bandwidth: number; url: string; audioGroup: string | null; codecs?: string };
 export type HlsMaster = { variants: HlsVariant[]; audio: Record<string, string> };
 
 export function isMasterPlaylist(text: string): boolean {
@@ -18,25 +19,30 @@ export function isMasterPlaylist(text: string): boolean {
 export function parseMaster(text: string, baseUrl: string): HlsMaster {
   const lines = text.split("\n").map((line) => line.trim());
   const audio: Record<string, string> = {};
+  const defaultAudio = new Set<string>();
   const variants: HlsVariant[] = [];
   for (let index = 0; index < lines.length; index += 1) {
     const line = lines[index];
     if (line.startsWith("#EXT-X-MEDIA:") && /TYPE=AUDIO/.test(line)) {
       const group = line.match(/GROUP-ID="([^"]+)"/)?.[1];
       const uri = line.match(/URI="([^"]+)"/)?.[1];
-      if (group && uri) {
+      const isDefault = /(?:^|,)DEFAULT=YES(?:,|$)/.test(line);
+      if (group && uri && (!audio[group] || (isDefault && !defaultAudio.has(group)))) {
         audio[group] = new URL(uri, baseUrl).href;
+        if (isDefault) defaultAudio.add(group);
       }
     } else if (line.startsWith("#EXT-X-STREAM-INF:")) {
       const target = lines[index + 1];
       if (target && !target.startsWith("#")) {
         const resolution = line.match(/RESOLUTION=(\d+)x(\d+)/);
+        const codecs = line.match(/CODECS="([^"]+)"/)?.[1];
         variants.push({
           width: resolution ? Number(resolution[1]) : 0,
           height: resolution ? Number(resolution[2]) : 0,
           bandwidth: Number(line.match(/BANDWIDTH=(\d+)/)?.[1] ?? 0),
           url: new URL(target, baseUrl).href,
           audioGroup: line.match(/AUDIO="([^"]+)"/)?.[1] ?? null,
+          ...(codecs ? { codecs } : {}),
         });
       }
     }
@@ -53,7 +59,8 @@ export async function assembleHls(net: Net, playlistUrl: string, headers: Header
   if (segments.length === 0) {
     throw new Error("HLS playlist has no segments");
   }
-  return concat(await fetchSegments(net, segments, headers));
+  const bytes = await fetchSegments(net, segments, headers);
+  return packedAacToMp4(bytes) ?? concat(bytes);
 }
 
 function mediaSegments(text: string, baseUrl: string): Segment[] {

package/src/internal.ts

@@ -19,8 +19,8 @@ export type MediaItem = {
   headers: HeadersInit;
   /**
    * When `true`, {@link MediaItem.url} (and `audio.url`, if set) are HLS media
-   * playlists rather than direct files: {@link download} assembles their segments
-   * into a fragmented MP4 before serving — and merges video with audio when both
+   * playlists rather than direct files: {@link download} assembles their fMP4
+   * segments (or packages packed AAC audio) before serving, and merges tracks when both
    * are present. Callers that read `url` directly get the playlist, not the media.
    */
   hls?: boolean;

package/src/packed-aac.ts

@@ -0,0 +1,187 @@
+import { buildBox, concat, readU32, writeU32 } from "./isobmff";
+
+// YouTube's fMP4 HLS video is paired with packed AAC: each audio segment is
+// ID3 (including a 90 kHz timestamp) followed by ADTS frames. Strip the transport
+// headers and put the original AAC samples into CMAF fragments for our merger.
+type Config = { frequencyIndex: number; sampleRate: number; channels: number };
+type Fragment = { samples: Uint8Array[]; timestamp: number };
+const sampleRates = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350];
+const encoder = new TextEncoder();
+
+export function packedAacToMp4(segments: Uint8Array[]): Uint8Array | null {
+  const first = segments[0];
+  if (!first || (!id3(first, 0) && !adts(first, 0))) {
+    return null;
+  }
+  let config: Config | undefined;
+  let nextTimestamp = 0;
+  const fragments: Fragment[] = [];
+  for (const segment of segments) {
+    let offset = 0;
+    let timestamp: number | undefined;
+    while (id3(segment, offset)) {
+      const tag = readId3(segment, offset);
+      timestamp ??= tag.timestamp;
+      offset = tag.end;
+    }
+    const samples: Uint8Array[] = [];
+    while (offset < segment.length) {
+      if (offset + 7 > segment.length || !adts(segment, offset)) {
+        throw new Error("Invalid packed AAC frame");
+      }
+      const profile = (segment[offset + 2] >> 6) + 1;
+      const frequencyIndex = (segment[offset + 2] >> 2) & 15;
+      const sampleRate = sampleRates[frequencyIndex];
+      const channels = ((segment[offset + 2] & 1) << 2) | (segment[offset + 3] >> 6);
+      if (profile !== 2 || !sampleRate || sampleRate > 65535 || channels === 0 || (segment[offset + 6] & 3) !== 0) {
+        throw new Error("Unsupported packed AAC configuration (expected AAC-LC)");
+      }
+      if (config && (config.frequencyIndex !== frequencyIndex || config.channels !== channels)) {
+        throw new Error("Packed AAC configuration changed between frames");
+      }
+      config ??= { frequencyIndex, sampleRate, channels };
+      const length = ((segment[offset + 3] & 3) << 11) | (segment[offset + 4] << 3) | (segment[offset + 5] >> 5);
+      const headerLength = segment[offset + 1] & 1 ? 7 : 9;
+      if (length <= headerLength || offset + length > segment.length) {
+        throw new Error("Truncated packed AAC frame");
+      }
+      samples.push(segment.subarray(offset + headerLength, offset + length));
+      offset += length;
+    }
+    if (!config || samples.length === 0) {
+      throw new Error("Packed AAC segment has no audio frames");
+    }
+    const start = timestamp === undefined ? nextTimestamp : Math.round(timestamp * config.sampleRate / 90000);
+    fragments.push({ samples, timestamp: start });
+    nextTimestamp = start + samples.length * 1024;
+  }
+  return concat([initSegment(config!), ...fragments.flatMap((fragment, index) => mediaFragment(fragment, index + 1))]);
+}
+
+function id3(bytes: Uint8Array, offset: number): boolean {
+  return bytes[offset] === 0x49 && bytes[offset + 1] === 0x44 && bytes[offset + 2] === 0x33;
+}
+
+function adts(bytes: Uint8Array, offset: number): boolean {
+  return bytes[offset] === 0xff && (bytes[offset + 1] & 0xf6) === 0xf0;
+}
+
+function synchsafe(bytes: Uint8Array, offset: number): number {
+  if (offset + 4 > bytes.length || bytes.subarray(offset, offset + 4).some((byte) => byte & 128)) {
+    throw new Error("Invalid packed AAC ID3 size");
+  }
+  return bytes[offset] * 2 ** 21 + bytes[offset + 1] * 2 ** 14 + bytes[offset + 2] * 128 + bytes[offset + 3];
+}
+
+function readId3(bytes: Uint8Array, offset: number): { end: number; timestamp?: number } {
+  const version = bytes[offset + 3];
+  if (offset + 10 > bytes.length || (version !== 3 && version !== 4) || (bytes[offset + 5] & 0xc0)) {
+    throw new Error("Unsupported packed AAC ID3 tag");
+  }
+  const end = offset + 10 + synchsafe(bytes, offset + 6);
+  if (end > bytes.length) {
+    throw new Error("Truncated packed AAC ID3 tag");
+  }
+  const owner = encoder.encode("com.apple.streaming.transportStreamTimestamp\0");
+  let timestamp: number | undefined;
+  for (let cursor = offset + 10; cursor + 10 <= end && bytes[cursor] !== 0;) {
+    const size = version === 4 ? synchsafe(bytes, cursor + 4) : readU32(bytes, cursor + 4);
+    const body = cursor + 10;
+    if (body + size > end) {
+      throw new Error("Truncated packed AAC ID3 frame");
+    }
+    if (String.fromCharCode(...bytes.subarray(cursor, cursor + 4)) === "PRIV" &&
+      size === owner.length + 8 && owner.every((byte, index) => bytes[body + index] === byte)) {
+      if (bytes[cursor + 8] !== 0 || bytes[cursor + 9] !== 0) {
+        throw new Error("Unsupported packed AAC timestamp encoding");
+      }
+      timestamp = Number(new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getBigUint64(body + owner.length) & 0x1ffffffffn);
+    }
+    cursor = body + size;
+  }
+  const footer = version === 4 && (bytes[offset + 5] & 0x10) ? 10 : 0;
+  if (end + footer > bytes.length) {
+    throw new Error("Truncated packed AAC ID3 footer");
+  }
+  return { end: end + footer, timestamp };
+}
+
+function u32(...values: number[]): Uint8Array {
+  const bytes = new Uint8Array(values.length * 4);
+  values.forEach((value, index) => writeU32(bytes, index * 4, value));
+  return bytes;
+}
+
+function fullBox(type: string, version: number, flags: number, payload: Uint8Array): Uint8Array {
+  return buildBox(type, concat([u32(version * 0x1000000 + flags), payload]));
+}
+
+function matrix(bytes: Uint8Array, offset: number): void {
+  bytes.set(u32(0x10000, 0, 0, 0, 0x10000, 0, 0, 0, 0x40000000), offset);
+}
+
+function initSegment(config: Config): Uint8Array {
+  const mvhd = new Uint8Array(96);
+  writeU32(mvhd, 8, 1000);
+  writeU32(mvhd, 16, 0x10000);
+  new DataView(mvhd.buffer).setUint16(20, 0x100);
+  matrix(mvhd, 32);
+  writeU32(mvhd, 92, 2);
+  const tkhd = new Uint8Array(80);
+  writeU32(tkhd, 8, 1);
+  new DataView(tkhd.buffer).setUint16(32, 0x100);
+  matrix(tkhd, 36);
+  const mdhd = concat([u32(0, 0, config.sampleRate, 0), Uint8Array.of(0x55, 0xc4, 0, 0)]);
+  const hdlr = concat([u32(0), encoder.encode("soun"), u32(0, 0, 0), encoder.encode("SoundHandler\0")]);
+  const stbl = buildBox("stbl", concat([
+    fullBox("stsd", 0, 0, concat([u32(1), sampleEntry(config)])),
+    ...["stts", "stsc", "stco"].map((type) => fullBox(type, 0, 0, u32(0))),
+    fullBox("stsz", 0, 0, u32(0, 0)),
+  ]));
+  const minf = buildBox("minf", concat([
+    fullBox("smhd", 0, 0, u32(0)),
+    buildBox("dinf", fullBox("dref", 0, 0, concat([u32(1), fullBox("url ", 0, 1, new Uint8Array())]))),
+    stbl,
+  ]));
+  const trak = buildBox("trak", concat([
+    fullBox("tkhd", 0, 7, tkhd),
+    buildBox("mdia", concat([fullBox("mdhd", 0, 0, mdhd), fullBox("hdlr", 0, 0, hdlr), minf])),
+  ]));
+  return concat([
+    buildBox("ftyp", concat([encoder.encode("isom"), u32(512), encoder.encode("isomiso6mp41")])),
+    buildBox("moov", concat([
+      fullBox("mvhd", 0, 0, mvhd), trak,
+      buildBox("mvex", fullBox("trex", 0, 0, u32(1, 1, 1024, 0, 0x02000000))),
+    ])),
+  ]);
+}
+
+function descriptor(tag: number, payload: Uint8Array): Uint8Array {
+  // The fixed AAC-LC descriptors below are all shorter than 128 bytes.
+  return concat([Uint8Array.of(tag, payload.length), payload]);
+}
+
+function sampleEntry(config: Config): Uint8Array {
+  const entry = new Uint8Array(28);
+  const view = new DataView(entry.buffer);
+  view.setUint16(6, 1);
+  view.setUint16(16, config.channels === 7 ? 8 : config.channels);
+  view.setUint16(18, 16);
+  view.setUint32(24, config.sampleRate * 65536);
+  const asc = Uint8Array.of((2 << 3) | (config.frequencyIndex >> 1), ((config.frequencyIndex & 1) << 7) | (config.channels << 3));
+  const decoder = descriptor(4, concat([Uint8Array.of(0x40, 0x15, 0, 0, 0), u32(0, 0), descriptor(5, asc)]));
+  const esds = descriptor(3, concat([Uint8Array.of(0, 1, 0), decoder, descriptor(6, Uint8Array.of(2))]));
+  return buildBox("mp4a", concat([entry, fullBox("esds", 0, 0, esds)]));
+}
+
+function mediaFragment(fragment: Fragment, sequence: number): Uint8Array[] {
+  const timestamp = new Uint8Array(8);
+  new DataView(timestamp.buffer).setBigUint64(0, BigInt(fragment.timestamp));
+  const trun = fullBox("trun", 0, 0x201, concat([u32(fragment.samples.length, 0), u32(...fragment.samples.map((sample) => sample.length))]));
+  const moof = buildBox("moof", concat([
+    fullBox("mfhd", 0, 0, u32(sequence)),
+    buildBox("traf", concat([fullBox("tfhd", 0, 0x020000, u32(1)), fullBox("tfdt", 1, 0, timestamp), trun])),
+  ]));
+  writeU32(moof, moof.length - trun.length + 16, moof.length + 8);
+  return [moof, buildBox("mdat", concat(fragment.samples))];
+}

package/src/youtube.ts

@@ -15,6 +15,7 @@ import {
   type MediaItem,
 } from "./internal";
 import { browserUserAgent } from "./fingerprint";
+import { parseMaster } from "./hls";
 
 type YoutubeSession = {
   cookie: string;
@@ -29,6 +30,16 @@ const androidVrClient = {
   version: "1.65.10",
 };
 
+const visionOsClient = {
+  clientName: "VISIONOS",
+  clientVersion: "1.02",
+  deviceMake: "Apple",
+  deviceModel: "RealityDevice17,1",
+  userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_7_3) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/605.1.15",
+  osName: "visionOS",
+  osVersion: "26.5.23O471",
+};
+
 const browserCookie = "PREF=hl=en&tz=UTC; SOCS=CAI";
 
 export async function resolveYoutube(input: ResolveContext): Promise<PostfetchResult> {
@@ -36,11 +47,33 @@ export async function resolveYoutube(input: ResolveContext): Promise<PostfetchRe
   if (!id) {
     throw new Error("YouTube video id not found");
   }
-  const session = await youtubeSession(input.net, id);
-  const response = await input.net("https://www.youtube.com/youtubei/v1/player?prettyPrint=false", {
-    body: JSON.stringify(playerBody(id, session)),
-    headers: playerHeaders(session),
-    method: "POST",
+  let session: YoutubeSession | undefined;
+  try {
+    session = await youtubeSession(input.net, id);
+    const payload = await youtubePlayer(input.net, playerBody(id, session), playerHeaders(session));
+    const streams = selectStreams(payload, input.preferredWidth);
+    if (!streams) {
+      throw new Error("YouTube mp4 stream not found");
+    }
+    const headers = { "user-agent": androidVrClient.userAgent };
+    // A successful player response can still contain CDN URLs that return 403.
+    // Check the actual GET and cancel its body: HEAD/Range probes can succeed
+    // even when YouTube rejects the full download.
+    await Promise.all([streams.video, streams.audio].filter((url): url is string => url !== null).map((url) => probeStream(input.net, url, headers)));
+    return youtubeResult(id, payload, streams, headers);
+  } catch (primaryError) {
+    try {
+      return await resolveVisionOs(input, id, session?.visitorData);
+    } catch (fallbackError) {
+      const message = (error: unknown) => error instanceof Error ? error.message : String(error);
+      throw new Error(`YouTube resolution failed: ${message(primaryError)}; visionOS HLS: ${message(fallbackError)}`, { cause: fallbackError });
+    }
+  }
+}
+
+async function youtubePlayer(net: Net, body: Json, headers: HeadersInit): Promise<unknown> {
+  const response = await net("https://www.youtube.com/youtubei/v1/player?prettyPrint=false", {
+    body: JSON.stringify(body), headers, method: "POST",
   });
   if (!response.ok) {
     throw new Error(`YouTube player failed: ${response.status}`);
@@ -51,12 +84,16 @@ export async function resolveYoutube(input: ResolveContext): Promise<PostfetchRe
     const reason = object(payload) && object(payload.playabilityStatus) ? string(payload.playabilityStatus.reason) : null;
     throw new Error(reason ?? "YouTube video unavailable");
   }
-  const streams = selectStreams(payload, input.preferredWidth);
-  if (!streams) {
-    throw new Error("YouTube mp4 stream not found");
-  }
+  return payload;
+}
+
+function youtubeResult(
+  id: string,
+  payload: unknown,
+  streams: { video: string; audio: string | null; hls?: boolean },
+  headers: HeadersInit,
+): PostfetchResult {
   const title = object(payload) && object(payload.videoDetails) ? string(payload.videoDetails.title) : null;
-  const headers = { "user-agent": androidVrClient.userAgent };
   const media: MediaItem = {
     filename: filename(`youtube_${title ?? id}_${id}.mp4`),
     headers,
@@ -65,11 +102,67 @@ export async function resolveYoutube(input: ResolveContext): Promise<PostfetchRe
     mime: "video/mp4",
     platform: "youtube",
     url: streams.video,
+    ...(streams.hls ? { hls: true } : {}),
     ...(streams.audio ? { audio: { headers, url: streams.audio } } : {}),
   };
   return { archiveFilename: filename(`youtube_${id}.zip`), id, items: [media], metadata: youtubeMetadata(payload), platform: "youtube" };
 }
 
+async function probeStream(net: Net, url: string, headers: HeadersInit): Promise<void> {
+  const response = await net(url, { headers }, 1);
+  await response.body?.cancel();
+  if (!response.ok) {
+    throw new Error(`YouTube stream failed: ${response.status}`);
+  }
+}
+
+async function resolveVisionOs(input: ResolveContext, id: string, visitorData?: string): Promise<PostfetchResult> {
+  const headers = { "user-agent": visionOsClient.userAgent };
+  const payload = await youtubePlayer(input.net, {
+    videoId: id,
+    contentCheckOk: true,
+    racyCheckOk: true,
+    context: { client: { ...visionOsClient, hl: "en", gl: "US", ...(visitorData ? { visitorData } : {}) } },
+  }, {
+    ...headers,
+    "content-type": "application/json",
+    "x-youtube-client-name": "101",
+    "x-youtube-client-version": visionOsClient.clientVersion,
+    ...(visitorData ? { "x-goog-visitor-id": visitorData } : {}),
+  });
+  const streaming = object(payload) && object(payload.streamingData) ? payload.streamingData : null;
+  const manifestUrl = streaming ? string(streaming.hlsManifestUrl) : null;
+  if (!manifestUrl) {
+    throw new Error("YouTube HLS manifest not found");
+  }
+  const response = await input.net(manifestUrl, { headers });
+  if (!response.ok) {
+    throw new Error(`YouTube HLS manifest failed: ${response.status}`);
+  }
+  const master = parseMaster(await response.text(), manifestUrl);
+  // YouTube's AVC HLS variants use MPEG-TS. VP9/AV1 variants use fMP4 and
+  // work with the bundled box-level merger. Require the paired AAC-LC track.
+  const variants = master.variants.filter((variant) =>
+    /(?:^|,)(?:vp09|av01)\./i.test(variant.codecs ?? "") &&
+    /(?:^|,)mp4a\.40\.2(?:,|$)/i.test(variant.codecs ?? "") &&
+    variant.audioGroup && master.audio[variant.audioGroup]
+  ).sort((left, right) =>
+    Math.abs(left.width - input.preferredWidth) - Math.abs(right.width - input.preferredWidth) || right.bandwidth - left.bandwidth
+  );
+  const variant = variants[0];
+  if (!variant?.audioGroup) {
+    throw new Error("YouTube fragmented MP4 HLS video with AAC audio not found");
+  }
+  const playlist = await input.net(variant.url, { headers });
+  if (!playlist.ok) {
+    throw new Error(`YouTube HLS playlist failed: ${playlist.status}`);
+  }
+  if (!(await playlist.text()).includes("#EXT-X-MAP:")) {
+    throw new Error("YouTube HLS video is not fragmented MP4");
+  }
+  return youtubeResult(id, payload, { video: variant.url, audio: master.audio[variant.audioGroup], hls: true }, headers);
+}
+
 export function youtubeMetadata(payload: unknown): PostMetadata & { extra?: YoutubeExtra } {
   const details = object(payload) && object(payload.videoDetails) ? payload.videoDetails : null;
   const renderer =