feat: find segment with highest integral jump in heatmap

src/cli/args.ts

@@ -2,14 +2,12 @@ export interface CliArgs {
   url?: string;
   output: string;
   format: string;
-  skipStartSeconds: number;
 }
 
 export function parseArgs(): CliArgs {
   const args: CliArgs = {
     output: "./downloads",
     format: "best",
-    skipStartSeconds: 30,
   };
 
   const rawArgs = Bun.argv;
@@ -24,9 +22,6 @@ export function parseArgs(): CliArgs {
     } else if (arg === "-f" || arg === "--format") {
       args.format = nextArg || "best";
       i++;
-    } else if (arg === "-s" || arg === "--skip-start") {
-      args.skipStartSeconds = parseFloat(nextArg || "30");
-      i++;
     } else if (arg === "-h" || arg === "--help") {
       console.log(`YouTube Most Watched Segment Downloader
 
@@ -36,16 +31,13 @@ Arguments:
   <url>              YouTube video URL (required)
 
 Options:
-  -o, --output <dir>      Output directory (default: ./downloads)
+  -o, --output <dir>    Output directory (default: ./downloads)
-  -f, --format <fmt>      Video format (default: best)
+  -f, --format <fmt>    Video format (default: best)
-  -s, --skip-start <sec>  Skip first N seconds (default: 30)
+  -h, --help            Show this help message
-                          Higher values skip more of the intro
-  -h, --help              Show this help message
 
 Examples:
   yt-segments "https://www.youtube.com/watch?v=abc123"
   yt-segments "https://youtu.be/abc123" -o ./videos -f mp4
-  yt-segments "https://www.youtube.com/watch?v=abc123" -s 60
 `);
       process.exit(0);
     } else if (!arg.startsWith("-") && !arg.includes("bun")) {

src/cli/downloader.ts

@@ -6,7 +6,6 @@ export interface DownloadOptions {
   url: string;
   outputDir: string;
   format: string;
-  skipStartSeconds: number;
 }
 
 interface RawHeatmapSegment {
@@ -23,7 +22,7 @@ interface ProcessedSegment {
   start: number;
   end: number;
   intensity: number;
-  integral: number;
+  integralJump: number;
 }
 
 interface VideoInfo {
@@ -143,9 +142,8 @@ function getIntensity(segment: RawHeatmapSegment): number {
   return segment.intensity ?? segment.heat ?? segment.value ?? 0;
 }
 
-function findSegmentByIntegral(
+function findHighestIntegralJump(
-  segments: RawHeatmapSegment[],
+  segments: RawHeatmapSegment[]
-  skipStartSeconds: number
 ): ProcessedSegment | null {
   // Convert to processed format and filter valid segments
   const validSegments = segments
@@ -166,32 +164,25 @@ function findSegmentByIntegral(
     return null;
   }
 
-  // Calculate the primitive (integral) for each segment
+  // Calculate integral jump for each segment (intensity × duration)
-  // The integral represents cumulative watch time contribution
-  let cumulativeIntegral = 0;
   const withIntegral = validSegments.map(seg => {
     const segmentDuration = seg.end - seg.start;
-    const segmentIntegral = seg.intensity * segmentDuration;
+    const integralJump = seg.intensity * segmentDuration;
-    cumulativeIntegral += segmentIntegral;
     return {
       ...seg,
-      integral: cumulativeIntegral,
+      integralJump,
     };
   });
 
-  // Sort by integral value (highest contribution first)
+  // Find the segment with the highest integral jump (biggest bump in the integral)
-  // The integral tells us which segment contributed most to total watch time
+  // This is the segment that contributed most to the total integral
-  withIntegral.sort((a, b) => b.integral - a.integral);
+  return withIntegral.reduce((max, current) => {
-
+    return current.integralJump > max.integralJump ? current : max;
-  // Find the highest integral segment that starts after skipStartSeconds
+  });
-  const candidate = withIntegral.find(seg => seg.start >= skipStartSeconds);
-
-  // If all segments are in the skipped region, return the highest one anyway
-  return candidate || withIntegral[0];
 }
 
 export async function downloadMostWatchedSegment(options: DownloadOptions): Promise<void> {
-  const { url, outputDir, format, skipStartSeconds } = options;
+  const { url, outputDir, format } = options;
 
   // Create output directory if it doesn't exist
   if (!existsSync(outputDir)) {
@@ -218,8 +209,8 @@ export async function downloadMostWatchedSegment(options: DownloadOptions): Prom
 
   console.log(`\nHeatmap data found: ${info.heatmap.length} segments`);
 
-  // Find the segment with highest integral (using primitive function)
+  // Find segment with highest integral jump (biggest bump)
-  const topSegment = findSegmentByIntegral(info.heatmap, skipStartSeconds);
+  const topSegment = findHighestIntegralJump(info.heatmap);
 
   if (!topSegment) {
     console.log("No valid segments found. Downloading full video...");
@@ -228,11 +219,11 @@ export async function downloadMostWatchedSegment(options: DownloadOptions): Prom
     return;
   }
 
-  console.log(`\nSegment with highest integral (primitive):`);
+  console.log(`\nSegment with highest integral jump:`);
   console.log(`  Time: ${formatTime(topSegment.start)} - ${formatTime(topSegment.end)}`);
   console.log(`  Duration: ${formatTime(topSegment.end - topSegment.start)}`);
   console.log(`  Intensity: ${(topSegment.intensity * 100).toFixed(1)}%`);
-  console.log(`  Integral: ${topSegment.integral.toFixed(4)}`);
+  console.log(`  Integral Jump: ${topSegment.integralJump.toFixed(4)}`);
 
   // Download the segment
   const outputPath = join(outputDir, `${safeTitle}_most_watched.%(ext)s`);
@@ -243,13 +234,12 @@ export async function downloadMostWatchedSegment(options: DownloadOptions): Prom
   // Save segment info
   const segmentInfoPath = join(outputDir, `${safeTitle}_segment_info.txt`);
   const segmentInfo = `# ${info.title}\n\n` +
-    `Most watched segment (highest integral from YouTube heatmap):\n` +
+    `Segment with highest integral jump (biggest bump in heatmap):\n` +
     `  Start: ${formatTime(topSegment.start)} (${topSegment.start.toFixed(1)}s)\n` +
     `  End: ${formatTime(topSegment.end)} (${topSegment.end.toFixed(1)}s)\n` +
     `  Duration: ${formatTime(topSegment.end - topSegment.start)}\n` +
     `  Intensity: ${(topSegment.intensity * 100).toFixed(1)}%\n` +
-    `  Integral: ${topSegment.integral.toFixed(4)}\n\n` +
+    `  Integral Jump: ${topSegment.integralJump.toFixed(4)}\n`;
-    `Note: This segment had the highest integral value (cumulative watch contribution).\n`;
 
   writeFileSync(segmentInfoPath, segmentInfo);
   console.log(`\nSegment info saved to: ${segmentInfoPath}`);

src/cli/index.ts

@@ -10,17 +10,15 @@ async function main() {
     console.error("Error: YouTube URL is required");
     console.log("Usage: yt-segments <url> [options]");
     console.log("Options:");
-    console.log("  -o, --output <dir>      Output directory (default: ./downloads)");
+    console.log("  -o, --output <dir>    Output directory (default: ./downloads)");
-    console.log("  -f, --format <fmt>      Video format (default: best)");
+    console.log("  -f, --format <fmt>    Video format (default: best)");
-    console.log("  -s, --skip-start <sec>  Skip first N seconds (default: 30)");
+    console.log("  -h, --help            Show help");
-    console.log("  -h, --help              Show help");
     process.exit(1);
   }
 
   console.log(`Downloading most watched segment from: ${args.url}`);
   console.log(`Output directory: ${args.output}`);
   console.log(`Format: ${args.format}`);
-  console.log(`Skip first ${args.skipStartSeconds} seconds`);
   console.log("");
 
   try {
@@ -28,7 +26,6 @@ async function main() {
       url: args.url,
       outputDir: args.output,
       format: args.format,
-      skipStartSeconds: args.skipStartSeconds,
     });
   } catch (error) {
     console.error("Error:", error instanceof Error ? error.message : error);