mediasnacks 0.0.1

package/.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = tab
+insert_final_newline = true
+
+[*.md]
+indent_style = space

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eric Fortis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# mediasnacks
+
+Utilities optimizing and preparing video and images for web.
+
+
+## Usage Overview
+**FFmpeg and Node.js must be installed.**
+
+```shell
+npx mediasnacks <command> <args>
+```
+
+Commands:
+- `avif` Converts images to AVIF
+- `resize` Resizes videos or images
+- `moov2front` Rearranges .mov and .mp4 metadata for fast-start streaming
+
+<br/>
+
+### Converting Images to AVIF
+```shell
+npx mediasnacks avif [-y | --overwrite] [--output-dir=<dir>] <images> 
+```
+
+<br/>
+
+### Resizing Images or Videos
+Resizes videos and images. The aspect ratio is preserved when only one dimension is specified.
+
+`--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
+
+```shell
+npx mediasnacks resize [--width=<num>] [--height=<num>] [-y | --overwrite] [--output-dir=<dir>] <files>
+```
+
+Example: Overwrites the input file (-y)
+```shell
+npx mediasnacks resize -y --width 480 'dir-a/**/*.png' 'dir-b/**/*.mp4'
+```
+
+Example: Output directory (-o)
+```shell
+npx mediasnacks resize --height 240 --output-dir /tmp/out video.mov
+```
+
+<br/>
+
+### Fast-Start Streaming Video
+Rearranges .mov and .mp4 metadata to the start of the file for fast-start streaming.
+
+**Files are overwritten**
+
+```shell
+npx mediasnacks moov2front <videos>
+```
+hat is Fast Start?
+- https://wiki.avblocks.com/avblocks-for-cpp/muxer-parameters/mp4
+- https://trac.ffmpeg.org/wiki/HowToCheckIfFaststartIsEnabledForPlayback
+
+
+<br/>
+
+### License
+MIT

package/TODO.md

@@ -0,0 +1,4 @@
+# TODO
+
+- Test on Windows
+- Test on Linux

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "mediasnacks",
+  "version": "0.0.1",
+  "description": "Utilities for preparing videos, images, and audio for the web",
+  "license": "MIT",
+  "author": "Eric Fortis",
+  "type": "module",
+	"bin": {
+		"mediasnacks": "src/cli.js"
+	},
+	"scripts": {
+		"test": "node --test"
+	}
+}

package/src/cli-avif.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import { join } from 'node:path'
+import { parseArgs } from 'node:util'
+
+import { glob, replaceExt, lstat } from './fs-utils.js'
+import { ffmpeg, assertUserHasFFmpeg } from './ffmpeg.js'
+
+
+const USAGE = `
+Usage: npx mediasnacks avif [-y | --overwrite] [--output-dir=<dir>] <images> 
+
+Converts images to AVIF.
+`.trim()
+
+
+async function main() {
+	const { values, positionals } = parseArgs({
+		options: {
+			'output-dir': { type: 'string', default: '' },
+			overwrite: { short: 'y', type: 'boolean', default: false },
+			help: { short: 'h', type: 'boolean', default: false },
+		},
+		allowPositionals: true
+	})
+
+	if (values.help) {
+		console.log(USAGE)
+		process.exit(0)
+	}
+
+	if (!positionals.length)
+		throw new Error('No images specified. See npx mediasnacks avif --help')
+
+	await assertUserHasFFmpeg()
+	
+	console.log('AVIF…')
+	for (const g of positionals)
+		for (const file of await glob(g))
+			await toAvif({
+				file,
+				outFile: join(values['output-dir'], replaceExt(file, 'avif')),
+				overwrite: values.overwrite
+			})
+}
+
+async function toAvif({ file, outFile, overwrite }) {
+	const stImg = lstat(file)
+	const stAvif = lstat(outFile)
+	
+	if (!overwrite && stAvif?.isFile()) {
+		console.log('(skipped: output file exists but --overwrite=false)', file)
+		return
+	}
+	if (stAvif?.mtimeMs > stImg?.mtimeMs) {
+		console.log('(skipped: avif is newer)', file)
+		return
+	}
+
+	// TODO test on linux
+	console.log(file)
+	await ffmpeg([
+		'-y', // overwrites
+		'-i', file,
+		'-c:v', 'libsvtav1',
+		'-svtav1-params', 'avif=1',
+		outFile
+	])
+}
+
+main().catch(err => {
+	console.error(err.message)
+	process.exit(1)
+})

package/src/cli-moov2front.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import { join } from 'node:path'
+import { parseArgs } from 'node:util'
+import { unlink, rename } from 'node:fs/promises'
+
+import { glob, makeTempDir, makeDirFor } from './fs-utils.js'
+import { ffmpeg, assertUserHasFFmpeg } from './ffmpeg.js'
+
+
+const USAGE = `
+Usage: npx mediasnacks moov2front <videos>
+
+Rearranges .mov and .mp4 metadata to the start of the file for fast-start streaming.
+
+Files are overwritten.
+`.trim()
+
+async function main() {
+	const { positionals } = parseArgs({ allowPositionals: true })
+
+	if (!positionals.length)
+		throw new Error(USAGE)
+
+	await assertUserHasFFmpeg()
+	console.log('Optimizing videos for progressive download…')
+
+	for (const g of positionals)
+		for (const file of await glob(g))
+			await moov2front(file)
+}
+
+
+async function moov2front(file) {
+	if (!/\.(mp4|mov)$/i.test(file)) {
+		console.log('(skipped: not mp4/mov)', file)
+		return
+	}
+	if (await moovIsBeforeMdat(file)) {
+		console.log('(skipped: no changes needed)', file)
+		return
+	}
+
+	console.log(file)
+	const tmp = join(await makeTempDir(), file) // FFmpeg can’t edit in-place
+	await makeDirFor(tmp)
+
+	await ffmpeg([
+		'-hide_banner',
+		'-i', file,
+		'-movflags', '+faststart',
+		tmp
+	])
+	await unlink(file)
+	await rename(tmp, file)
+}
+
+async function moovIsBeforeMdat(file) {
+	const { stderr } = await ffmpeg([
+		'-hide_banner',
+		'-v', 'trace',
+		'-i', file,
+		'-f', 'null', '-'
+	])
+	const firstMatchedAtom = stderr.match(/type:'(moov|mdat)'/)?.[1]
+	return firstMatchedAtom === 'moov'
+}
+
+
+main().catch(err => {
+	console.error(err.message)
+	process.exit(1)
+})

package/src/cli-resize.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { join } from 'node:path'
+import { rename } from 'node:fs/promises'
+import { parseArgs } from 'node:util'
+
+import { glob, isFile, makeTempDir, makeDirFor } from './fs-utils.js'
+import { ffmpeg, videoAttrs, assertUserHasFFmpeg } from './ffmpeg.js'
+
+
+
+const USAGE = `
+Usage: npx mediasnacks resize [--width=<num>] [--height=<num>] [-y | --overwrite] [--output-dir=<dir>] <files>
+
+Resizes videos and images. The aspect ratio is preserved when only one dimension is specified.
+
+Example: Overwrites the input file (-y)
+    npx mediasnacks resize -y --width 480 'dir-a/**/*.png' 'dir-b/**/*.mp4'
+
+Example: Output directory (-o)
+    npx mediasnacks resize --height 240 --output-dir /tmp/out video.mov
+   
+Details:
+	--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
+`.trim()
+
+
+async function main() {
+	const { values, positionals } = parseArgs({
+		options: {
+			width: { type: 'string', default: '-2' },
+			height: { type: 'string', default: '-2' },
+			'output-dir': { type: 'string', default: '' },
+			overwrite: { short: 'y', type: 'boolean', default: false },
+			help: { short: 'h', type: 'boolean', default: false },
+		},
+		allowPositionals: true
+	})
+
+	if (values.help) {
+		console.log(USAGE)
+		process.exit(0)
+	}
+
+	const width = Number(values.width)
+	const height = Number(values.height)
+
+	if (width <= 0 && height <= 0)
+		throw new Error('--width or --height need to be greater than 0')
+
+	if (!positionals.length)
+		throw new Error('No video files specified')
+
+	await assertUserHasFFmpeg()
+
+	console.log('Resizing…')
+	for (const g of positionals)
+		for (const file of await glob(g))
+			await resize({
+				file,
+				outFile: join(values['output-dir'], file),
+				overwrite: values.overwrite,
+				width,
+				height,
+			})
+}
+
+
+async function resize({ file, outFile, overwrite, width, height }) {
+	const v = await videoAttrs(file, 'width', 'height')
+	if (width === v.width && height === v.height
+		|| width < 0 && height === v.height
+		|| height < 0 && width === v.width) {
+		console.log('(skipped: no changes needed)', file)
+		return
+	}
+
+	if (!overwrite && isFile(outFile)) {
+		console.log('(skipped: output file exists but --overwrite=false)', file)
+		return
+	}
+
+	console.log(file)
+	const tmp = join(await makeTempDir(), file) // FFmpeg can’t edit in-place
+	await makeDirFor(tmp)
+	await makeDirFor(outFile)
+
+	await ffmpeg([
+		'-i', file,
+		'-vf', `scale=${width}:${height}`,
+		'-movflags', '+faststart',
+		tmp
+	])
+	await rename(tmp, outFile)
+}
+
+
+main().catch(err => {
+	console.error(err.message)
+	process.exit(1)
+})

package/src/cli.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import { join } from 'node:path'
+import { spawn } from 'node:child_process'
+import pkgJSON from '../package.json' with { type: 'json' }
+
+
+const COMMANDS = {
+	avif: join(import.meta.dirname, 'cli-avif.js'),
+	resize: join(import.meta.dirname, 'cli-resize.js'),
+	moov2front: join(import.meta.dirname, 'cli-moov2front.js')
+}
+
+const USAGE = `
+Usage: npx mediasnacks <command> <args>
+
+Commands:
+    avif: Converts images to AVIF
+    resize: Resizes videos or images
+    moov2front: Rearranges .mov and .mp4 metadata for fast-start streaming
+`.trim()
+
+
+const [, , opt, ...args] = process.argv
+
+if (opt === '-v' || opt === '--version') {
+	console.log(pkgJSON.version)
+	process.exit(0)
+}
+
+if (opt === '-h' || opt === '--help') {
+	console.log(USAGE)
+	process.exit(0)
+}
+
+if (!opt) {
+	console.log(USAGE)
+	process.exit(1)
+}
+
+if (!Object.hasOwn(COMMANDS, opt)) {
+	console.error(`'${opt}' is not a mediasnacks command. See npx mediasnacks --help\n`)
+	process.exit(1)
+}
+
+spawn(process.execPath, [COMMANDS[opt], ...args], { stdio: 'inherit' })
+	.on('exit', code => process.exit(code))

package/src/ffmpeg.js

@@ -0,0 +1,51 @@
+import { spawn } from 'node:child_process'
+
+
+export async function ffmpeg(args) {
+	return run('ffmpeg', args)
+}
+
+export async function assertUserHasFFmpeg() {
+	try {
+		await run('ffmpeg', ['-version'])
+		await run('ffprobe', ['-version'])
+	}
+	catch {
+		throw new Error('ffmpeg not found. Please install ffmpeg.')
+	}
+}
+
+export async function videoAttrs(v, ...props) {
+	const { stdout } = await run('ffprobe', [
+		'-v', 'error',
+		'-select_streams', 'v:0',
+		'-show_entries', `stream=${props.join(',')}`,
+		'-of', 'json',
+		v
+	])
+	return JSON.parse(stdout).streams[0]
+}
+
+
+async function run(program, args) {
+	return new Promise((resolve, reject) => {
+		const stdout = []
+		const stderr = []
+
+		const p = spawn(program, args)
+		p.stdout.on('data', chunk => { stdout.push(chunk) })
+		p.stderr.on('data', chunk => { stderr.push(chunk) })
+
+		p.on('error', reject)
+		p.on('close', code => {
+			if (code === 0)
+				resolve({
+					stdout: Buffer.concat(stdout).toString(),
+					stderr: Buffer.concat(stderr).toString(),
+				})
+			else
+				reject(new Error(`${program} failed with code ${code}\n${Buffer.concat(stderr).toString()}`))
+		})
+	})
+}
+

package/src/fs-utils.js

@@ -0,0 +1,22 @@
+import { tmpdir } from 'node:os'
+import { promisify } from 'node:util'
+import { join, dirname } from 'node:path'
+import { mkdtemp, mkdir } from 'node:fs/promises'
+import { lstatSync, glob as _glob } from 'node:fs'
+
+
+export const glob = promisify(_glob)
+
+export const lstat = f => lstatSync(f, { throwIfNoEntry: false })
+export const isFile = path => lstat(path)?.isFile()
+
+export const makeDirFor = async file => mkdir(dirname(file), { recursive: true })
+export const makeTempDir = async () => mkdtemp(join(tmpdir(), 'mediasnacks-'))
+
+export const replaceExt = (f, ext) => {
+	const parts = f.split('.')
+	if (parts.length > 1 && parts[0])
+		parts.pop()
+	parts.push(ext)
+	return parts.join('.')
+}

package/src/fs-utils.test.js

@@ -0,0 +1,21 @@
+import { equal } from 'node:assert/strict'
+import test, { describe } from 'node:test'
+import { replaceExt } from './fs-utils.js'
+
+
+describe('replaceExt', () => {
+	test('replaces a simple extension', () => 
+		equal(replaceExt('file.txt', 'md'), 'file.md'))
+
+	test('replaces a multi-part extension', () => 
+		equal(replaceExt('archive.tar.gz', 'zip'), 'archive.tar.zip'))
+
+	test('adds extension when none exists', () => 
+		equal(replaceExt('README', 'md'), 'README.md'))
+
+	test('handles empty filename', () =>
+		equal(replaceExt('', 'ext'), '.ext'))
+	
+	test('handles dot-files', () =>
+		equal(replaceExt('.env', 'txt'), '.env.txt'))
+})