@storyteller-platform/align 0.1.47 → 0.1.48

package/dist/common/ffmpeg.cjs

@@ -28,8 +28,11 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var ffmpeg_exports = {};
 __export(ffmpeg_exports, {
+  MP3_CBR_BITRATES: () => MP3_CBR_BITRATES,
   getTrackDuration: () => getTrackDuration,
   getTrackInfo: () => getTrackInfo,
+  isVbrMp3: () => isVbrMp3,
+  selectCbrBitrate: () => selectCbrBitrate,
   splitFile: () => splitFile,
   transcodeFile: () => transcodeFile
 });
@@ -74,6 +77,52 @@ async function getTrackDuration(path, logger) {
   const info = await getTrackInfo(path, logger);
   return info["duration"];
 }
+const MP3_CBR_BITRATES = [
+  64e3,
+  8e4,
+  96e3,
+  112e3,
+  128e3,
+  16e4,
+  192e3,
+  224e3,
+  256e3,
+  32e4
+];
+const VBR_PROBE_PACKET_COUNT = 50;
+const MP3_CBR_MAX_DISTINCT_SIZES = 2;
+const VBR_PROBE_MIN_SEEKABLE_SECONDS = 180;
+async function probeAudioDuration(path) {
+  const stdout = await execCmd(
+    `ffprobe -i ${(0, import_shell.quotePath)(path)} -v error -show_entries format=duration -output_format json`
+  );
+  const { format } = JSON.parse(stdout);
+  const duration = Number(format?.duration);
+  return Number.isFinite(duration) && duration > 0 ? duration : null;
+}
+async function probePacketSizes(path, startSeconds) {
+  const interval = startSeconds > 0 ? `${startSeconds}%+#${VBR_PROBE_PACKET_COUNT}` : `%+#${VBR_PROBE_PACKET_COUNT}`;
+  const stdout = await execCmd(
+    `ffprobe -i ${(0, import_shell.quotePath)(path)} -v error -select_streams a:0 -read_intervals "${interval}" -show_entries packet=size -output_format json`
+  );
+  const { packets } = JSON.parse(stdout);
+  return (packets ?? []).map((packet) => Number(packet.size)).filter((size) => Number.isFinite(size) && size > 0);
+}
+async function isVbrMp3(path) {
+  if ((0, import_node_path.extname)(path).toLowerCase() !== ".mp3") return false;
+  const duration = await probeAudioDuration(path);
+  const startSeconds = duration && duration > VBR_PROBE_MIN_SEEKABLE_SECONDS ? Math.floor(duration / 3) : 0;
+  let sizes = await probePacketSizes(path, startSeconds);
+  if (sizes.length === 0 && startSeconds > 0) {
+    sizes = await probePacketSizes(path, 0);
+  }
+  if (sizes.length === 0) return false;
+  const distinctSizes = new Set(sizes).size;
+  return distinctSizes > MP3_CBR_MAX_DISTINCT_SIZES;
+}
+function selectCbrBitrate(averageBitrate) {
+  return MP3_CBR_BITRATES.find((tier) => tier >= averageBitrate) ?? MP3_CBR_BITRATES.at(-1) ?? MP3_CBR_BITRATES[0];
+}
 function parseTrackInfo(format) {
   return {
     filename: format.filename,
@@ -136,15 +185,16 @@ async function constructExtractCoverArtCommand(source, destExtension) {
   ];
   return `${command} ${args.join(" ")} | `;
 }
-function commonFfmpegArguments(sourceExtension, destExtension, codec, bitrate) {
+function commonFfmpegArguments(options) {
+  const { sourceExtension, destExtension, codec, bitrate } = options;
   const args = ["-vn"];
   if (codec) {
-    args.push(
-      "-c:a",
-      codec,
-      ...codec === "libopus" ? ["-b:a", bitrate && /^\d+[kK]$/i.test(bitrate) ? bitrate : "32K"] : [],
-      ...codec === "libmp3lame" && bitrate ? ["-q:a", bitrate] : []
-    );
+    args.push("-c:a", codec);
+    if (codec === "libopus") {
+      args.push("-b:a", bitrate && /^\d+[kK]$/i.test(bitrate) ? bitrate : "32K");
+    } else if (codec === "libmp3lame" && bitrate) {
+      args.push("-b:a", bitrate);
+    }
   } else if ((0, import_mime.areSameType)(sourceExtension, destExtension) || destExtension == ".mp4") {
     args.push("-c:a", "copy");
   }
@@ -168,12 +218,12 @@ async function splitFile(input, output, start, end, encoding, signal, logger) {
     end,
     "-i",
     (0, import_shell.quotePath)(input),
-    ...commonFfmpegArguments(
-      (0, import_node_path.extname)(input),
-      (0, import_node_path.extname)(output),
-      encoding?.codec ?? null,
-      encoding?.bitrate ?? null
-    ),
+    ...commonFfmpegArguments({
+      sourceExtension: (0, import_node_path.extname)(input),
+      destExtension: (0, import_node_path.extname)(output),
+      codec: encoding?.codec ?? null,
+      bitrate: encoding?.bitrate ?? null
+    }),
     (0, import_shell.quotePath)(output)
   ];
   const coverArtCommand = await constructExtractCoverArtCommand(
@@ -203,12 +253,12 @@ async function transcodeFile(input, output, encoding, signal, logger) {
     "-nostdin",
     "-i",
     (0, import_shell.quotePath)(input),
-    ...commonFfmpegArguments(
-      (0, import_node_path.extname)(input),
-      (0, import_node_path.extname)(output),
-      encoding?.codec ?? null,
-      encoding?.bitrate ?? null
-    ),
+    ...commonFfmpegArguments({
+      sourceExtension: (0, import_node_path.extname)(input),
+      destExtension: (0, import_node_path.extname)(output),
+      codec: encoding?.codec ?? null,
+      bitrate: encoding?.bitrate ?? null
+    }),
     (0, import_shell.quotePath)(output)
   ];
   const coverArtCommand = await constructExtractCoverArtCommand(
@@ -224,8 +274,11 @@ async function transcodeFile(input, output, encoding, signal, logger) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  MP3_CBR_BITRATES,
   getTrackDuration,
   getTrackInfo,
+  isVbrMp3,
+  selectCbrBitrate,
   splitFile,
   transcodeFile
 });

package/dist/common/ffmpeg.d.cts

@@ -3,6 +3,22 @@ import { AudioEncoding } from '../process/AudioEncoding.cjs';
 
 declare const getTrackInfo: (path: string, logger?: Logger) => Promise<TrackInfo>;
 declare function getTrackDuration(path: string, logger?: Logger): Promise<number>;
+/**
+ * CBR bitrates (bps) offered for MP3 output, roughly matching LAME -V9..-V0
+ */
+declare const MP3_CBR_BITRATES: readonly [64000, 80000, 96000, 112000, 128000, 160000, 192000, 224000, 256000, 320000];
+/**
+ * Detect whether an MP3 file uses a variable bitrate
+ * Does this by sampling the first few packets and checking if the sizes are different
+ * CBR MP3 files will have the same packet size for the entire file
+ *
+ * Can't really trust the reported bitrate to tell CBR from VBR
+ * LAME writes a Xing header carrying the *average* bitrate,
+ * which ffprobe surfaces as a normal per-stream `bit_rate`,
+ * so a VBR file looks identical to a CBR one by that measure.
+ */
+declare function isVbrMp3(path: string): Promise<boolean>;
+declare function selectCbrBitrate(averageBitrate: number): number;
 type TrackInfo = {
     filename: string;
     nbStreams: number;
@@ -30,4 +46,4 @@ type TrackInfo = {
 declare function splitFile(input: string, output: string, start: number, end: number, encoding?: AudioEncoding | null, signal?: AbortSignal | null, logger?: Logger | null): Promise<boolean>;
 declare function transcodeFile(input: string, output: string, encoding?: AudioEncoding | null, signal?: AbortSignal | null, logger?: Logger | null): Promise<true | undefined>;
 
-export { getTrackDuration, getTrackInfo, splitFile, transcodeFile };
+export { MP3_CBR_BITRATES, getTrackDuration, getTrackInfo, isVbrMp3, selectCbrBitrate, splitFile, transcodeFile };

package/dist/common/ffmpeg.d.ts

@@ -3,6 +3,22 @@ import { AudioEncoding } from '../process/AudioEncoding.js';
 
 declare const getTrackInfo: (path: string, logger?: Logger) => Promise<TrackInfo>;
 declare function getTrackDuration(path: string, logger?: Logger): Promise<number>;
+/**
+ * CBR bitrates (bps) offered for MP3 output, roughly matching LAME -V9..-V0
+ */
+declare const MP3_CBR_BITRATES: readonly [64000, 80000, 96000, 112000, 128000, 160000, 192000, 224000, 256000, 320000];
+/**
+ * Detect whether an MP3 file uses a variable bitrate
+ * Does this by sampling the first few packets and checking if the sizes are different
+ * CBR MP3 files will have the same packet size for the entire file
+ *
+ * Can't really trust the reported bitrate to tell CBR from VBR
+ * LAME writes a Xing header carrying the *average* bitrate,
+ * which ffprobe surfaces as a normal per-stream `bit_rate`,
+ * so a VBR file looks identical to a CBR one by that measure.
+ */
+declare function isVbrMp3(path: string): Promise<boolean>;
+declare function selectCbrBitrate(averageBitrate: number): number;
 type TrackInfo = {
     filename: string;
     nbStreams: number;
@@ -30,4 +46,4 @@ type TrackInfo = {
 declare function splitFile(input: string, output: string, start: number, end: number, encoding?: AudioEncoding | null, signal?: AbortSignal | null, logger?: Logger | null): Promise<boolean>;
 declare function transcodeFile(input: string, output: string, encoding?: AudioEncoding | null, signal?: AbortSignal | null, logger?: Logger | null): Promise<true | undefined>;
 
-export { getTrackDuration, getTrackInfo, splitFile, transcodeFile };
+export { MP3_CBR_BITRATES, getTrackDuration, getTrackInfo, isVbrMp3, selectCbrBitrate, splitFile, transcodeFile };

package/dist/common/ffmpeg.js

@@ -39,6 +39,52 @@ async function getTrackDuration(path, logger) {
   const info = await getTrackInfo(path, logger);
   return info["duration"];
 }
+const MP3_CBR_BITRATES = [
+  64e3,
+  8e4,
+  96e3,
+  112e3,
+  128e3,
+  16e4,
+  192e3,
+  224e3,
+  256e3,
+  32e4
+];
+const VBR_PROBE_PACKET_COUNT = 50;
+const MP3_CBR_MAX_DISTINCT_SIZES = 2;
+const VBR_PROBE_MIN_SEEKABLE_SECONDS = 180;
+async function probeAudioDuration(path) {
+  const stdout = await execCmd(
+    `ffprobe -i ${quotePath(path)} -v error -show_entries format=duration -output_format json`
+  );
+  const { format } = JSON.parse(stdout);
+  const duration = Number(format?.duration);
+  return Number.isFinite(duration) && duration > 0 ? duration : null;
+}
+async function probePacketSizes(path, startSeconds) {
+  const interval = startSeconds > 0 ? `${startSeconds}%+#${VBR_PROBE_PACKET_COUNT}` : `%+#${VBR_PROBE_PACKET_COUNT}`;
+  const stdout = await execCmd(
+    `ffprobe -i ${quotePath(path)} -v error -select_streams a:0 -read_intervals "${interval}" -show_entries packet=size -output_format json`
+  );
+  const { packets } = JSON.parse(stdout);
+  return (packets ?? []).map((packet) => Number(packet.size)).filter((size) => Number.isFinite(size) && size > 0);
+}
+async function isVbrMp3(path) {
+  if (extname(path).toLowerCase() !== ".mp3") return false;
+  const duration = await probeAudioDuration(path);
+  const startSeconds = duration && duration > VBR_PROBE_MIN_SEEKABLE_SECONDS ? Math.floor(duration / 3) : 0;
+  let sizes = await probePacketSizes(path, startSeconds);
+  if (sizes.length === 0 && startSeconds > 0) {
+    sizes = await probePacketSizes(path, 0);
+  }
+  if (sizes.length === 0) return false;
+  const distinctSizes = new Set(sizes).size;
+  return distinctSizes > MP3_CBR_MAX_DISTINCT_SIZES;
+}
+function selectCbrBitrate(averageBitrate) {
+  return MP3_CBR_BITRATES.find((tier) => tier >= averageBitrate) ?? MP3_CBR_BITRATES.at(-1) ?? MP3_CBR_BITRATES[0];
+}
 function parseTrackInfo(format) {
   return {
     filename: format.filename,
@@ -101,15 +147,16 @@ async function constructExtractCoverArtCommand(source, destExtension) {
   ];
   return `${command} ${args.join(" ")} | `;
 }
-function commonFfmpegArguments(sourceExtension, destExtension, codec, bitrate) {
+function commonFfmpegArguments(options) {
+  const { sourceExtension, destExtension, codec, bitrate } = options;
   const args = ["-vn"];
   if (codec) {
-    args.push(
-      "-c:a",
-      codec,
-      ...codec === "libopus" ? ["-b:a", bitrate && /^\d+[kK]$/i.test(bitrate) ? bitrate : "32K"] : [],
-      ...codec === "libmp3lame" && bitrate ? ["-q:a", bitrate] : []
-    );
+    args.push("-c:a", codec);
+    if (codec === "libopus") {
+      args.push("-b:a", bitrate && /^\d+[kK]$/i.test(bitrate) ? bitrate : "32K");
+    } else if (codec === "libmp3lame" && bitrate) {
+      args.push("-b:a", bitrate);
+    }
   } else if (areSameType(sourceExtension, destExtension) || destExtension == ".mp4") {
     args.push("-c:a", "copy");
   }
@@ -133,12 +180,12 @@ async function splitFile(input, output, start, end, encoding, signal, logger) {
     end,
     "-i",
     quotePath(input),
-    ...commonFfmpegArguments(
-      extname(input),
-      extname(output),
-      encoding?.codec ?? null,
-      encoding?.bitrate ?? null
-    ),
+    ...commonFfmpegArguments({
+      sourceExtension: extname(input),
+      destExtension: extname(output),
+      codec: encoding?.codec ?? null,
+      bitrate: encoding?.bitrate ?? null
+    }),
     quotePath(output)
   ];
   const coverArtCommand = await constructExtractCoverArtCommand(
@@ -168,12 +215,12 @@ async function transcodeFile(input, output, encoding, signal, logger) {
     "-nostdin",
     "-i",
     quotePath(input),
-    ...commonFfmpegArguments(
-      extname(input),
-      extname(output),
-      encoding?.codec ?? null,
-      encoding?.bitrate ?? null
-    ),
+    ...commonFfmpegArguments({
+      sourceExtension: extname(input),
+      destExtension: extname(output),
+      codec: encoding?.codec ?? null,
+      bitrate: encoding?.bitrate ?? null
+    }),
     quotePath(output)
   ];
   const coverArtCommand = await constructExtractCoverArtCommand(
@@ -188,8 +235,11 @@ async function transcodeFile(input, output, encoding, signal, logger) {
   return true;
 }
 export {
+  MP3_CBR_BITRATES,
   getTrackDuration,
   getTrackInfo,
+  isVbrMp3,
+  selectCbrBitrate,
   splitFile,
   transcodeFile
 };

package/dist/process/processAudiobook.cjs

@@ -126,6 +126,27 @@ async function processAudiobook(input, output, options) {
   );
   return timing;
 }
+async function resolveVbrEncoding(filepath, userEncoding, logger) {
+  if (userEncoding?.codec && userEncoding.codec !== "libmp3lame") {
+    return userEncoding;
+  }
+  const sourceIsMp3 = (0, import_node_path.extname)(filepath).toLowerCase() === ".mp3";
+  if (!userEncoding?.codec && !sourceIsMp3) {
+    return userEncoding;
+  }
+  if (!userEncoding?.codec && !await (0, import_ffmpeg.isVbrMp3)(filepath)) {
+    return userEncoding;
+  }
+  const trackInfo = await (0, import_ffmpeg.getTrackInfo)(filepath, logger ?? void 0);
+  const targetBitrate = (0, import_ffmpeg.selectCbrBitrate)(trackInfo.bitRate);
+  logger?.info(
+    `Forcing CBR MP3 for ${filepath} (avg ${trackInfo.bitRate}bps) at ${targetBitrate / 1e3}k`
+  );
+  return {
+    codec: "libmp3lame",
+    bitrate: `${targetBitrate / 1e3}k`
+  };
+}
 async function processFile(input, output, prefix, options) {
   var _stack = [];
   try {
@@ -144,13 +165,26 @@ async function processFile(input, output, prefix, options) {
       options.signal,
       options.logger
     );
+    const vbrEncodings = /* @__PURE__ */ new Map();
+    const uniqueFilepaths = [...new Set(ranges.map((r) => r.filepath))];
+    await Promise.all(
+      uniqueFilepaths.map(async (filepath) => {
+        const result = await resolveVbrEncoding(
+          filepath,
+          options.encoding,
+          options.logger
+        );
+        vbrEncodings.set(filepath, result);
+      })
+    );
     await Promise.all(
       ranges.map(async (range, index) => {
         var _stack2 = [];
         try {
+          const effectiveEncoding = vbrEncodings.has(range.filepath) ? vbrEncodings.get(range.filepath) : options.encoding;
           const outputExtension = determineExtension(
             range.filepath,
-            options.encoding?.codec
+            effectiveEncoding?.codec
           );
           const outputFilename = `${prefix}${(index + 1).toString().padStart(5, "0")}${outputExtension}`;
           const outputFilepath = (0, import_node_path.join)(output, outputFilename);
@@ -168,7 +202,7 @@ async function processFile(input, output, prefix, options) {
                 outputFilepath,
                 range.start,
                 range.end,
-                options.encoding,
+                effectiveEncoding,
                 options.signal,
                 options.logger
               );

package/dist/process/processAudiobook.js

@@ -19,7 +19,12 @@ import {
   createAggregator,
   createTiming
 } from "@storyteller-platform/ghost-story";
-import { splitFile } from "../common/ffmpeg.js";
+import {
+  getTrackInfo,
+  isVbrMp3,
+  selectCbrBitrate,
+  splitFile
+} from "../common/ffmpeg.js";
 import { getSafeChapterRanges } from "./ranges.js";
 async function processAudiobook(input, output, options) {
   const timing = createAggregator();
@@ -73,6 +78,27 @@ async function processAudiobook(input, output, options) {
   );
   return timing;
 }
+async function resolveVbrEncoding(filepath, userEncoding, logger) {
+  if (userEncoding?.codec && userEncoding.codec !== "libmp3lame") {
+    return userEncoding;
+  }
+  const sourceIsMp3 = extname(filepath).toLowerCase() === ".mp3";
+  if (!userEncoding?.codec && !sourceIsMp3) {
+    return userEncoding;
+  }
+  if (!userEncoding?.codec && !await isVbrMp3(filepath)) {
+    return userEncoding;
+  }
+  const trackInfo = await getTrackInfo(filepath, logger ?? void 0);
+  const targetBitrate = selectCbrBitrate(trackInfo.bitRate);
+  logger?.info(
+    `Forcing CBR MP3 for ${filepath} (avg ${trackInfo.bitRate}bps) at ${targetBitrate / 1e3}k`
+  );
+  return {
+    codec: "libmp3lame",
+    bitrate: `${targetBitrate / 1e3}k`
+  };
+}
 async function processFile(input, output, prefix, options) {
   var _stack = [];
   try {
@@ -91,13 +117,26 @@ async function processFile(input, output, prefix, options) {
       options.signal,
       options.logger
     );
+    const vbrEncodings = /* @__PURE__ */ new Map();
+    const uniqueFilepaths = [...new Set(ranges.map((r) => r.filepath))];
+    await Promise.all(
+      uniqueFilepaths.map(async (filepath) => {
+        const result = await resolveVbrEncoding(
+          filepath,
+          options.encoding,
+          options.logger
+        );
+        vbrEncodings.set(filepath, result);
+      })
+    );
     await Promise.all(
       ranges.map(async (range, index) => {
         var _stack2 = [];
         try {
+          const effectiveEncoding = vbrEncodings.has(range.filepath) ? vbrEncodings.get(range.filepath) : options.encoding;
           const outputExtension = determineExtension(
             range.filepath,
-            options.encoding?.codec
+            effectiveEncoding?.codec
           );
           const outputFilename = `${prefix}${(index + 1).toString().padStart(5, "0")}${outputExtension}`;
           const outputFilepath = join(output, outputFilename);
@@ -115,7 +154,7 @@ async function processFile(input, output, prefix, options) {
                 outputFilepath,
                 range.start,
                 range.end,
-                options.encoding,
+                effectiveEncoding,
                 options.signal,
                 options.logger
               );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storyteller-platform/align",
-  "version": "0.1.47",
+  "version": "0.1.48",
   "description": "A library and CLI for automatically aligning audiobooks and EPUBs to produce Media Overlays",
   "author": "Shane Friedman",
   "license": "MIT",
@@ -71,7 +71,7 @@
     "@optique/run": "^0.10.7",
     "@readium/shared": "^2.2.0",
     "@storyteller-platform/audiobook": "^0.4.1",
-    "@storyteller-platform/epub": "^0.6.1",
+    "@storyteller-platform/epub": "^0.6.2",
     "@storyteller-platform/ghost-story": "^0.1.11",
     "@storyteller-platform/transliteration": "^3.1.2",
     "chalk": "^5.4.1",