mediasnacks 0.18.2 → 0.19.1

package/.zsh/completions/_mediasnacks

@@ -8,7 +8,8 @@ _mediasnacks_commands=(
   'edgespic:Extracts first and last frames'
   'gif:Video to GIF'
   
-  'dropdups:Removes duplicate frames in a video'
+  'detectdups:Detects sequentially duplicate frames in a video'
+  'dropdups:Removes sequentially duplicate frames in a video'
   'framediff:ffplay with a filter for diffing adjacent frames'
   'hev1tohvc1:Fixes video thumbnails not rendering in macOS Finder'
   'moov2front:Rearranges metadata for fast-start streaming'
@@ -38,7 +39,7 @@ fi
 
 local cmd="$words[2]"
 case "$cmd" in
-	avif|resize|sqcrop|moov2front|dropdups|edgespic|seqcheck|hev1tohvc1|framediff|vdiff|vconcat|vsplit|vtrim|dlaudio|dlvideo|unemoji|rmcover|curltime|gif|flattendir|prores)
+	avif|resize|sqcrop|moov2front|detectdups|dropdups|edgespic|seqcheck|hev1tohvc1|framediff|vdiff|vconcat|vsplit|vtrim|dlaudio|dlvideo|unemoji|rmcover|curltime|gif|flattendir|prores)
 		_files
 		;;
 	qdir)

package/README.md

@@ -34,7 +34,8 @@ mediasnacks <command> <args>
 - `gif`: Video to GIF
 
 
-- `dropdups` Removes duplicate frames in a video
+- `detectdups` Detects sequentially duplicate frames in a video
+- `dropdups` Removes sequentially duplicate frames in a video
 - `framediff`: Plays a video of adjacent frames diff
 - `hev1tohvc1`: Fixes video thumbnails not rendering in macOS Finder
 - `moov2front` Rearranges .mov and .mp4 metadata for fast-start streaming

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mediasnacks",
-  "version": "0.18.2",
+  "version": "0.19.1",
   "description": "Utilities for optimizing and preparing videos and images",
   "license": "MIT",
   "author": "Eric Fortis",

package/src/avif.js

@@ -7,10 +7,12 @@ import { replaceExt, lstat } from './utils/fs-utils.js'
 import { ffmpeg, assertUserHasFFmpeg } from './utils/ffmpeg.js'
 
 
-const USAGE = `
-Usage: mediasnacks avif [-y | --overwrite] [--output-dir=<dir>] <images> 
+const MAN = `
+SYNOPSIS
+  mediasnacks avif [-y | --overwrite] [--output-dir=<dir>] <images> 
 
-Converts images to AVIF.
+DESCRIPTION
+ Converts images to AVIF.
 `.trim()
 
 
@@ -24,7 +26,7 @@ async function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}
 

package/src/cli.js

@@ -14,6 +14,7 @@ const COMMANDS = {
 	edgespic: ['edgespic.js', 'Extracts first and last frames'],
 	gif: ['gif.sh', 'Video to GIF\n'],
 
+	detectdups: ['detectdups.js', 'Detects duplicate frames in a video'],
 	dropdups: ['dropdups.js', 'Removes duplicate frames in a video'],
 	framediff: ['framediff.sh', 'Plays a video of adjacent frames diff'],
 	hev1tohvc1: ['hev1tohvc1.js', 'Fixes video thumbnails not rendering in macOS Finder '],
@@ -37,12 +38,13 @@ const COMMANDS = {
 	curltime: ['curltime.sh', 'Measures request response timings'],
 }
 
-const USAGE = `
-Usage: mediasnacks <command> <args>
+const MAN = `
+SYNOPSIS
+  mediasnacks <command> <args>
 
-Commands:
+COMMANDS
 ${Object.entries(COMMANDS).map(([cmd, [, title]]) =>
-	`   ${styleText('bold', cmd.padEnd(12, ' '))}\t${title}`).join('\n')}
+	`  ${styleText('bold', cmd.padEnd(12, ' '))}\t${title}`).join('\n')}
 `.trim()
 
 
@@ -53,12 +55,12 @@ if (opt === '-v' || opt === '--version') {
 	process.exit(0)
 }
 if (opt === '-h' || opt === '--help') {
-	console.log(USAGE)
+	console.log(MAN)
 	process.exit(0)
 }
 
 if (!opt) {
-	console.log(USAGE)
+	console.log(MAN)
 	process.exit(1)
 }
 if (!Object.hasOwn(COMMANDS, opt)) {

package/src/detectdups.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+import { parseOptions } from './utils/parseOptions.js'
+import { ffmpeg, assertUserHasFFmpeg, videoAttrs } from './utils/ffmpeg.js'
+
+
+const MAN = `
+Usage: mediasnacks detectdups [options] <video>
+
+Detects sequentially duplicate frames in a video and prints a histogram of their distance.
+
+EXAMPLES
+  Peak at N=2, means that every other frame is repeated, such as in a 
+  video that was converted from 30 to 60fps without interpolation.
+
+  Peak at N=6, means that the 6th frame in a sequence is repeated.
+  For instance, a video converted from 25 to 30fps, or 50 to 60fps.
+
+OPTIONS
+  -s, --seek <sec>      Video start time for detection
+  -d, --duration <sec>  Analyze this many seconds of video
+  -v, --verbose
+  -h, --help
+  
+SEE ALSO
+  mediasnacks framediff
+`.trim()
+
+
+async function main() {
+	await assertUserHasFFmpeg()
+
+	const { values, files } = await parseOptions({
+		seek: { short: 's', type: 'string', },
+		duration: { short: 'd', type: 'string' },
+		help: { short: 'h', type: 'boolean' }
+	})
+
+	if (values.help) {
+		console.log(MAN)
+		process.exit(0)
+	}
+
+	if (files.length !== 1)
+		throw new Error('Invalid input file. One video file must be specified. See mediasnacks detectdups --help')
+
+	const v = await videoAttrs(files[0])
+
+	if (v.codec_type !== 'video')
+		throw new Error('Invalid input file. Must be a video.')
+
+	const vDur = Number(v.duration)
+
+	const seek = values.seek
+		? Number(values.seek)
+		: vDur > 60 ? 20 : 0
+
+	const duration = values.duration
+		? Number(values.duration)
+		: vDur > 60 ? 20 : vDur
+
+	if (isNaN(seek) || seek < 0)
+		throw new Error(`Invalid --seek value: ${values.seek}`)
+
+	if (isNaN(duration) || duration < 1)
+		throw new Error(`Invalid --duration value: ${values.duration}`)
+
+	if ((seek + duration) > vDur)
+		throw new Error(`Invalid analysis range. Exceeds video duration: ${vDur}`)
+
+
+	const dups = await detectDuplicateFramesNums(files[0], seek, duration)
+	analyze(dups, seek, duration)
+}
+
+async function detectDuplicateFramesNums(video, seek, duration) {
+	const { stderr } = await ffmpeg([
+		'-v', 'info',
+		'-stats',
+		'-ss', seek,
+		'-t', duration,
+		'-i', video,
+		'-vf', [
+			'scale=320:-1',
+			'tblend=all_mode=difference',
+			'format=gray',
+			'showinfo',
+		].join(','),
+		'-f', 'null', '-',
+	])
+
+	const reBlackFramesNum = /n:\s*(\d+).*?mean:\[0]/
+	const dupFrames = []
+	for (const line of stderr.split('\n')) {
+		const match = line.match(reBlackFramesNum)
+		if (match)
+			dupFrames.push(Number(match[1]))
+	}
+	return dupFrames
+}
+
+function analyze(dup_frames, seek, duration) {
+	const histogram = {}
+	for (let i = 1; i < dup_frames.length; i++) {
+		const diff = dup_frames[i] - dup_frames[i - 1]
+		histogram[diff] = (histogram[diff] || 0) + 1
+	}
+	console.log(JSON.stringify({
+		analyzed_region: {
+			start_sec: seek,
+			end_sec: seek + duration
+		},
+		histogram
+	}, null, 2))
+}
+
+main().catch(err => {
+	console.error(err.message || err)
+	process.exit(1)
+})

package/src/dropdups.js

@@ -17,12 +17,14 @@ const PRORES_PROFILES = {
 const PROFILE = PRORES_PROFILES.hq
 
 
-const USAGE = `
-Usage: mediasnacks dropdups [-n <bad-frame-number>] <video>
+const MAN = `
+SYNOPSIS
+  mediasnacks dropdups [-n <bad-frame-number>] <video>
 
-Removes duplicate frames and outputs ProRes 422 HQ.
+DESCRIPTION
+  Removes sequentially duplicate frames and outputs ProRes 422 HQ.
 
-Options:
+OPTIONS
   -n, --bad-frame-number <n>  Known frame interval to drop.
 		         (default: n=0) auto-detects repeated frames (slower)
              Ex.A: Use n=2 when every other frame is repeated.
@@ -40,7 +42,7 @@ async function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}
 

package/src/edgespic.js

@@ -7,15 +7,17 @@ import { parseOptions } from './utils/parseOptions.js'
 import { ffmpeg, videoAttrs, assertUserHasFFmpeg } from './utils/ffmpeg.js'
 
 
-const USAGE = `
-Usage: mediasnacks edgespic [--width=<num>] <files>
+const MAN = `
+SYNOPSIS
+  mediasnacks edgespic [--width=<num>] <files>
 
-Extracts the first and last frames from each video and saves them to the 'edgepics/' subfolder.
---width defaults to 640px and The aspect ratio is preserved.
+DESCRIPTION
+  Extracts the first and last frames from each video and saves them to the 'edgepics/' subfolder.
+  --width defaults to 640px and The aspect ratio is preserved.
 
-Example:
-    mediasnacks edgespic --width 800 *.mov
-    mediasnacks edgespic -w 600 'videos/**/*.mp4'
+EXAMPLES
+  mediasnacks edgespic --width 800 *.mov
+  mediasnacks edgespic -w 600 'videos/**/*.mp4'
 `.trim()
 
 
@@ -28,7 +30,7 @@ async function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}
 

package/src/framediff.sh

@@ -1,8 +1,23 @@
 #!/bin/sh
 
-# Plays a video with a filter for diffing adjacent frames.
-# I use this for finding repeated frames. For example, you’ll see 
-# a black frame if two consecutive frames are almost similar.
+
+if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+/bin/cat << EOF
+SYNOPSIS
+  mediasnacks framediff <video>
+
+DESCRIPTION
+  Runs FFplay with a video filter for diffing adjacent frames. Useful for
+  finding duplicate frames, which will show up a a black frame.
+
+TIPS
+  Hit [s] to step frame-by-frame.
+
+SEE ALSO
+  mediasnacks detectdups, ffplay(1)
+EOF
+  exit 0
+fi
 
 ffplay -v error "$1" -vf "
     tblend=all_mode=difference,

package/src/hev1tohvc1.js

@@ -5,12 +5,14 @@ import { uniqueFilenameFor, overwrite } from './utils/fs-utils.js'
 import { videoAttrs, ffmpeg, assertUserHasFFmpeg } from './utils/ffmpeg.js'
 
 
-const USAGE = `
-Usage: mediasnacks hev1tohvc1 <videos>
-
-This program fixes video thumbnails not rendering in macOS
-Finder, and fixes video not importable in Final Cut Pro. That’s done 
-by changing the container’s sample entry code from HEV1 to HVC1.
+const MAN = `
+SYNOPSIS
+  mediasnacks hev1tohvc1 <videos>
+
+DESCRIPTION
+  This program fixes video thumbnails not rendering in macOS
+  Finder, and fixes video not importable in Final Cut Pro. That’s done 
+  by changing the container’s sample entry code from HEV1 to HVC1.
 `.trim()
 
 
@@ -20,7 +22,7 @@ async function main() {
 	const { files } = await parseOptions()
 
 	if (!files.length)
-		throw new Error(USAGE)
+		throw new Error(MAN)
 
 	console.log('HEV1 to HVC1…')
 	for (const file of files)

package/src/moov2front.js

@@ -5,12 +5,15 @@ import { uniqueFilenameFor, overwrite } from './utils/fs-utils.js'
 import { parseOptions } from './utils/parseOptions.js'
 
 
-const USAGE = `
-Usage: mediasnacks moov2front <videos>
+const MAN = `
+SYNOPSIS
+  mediasnacks moov2front <videos>
 
-Rearranges .mov and .mp4 metadata to the start of the file for fast-start streaming.
-
-Files are overwritten.
+DESCRIPTION
+  Rearranges .mov and .mp4 metadata to the start of the file for fast-start streaming.
+ 
+NOTES
+  Files are overwritten.
 `.trim()
 
 async function main() {
@@ -19,7 +22,7 @@ async function main() {
 	const { files } = await parseOptions()
 
 	if (!files.length)
-		throw new Error(USAGE)
+		throw new Error(MAN)
 
 	console.log('Optimizing video for progressive download…')
 	for (const file of files)

package/src/prores.js

@@ -14,23 +14,22 @@ const PRORES_PROFILES = {
 	'4444xq': 5,
 }
 
-const USAGE = `
-Usage: mediasnacks prores [options] <video>
+const MAN = `
+SYNOPSIS
+  mediasnacks prores [options] <video>
 
-Converts a video to ProRes format.
+DESCRIPTION
+  Converts a video to ProRes format.
 
-Arguments:
-  <video>  Video file to convert
-
-Options:
+OPTIONS
   -p, --profile <n>  ProRes profile (default: 3 (422 HQ))
   -h, --help         Show this help message
 
-Example:
+EXAMPLES
   mediasnacks prores video.mov
   mediasnacks prores --profile 2 video.mov
 
-  Outputs: video.prores.mov
+  Both output a file named: video.prores.mov
 `.trim()
 
 
@@ -43,7 +42,7 @@ async function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}
 

package/src/qdir.js

@@ -8,10 +8,12 @@ import { readdir, writeFile, unlink, rename } from 'node:fs/promises'
 import { isFile } from './utils/fs-utils.js'
 
 
-const USAGE = `
-Usage: mediasnacks qdir [folder]
+const MAN = `
+SYNOPSIS
+  mediasnacks qdir [folder]
 
-Sequentially runs all *.sh files in a folder (cwd by default). 
+DESCRIPTION
+  Sequentially runs all *.sh files in a folder (cwd by default). 
 `.trim()
 
 
@@ -24,7 +26,7 @@ async function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}
 

package/src/resize.js

@@ -8,19 +8,21 @@ import { isFile, uniqueFilenameFor } from './utils/fs-utils.js'
 import { ffmpeg, videoAttrs, assertUserHasFFmpeg } from './utils/ffmpeg.js'
 
 
+const MAN = `
+SYNOPSIS
+  mediasnacks resize [--width=<num>] [--height=<num>] [-y | --overwrite] [--output-dir=<dir>] <files>
 
-const USAGE = `
-Usage: mediasnacks resize [--width=<num>] [--height=<num>] [-y | --overwrite] [--output-dir=<dir>] <files>
+DESCRIPTION
+  Resizes videos and images. The aspect ratio is preserved when only one dimension is specified.
 
-Resizes videos and images. The aspect ratio is preserved when only one dimension is specified.
-
-Example: Overwrites the input file (-y)
+EXAMPLES
+  Overwrites the input file (-y)
     mediasnacks resize -y --width 480 'dir-a/**/*.png' 'dir-b/**/*.mp4'
 
-Example: Output directory (-o)
+  Output directory (-o)
     mediasnacks resize --height 240 --output-dir /tmp/out video.mov
    
-Details:
+OPTIONS
 	--width and --height are -2 by default:
 		-1 = auto-compute while preserving the aspect ratio (may result in an odd number)
 		-2 = same as -1 but rounds to the nearest even number
@@ -39,7 +41,7 @@ async function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}
 

package/src/seqcheck.js

@@ -4,12 +4,14 @@ import { parseArgs } from 'node:util'
 import { readdirSync } from 'node:fs'
 
 
-const USAGE = `
-Usage: mediasnacks seqcheck [options] [folder]
+const MAN = `
+SYNOPSIS
+  mediasnacks seqcheck [options] [folder]
 
-Find missing numbered files in a sequence.
+DESCRIPTION
+  Find missing numbered files in a sequence.
 
-Options:
+OPTIONS
   -ld, --left-delimiter <str>   Delimiter before the number (default: "_")
   -rd, --right-delimiter <str>  Delimiter after the number (default: ".")
   -h,  --help
@@ -27,7 +29,7 @@ function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}
 

package/src/sqcrop.js

@@ -8,10 +8,12 @@ import { lstat, uniqueFilenameFor } from './utils/fs-utils.js'
 import { parseOptions } from './utils/parseOptions.js'
 
 
-const USAGE = `
-Usage: mediasnacks sqcrop [-y | --overwrite] [--output-dir=<dir>] <images> 
+const MAN = `
+SYNOPSIS
+  mediasnacks sqcrop [-y | --overwrite] [--output-dir=<dir>] <images> 
 
-Square crops images
+DESCRIPTION
+  Square crops images
 `.trim()
 
 
@@ -25,7 +27,7 @@ async function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}
 

package/src/utils/ffmpeg.js

@@ -141,7 +141,7 @@ export async function videoAttrs(v) {
 		'-of', 'json',
 		v
 	])
-	return JSON.parse(stdout).streams[0]
+	return JSON.parse(stdout).streams?.[0] || {}
 }
 
 

package/src/vconcat.sh

@@ -2,9 +2,9 @@
 
 if [ "$#" -lt 2 ]; then
   cat << EOF
-Usage:
-    $(basename "$0") vid1.mov vid2.mov [...]
-    $(basename "$0") *.mp4
+EXAMPLES
+  $(basename "$0") vid1.mov vid2.mov [...]
+  $(basename "$0") *.mp4
 EOF
   exit 1
 fi

package/src/vsplit.js

@@ -9,16 +9,18 @@ import { assertUserHasFFmpeg, run } from './utils/ffmpeg.js'
 
 // TODO looks like it's missing a frame (perhaps becaue of -c copy)
 
-const USAGE = `
-Usage: mediasnacks vsplit <csv> <video>
+const MAN = `
+SYNOPSIS
+  mediasnacks vsplit <csv> <video>
 
-Splits a video into multiple clips from CSV timestamps.
+DESCRIPTION
+  Splits a video into multiple clips from CSV timestamps.
 
-Arguments:
+ARGUMENTS
   <csv>    CSV file with start,end columns (in seconds)
   <video>  Video file to split
 
-Example:
+EXAMPLE
   mediasnacks vsplit clips.csv video.mov
 
   Given clips.csv:
@@ -39,7 +41,7 @@ async function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}
 

package/src/vtrim.js

@@ -5,12 +5,14 @@ import { parseOptions } from './utils/parseOptions.js'
 import { ffmpeg, assertUserHasFFmpeg } from './utils/ffmpeg.js'
 
 
-const USAGE = `
-Usage: mediasnacks vtrim [--start <time>] [--end <time>] <video>
+const MAN = `
+SYNOPSIS
+  mediasnacks vtrim [--start <time>] [--end <time>] <video>
 
-Trims a video without re-encoding (fast, but approximate cuts).
+DESCRIPTION
+  Trims a video without re-encoding (fast, but approximate cuts).
 
-Options:
+OPTIONS
   -s, --start <time>   Start time (e.g. 10, 00:00:10, 1:23.5). Default: beginning.
   -e, --end <time>     End time (e.g. 30, 00:00:30, 2:45.0). Default: end of video.
   -h, --help
@@ -27,7 +29,7 @@ async function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}