mediasnacks 0.23.0 → 0.25.0

package/README.md

@@ -10,12 +10,6 @@ Utilities video and images.
 npm install -g mediasnacks
 ```
 
-Optionally, if you have `ignore-scripts=true` in your `.npmprc`, 
-you can install zsh auto-completions with:
-```sh
-$(npm root -g)/mediasnacks/install-zsh-completions.js
-```
-
 
 
 ## Overview
@@ -32,6 +26,8 @@ mediasnacks <command> <args>
 
 - `resize` Resizes videos or images
 - `edgespic` Extracts first and last frames
+- `frameseq` Converts video to sequence of PNGs
+- `countframes` Counts frames in a video
 - `ssim` Computes similarity of two images
 - `gif`: Video to GIF
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mediasnacks",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Utilities for optimizing and preparing videos and images",
   "license": "MIT",
   "author": "Eric Fortis",
@@ -9,7 +9,8 @@
 		"mediasnacks": "src/cli.js"
 	},
 	"scripts": {
-		"test": "docker run --rm $(docker build -q .)",
+		"test": "FORCE_COLOR=1 node --test",
+		"test-docker": "docker run --rm $(docker build -q .)",
 		"postinstall": "node install-zsh-completions.js",
 		"dev-install": "npm i -g . --ignore-scripts=false"
 	},

package/src/cli.js

@@ -13,6 +13,8 @@ const COMMANDS = {
 
 	resize: ['resize.js', 'Resizes videos or images'],
 	edgespic: ['edgespic.js', 'Extracts first and last frames'],
+	frameseq: ['frameseq.js', 'Converts video to sequence of PNGs'],
+	countframes: ['countframes.js', 'Counts frames in a video'],
 	ssim: ['ssim.js', 'Computes SSIM between two images'],
 	gif: ['gif.sh', 'Video to GIF\n'],
 

package/src/countframes.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import { parseOptions } from './utils/parseOptions.js'
+import { assertUserHasFFmpeg } from './utils/subprocess.js'
+import { videoAttrs } from './utils/videoAttrs.js'
+import { parseTimecode } from './utils/parseTimecode.js'
+
+
+const HELP = `
+SYNOPSIS
+  mediasnacks countframes [options] <file>
+
+DESCRIPTION
+  Counts the number of frames in a video between optional start and end bounds.
+
+OPTIONS
+  -f, --fps <num>          Frames per second (default: same as video)
+  -s, --start <timecode>   Start time in seconds (default: 0)
+  -e, --end <timecode>     End time in seconds (default: end of video)
+
+EXAMPLES
+  mediasnacks countframes --start=1:30.16 --end=60 video.mov
+  mediasnacks countframes --fps=12 video.mov
+`.trim()
+
+
+async function main() {
+	await assertUserHasFFmpeg()
+
+	const { values, files } = await parseOptions({
+		fps: { type: 'string', default: '' },
+		start: { short: 's', type: 'string', default: '' },
+		end: { short: 'e', type: 'string', default: '' },
+		help: { short: 'h', type: 'boolean' }
+	})
+
+	if (values.help) {
+		console.log(HELP)
+		return
+	}
+
+	const { fps, start, end } = values
+	const file = files[0]
+	if (!file) throw new Error('No video file specified')
+
+	const n = await countframes(file, fps, start, end)
+	console.log(String(n))
+}
+
+
+export async function countframes(file, fps, start, end) {
+	const v = await videoAttrs(file)
+	const videoDuration = parseFloat(v.duration || 0)
+	const startSecs = start ? parseTimecode(start) : 0
+	const endSecs = end ? parseTimecode(end) : videoDuration
+	const durationLimit = Math.max(0, endSecs - startSecs)
+	const actualFps = fps ? Number(fps) : eval(v.r_frame_rate)
+	return Math.ceil(durationLimit * actualFps)
+}
+
+
+if (import.meta.main)
+	main().catch(err => {
+		console.error(err.message)
+		process.exit(1)
+	})

package/src/detectdups.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 import { parseOptions } from './utils/parseOptions.js'
-import { ffmpeg, assertUserHasFFmpeg, videoAttrs } from './utils/subprocess.js'
+import { ffmpeg, assertUserHasFFmpeg } from './utils/subprocess.js'
+import { videoAttrs } from './utils/videoAttrs.js'
 
 const STDEV_THRESHOLD = 0.2
 

package/src/dropdups.js

@@ -4,10 +4,10 @@ import { resolve, parse, format } from 'node:path'
 
 import { parseOptions } from './utils/parseOptions.js'
 import { ffmpeg, assertUserHasFFmpeg, run } from './utils/subprocess.js'
-import { PRORES_PROFILES } from './prores.js'
+import { ProresProfiles } from './prores.js'
 
 
-const PROFILE = PRORES_PROFILES.hq
+const PROFILE = ProresProfiles.default
 
 const HELP = `
 SYNOPSIS
@@ -65,9 +65,7 @@ async function dropdups(video, dupFrameNum) {
 			? `decimate=cycle=${dupFrameNum}`
 			: 'mpdecimate,setpts=N/FRAME_RATE/TB',
 		'-fps_mode', 'cfr',
-		'-c:v', 'prores_ks',
-		'-profile:v', PROFILE,
-		'-pix_fmt', 'yuv422p10le',
+		'-c:v', 'prores_ks', '-profile:v', PROFILE,
 		makeOutputPath(video)
 	])
 }

package/src/edgespic.js

@@ -4,7 +4,8 @@ import { basename, extname, join, parse } from 'node:path'
 
 import { mkDir } from './utils/fs-utils.js'
 import { parseOptions } from './utils/parseOptions.js'
-import { ffmpeg, videoAttrs, assertUserHasFFmpeg } from './utils/subprocess.js'
+import { ffmpeg, assertUserHasFFmpeg } from './utils/subprocess.js'
+import { videoAttrs } from './utils/videoAttrs.js'
 
 
 const HELP = `

package/src/frameseq.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+import { basename, extname, join, parse } from 'node:path'
+
+import { mkDir } from './utils/fs-utils.js'
+import { parseOptions } from './utils/parseOptions.js'
+import { ffmpeg, assertUserHasFFmpeg } from './utils/subprocess.js'
+import { countframes } from './countframes.js'
+
+
+const HELP = `
+SYNOPSIS
+  mediasnacks frameseq [options] <files>
+
+DESCRIPTION
+  Converts a video into a sequence of PNGs.
+
+OPTIONS
+  -f, --fps <num>          Frames per second (default: same as video)
+  -s, --start <timecode>   Start time in seconds (default: 0)
+  -e, --end <timecode>     End time in seconds (default: end of video)
+
+EXAMPLES
+  Start and End
+  mediasnacks frameseq --start=1:30.16 --end=60 video.mov
+  
+  Custom framerate, all video duration
+  mediasnacks frameseq --fps=12 video.mov
+`.trim()
+
+
+async function main() {
+	await assertUserHasFFmpeg()
+
+	const { values, files } = await parseOptions({
+		fps: { type: 'string', default: '' },
+		start: { short: 's', type: 'string', default: '' },
+		end: { short: 'e', type: 'string', default: '' },
+		help: { short: 'h', type: 'boolean' }
+	})
+
+	if (values.help) {
+		console.log(HELP)
+		return
+	}
+
+	const { fps, start, end } = values
+	const file = files[0]
+	if (!file) throw new Error('No video files specified')
+	if (fps && isNaN(parseFloat(fps))) throw new Error('Invalid --fps')
+	if (start && isNaN(parseFloat(start))) throw new Error('Invalid --start')
+	if (end && isNaN(parseFloat(end))) throw new Error('Invalid --end')
+
+	const nFrames = await countframes(file, fps, start, end)
+	const pad = String(nFrames).length
+	await frameseq(file, fps, start, end, pad)
+}
+
+async function frameseq(video, fps, start, end, pad) {
+	const name = basename(video, extname(video))
+	const outDir = join(parse(video).dir, name)
+	await mkDir(outDir)
+	await ffmpeg([
+		start ? ['-ss', start] : [],
+		end ? ['-to', end] : [],
+		'-i', video,
+		fps ? ['-vf', `fps=${fps}`] : [],
+		join(outDir, `${name}_%0${pad}d.png`)
+	].flat())
+}
+
+main().catch(err => {
+	console.error(err.message)
+	process.exit(1)
+})

package/src/hev1tohvc1.js

@@ -2,7 +2,8 @@
 
 import { parseOptions } from './utils/parseOptions.js'
 import { uniqueFilenameFor, overwrite } from './utils/fs-utils.js'
-import { videoAttrs, ffmpeg, assertUserHasFFmpeg } from './utils/subprocess.js'
+import { ffmpeg, assertUserHasFFmpeg } from './utils/subprocess.js'
+import { videoAttrs } from './utils/videoAttrs.js'
 
 
 const HELP = `
@@ -31,7 +32,6 @@ async function main() {
 	if (!files.length)
 		throw new Error(HELP)
 
-	console.log('HEV1 to HVC1…')
 	for (const file of files)
 		await hev1tohvc1(file)
 }

package/src/prores.js

@@ -3,13 +3,24 @@ import { resolve, parse, join } from 'node:path'
 import { parseOptions } from './utils/parseOptions.js'
 import { assertUserHasFFmpeg, run } from './utils/subprocess.js'
 
-export const PRORES_PROFILES = {
-	'proxy': 0,
-	'lt': 1,
-	'standard': 2,
-	'hq': 3,
-	'4444': 4,
-	'4444xq': 5,
+export const ProresProfiles = new class {
+  // https://github.com/oyvindln/vhs-decode/wiki/ProRes-The-Definitive-FFmpeg-Guide#profiles-can-be-the-following
+	profiles = {
+		// 10-bit color depth
+		0: '422 Proxy',
+		1: '422 LT',
+		2: '422 Standard',
+		3: '422 High Quality',
+
+		// 12-bit
+		4: '4444',
+		5: '4444XQ'
+	}
+	default = 3
+
+	list = () => Object.keys(this.profiles)
+	isValid = n => Object.hasOwn(this.profiles, n)
+	table = () => Object.entries(this.profiles)
 }
 
 const HELP = `
@@ -17,17 +28,25 @@ SYNOPSIS
   mediasnacks prores [options] <video>
 
 DESCRIPTION
-  Converts a video to ProRes format.
+  Converts a video to Apple ProRes
 
 OPTIONS
-  -p, --profile <n>  ProRes profile (default: 3 (422 HQ))
+  -p, --profile <n>    Default: ${ProresProfiles.default}
+  -s, --start <time>   In time. Unset means beginning
+  -e, --end <time>     Out time. Unset means end
   -h, --help
+  
+PROFILES
+${ProresProfiles.table().map(([num, name]) =>
+	`  ${num}: ${name}`).join('\n')}
 
-EXAMPLES
-  mediasnacks prores video.mov
-  mediasnacks prores --profile 2 video.mov
+TIME FORMAT
+  5.1      -- pure seconds
+  20:10.0  -- 20m 10s
 
-  Both output a file named: video.prores.mov
+EXAMPLES
+  mediasnacks prores --end=60 video.mov   // outputs video.prores.mov
+  mediasnacks prores -p2 *.mov
 `.trim()
 
 
@@ -35,8 +54,10 @@ async function main() {
 	await assertUserHasFFmpeg()
 
 	const { values, files } = await parseOptions({
-		profile: { short: 'p', type: 'string', default: String(PRORES_PROFILES.hq) },
-		help: { short: 'h', type: 'boolean' },
+		profile: { short: 'p', type: 'string', default: String(ProresProfiles.default) },
+		start: { short: 's', type: 'string', default: '' },
+		end: { short: 'e', type: 'string', default: '' },
+		help: { short: 'h', type: 'boolean' }
 	})
 
 	if (values.help) {
@@ -44,6 +65,9 @@ async function main() {
 		return
 	}
 
+	if (!ProresProfiles.isValid(Number(values.profile)))
+		throw new Error('Invalid profile. Must be one of: ' + ProresProfiles.list().join(','))
+
 	if (files.length !== 1)
 		throw new Error('Expected 1 argument: video file. See mediasnacks prores --help')
 
@@ -51,20 +75,19 @@ async function main() {
 	const { name, dir } = parse(video)
 	const output = join(dir, `${name}.prores.mov`)
 
-	console.log(`Converting to ProRes…`)
-	await prores(video, values.profile, output)
+	await prores(video, values.start, values.end, values.profile, output)
 }
 
-async function prores(video, profile, output) {
+async function prores(video, start, end, profile, output) {
 	await run('ffmpeg', [
 		'-v', 'error',
 		'-stats',
+		start ? ['-ss', start] : [],
+		end ? ['-to', end] : [],
 		'-i', video,
-		'-c:v', 'prores_ks',
-		'-profile:v', profile,
-		'-pix_fmt', 'yuv422p10le',
+		'-c:v', 'prores_ks', '-profile:v', profile,
 		output
-	])
+	].flat())
 }
 
 if (import.meta.main)

package/src/resize.js

@@ -4,7 +4,8 @@ import { rename } from 'node:fs/promises'
 
 import { parseOptions } from './utils/parseOptions.js'
 import { isFile, uniqueFilenameFor } from './utils/fs-utils.js'
-import { ffmpeg, videoAttrs, assertUserHasFFmpeg } from './utils/subprocess.js'
+import { ffmpeg, assertUserHasFFmpeg } from './utils/subprocess.js'
+import { videoAttrs } from './utils/videoAttrs.js'
 
 
 const HELP = `

package/src/utils/parseTimecode.js

@@ -0,0 +1,16 @@
+export function parseTimecode(time) {
+	if (Number.isFinite(time))
+		return time
+
+	const parts = time.split(':').map(Number)
+	if (parts.some(isNaN) || parts.length > 3)
+		throw new Error(`Invalid time: ${time}`)
+
+	// HH:MM:SS or HH:MM:SS.mmm
+	if (parts.length === 3) return parts[0] * 3600 + parts[1] * 60 + parts[2]
+
+	// MM:SS or MM:SS.mmm
+	if (parts.length === 2) return parts[0] * 60 + parts[1]
+
+	return parts[0]
+}

package/src/utils/subprocess.js

@@ -15,7 +15,7 @@ export async function ffmpeg(args) {
 	return runSilently('ffmpeg', args)
 }
 
-async function runSilently(program, args) {
+export async function runSilently(program, args) {
 	return new Promise((resolve, reject) => {
 		const stdout = []
 		const stderr = []
@@ -52,95 +52,3 @@ export async function run(program, args) {
 	})
 }
 
-
-/**
- * Describes disposition flags that define how the video stream should be treated
- * by players or downstream consumers.
- * @typedef {Object} VideoStreamDisposition
- * @prop {number} default Is whether this stream is the default selection.
- * @prop {number} dub is dubbed?
- * @prop {number} original is original?
- * @prop {number} comment contains commentary?
- * @prop {number} lyrics has lyrics?
- * @prop {number} karaoke is karaoke?
- * @prop {number} forced must always be rendered?
- * @prop {number} hearing_impaired targets hearing-impaired audiences?
- * @prop {number} visual_impaired targets visually-impaired audiences?
- * @prop {number} clean_effects removes certain effects or noise?
- * @prop {number} attached_pic represents embedded artwork?
- * @prop {number} timed_thumbnails timed thumbnail data?
- * @prop {number} non_diegetic non-diegetic content?
- * @prop {number} captions has captions?
- * @prop {number} descriptions has audio descriptions?
- * @prop {number} metadata has supplemental metadata?
- * @prop {number} dependent depends on another stream?
- * @prop {number} still_image still-image video content?
- * @prop {number} multilayer multilayer stream content?
- */
-
-/**
- * Describes metadata tags associated with a video stream.
- * @typedef {Object} VideoStreamTags
- * @prop {string} language stream language.
- * @prop {string} handler_name handler or track label.
- * @prop {string} vendor_id vendor for the encoder or container.
- */
-
-/**
- * Full set of attributes returned by ffprobe for a single video stream.
- * @typedef {Object} VideoStream
- * @prop {number} index Numerical index of the stream within the container.
- * @prop {string} codec_name Short codec identifier used by FFmpeg.
- * @prop {string} codec_long_name Descriptive codec name.
- * @prop {string} profile Codec profile used during encoding.
- * @prop {string} codec_type The media type, typically "video".
- * @prop {string} codec_tag_string Codec tag string declared in the container.
- * @prop {string} codec_tag Numeric codec tag in hexadecimal form.
- * @prop {number} width Video width in pixels.
- * @prop {number} height Video height in pixels.
- * @prop {number} coded_width Internal coded width, which may differ from output width.
- * @prop {number} coded_height Internal coded height.
- * @prop {number} has_b_frames Number of B-frames used by the encoder.
- * @prop {string} sample_aspect_ratio Pixel aspect ratio declared in the stream.
- * @prop {string} display_aspect_ratio Display aspect ratio after scaling.
- * @prop {string} pix_fmt Pixel format used by the video stream.
- * @prop {number} level Codec level used during encoding.
- * @prop {string} chroma_location The chroma sample position pattern.
- * @prop {string} field_order Field order (progressive, top-field-first, etc.).
- * @prop {number} refs Number of reference frames used by the encoder.
- * @prop {string} is_avc Indicates whether the stream uses AVC-style NAL units.
- * @prop {string} nal_length_size Length of NAL unit size prefixes.
- * @prop {string} id Stream identifier within the container.
- * @prop {string} r_frame_rate Raw frame rate reported by the demuxer.
- * @prop {string} avg_frame_rate Average frame rate.
- * @prop {string} time_base The fundamental time base of the stream.
- * @prop {number} start_pts Presentation timestamp where the stream begins.
- * @prop {string} start_time Wall-clock start time in seconds.
- * @prop {number} duration_ts Duration expressed in time-base units.
- * @prop {string} duration Stream duration in seconds.
- * @prop {string} bit_rate Declared bit rate of the video stream.
- * @prop {string} bits_per_raw_sample Bit depth of the raw samples.
- * @prop {string} nb_frames Number of frames according to the container.
- * @prop {number} extradata_size Size of the extra codec data.
- * @prop {VideoStreamDisposition} disposition Disposition flags describing playback intent.
- * @prop {VideoStreamTags} tags Metadata tags for the stream.
- */
-
-/**
- * Extracts full metadata for the primary video stream (v:0) using ffprobe.
- * @param {string} video Path to the video file.
- * @returns {Promise<VideoStream>} All video stream attributes.
- */
-export async function videoAttrs(v) {
-	const { stdout } = await runSilently('ffprobe', [
-		'-v', 'error',
-		'-select_streams', 'v:0',
-		'-show_entries', 'stream',
-		'-of', 'json',
-		v
-	])
-	return JSON.parse(stdout).streams?.[0] || {}
-}
-
-
-

package/src/utils/videoAttrs.js

@@ -0,0 +1,91 @@
+import { runSilently } from './subprocess.js'
+
+/**
+ * Describes disposition flags that define how the video stream should be treated
+ * by players or downstream consumers.
+ * @typedef {Object} VideoStreamDisposition
+ * @prop {number} default Is whether this stream is the default selection.
+ * @prop {number} dub is dubbed?
+ * @prop {number} original is original?
+ * @prop {number} comment contains commentary?
+ * @prop {number} lyrics has lyrics?
+ * @prop {number} karaoke is karaoke?
+ * @prop {number} forced must always be rendered?
+ * @prop {number} hearing_impaired targets hearing-impaired audiences?
+ * @prop {number} visual_impaired targets visually-impaired audiences?
+ * @prop {number} clean_effects removes certain effects or noise?
+ * @prop {number} attached_pic represents embedded artwork?
+ * @prop {number} timed_thumbnails timed thumbnail data?
+ * @prop {number} non_diegetic non-diegetic content?
+ * @prop {number} captions has captions?
+ * @prop {number} descriptions has audio descriptions?
+ * @prop {number} metadata has supplemental metadata?
+ * @prop {number} dependent depends on another stream?
+ * @prop {number} still_image still-image video content?
+ * @prop {number} multilayer multilayer stream content?
+ */
+
+/**
+ * Describes metadata tags associated with a video stream.
+ * @typedef {Object} VideoStreamTags
+ * @prop {string} language stream language.
+ * @prop {string} handler_name handler or track label.
+ * @prop {string} vendor_id vendor for the encoder or container.
+ */
+
+/**
+ * Full set of attributes returned by ffprobe for a single video stream.
+ * @typedef {Object} VideoStream
+ * @prop {number} index Numerical index of the stream within the container.
+ * @prop {string} codec_name Short codec identifier used by FFmpeg.
+ * @prop {string} codec_long_name Descriptive codec name.
+ * @prop {string} profile Codec profile used during encoding.
+ * @prop {string} codec_type The media type, typically "video".
+ * @prop {string} codec_tag_string Codec tag string declared in the container.
+ * @prop {string} codec_tag Numeric codec tag in hexadecimal form.
+ * @prop {number} width Video width in pixels.
+ * @prop {number} height Video height in pixels.
+ * @prop {number} coded_width Internal coded width, which may differ from output width.
+ * @prop {number} coded_height Internal coded height.
+ * @prop {number} has_b_frames Number of B-frames used by the encoder.
+ * @prop {string} sample_aspect_ratio Pixel aspect ratio declared in the stream.
+ * @prop {string} display_aspect_ratio Display aspect ratio after scaling.
+ * @prop {string} pix_fmt Pixel format used by the video stream.
+ * @prop {number} level Codec level used during encoding.
+ * @prop {string} chroma_location The chroma sample position pattern.
+ * @prop {string} field_order Field order (progressive, top-field-first, etc.).
+ * @prop {number} refs Number of reference frames used by the encoder.
+ * @prop {string} is_avc Indicates whether the stream uses AVC-style NAL units.
+ * @prop {string} nal_length_size Length of NAL unit size prefixes.
+ * @prop {string} id Stream identifier within the container.
+ * @prop {string} r_frame_rate Raw frame rate reported by the demuxer.
+ * @prop {string} avg_frame_rate Average frame rate.
+ * @prop {string} time_base The fundamental time base of the stream.
+ * @prop {number} start_pts Presentation timestamp where the stream begins.
+ * @prop {string} start_time Wall-clock start time in seconds.
+ * @prop {number} duration_ts Duration expressed in time-base units.
+ * @prop {string} duration Stream duration in seconds.
+ * @prop {string} bit_rate Declared bit rate of the video stream.
+ * @prop {string} bits_per_raw_sample Bit depth of the raw samples.
+ * @prop {string} nb_frames Number of frames according to the container.
+ * @prop {number} extradata_size Size of the extra codec data.
+ * @prop {VideoStreamDisposition} disposition Disposition flags describing playback intent.
+ * @prop {VideoStreamTags} tags Metadata tags for the stream.
+ */
+
+
+/**
+ * Extracts full metadata for the primary video stream (v:0) using ffprobe.
+ * @param {string} video Path to the video file.
+ * @returns {Promise<VideoStream>} All video stream attributes.
+ */
+export async function videoAttrs(v) {
+	const { stdout } = await runSilently('ffprobe', [
+		'-v', 'error',
+		'-select_streams', 'v:0',
+		'-show_entries', 'stream',
+		'-of', 'json',
+		v
+	])
+	return JSON.parse(stdout).streams?.[0] || {}
+}