@postfetch/core 0.9.2 → 0.10.0

package/README.md

@@ -24,9 +24,29 @@ defaults to off, uses `ffmpeg` and `ffprobe` from `PATH` unless their paths are
 set, and throws if the complete result cannot be produced. The legacy
 `(url, headers?, options?)` overload remains supported for non-remux downloads.
 
+`buildAudioSliderVideo(items, { delay: 3000 })` returns an MP4 `Blob` from one or
+more images/videos followed by exactly one audio item. `delay` is milliseconds
+per visual, rounded to 30 fps (minimum two frames), including a right-to-left
+transition lasting up to 300 ms or half the delay. The last visual stays visible;
+a single visual has no transition. Total duration is visual count × rounded
+delay. Videos loop or trim to fit and their own audio is discarded; the trailing
+audio loops and trims to the result. The default 720×1280 canvas preserves
+aspect ratio with black padding. `AudioSliderVideoOptions` supports `width` and
+`height` (positive even integers), `fetch`, and `ffmpegPath`. Requires local
+FFmpeg with `libx264` and a runtime with filesystem/process access (Node, Bun,
+Deno). Downloads retain item headers and assemble HLS; temporary files are
+cleaned up on success and failure.
+
+```ts
+import { buildAudioSliderVideo } from "@postfetch/core";
+
+const blob = await buildAudioSliderVideo(result.items, { delay: 3000 });
+form.append("video", blob, "slideshow.mp4");
+```
+
 - `PostfetchOptions` — `{ fetch?: typeof fetch; preferredWidth?: number; tryMaxBytes?: number }`. `tryMaxBytes` is a soft byte cap. X probes every MP4 variant and selects the highest-quality complete result that fits, falling back to its smallest variants when none do. Other platforms return a smaller available rendition when possible and otherwise keep the normal result. Inject `fetch` to unit-test resolvers offline.
 - Every request rotates a consistent browser/app fingerprint, so a fixed user-agent never gets the whole fleet blocked.
 - No runtime dependencies, no `yt-dlp`, no cookies. `ffmpeg` is only used when
-  the opt-in `downloadBlob(..., { remux: true })` path is requested.
+  `downloadBlob(..., { remux: true })` or `buildAudioSliderVideo` is requested.
 
 See the [root README](https://github.com/chelokot/postfetch#readme) for the full API table, supported inputs and the fingerprint design.

package/dist/audio-slider.d.ts

@@ -0,0 +1,36 @@
+import { type DownloadOptions } from "./download";
+import { type MediaItem } from "./internal";
+/** Options for {@link buildAudioSliderVideo}. Requires a local FFmpeg binary. */
+export type AudioSliderVideoOptions = DownloadOptions & {
+    /** Time per visual item in milliseconds, including its outgoing transition. */
+    delay: number;
+    /** Output width in pixels; a positive even integer. Defaults to 720. */
+    width?: number;
+    /** Output height in pixels; a positive even integer. Defaults to 1280. */
+    height?: number;
+    /** FFmpeg command or executable path. Defaults to `ffmpeg` from PATH. */
+    ffmpegPath?: string;
+};
+/**
+ * Build an H.264/AAC MP4 Blob from one or more images/videos followed by exactly
+ * one audio item. Downloads preserve each item's headers and assemble HLS.
+ * Visuals retain their aspect ratio, padded with black to the output size.
+ * Video clips play from the beginning, looping or trimming to fit; their own
+ * audio is discarded. The final audio item loops and is trimmed to the result.
+ *
+ * Each visual gets `delay` ms (rounded to 30 fps, minimum two frames). Adjacent
+ * visuals slide right to left over the last 300 ms or half the delay, whichever
+ * is shorter. The last visual stays on screen; a single visual has no transition.
+ * Total duration is the number of visuals times the rounded delay.
+ *
+ * Requires Node, Bun or Deno with filesystem/process access and FFmpeg with
+ * libx264. Temporary files are removed on success and failure.
+ *
+ * @example
+ * ```ts
+ * const result = await postfetch(photoUrl);
+ * const blob = await buildAudioSliderVideo(result.items, { delay: 3000 });
+ * form.append("video", blob, "slideshow.mp4");
+ * ```
+ */
+export declare function buildAudioSliderVideo(items: readonly MediaItem[], options: AudioSliderVideoOptions): Promise<Blob>;

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.d.ts

@@ -20,6 +20,7 @@
  * @module
  */
 export { postfetch, detect, type PostfetchOptions } from "./postfetch";
+export { buildAudioSliderVideo, type AudioSliderVideoOptions } from "./audio-slider";
 export { download, downloadBlob, archive, toResponse, type Archive, type DownloadBlobOptions, type DownloadOptions, type RemuxedVideo, } from "./download";
 export { PostfetchError } from "./internal";
 export type { InstagramExtra, MediaItem, MediaKind, PinterestExtra, Platform, PlatformResult, PostAuthor, PostfetchReason, PostfetchResult, PostMetadata, RedditExtra, SoundcloudExtra, TiktokExtra, TwitterExtra, TwitterQuotedTweet, YoutubeExtra, } from "./internal";

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 };
   });
@@ -3064,12 +3313,80 @@ async function fetchBytes(net, url, headers) {
 function toArrayBuffer(bytes) {
   return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
 }
+
+// src/audio-slider.ts
+var fps = 30;
+async function buildAudioSliderVideo(items, options) {
+  if (!Array.isArray(items) || items.length < 2 || items.at(-1)?.kind !== "audio" || Array.from(items.slice(0, -1)).some((item) => item?.kind !== "image" && item?.kind !== "video")) {
+    throw new PostfetchError(400, "Expected one or more image/video items followed by exactly one audio item");
+  }
+  if (!options || !Number.isFinite(options.delay) || options.delay <= 0) {
+    throw new PostfetchError(400, "delay must be a positive finite number of milliseconds");
+  }
+  const width = options.width ?? 720;
+  const height2 = options.height ?? 1280;
+  for (const [name, value] of [["width", width], ["height", height2]]) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value % 2 !== 0) {
+      throw new PostfetchError(400, `${name} must be a positive even integer`);
+    }
+  }
+  const visuals = items.slice(0, -1);
+  const frames = Math.max(2, Math.round(options.delay * fps / 1000));
+  if (!Number.isSafeInteger(frames * visuals.length)) {
+    throw new PostfetchError(400, "delay produces an unsupported video duration");
+  }
+  const seconds = frames / fps;
+  const transition = Math.min(0.3, seconds / 2);
+  const duration = seconds * visuals.length;
+  const io = await nodeRuntime();
+  const directory = await io.makeTempDir("postfetch-slider-");
+  try {
+    const paths = [];
+    for (const [index, item] of items.entries()) {
+      const path = `${directory}/input-${index}`;
+      const response = await download(item, options);
+      await io.writeFile(path, new Uint8Array(await response.arrayBuffer()));
+      paths.push(path);
+    }
+    const args = ["-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-filter_complex_threads", "1"];
+    for (const [index, item] of visuals.entries()) {
+      args.push(...item.kind === "image" ? ["-loop", "1", "-framerate", String(fps)] : ["-stream_loop", "-1"]);
+      args.push("-i", paths[index]);
+    }
+    args.push("-stream_loop", "-1", "-i", paths[visuals.length]);
+    const filters = visuals.map((_, index) => `[${index}:v:0]setpts=PTS-STARTPTS,` + `scale=${width}:${height2}:force_original_aspect_ratio=decrease:force_divisible_by=2,` + `pad=${width}:${height2}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${fps},` + `format=yuv444p,trim=duration=${seconds + (index > 0 ? transition : 0)},setpts=PTS-STARTPTS,fps=${fps},settb=AVTB[v${index}]`);
+    let current = "v0";
+    for (let index = 1;index < visuals.length; index += 1) {
+      const next = `slide${index}`;
+      filters.push(`[${current}][v${index}]xfade=transition=slideleft:duration=${transition}:offset=${index * seconds - transition},fps=${fps},settb=AVTB[${next}]`);
+      current = next;
+    }
+    filters.push(`[${current}]format=yuv420p[outv]`);
+    filters.push(`[${visuals.length}:a:0]asetpts=PTS-STARTPTS,atrim=duration=${duration}[outa]`);
+    const output = `${directory}/slideshow.mp4`;
+    args.push("-filter_complex", filters.join(";"), "-map", "[outv]", "-map", "[outa]", "-t", String(duration), "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", output);
+    const result = await io.run(options.ffmpegPath ?? "ffmpeg", args);
+    if (!result.success) {
+      throw new PostfetchError(500, `Audio slider video encoding failed: ${result.stderr}`);
+    }
+    const bytes = await io.readFile(output);
+    if (bytes.length === 0) {
+      throw new PostfetchError(500, "Audio slider video encoding produced an empty file");
+    }
+    return new Blob([new Uint8Array(bytes).buffer], { type: "video/mp4" });
+  } finally {
+    await io.removeDir(directory).catch(() => {
+      return;
+    });
+  }
+}
 export {
   toResponse,
   postfetch,
   downloadBlob,
   download,
   detect,
+  buildAudioSliderVideo,
   archive,
   PostfetchError
 };

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/mp4-remux.d.ts

@@ -23,4 +23,5 @@ export type Mp4RemuxRuntime = {
  * FFmpeg only rebuilds the container and timing tables.
  */
 export declare function prepareMp4(bytes: Uint8Array, ffmpegPath?: string, ffprobePath?: string, runtime?: Mp4RemuxRuntime): Promise<PreparedMp4 | null>;
+export declare function nodeRuntime(): Promise<Mp4RemuxRuntime>;
 export {};

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.2",
+  "version": "0.10.0",
   "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/audio-slider.ts

@@ -0,0 +1,118 @@
+import { download, type DownloadOptions } from "./download";
+import { PostfetchError, type MediaItem } from "./internal";
+import { nodeRuntime } from "./mp4-remux";
+
+/** Options for {@link buildAudioSliderVideo}. Requires a local FFmpeg binary. */
+export type AudioSliderVideoOptions = DownloadOptions & {
+  /** Time per visual item in milliseconds, including its outgoing transition. */
+  delay: number;
+  /** Output width in pixels; a positive even integer. Defaults to 720. */
+  width?: number;
+  /** Output height in pixels; a positive even integer. Defaults to 1280. */
+  height?: number;
+  /** FFmpeg command or executable path. Defaults to `ffmpeg` from PATH. */
+  ffmpegPath?: string;
+};
+
+const fps = 30;
+
+/**
+ * Build an H.264/AAC MP4 Blob from one or more images/videos followed by exactly
+ * one audio item. Downloads preserve each item's headers and assemble HLS.
+ * Visuals retain their aspect ratio, padded with black to the output size.
+ * Video clips play from the beginning, looping or trimming to fit; their own
+ * audio is discarded. The final audio item loops and is trimmed to the result.
+ *
+ * Each visual gets `delay` ms (rounded to 30 fps, minimum two frames). Adjacent
+ * visuals slide right to left over the last 300 ms or half the delay, whichever
+ * is shorter. The last visual stays on screen; a single visual has no transition.
+ * Total duration is the number of visuals times the rounded delay.
+ *
+ * Requires Node, Bun or Deno with filesystem/process access and FFmpeg with
+ * libx264. Temporary files are removed on success and failure.
+ *
+ * @example
+ * ```ts
+ * const result = await postfetch(photoUrl);
+ * const blob = await buildAudioSliderVideo(result.items, { delay: 3000 });
+ * form.append("video", blob, "slideshow.mp4");
+ * ```
+ */
+export async function buildAudioSliderVideo(
+  items: readonly MediaItem[],
+  options: AudioSliderVideoOptions,
+): Promise<Blob> {
+  if (
+    !Array.isArray(items) || items.length < 2 || items.at(-1)?.kind !== "audio" ||
+    Array.from(items.slice(0, -1)).some((item) => item?.kind !== "image" && item?.kind !== "video")
+  ) {
+    throw new PostfetchError(400, "Expected one or more image/video items followed by exactly one audio item");
+  }
+  if (!options || !Number.isFinite(options.delay) || options.delay <= 0) {
+    throw new PostfetchError(400, "delay must be a positive finite number of milliseconds");
+  }
+  const width = options.width ?? 720;
+  const height = options.height ?? 1280;
+  for (const [name, value] of [["width", width], ["height", height]] as const) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value % 2 !== 0) {
+      throw new PostfetchError(400, `${name} must be a positive even integer`);
+    }
+  }
+  const visuals = items.slice(0, -1);
+  const frames = Math.max(2, Math.round(options.delay * fps / 1000));
+  if (!Number.isSafeInteger(frames * visuals.length)) {
+    throw new PostfetchError(400, "delay produces an unsupported video duration");
+  }
+  const seconds = frames / fps;
+  const transition = Math.min(0.3, seconds / 2);
+  const duration = seconds * visuals.length;
+  const io = await nodeRuntime();
+  const directory = await io.makeTempDir("postfetch-slider-");
+  try {
+    // Numbered local paths keep remote filenames out of FFmpeg arguments.
+    const paths: string[] = [];
+    for (const [index, item] of items.entries()) {
+      const path = `${directory}/input-${index}`;
+      const response = await download(item, options);
+      await io.writeFile(path, new Uint8Array(await response.arrayBuffer()));
+      paths.push(path);
+    }
+    const args = ["-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-filter_complex_threads", "1"];
+    for (const [index, item] of visuals.entries()) {
+      args.push(...(item.kind === "image" ? ["-loop", "1", "-framerate", String(fps)] : ["-stream_loop", "-1"]));
+      args.push("-i", paths[index]);
+    }
+    args.push("-stream_loop", "-1", "-i", paths[visuals.length]);
+    const filters = visuals.map((_, index) =>
+      `[${index}:v:0]setpts=PTS-STARTPTS,` +
+      `scale=${width}:${height}:force_original_aspect_ratio=decrease:force_divisible_by=2,` +
+      `pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${fps},` +
+      `format=yuv444p,trim=duration=${seconds + (index > 0 ? transition : 0)},setpts=PTS-STARTPTS,fps=${fps},settb=AVTB[v${index}]`,
+    );
+    let current = "v0";
+    for (let index = 1; index < visuals.length; index += 1) {
+      const next = `slide${index}`;
+      filters.push(`[${current}][v${index}]xfade=transition=slideleft:duration=${transition}:offset=${index * seconds - transition},fps=${fps},settb=AVTB[${next}]`);
+      current = next;
+    }
+    filters.push(`[${current}]format=yuv420p[outv]`);
+    filters.push(`[${visuals.length}:a:0]asetpts=PTS-STARTPTS,atrim=duration=${duration}[outa]`);
+    const output = `${directory}/slideshow.mp4`;
+    args.push(
+      "-filter_complex", filters.join(";"), "-map", "[outv]", "-map", "[outa]",
+      "-t", String(duration), "-c:v", "libx264", "-preset", "veryfast", "-crf", "23",
+      "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", output,
+    );
+    const result = await io.run(options.ffmpegPath ?? "ffmpeg", args);
+    if (!result.success) {
+      throw new PostfetchError(500, `Audio slider video encoding failed: ${result.stderr}`);
+    }
+    const bytes = await io.readFile(output);
+    if (bytes.length === 0) {
+      throw new PostfetchError(500, "Audio slider video encoding produced an empty file");
+    }
+    return new Blob([new Uint8Array(bytes).buffer], { type: "video/mp4" });
+  } finally {
+    await io.removeDir(directory).catch(() => undefined);
+  }
+}

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/index.ts

@@ -20,6 +20,7 @@
  * @module
  */
 export { postfetch, detect, type PostfetchOptions } from "./postfetch";
+export { buildAudioSliderVideo, type AudioSliderVideoOptions } from "./audio-slider";
 export {
   download,
   downloadBlob,

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/mp4-remux.ts

@@ -161,7 +161,7 @@ function parseVideoMetadata(value: string): Pick<PreparedMp4, "duration" | "heig
 // Deno, Bun and Node all expose the Node compatibility modules used here. They
 // stay behind dynamic imports so browser/edge consumers that leave remux off do
 // not load or execute any process/filesystem code.
-async function nodeRuntime(): Promise<Mp4RemuxRuntime> {
+export async function nodeRuntime(): Promise<Mp4RemuxRuntime> {
   const [{ spawn }, { mkdtemp, readFile, rm, writeFile }, { tmpdir }, { join }] = await Promise.all([
     import("node:child_process"),
     import("node:fs/promises"),

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 =