mediasnacks 0.19.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mediasnacks",
-  "version": "0.19.0",
+  "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

@@ -38,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()
 
 
@@ -54,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

@@ -4,16 +4,26 @@ import { parseOptions } from './utils/parseOptions.js'
 import { ffmpeg, assertUserHasFFmpeg, videoAttrs } from './utils/ffmpeg.js'
 
 
-const USAGE = `
+const MAN = `
 Usage: mediasnacks detectdups [options] <video>
 
-Detects sequentially duplicate frames in a video and prints their frame numbers.
+Detects sequentially duplicate frames in a video and prints a histogram of their distance.
 
-Options:
+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()
 
 
@@ -27,21 +37,27 @@ async function main() {
 	})
 
 	if (values.help) {
-		console.log(USAGE)
+		console.log(MAN)
 		process.exit(0)
 	}
 
 	if (files.length !== 1)
-		throw new Error('One video file must be specified. See mediasnacks detectdups --help')
+		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('Input file must be a video.')
+		throw new Error('Invalid input file. Must be a video.')
 
 	const vDur = Number(v.duration)
-	const seek = Number(values.seek) || (vDur > 60 ? 20 : 0)
-	const duration = Number(values.duration) || (vDur > 60 ? 20 : vDur)
+
+	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}`)
@@ -53,8 +69,8 @@ async function main() {
 		throw new Error(`Invalid analysis range. Exceeds video duration: ${vDur}`)
 
 
-	const dupFrames = await detectDuplicateFramesNums(files[0], seek, duration)
-	analyze(dupFrames, seek, duration)
+	const dups = await detectDuplicateFramesNums(files[0], seek, duration)
+	analyze(dups, seek, duration)
 }
 
 async function detectDuplicateFramesNums(video, seek, duration) {
@@ -84,22 +100,18 @@ async function detectDuplicateFramesNums(video, seek, duration) {
 }
 
 function analyze(dup_frames, seek, duration) {
-	const dup_distance = []
 	const histogram = {}
 	for (let i = 1; i < dup_frames.length; i++) {
 		const diff = dup_frames[i] - dup_frames[i - 1]
-		dup_distance.push(diff)
 		histogram[diff] = (histogram[diff] || 0) + 1
 	}
-	console.log({
+	console.log(JSON.stringify({
 		analyzed_region: {
-			start: seek + 's',
-			end: (seek + duration) + 's',
+			start_sec: seek,
+			end_sec: seek + duration
 		},
-		dup_frames,
-		dup_distance,
 		histogram
-	})
+	}, null, 2))
 }
 
 main().catch(err => {

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 sequentially 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/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)
 	}