@postfetch/core 0.13.3 → 0.13.5

package/dist/audio-slider.d.ts

@@ -18,8 +18,9 @@ export type AudioSliderVideoOptions = DownloadOptions & {
  * 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 plays in full; when the minimum
- * slideshow duration is longer, it loops and is trimmed to the result.
+ * audio is discarded. The final audio item's optional `clip` selects the attached
+ * segment; otherwise the whole track plays. When the minimum slideshow duration
+ * is longer, that segment/track loops and is trimmed to the result.
  *
  * Each visual gets at least `delay` ms or audio duration / visual count,
  * whichever is longer (rounded up to 30 fps, minimum two frames). Adjacent

package/dist/index.js

@@ -381,9 +381,11 @@ async function resolveInstagram(input) {
   const code = shortcode(input.url);
   const videoRequired = /\/(?:reel|reels|tv)\//.test(asUrl(input.url).pathname);
   const page = await pageMedia(input.net, code, input.preferredWidth);
+  let mobile;
+  const getMobile = () => mobile ??= mobileMedia(input.net, code, input.preferredWidth, page.media);
   const resolvers = [
     async () => page.media,
-    () => mobileMedia(input.net, code, input.preferredWidth),
+    getMobile,
     () => embedMedia(input.net, code),
     () => graphqlMedia(input.net, code)
   ];
@@ -402,6 +404,13 @@ async function resolveInstagram(input) {
   if (items.length === 0) {
     throw new Error("Instagram media url not found");
   }
+  if (soundtrackEligible(items) && !items.some((item) => item.kind === "audio") && media.music_metadata === undefined && !object(media.clips_metadata)) {
+    const richer = await getMobile().catch(() => null);
+    const samePost = richer && (string(richer.code) ? richer.code === code : string(richer.pk) !== null && string(richer.pk) === string(media.pk));
+    const audio = samePost ? instagramAudio(richer, code) : null;
+    if (audio)
+      items.push(audio);
+  }
   return { archiveFilename: filename(`instagram_${code}.zip`), comments: [], id: code, items, metadata: instagramMetadata(media), platform: "instagram" };
 }
 async function instagramUnavailable(net, code, pageReason) {
@@ -409,13 +418,13 @@ async function instagramUnavailable(net, code, pageReason) {
   url.searchParams.set("url", `https://www.instagram.com/p/${code}/`);
   const response = await net(url.href, { headers: mobileHeaders() }, 1).catch(() => null);
   const body = response ? await response.text().catch(() => "") : "";
-  const reason = pageReason ?? instagramUnavailableReason(response?.status ?? 0, body);
+  const reason = pageReason ?? instagramUnavailableReason(response?.status ?? 0, body, code);
   const probe = response ? `oembed ${response.status}` : "oembed unreachable";
   return new PostfetchError(reasonStatus(reason), `Instagram post unavailable: ${reason} (${probe})`, reason);
 }
-function instagramUnavailableReason(status, body) {
+function instagramUnavailableReason(status, body, code) {
   if (status === 404) {
-    return "notFound";
+    return code && isPrivateShortcode(code) ? "private" : "notFound";
   }
   if (status === 429) {
     return "rateLimited";
@@ -434,6 +443,9 @@ function instagramUnavailableReason(status, body) {
   }
   return "unavailable";
 }
+function isPrivateShortcode(code) {
+  return code.length > 11;
+}
 function reasonStatus(reason) {
   switch (reason) {
     case "ageRestricted":
@@ -546,8 +558,8 @@ function searchMedia(node, code) {
   }
   return null;
 }
-async function mobileMedia(net, code, preferredWidth) {
-  const id = await mediaId(net, code);
+async function mobileMedia(net, code, preferredWidth, hint) {
+  const id = string(hint?.pk) ?? string(hint?.id) ?? await mediaId(net, code);
   if (!id) {
     return null;
   }
@@ -703,15 +715,42 @@ function mediaItems(media, code, preferredWidth) {
     const node = object(edge) && object(edge.node) ? edge.node : null;
     return node ? instagramItem(node, code, index + 1, preferredWidth) : [];
   });
-  if (oldItems.length > 0) {
-    return oldItems;
-  }
   const carousel = Array.isArray(media.carousel_media) ? media.carousel_media.filter(object) : [];
   const newItems = carousel.flatMap((item, index) => instagramItem(item, code, index + 1, preferredWidth));
-  if (newItems.length > 0) {
-    return newItems;
-  }
-  return instagramItem(media, code, null, preferredWidth);
+  const items = oldItems.length > 0 ? oldItems : newItems.length > 0 ? newItems : instagramItem(media, code, null, preferredWidth);
+  const audio = soundtrackEligible(items) ? instagramAudio(media, code) : null;
+  return audio ? [...items, audio] : items;
+}
+function soundtrackEligible(items) {
+  return items.length > 1 || items[0]?.kind === "image";
+}
+function instagramAudio(media, code) {
+  const metadata = object(media.music_metadata) ? media.music_metadata : object(media.clips_metadata) ? media.clips_metadata : null;
+  if (!metadata)
+    return null;
+  const info = object(metadata.music_info) ? metadata.music_info : null;
+  const consumption = info && object(info.music_consumption_info) ? info.music_consumption_info : null;
+  if (consumption?.should_mute_audio === true)
+    return null;
+  const asset = info && object(info.music_asset_info) ? info.music_asset_info : null;
+  const original = object(metadata.original_sound_info) ? metadata.original_sound_info : null;
+  const selected = [asset, original].find((value) => value && (string(value.progressive_download_url) ?? string(value.fast_start_progressive_download_url)));
+  const url = selected && (string(selected.progressive_download_url) ?? string(selected.fast_start_progressive_download_url));
+  if (!url || !/^https?:\/\//i.test(url))
+    return null;
+  const start = number(consumption?.audio_asset_start_time_in_ms);
+  const duration = number(consumption?.overlap_duration_in_ms);
+  const clip = start !== null && start >= 0 || duration !== null && duration > 0 ? { start: Math.max(0, start ?? 0) / 1000, ...duration !== null && duration > 0 ? { duration: duration / 1000 } : {} } : undefined;
+  return {
+    filename: filename(`instagram_${code}_audio.m4a`),
+    headers: { "user-agent": browserUserAgent() },
+    id: code,
+    kind: "audio",
+    mime: "audio/mp4",
+    platform: "instagram",
+    url,
+    ...clip && { clip }
+  };
 }
 function instagramCookies(headers, fallback) {
   const getter = headers.getSetCookie;
@@ -3910,6 +3949,10 @@ async function buildAudioSliderVideo(items, options) {
   if (!options || !Number.isFinite(options.delay) || options.delay <= 0) {
     throw new PostfetchError(400, "delay must be a positive finite number of milliseconds");
   }
+  const clip = items.at(-1)?.clip;
+  if (clip && (!Number.isFinite(clip.start) || clip.start < 0 || clip.duration !== undefined && (!Number.isFinite(clip.duration) || clip.duration <= 0))) {
+    throw new PostfetchError(400, "Audio clip must have a non-negative finite start and a positive finite duration");
+  }
   const width = options.width ?? 720;
   const height2 = options.height ?? 1280;
   for (const [name, value] of [["width", width], ["height", height2]]) {
@@ -3932,6 +3975,30 @@ async function buildAudioSliderVideo(items, options) {
       await io.writeFile(path, new Uint8Array(await response.arrayBuffer()));
       paths.push(path);
     }
+    if (clip) {
+      const path = `${directory}/soundtrack.wav`;
+      const trimmed = await io.run(options.ffmpegPath ?? "ffmpeg", [
+        "-nostdin",
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-y",
+        "-ss",
+        String(clip.start),
+        "-i",
+        paths[visuals.length],
+        ...clip.duration === undefined ? [] : ["-t", String(clip.duration)],
+        "-map",
+        "0:a:0",
+        "-c:a",
+        "pcm_s16le",
+        path
+      ]);
+      if (!trimmed.success) {
+        throw new PostfetchError(500, `Audio slider soundtrack trimming failed: ${trimmed.stderr}`);
+      }
+      paths[visuals.length] = path;
+    }
     const probe = await io.run(options.ffprobePath ?? "ffprobe", [
       "-v",
       "error",

package/dist/instagram.d.ts

@@ -1,6 +1,6 @@
 import { type InstagramExtra, type PostMetadata, type PostfetchReason, type ResolveContext, type Json, type PostfetchResult } from "./internal";
 export declare function resolveInstagram(input: ResolveContext): Promise<PostfetchResult>;
-export declare function instagramUnavailableReason(status: number, body: string): PostfetchReason;
+export declare function instagramUnavailableReason(status: number, body: string, code?: string): PostfetchReason;
 export declare function instagramMetadata(media: Json): PostMetadata & {
     extra?: InstagramExtra;
 };

package/dist/internal.d.ts

@@ -14,6 +14,15 @@ export type MediaItem = {
         headers: HeadersInit;
         url: string;
     };
+    /**
+     * Playback segment in seconds when this audio item is a slideshow soundtrack.
+     * Download helpers return the source file; buildAudioSliderVideo trims this
+     * segment before measuring or looping it. Omitted duration plays to the end.
+     */
+    clip?: {
+        start: number;
+        duration?: number;
+    };
     /** Suggested download filename. */
     filename: string;
     /** Headers required to fetch {@link MediaItem.url} from the CDN. */

package/package.json

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

package/src/audio-slider.ts

@@ -23,8 +23,9 @@ const fps = 30;
  * 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 plays in full; when the minimum
- * slideshow duration is longer, it loops and is trimmed to the result.
+ * audio is discarded. The final audio item's optional `clip` selects the attached
+ * segment; otherwise the whole track plays. When the minimum slideshow duration
+ * is longer, that segment/track loops and is trimmed to the result.
  *
  * Each visual gets at least `delay` ms or audio duration / visual count,
  * whichever is longer (rounded up to 30 fps, minimum two frames). Adjacent
@@ -55,6 +56,11 @@ export async function buildAudioSliderVideo(
   if (!options || !Number.isFinite(options.delay) || options.delay <= 0) {
     throw new PostfetchError(400, "delay must be a positive finite number of milliseconds");
   }
+  const clip = items.at(-1)?.clip;
+  if (clip && (!Number.isFinite(clip.start) || clip.start < 0 ||
+      (clip.duration !== undefined && (!Number.isFinite(clip.duration) || clip.duration <= 0)))) {
+    throw new PostfetchError(400, "Audio clip must have a non-negative finite start and a positive finite duration");
+  }
   const width = options.width ?? 720;
   const height = options.height ?? 1280;
   for (const [name, value] of [["width", width], ["height", height]] as const) {
@@ -78,6 +84,19 @@ export async function buildAudioSliderVideo(
       await io.writeFile(path, new Uint8Array(await response.arrayBuffer()));
       paths.push(path);
     }
+    if (clip) {
+      const path = `${directory}/soundtrack.wav`;
+      const trimmed = await io.run(options.ffmpegPath ?? "ffmpeg", [
+        "-nostdin", "-hide_banner", "-loglevel", "error", "-y",
+        "-ss", String(clip.start), "-i", paths[visuals.length],
+        ...(clip.duration === undefined ? [] : ["-t", String(clip.duration)]),
+        "-map", "0:a:0", "-c:a", "pcm_s16le", path,
+      ]);
+      if (!trimmed.success) {
+        throw new PostfetchError(500, `Audio slider soundtrack trimming failed: ${trimmed.stderr}`);
+      }
+      paths[visuals.length] = path;
+    }
     const probe = await io.run(options.ffprobePath ?? "ffprobe", [
       "-v", "error", "-select_streams", "a:0", "-show_entries",
       "stream=duration:format=duration", "-of", "json", paths[visuals.length],

package/src/instagram.ts

@@ -60,9 +60,11 @@ export async function resolveInstagram(input: ResolveContext): Promise<Postfetch
   const code = shortcode(input.url);
   const videoRequired = /\/(?:reel|reels|tv)\//.test(asUrl(input.url).pathname);
   const page = await pageMedia(input.net, code, input.preferredWidth);
+  let mobile: Promise<Json | null> | undefined;
+  const getMobile = () => mobile ??= mobileMedia(input.net, code, input.preferredWidth, page.media);
   const resolvers: Array<() => Promise<Json | null>> = [
     async () => page.media,
-    () => mobileMedia(input.net, code, input.preferredWidth),
+    getMobile,
     () => embedMedia(input.net, code),
     () => graphqlMedia(input.net, code),
   ];
@@ -81,6 +83,18 @@ export async function resolveInstagram(input: ResolveContext): Promise<Postfetch
   if (items.length === 0) {
     throw new Error("Instagram media url not found");
   }
+  // The logged-out page often omits music_metadata altogether. Ask the mobile
+  // endpoint once for that post's soundtrack, retaining the page's visuals and
+  // metadata even when the optional lookup is gated or fails. An explicit null
+  // means there is no soundtrack; a video's audio is already in its MP4.
+  if (soundtrackEligible(items) && !items.some((item) => item.kind === "audio") &&
+      media.music_metadata === undefined && !object(media.clips_metadata)) {
+    const richer = await getMobile().catch(() => null);
+    const samePost = richer && (string(richer.code) ? richer.code === code :
+      string(richer.pk) !== null && string(richer.pk) === string(media.pk));
+    const audio = samePost ? instagramAudio(richer, code) : null;
+    if (audio) items.push(audio);
+  }
   return { archiveFilename: filename(`instagram_${code}.zip`), comments: [], id: code, items, metadata: instagramMetadata(media), platform: "instagram" };
 }
 
@@ -91,7 +105,7 @@ async function instagramUnavailable(net: Net, code: string, pageReason?: Postfet
   const body = response ? await response.text().catch(() => "") : "";
   // The page can identify an age gate even when oembed only reports a generic
   // geoblock_required error with no MIN_AGE_ACCOUNT marker.
-  const reason = pageReason ?? instagramUnavailableReason(response?.status ?? 0, body);
+  const reason = pageReason ?? instagramUnavailableReason(response?.status ?? 0, body, code);
   // Carry the oembed status so an unclassified failure still leaves a raw clue
   // (200 = post is public but no media could be parsed; 429 = throttled; …).
   const probe = response ? `oembed ${response.status}` : "oembed unreachable";
@@ -101,10 +115,11 @@ async function instagramUnavailable(net: Net, code: string, pageReason?: Postfet
 // Classifies why the post is gone from the oembed endpoint, which returns a
 // telling status and body (404 when removed; 429 when throttled; 400 with a
 // MIN_AGE_ACCOUNT block for 18+ accounts) while the media endpoints just come
-// back empty.
-export function instagramUnavailableReason(status: number, body: string): PostfetchReason {
+// back empty. Share links to posts from private accounts carry a long
+// shortcode, and oembed answers those with the same 404 as a removed post.
+export function instagramUnavailableReason(status: number, body: string, code?: string): PostfetchReason {
   if (status === 404) {
-    return "notFound";
+    return code && isPrivateShortcode(code) ? "private" : "notFound";
   }
   if (status === 429) {
     return "rateLimited";
@@ -124,6 +139,12 @@ export function instagramUnavailableReason(status: number, body: string): Postfe
   return "unavailable";
 }
 
+// Public shortcodes are at most 11 characters; private share links append an
+// owner-scoped suffix (for example 39 characters in total).
+function isPrivateShortcode(code: string): boolean {
+  return code.length > 11;
+}
+
 function reasonStatus(reason: PostfetchReason): number {
   switch (reason) {
     case "ageRestricted":
@@ -254,8 +275,8 @@ function searchMedia(node: unknown, code: string): Json | null {
   return null;
 }
 
-async function mobileMedia(net: Net, code: string, preferredWidth: number): Promise<Json | null> {
-  const id = await mediaId(net, code);
+async function mobileMedia(net: Net, code: string, preferredWidth: number, hint?: Json | null): Promise<Json | null> {
+  const id = string(hint?.pk) ?? string(hint?.id) ?? await mediaId(net, code);
   if (!id) {
     return null;
   }
@@ -422,15 +443,46 @@ function mediaItems(media: Json, code: string, preferredWidth: number): MediaIte
     const node = object(edge) && object(edge.node) ? edge.node : null;
     return node ? instagramItem(node, code, index + 1, preferredWidth) : [];
   });
-  if (oldItems.length > 0) {
-    return oldItems;
-  }
   const carousel = Array.isArray(media.carousel_media) ? media.carousel_media.filter(object) : [];
   const newItems = carousel.flatMap((item, index) => instagramItem(item, code, index + 1, preferredWidth));
-  if (newItems.length > 0) {
-    return newItems;
-  }
-  return instagramItem(media, code, null, preferredWidth);
+  const items = oldItems.length > 0 ? oldItems : newItems.length > 0 ? newItems : instagramItem(media, code, null, preferredWidth);
+  const audio = soundtrackEligible(items) ? instagramAudio(media, code) : null;
+  return audio ? [...items, audio] : items;
+}
+
+function soundtrackEligible(items: MediaItem[]): boolean {
+  return items.length > 1 || items[0]?.kind === "image";
+}
+
+// Normalize Instagram's field names to the same trailing audio item used by
+// other resolvers. Consumers can build a slideshow without platform branches.
+function instagramAudio(media: Json, code: string): MediaItem | null {
+  const metadata = object(media.music_metadata) ? media.music_metadata : object(media.clips_metadata) ? media.clips_metadata : null;
+  if (!metadata) return null;
+  const info = object(metadata.music_info) ? metadata.music_info : null;
+  const consumption = info && object(info.music_consumption_info) ? info.music_consumption_info : null;
+  if (consumption?.should_mute_audio === true) return null;
+  const asset = info && object(info.music_asset_info) ? info.music_asset_info : null;
+  const original = object(metadata.original_sound_info) ? metadata.original_sound_info : null;
+  const selected = [asset, original].find((value) => value &&
+    (string(value.progressive_download_url) ?? string(value.fast_start_progressive_download_url)));
+  const url = selected && (string(selected.progressive_download_url) ?? string(selected.fast_start_progressive_download_url));
+  if (!url || !/^https?:\/\//i.test(url)) return null;
+  const start = number(consumption?.audio_asset_start_time_in_ms);
+  const duration = number(consumption?.overlap_duration_in_ms);
+  const clip = (start !== null && start >= 0) || (duration !== null && duration > 0)
+    ? { start: Math.max(0, start ?? 0) / 1000, ...(duration !== null && duration > 0 ? { duration: duration / 1000 } : {}) }
+    : undefined;
+  return {
+    filename: filename(`instagram_${code}_audio.m4a`),
+    headers: { "user-agent": browserUserAgent() },
+    id: code,
+    kind: "audio",
+    mime: "audio/mp4",
+    platform: "instagram",
+    url,
+    ...(clip && { clip }),
+  };
 }
 
 function instagramCookies(headers: Headers, fallback: Record<string, string | null>): string {

package/src/internal.ts

@@ -13,6 +13,12 @@ export type MediaItem = {
    * the bundled remuxer; callers that read `url` directly get the silent video.
    */
   audio?: { headers: HeadersInit; url: string };
+  /**
+   * Playback segment in seconds when this audio item is a slideshow soundtrack.
+   * Download helpers return the source file; buildAudioSliderVideo trims this
+   * segment before measuring or looping it. Omitted duration plays to the end.
+   */
+  clip?: { start: number; duration?: number };
   /** Suggested download filename. */
   filename: string;
   /** Headers required to fetch {@link MediaItem.url} from the CDN. */