mediatuna 1.21.11 → 1.22.0

package/README.md

@@ -10,15 +10,12 @@ A home archive is mixed types, interlaced DV, missing tags, and Windows dates th
 
 **Docs:** [mediatuna.dev/docs](https://mediatuna.dev/docs) · **Site:** [mediatuna.dev](https://mediatuna.dev)
 
-Your **local agent** can run this for you — dry-run, sample, convert. It should call `mediatuna`, not invent an ffmpeg command line. [Agents](docs/agents.md).
-
 ## Install
 
 [Node.js](https://nodejs.org/) 18+ and **ffmpeg** / **ffprobe** on PATH. [Full install](docs/install.md).
 
 ```bash
-pnpm install
-npm link
+npm install -g mediatuna
 mediatuna --version
 ```
 
@@ -36,15 +33,24 @@ More examples: [docs/usage.md](docs/usage.md). Every flag: [docs/options.md](doc
 
 ## What you get
 
+### Core
+
 - One pass over video and audio (or `--video-only` / `--audio-only`)
 - Safe defaults — dry-run, duration verify, Recycle Bin, hash before recup cleanup
-- Dates survive container tags, filenames, and Windows Created/Modified
 - Skip normalized MP3s and existing outputs; `--resume` a long batch
 - AAC copy when the source is already AAC LC (`--reencode-audio` to force 192k)
+
+### Data preservation
+
+- Dates survive container tags, filenames, and Windows Created/Modified
 - Recovery helpers — Everything dupes, PhotoRec folder rebuild
 
 Stays 100% local. Flags, logging, dates, and recovery live in the [docs](docs/README.md).
 
+## Agents
+
+A **local agent** (Cursor, Claude Code, and the like) can dry-run, sample, and convert for you. It should call `mediatuna`, not invent an ffmpeg command line. [Agents](docs/agents.md).
+
 ## Safety
 
 Hardening is care, not a guarantee. Encoding is lossy; “same file” is usually size or duration. **Keep a backup you can restore from.** Details: [docs/safety.md](docs/safety.md).
@@ -53,6 +59,8 @@ Hardening is care, not a guarantee. Encoding is lossy; “same file” is usuall
 
 ## Development
 
+Checkout, `pnpm install`, and `npm link` — [full install](docs/install.md).
+
 ```bash
 pnpm test           # unit suite; ffmpeg cases run only if ffmpeg is on PATH
 pnpm test:ffmpeg    # synthetic encode checks
@@ -62,4 +70,4 @@ Core logic is in `lib/`; `index.js` is the CLI. Site (FilePress + docs mount): `
 
 ## Roadmap
 
-Shipped work and open items: [specs/improvements.md](specs/improvements.md), [specs/mediatuna.md](specs/mediatuna.md), [specs/partial/hardening.md](specs/partial/hardening.md), [specs/testing.md](specs/testing.md). Parked: [output formats](specs/output-formats.md), [agents](specs/agents.md).
+Shipped work and open items: [specs/improvements.md](specs/improvements.md), [specs/mediatuna.md](specs/mediatuna.md), [specs/partial/hardening.md](specs/partial/hardening.md), [specs/testing.md](specs/testing.md). Parked: [output formats](specs/output-formats.md), [agents](specs/agents.md). Post-publish review: [specs/post-publish-review.md](specs/post-publish-review.md).

package/index.js

@@ -107,6 +107,8 @@ Options:
   --recup-map          Map a PhotoRec-style dump to folders using copies found elsewhere
   --ext <list>         With --recup-map: extensions (default: audio + phone video)
   --apply              With --recup-map: copy placed files into proposed-tree/
+  --ledger             Write provenance into each new MP4/MP3 (comment + mediatuna tag)
+  --ledger-json        Also append .mediatuna/archive.json under --output (or cwd)
 
 Video formats: AVI, MOV, MOD, VOB, MTS, M2TS, MPG, MPEG, WMV, 3GP, 3G2 → MP4
 Audio formats: MP3, FLAC, WAV, AIFF, M4A, AAC, OGG, Opus, WMA, AC3, DTS, AMR, QCP → MP3
@@ -175,6 +177,7 @@ const {
     deleteOriginals, cleanupOriginals, audioQuality, extractAudio, resume, jobs: requestedJobs,
     stampDates, stampVideo, backupDir, dupeReport, dupeHash, recupMap, recupExt, recupApply,
     yes, deletePermanent, include, exclude, archiveDir, sampleSeconds, reencodeAudio,
+    ledger, ledgerJsonPath,
 } = cli;
 
 const LOG_FILE = cli.logFile;
@@ -554,6 +557,7 @@ const modeParts = buildModeParts({
     nvenc, quality, deinterlace, mediaMode, preferMtime, embedArt, extractAudio, audioQuality,
     verify, deleteOriginals, deletePermanent, dryRun, resume, jobs,
     archiveDir, sampleSeconds, reencodeAudio,
+    ledger, ledgerJsonPath,
 });
 logConsole(`MediaTuna: ${files.length} files | ${modeParts.join(' | ')}`);
 const sourceDir = resolved.mode === 'folder' ? resolved.targetPath : path.dirname(files[0]);
@@ -562,6 +566,10 @@ logConsole(formatWriteLocationBanner({
     outputDir,
     sourceDir,
 }));
+if (ledger) {
+    logFile('Ledger: embed provenance in each new MP4/MP3 (comment + mediatuna tag)');
+    if (ledgerJsonPath) logFile(`Ledger json: ${ledgerJsonPath}`);
+}
 
 let preflight = await buildPreflightEntries(files, outputDir, force, mediaMode, {
     audioQuality,
@@ -687,6 +695,9 @@ const { stats, failedPaths, convertedInputs } = await runConversion({
     config: {
         dryRun, verify, keepPartial, quality, audioQuality, deinterlace, nvenc,
         preferMtime, embedArt, extractAudio, mediaMode, verbose, jobs, sampleSeconds, reencodeAudio,
+        ledger, ledgerJsonPath,
+        sourceRoot: resolved.mode === 'folder' ? resolved.targetPath : path.dirname(files[0]),
+        mediatunaVersion: pkg.version,
     },
     logger,
     progress: {

package/lib/cli-config.js

@@ -3,6 +3,7 @@ import path from 'path';
 import { VALID_DEINTERLACE, VALID_QUALITY } from './constants.js';
 import { parseJobsValue } from './jobs.js';
 import { parseGlobList } from './globs.js';
+import { defaultLedgerJsonPath } from './ledger.js';
 
 export class CliConfigError extends Error {
     constructor(message) {
@@ -53,6 +54,8 @@ export const CLI_PARSE_OPTIONS = {
     archive: { type: 'string' },
     sample: { type: 'string' },
     'reencode-audio': { type: 'boolean' },
+    ledger: { type: 'boolean' },
+    'ledger-json': { type: 'boolean' },
 };
 
 export function buildCliConfig(values, positionals, { cwd = process.cwd(), homedir = os.homedir() } = {}) {
@@ -280,6 +283,36 @@ export function buildCliConfig(values, positionals, { cwd = process.cwd(), homed
         throw new CliConfigError('--sample cannot be used with --recup-map.');
     }
 
+    const ledgerJson = values['ledger-json'] ?? false;
+    const ledger = (values.ledger ?? false) || ledgerJson;
+
+    if (ledger && values['stamp-dates']) {
+        throw new CliConfigError('--ledger cannot be used with --stamp-dates.');
+    }
+
+    if (ledger && values['dupe-report']) {
+        throw new CliConfigError('--ledger cannot be used with --dupe-report.');
+    }
+
+    if (ledger && values['recup-map']) {
+        throw new CliConfigError('--ledger cannot be used with --recup-map.');
+    }
+
+    if (ledger && sampleSeconds) {
+        throw new CliConfigError('--ledger cannot be used with --sample (samples are not the archive).');
+    }
+
+    if (ledger && values['cleanup-originals']) {
+        throw new CliConfigError('--ledger writes provenance on new outputs; omit --cleanup-originals.');
+    }
+
+    const ledgerJsonPath = ledgerJson
+        ? defaultLedgerJsonPath({
+            outputDir: values.output ? path.resolve(values.output) : null,
+            cwd,
+        })
+        : null;
+
     let jobs;
     try {
         jobs = parseJobsValue(values.jobs);
@@ -331,6 +364,8 @@ export function buildCliConfig(values, positionals, { cwd = process.cwd(), homed
         archiveDir: values.archive ? path.resolve(values.archive) : null,
         sampleSeconds,
         reencodeAudio: values['reencode-audio'] ?? false,
+        ledger,
+        ledgerJsonPath,
         target,
     };
 }

package/lib/ledger.js

@@ -0,0 +1,169 @@
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { parseFilenameDate } from './filename-dates.js';
+import { parseCreationDate } from './stamp-dates.js';
+
+export const LEDGER_JSON_NAME = 'archive.json';
+
+let sidecarChain = Promise.resolve();
+
+export function defaultLedgerJsonPath({ outputDir = null, cwd = process.cwd() } = {}) {
+    return path.join(outputDir || cwd, '.mediatuna', LEDGER_JSON_NAME);
+}
+
+export function relativeLedgerPath(root, abs) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedAbs = path.resolve(abs);
+    const rel = path.relative(resolvedRoot, resolvedAbs);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
+        return resolvedAbs.split(path.sep).join('/');
+    }
+    return rel.split(path.sep).join('/');
+}
+
+export function isoFromParsed(parsed) {
+    if (!parsed) return null;
+    const date = `${parsed.year}-${parsed.month}-${parsed.day}`;
+    if (!parsed.hasTime) return date;
+    return `${date}T${parsed.hour}:${parsed.minute}:${parsed.second}`;
+}
+
+function fromFilesystemTime(value) {
+    if (value == null || value === 'N/A') return null;
+    const parsed = parseCreationDate(value);
+    if (!parsed) return null;
+    return { sourceDate: isoFromParsed(parsed), dateSource: 'filesystem' };
+}
+
+function fromFilename(input) {
+    const hit = parseFilenameDate(path.basename(input));
+    if (!hit?.parsed) return null;
+    return {
+        sourceDate: isoFromParsed(hit.parsed),
+        dateSource: hit.source === 'mtime' ? 'filesystem' : 'filename',
+    };
+}
+
+export function resolveLedgerDate(meta, input, { preferMtime = false } = {}) {
+    const fromTag = parseCreationDate(meta?.creation_time);
+    if (fromTag) {
+        return { sourceDate: isoFromParsed(fromTag), dateSource: 'embedded' };
+    }
+
+    const filenameHit = fromFilename(input);
+    const fsHit = fromFilesystemTime(meta?.modified_time);
+
+    if (preferMtime) return fsHit || filenameHit || { sourceDate: null, dateSource: null };
+    return filenameHit || fsHit || { sourceDate: null, dateSource: null };
+}
+
+export function ledgerAction(mode) {
+    return mode === 'extract' ? 'extract' : 'transcode';
+}
+
+export function buildLedgerRecord({
+    input,
+    out,
+    meta,
+    mode,
+    sourceRoot,
+    mediatunaVersion,
+    preferMtime = false,
+    verified = false,
+    durationDeltaMs = null,
+    processedAt = new Date().toISOString(),
+}) {
+    const { sourceDate, dateSource } = resolveLedgerDate(meta, input, { preferMtime });
+    const ext = path.extname(input).slice(1).toLowerCase() || 'unknown';
+    return {
+        source: relativeLedgerPath(sourceRoot, input),
+        sourceFormat: ext,
+        sourceDate,
+        dateSource,
+        action: ledgerAction(mode),
+        output: relativeLedgerPath(sourceRoot, out),
+        verified,
+        durationDeltaMs,
+        processedAt,
+        mediatunaVersion,
+    };
+}
+
+export function formatLedgerComment(record) {
+    const date = record.sourceDate ? ` ${record.sourceDate}` : '';
+    const dest = path.posix.basename(String(record.output || '').replaceAll('\\', '/'));
+    return `MediaTuna ${record.mediatunaVersion} ${record.action} ${record.source} → ${dest}${date}`.slice(0, 250);
+}
+
+export function buildLedgerRemuxArgs(src, dest, record, { video }) {
+    const comment = formatLedgerComment(record);
+    const tag = JSON.stringify(record);
+    const args = [
+        '-hide_banner', '-loglevel', 'error', '-y',
+        '-i', src,
+        '-map', '0',
+        '-c', 'copy',
+        '-map_metadata', '0',
+    ];
+    if (video) {
+        args.push('-movflags', '+faststart+use_metadata_tags');
+    } else {
+        args.push('-id3v2_version', '3', '-write_id3v1', '0');
+    }
+    args.push('-metadata', `comment=${comment}`, '-metadata', `mediatuna=${tag}`, dest);
+    return args;
+}
+
+export function applyLedgerMetadata(outPath, record, { ffmpeg = 'ffmpeg' } = {}) {
+    const ext = path.extname(outPath);
+    const tmp = `${outPath}.ledger${ext}`;
+    const args = buildLedgerRemuxArgs(outPath, tmp, record, {
+        video: ext.toLowerCase() === '.mp4',
+    });
+    try {
+        execFileSync(ffmpeg, args, { stdio: 'pipe', timeout: 120_000 });
+        if (!fs.existsSync(tmp)) {
+            throw new Error('ledger remux produced no file');
+        }
+        if (fs.existsSync(outPath)) fs.unlinkSync(outPath);
+        fs.renameSync(tmp, outPath);
+    } catch (err) {
+        try {
+            if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+        } catch { /* keep the original output */ }
+        throw err;
+    }
+}
+
+export function upsertLedgerSidecar(filePath, record) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    let doc = { version: 1, updatedAt: record.processedAt, entries: [] };
+    if (fs.existsSync(filePath)) {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (parsed && typeof parsed === 'object') {
+            doc = parsed;
+        }
+        if (!Array.isArray(doc.entries)) doc.entries = [];
+        if (doc.version == null) doc.version = 1;
+    }
+    const index = doc.entries.findIndex((entry) => entry.output === record.output);
+    if (index >= 0) doc.entries[index] = record;
+    else doc.entries.push(record);
+    doc.updatedAt = record.processedAt;
+    fs.writeFileSync(filePath, `${JSON.stringify(doc, null, 2)}\n`);
+    return doc;
+}
+
+export function enqueueSidecarWrite(filePath, record) {
+    const next = sidecarChain.then(
+        () => upsertLedgerSidecar(filePath, record),
+        () => upsertLedgerSidecar(filePath, record),
+    );
+    sidecarChain = next.catch(() => {});
+    return next;
+}
+
+export function resetSidecarQueue() {
+    sidecarChain = Promise.resolve();
+}

package/lib/resolve-inputs.js

@@ -73,7 +73,7 @@ export function buildModeParts({
     mediaMode, preferMtime, embedArt, extractAudio, audioQuality, verify,
     deleteOriginals, deletePermanent = false, dryRun, resume, jobs = 1, dupeReport = false, dupeHash = false,
     recupMap = false, recupApply = false, archiveDir = null, sampleSeconds = null,
-    reencodeAudio = false,
+    reencodeAudio = false, ledger = false, ledgerJsonPath = null,
 }) {
     if (recupMap) {
         const parts = ['recup-map'];
@@ -118,6 +118,8 @@ export function buildModeParts({
     if (archiveDir) modeParts.push('archive');
     if (sampleSeconds) modeParts.push(`sample:${sampleSeconds}s`);
     if (reencodeAudio) modeParts.push('reencode-audio');
+    if (ledger) modeParts.push('ledger');
+    if (ledgerJsonPath) modeParts.push('ledger-json');
     if (resume) modeParts.push('resume');
     if (jobs > 1) modeParts.push(`jobs:${jobs}`);
     if (dryRun) modeParts.push('dry-run');

package/lib/run.js

@@ -21,6 +21,11 @@ import { formatDryRunProgress, shellQuote } from './format.js';
 import { secondsToHMS, formatHMSValue, formatTimeHMS, timeToSeconds } from './time.js';
 import { verifyOutput } from './verify.js';
 import { runWithConcurrency } from './jobs.js';
+import {
+    applyLedgerMetadata,
+    buildLedgerRecord,
+    enqueueSidecarWrite,
+} from './ledger.js';
 
 export async function runConversion({
     preflight,
@@ -33,6 +38,7 @@ export async function runConversion({
         dryRun, verify, keepPartial, quality, audioQuality, deinterlace, nvenc,
         preferMtime, embedArt, extractAudio, mediaMode, verbose, jobs = 1,
         sampleSeconds = null, reencodeAudio = false,
+        ledger = false, ledgerJsonPath = null, sourceRoot = null, mediatunaVersion = null,
     } = config;
 
     const stats = { done: 0, skipped: 0, failed: 0, resumed: 0 };
@@ -158,26 +164,61 @@ export async function runConversion({
                 ? `${Math.floor(elapsedSec / 60)}m ${Math.round(elapsedSec % 60)}s`
                 : `${elapsedSec.toFixed(1)}s`;
 
+            let check = null;
             if (verify) {
                 const verifyContext = isAudioJob ? { sourceMeta: meta, sourceSize: meta.size } : null;
-                const check = verifyOutput(out, expectedDuration, expectedType, verifyContext);
+                check = verifyOutput(out, expectedDuration, expectedType, verifyContext);
                 if (!check.ok) throw new Error(`verification failed: ${check.reason}`);
                 for (const warning of check.warnings ?? []) {
                     logger.logFile(`[WARN] ${passName}: ${warning}`);
                     if (verbose) logger.logConsole(`[WARN] ${passName}: ${warning}`);
                 }
+            }
+
+            if (ledger) {
+                const durationDeltaMs = check?.ok && expectedDuration > 0
+                    ? Math.round((check.duration - expectedDuration) * 1000)
+                    : null;
+                const record = buildLedgerRecord({
+                    input,
+                    out,
+                    meta,
+                    mode,
+                    sourceRoot: sourceRoot || path.dirname(input),
+                    mediatunaVersion,
+                    preferMtime,
+                    verified: Boolean(check?.ok),
+                    durationDeltaMs,
+                });
                 try {
-                    applyOutputTimestamps(input, out);
-                } catch { }
-                const outBase = path.basename(out);
+                    applyLedgerMetadata(out, record);
+                    logger.logFile(`Ledger: wrote metadata on ${path.basename(out)}`);
+                } catch (err) {
+                    logger.logFile(`[WARN] ledger metadata failed for ${path.basename(out)}: ${err.message}`);
+                    if (verbose) {
+                        logger.logConsole(`[WARN] ledger metadata failed for ${path.basename(out)}: ${err.message}`);
+                    }
+                }
+                if (ledgerJsonPath) {
+                    try {
+                        await enqueueSidecarWrite(ledgerJsonPath, record);
+                    } catch (err) {
+                        logger.logFile(`[WARN] ledger json failed: ${err.message}`);
+                        if (verbose) logger.logConsole(`[WARN] ledger json failed: ${err.message}`);
+                    }
+                }
+            }
+
+            try {
+                applyOutputTimestamps(input, out);
+            } catch { }
+
+            const outBase = path.basename(out);
+            if (verify) {
                 const detail = `✓ ${outBase} | Verified (${secondsToHMS(check.duration)}) | Metadata copied`;
                 logger.logFile(`${detail} | --- end ${passName} (${elapsedStr}) ---`);
                 logger.logToConsole(verbose ? detail : `✓ ${outBase}`);
             } else {
-                try {
-                    applyOutputTimestamps(input, out);
-                } catch { }
-                const outBase = path.basename(out);
                 logger.logFile(`✓ ${outBase} | --- end ${passName} (${elapsedStr}) ---`);
                 logger.logToConsole(verbose ? `✓ ${outBase}` : `✓ ${outBase}`);
             }
@@ -235,6 +276,10 @@ export async function runConversion({
                 stats.resumed++;
                 convertedInputs.push(input);
             }
+            if (ledger && (videoStatus.startsWith('convert') || extractStatus?.startsWith('convert'))) {
+                logger.logFile(`Would write ledger metadata for ${base}`);
+                if (ledgerJsonPath) logger.logFile(`Would append ledger json: ${ledgerJsonPath}`);
+            }
             if (total > 1) {
                 logger.logConsole(formatDryRunProgress(index, total, entry.status, base));
             } else if (verbose && (videoStatus.startsWith('convert') || extractStatus?.startsWith('convert'))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mediatuna",
-  "version": "1.21.11",
+  "version": "1.22.0",
   "type": "module",
   "description": "Make sure the old files can still play. Local convert to MP4 and MP3, dates kept.",
   "main": "index.js",
@@ -33,7 +33,8 @@
   "homepage": "https://mediatuna.dev",
   "files": [
     "index.js",
-    "lib"
+    "lib",
+    "skills"
   ],
   "scripts": {
     "start": "node index.js",

package/skills/mediatuna/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: mediatuna
+description: >-
+  Runs the MediaTuna local CLI to batch-convert home video/audio archives to
+  MP4 and MP3 (ffmpeg, dates, skip-already-done). Use when the user mentions
+  MediaTuna, old camcorder files, PhotoRec dumps, or converting a folder
+  of AVI/MOV/MOD/VOB/FLAC/WMA to playable files.
+---
+
+# MediaTuna
+
+Local batch convert. Stays 100% local. The CLI is the only encoder — do not replace it with a hand-rolled ffmpeg line.
+
+## Before any write
+
+1. `mediatuna --version` (or `node index.js --version` from a checkout). If missing: Node 18+, ffmpeg/ffprobe on PATH, then `npm install -g mediatuna`. Docs: https://mediatuna.dev/docs/install/
+2. Confirm the user has a **restore backup** of the source folder. If they do not, stop and say so.
+3. `--dry-run` first. Read the preflight table with them.
+
+```bash
+mediatuna "./archives/media" --dry-run
+```
+
+4. Then a short sample to a **different** folder:
+
+```bash
+mediatuna "./archives/media" --sample 20 --output "./samples"
+```
+
+5. Full convert to `--output`, not in-place, until they have checked a sample:
+
+```bash
+mediatuna "./archives/media" --output "./converted"
+```
+
+## Do not
+
+- `--delete-originals`, `--cleanup-originals`, or `--archive` unless the user explicitly asked **and** the backup exists.
+- `--force` on a first run.
+- Upload source media, samples, or logs that contain home paths to a remote host beyond what this agent session already does.
+- Promise lossless. Encodes are lossy. “Same file” is size or duration, not a bitstream compare.
+
+## Useful flags
+
+| Need | Flag |
+|------|------|
+| Video or audio only | `--video-only` / `--audio-only` |
+| Nested folders | `--recursive` |
+| Resume overnight | `--resume` |
+| Skip junk paths | `--include "*.avi"` / `--exclude "previews/**"` |
+| NVENC parallel | `--jobs 3` (after a single-job sample works) |
+| Forced AAC 192k on video | `--reencode-audio` (default copies AAC LC) |
+| PhotoRec tree | `--recup-map` — add `--hash` before `--apply` or cleanup |
+| Dupes | `--dupe-report` (Everything / `es.exe` on Windows) |
+| Provenance on new files | `--ledger` (embed). Add `--ledger-json` for `.mediatuna/archive.json` |
+
+Full list: https://mediatuna.dev/docs/options/ · safety: https://mediatuna.dev/docs/safety/
+
+## Install
+
+```bash
+npm install -g mediatuna
+mediatuna --version
+```
+
+Copy this skill from the global package if you are not in a checkout:
+
+```bash
+mkdir -p ~/.cursor/skills/mediatuna
+cp "$(npm root -g)/mediatuna/skills/mediatuna/SKILL.md" ~/.cursor/skills/mediatuna/SKILL.md
+```
+
+### Development checkout
+
+```bash
+pnpm install
+npm link
+mediatuna --version
+```
+
+`pnpm link -g` errors on some setups. After `git pull`, run `npm link` again.