@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/files/media/encoding.js

@@ -0,0 +1,308 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { stampPackedAudio } from './packedAudio.js';
+const FORMATS = 'mov,matroska,webm,mp3,wav,flac,ogg,aac,avi,aiff,png_pipe,jpeg_pipe,webp_pipe,bmp_pipe,tiff_pipe,gif';
+const BOUNDS = ['-v', 'error', '-max_alloc', '134217728', '-protocol_whitelist', 'file', '-format_whitelist', FORMATS];
+const MAX_SEGMENT_BYTES = 8 * 1024 * 1024;
+const MAX_OBJECT_BYTES = 512 * 1024 * 1024;
+const NO_PROGRESS_MS = 30_000;
+/** Where relative AXOM_FFMPEG / AXOM_FFPROBE values are anchored: the process cwd at startup. Decoders run with
+ * `cwd: '/'` (a pinned file operation may own the process cwd meanwhile), so a relative path cannot stay relative. */
+const STARTUP_CWD = globalThis.process.cwd();
+/** The decoder named by `variable` (or `fallback`); a bare name is a PATH lookup, a relative path is made absolute. */
+export function decoderCommand(variable, fallback, env = globalThis.process.env) {
+    const value = env[variable] ?? fallback;
+    return value.includes('/') && !path.isAbsolute(value) ? path.resolve(STARTUP_CWD, value) : value;
+}
+const identifier = () => randomUUID().replaceAll('-', '');
+async function identity(input) {
+    const s = await input.stat({ bigint: true });
+    if (!s.isFile() || s.size > 32n * 1024n * 1024n * 1024n)
+        throw new Error('Not a supported regular media file');
+    return [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].join(':');
+}
+function cancelled(signal) { if (signal.aborted)
+    throw new Error('Media preparation cancelled'); }
+/** Only local self-contained inputs. Diagnostics containing user paths never reach callers. */
+async function runDecoder(command, args, input, signal, progress) {
+    cancelled(signal);
+    return new Promise((resolve, reject) => {
+        // An explicit cwd: the files host changes its own cwd inside pinned() sections, which a child would otherwise inherit.
+        const child = spawn(command, args, { cwd: '/', stdio: input ? ['ignore', 'pipe', 'pipe', input.fd] : ['ignore', 'pipe', 'pipe'] });
+        let output = '';
+        let line = '';
+        let error;
+        let lastProgress = Date.now();
+        let previous = -1;
+        let kill;
+        const cancel = (reason = 'Media preparation cancelled') => {
+            error ??= new Error(reason);
+            child.kill('SIGTERM');
+            if (!kill) {
+                kill = setTimeout(() => child.kill('SIGKILL'), 2000);
+                kill.unref();
+            }
+        };
+        const abort = () => cancel();
+        const timer = setInterval(() => { if (Date.now() - lastProgress > NO_PROGRESS_MS)
+            cancel('Media preparation made no progress'); }, 1000);
+        timer.unref();
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        child.stdout.on('data', chunk => {
+            if (!progress) {
+                output += chunk.toString();
+                if (output.length > 1024 * 1024)
+                    cancel('Media metadata exceeds limit');
+            }
+            else {
+                line += chunk.toString();
+                if (line.length > 64 * 1024) {
+                    cancel('Invalid media progress');
+                    return;
+                }
+                const lines = line.split('\n');
+                line = lines.pop();
+                for (const value of lines)
+                    if (value.startsWith('out_time_us=')) {
+                        const ms = Number(value.slice(12)) / 1000;
+                        if (Number.isFinite(ms) && ms > previous) {
+                            previous = ms;
+                            lastProgress = Date.now();
+                            progress(Math.max(0, ms));
+                        }
+                    }
+            }
+        });
+        child.stderr.resume();
+        child.on('error', e => { error = new Error(e.code === 'ENOENT' ? 'Install FFmpeg and ffprobe on this workstation (or set AXOM_FFMPEG / AXOM_FFPROBE).' : 'Unable to start workstation media decoder'); });
+        child.on('close', code => {
+            clearInterval(timer);
+            if (kill)
+                clearTimeout(kill);
+            signal.removeEventListener('abort', abort);
+            if (error)
+                reject(error);
+            else if (code !== 0)
+                reject(new Error('Unable to prepare this media file. It may be damaged or unsupported.'));
+            else
+                resolve(output);
+        });
+    });
+}
+export async function probeSource(input, signal) {
+    if (process.platform === 'win32')
+        throw new Error('Workstation media preparation currently requires macOS or Linux FFmpeg');
+    const raw = await runDecoder(decoderCommand('AXOM_FFPROBE', 'ffprobe'), [...BOUNDS, '-show_format', '-show_streams', '-of', 'json', '/dev/fd/3'], input, signal);
+    const data = JSON.parse(raw);
+    const video = data.streams.find(s => s.codec_type === 'video' && !s.disposition?.attached_pic);
+    const audio = data.streams.find(s => s.codec_type === 'audio');
+    const seconds = Number(data.format.duration ?? video?.duration ?? audio?.duration);
+    const image = !!video && !audio && !Number.isFinite(seconds);
+    if ((!video && !audio) || (!image && (!Number.isFinite(seconds) || seconds < 0 || seconds > 21600)))
+        throw new Error('Unsupported media or duration exceeds six hours');
+    if (video && (!video.width || !video.height || video.width * video.height > 40_000_000))
+        throw new Error('Image/video dimensions exceed preview limits');
+    const rate = video?.avg_frame_rate?.split('/').map(Number);
+    const ffmpegVersion = (await runDecoder(decoderCommand('AXOM_FFMPEG', 'ffmpeg'), ['-version'], null, signal)).split('\n')[0];
+    return { kind: image ? 'image' : video ? 'video' : 'audio', durationMs: image ? 0 : Math.round(seconds * 1000), durationAccuracy: 'exact',
+        sourceBytes: Number((await input.stat()).size), codec: video?.codec_name ?? audio.codec_name, audioCodec: audio?.codec_name,
+        pixelFormat: video?.pix_fmt, width: video?.width, height: video?.height, frameRate: rate && rate[1] ? rate[0] / rate[1] : undefined, ffmpegVersion };
+}
+export async function encodeGeneration(input, probe, startMs, directory, signal, onObject, onProgress) {
+    cancelled(signal);
+    if (!Number.isSafeInteger(startMs) || startMs < 0 || probe.durationMs == null || startMs > probe.durationMs)
+        throw new Error('Invalid media seek');
+    if (probe.kind === 'image')
+        throw new Error('Images use completed finite preparation');
+    const stamp = await identity(input);
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    const stat = await fs.lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()))
+        throw new Error('Unsafe media cache');
+    const generation = { id: /^[a-f0-9]{32}$/.test(path.basename(directory)) ? path.basename(directory) : identifier(), sourceOffsetMs: startMs, timestampOriginMs: 0, targetDurationMs: 4000, objects: [], complete: false, sourceComplete: false, createdAtMs: Date.now() };
+    const video = probe.kind === 'video';
+    const extension = video ? 'ts' : 'mp3';
+    const list = path.join(directory, video ? 'encoder.m3u8' : 'encoder.csv');
+    const args = ['-nostdin', ...BOUNDS, '-threads', '2', '-filter_threads', '2', '-ss', String(startMs / 1000), '-i', '/dev/fd/3', '-map_metadata', '-1', '-progress', 'pipe:1', '-stats_period', '0.1'];
+    if (video)
+        args.push('-map', '0:v:0', '-map', '0:a:0?', '-vf', "fps=30,scale=w='min(1280,iw)':h='min(720,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2", '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '26', '-maxrate', '1800k', '-bufsize', '3600k', '-pix_fmt', 'yuv420p', '-threads', '2', '-g', '120', '-keyint_min', '120', '-sc_threshold', '0', '-flags', '+cgop', '-c:a', 'aac', '-b:a', '128k', '-ac', '2', 
+        // Keep B-frame/AAC preroll positive with one fixed origin. Automatic MPEG-TS
+        // timestamp shifts differ after seeks and cause a repeated/missing boundary frame.
+        '-avoid_negative_ts', 'disabled', '-output_ts_offset', String(startMs / 1000 + 2), '-f', 'hls', '-hls_segment_options', 'mpegts_copyts=1', '-hls_time', '4', '-hls_list_size', '0', '-hls_flags', 'independent_segments+temp_file', '-hls_segment_filename', path.join(directory, 'raw_%06d.ts'), '-y', list);
+    else
+        args.push('-map', '0:a:0', '-vn', '-c:a', 'libmp3lame', '-b:a', '128k', '-ac', '2', '-ar', '44100', '-reservoir', '0', '-f', 'segment', '-segment_time', '4', '-segment_list', list, '-segment_list_type', 'csv', '-segment_format', 'mp3', '-segment_format_options', 'write_xing=0:id3v2_version=0', '-y', path.join(directory, 'raw_%06d.mp3'));
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted)
+        abort();
+    let finished = false;
+    let failure;
+    const encoding = runDecoder(decoderCommand('AXOM_FFMPEG', 'ffmpeg'), args, input, controller.signal, ms => onProgress(Math.min(probe.durationMs, startMs + ms)))
+        .then(() => { finished = true; }, error => { failure = error; finished = true; });
+    const published = new Set();
+    const publish = async () => {
+        cancelled(signal);
+        let text;
+        try {
+            const info = await fs.lstat(list);
+            if (info.size > 2 * 1024 * 1024 || !info.isFile() || info.isSymbolicLink())
+                throw new Error('Invalid media segment list');
+            text = await fs.readFile(list, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        const entries = [];
+        if (video) {
+            let duration = null;
+            let offset = 0;
+            for (const line of text.split('\n')) {
+                if (line.startsWith('#EXTINF:'))
+                    duration = Number(line.slice(8).split(',')[0]);
+                else if (/^raw_\d{6}\.ts$/.test(line) && duration != null && Number.isFinite(duration) && duration > 0) {
+                    entries.push({ name: line, start: offset, end: offset + duration });
+                    offset += duration;
+                    duration = null;
+                }
+            }
+        }
+        else
+            for (const line of text.split('\n').slice(0, -1)) {
+                const m = /^(raw_\d{6}\.mp3),([\d.]+),([\d.]+)$/.exec(line);
+                if (m)
+                    entries.push({ name: m[1], start: Number(m[2]), end: Number(m[3]) });
+            }
+        for (const entry of entries) {
+            if (published.has(entry.name))
+                continue;
+            cancelled(signal);
+            if (stamp !== await identity(input))
+                throw new Error('Media source changed; reopen its preview');
+            const raw = path.join(directory, entry.name);
+            const handle = await fs.open(raw, constants.O_RDONLY | constants.O_NOFOLLOW);
+            let bytes;
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || !stat.size || stat.size >= MAX_SEGMENT_BYTES)
+                    throw new Error('Media object exceeds preview limits');
+                bytes = await handle.readFile();
+            }
+            finally {
+                await handle.close();
+            }
+            const timestamp90k = Math.round((startMs / 1000 + entry.start) * 90000);
+            if (!video)
+                bytes = stampPackedAudio(bytes, BigInt(timestamp90k));
+            const id = identifier();
+            const file = path.join(directory, `${id}.${extension}`);
+            const temp = `${file}.tmp`;
+            try {
+                await fs.writeFile(temp, bytes, { mode: 0o600, flag: 'wx' });
+                cancelled(signal);
+                await fs.rename(temp, file);
+            }
+            finally {
+                await fs.unlink(temp).catch(() => { });
+            }
+            const start = Math.min(probe.durationMs, startMs + Math.round(entry.start * 1000));
+            const end = Math.min(probe.durationMs, startMs + Math.round(entry.end * 1000));
+            if (end <= start) {
+                await fs.unlink(file);
+                published.add(entry.name);
+                await fs.unlink(raw);
+                continue;
+            }
+            const object = { id, type: 'segment', extension, mimeType: video ? 'video/mp2t' : 'audio/mpeg', size: bytes.length,
+                etag: createHash('sha256').update(bytes).digest('hex'), startMs: start, endMs: end, sequence: generation.objects.length, timestamp90k, file };
+            await onObject(object);
+            generation.objects.push(object);
+            published.add(entry.name);
+            await fs.unlink(raw);
+        }
+    };
+    try {
+        while (!finished) {
+            await publish();
+            await new Promise(resolve => setTimeout(resolve, 25));
+        }
+        await encoding;
+        if (failure)
+            throw failure;
+        await publish();
+        cancelled(signal);
+        if (stamp !== await identity(input))
+            throw new Error('Media source changed; reopen its preview');
+        if (!generation.objects.length)
+            throw new Error('No playable media segments');
+        generation.complete = true;
+        generation.sourceComplete = true;
+        return generation;
+    }
+    finally {
+        controller.abort();
+        await encoding;
+        signal.removeEventListener('abort', abort);
+        for (const name of await fs.readdir(directory))
+            if (/^raw_\d{6}\.(ts|mp3)(\.tmp)?$/.test(name) || name === 'encoder.m3u8.tmp')
+                await fs.unlink(path.join(directory, name)).catch(() => { });
+    }
+}
+export async function remuxRange(generation, destination, signal) {
+    cancelled(signal);
+    if (!generation.complete || !generation.objects.length)
+        throw new Error('Media generation is incomplete');
+    const video = generation.objects[0].extension === 'ts';
+    const extension = video ? 'mp4' : 'mp3';
+    if (path.extname(destination) !== `.${extension}`)
+        throw new Error('Invalid finite media output');
+    const directory = path.dirname(generation.objects[0].file);
+    // Only generated UUID objects in one private directory may enter the internal concat demuxer.
+    for (const object of generation.objects)
+        if (path.dirname(object.file) !== directory || !/^[a-f0-9]{32}\.(ts|mp3)$/.test(path.basename(object.file)))
+            throw new Error('Invalid remux object');
+    const list = path.join(directory, `${identifier()}.ffconcat`);
+    const temp = `${destination}.${identifier()}.tmp`;
+    const total = generation.objects.reduce((sum, item) => sum + item.size, 0);
+    if (total >= MAX_OBJECT_BYTES)
+        throw new Error('Media preview exceeds 512 MiB');
+    try {
+        await fs.writeFile(list, 'ffconcat version 1.0\n' + generation.objects.map(o => `file ${path.basename(o.file)}\n`).join(''), { mode: 0o600, flag: 'wx' });
+        const args = ['-nostdin', '-v', 'error', '-max_alloc', '134217728', '-protocol_whitelist', 'file', '-format_whitelist', 'concat,mpegts,mp3', '-safe', '1', '-f', 'concat', '-i', list,
+            '-map_metadata', '-1', '-c', 'copy', ...(video ? ['-movflags', '+faststart'] : []), '-fs', String(MAX_OBJECT_BYTES), '-f', extension, '-y', temp];
+        await runDecoder(decoderCommand('AXOM_FFMPEG', 'ffmpeg'), args, null, signal);
+        cancelled(signal);
+        const stat = await fs.lstat(temp);
+        if (!stat.isFile() || !stat.size || stat.size >= MAX_OBJECT_BYTES)
+            throw new Error('Media preview exceeds 512 MiB');
+        const etag = await hashFile(temp, signal);
+        await fs.rename(temp, destination);
+        return { id: identifier(), type: 'range', extension, mimeType: video ? 'video/mp4' : 'audio/mpeg', size: stat.size, etag,
+            startMs: generation.sourceOffsetMs, endMs: generation.objects.at(-1).endMs, sequence: 0, timestamp90k: 0, file: destination };
+    }
+    finally {
+        await fs.unlink(list).catch(() => { });
+        await fs.unlink(temp).catch(() => { });
+    }
+}
+async function hashFile(file, signal) {
+    const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const hash = createHash('sha256');
+    try {
+        for await (const chunk of handle.createReadStream({ autoClose: false, highWaterMark: 64 * 1024 })) {
+            cancelled(signal);
+            hash.update(chunk);
+        }
+        return hash.digest('hex');
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/workstation/files/media/estimator.js

@@ -0,0 +1,100 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+const unknown = () => ({ serviceMs: null, firstPlayableMs: null, confidence: 'low', producerSpeed: null });
+const p75 = (values) => values.sort((a, b) => a - b)[Math.ceil(values.length * .75) - 1];
+function valid(o) {
+    return Number.isFinite(o.sourceMs) && o.sourceMs > 0 && o.sourceMs <= 21600000 && Number.isFinite(o.elapsedMs) && o.elapsedMs > 0
+        && Number.isSafeInteger(o.sourceBytes) && o.sourceBytes >= 0 && Number.isFinite(o.finalizationMs) && o.finalizationMs >= 0
+        && (o.startupMs === undefined || (Number.isFinite(o.startupMs) && o.startupMs >= 0 && o.startupMs < o.elapsedMs));
+}
+/** Local bounded history. Queueing is intentionally absent from measured service time. */
+export class MediaEstimator {
+    directory;
+    history;
+    queue = Promise.resolve();
+    constructor(directory, history) {
+        this.directory = directory;
+        this.history = history;
+    }
+    static async load(directory, ffmpegVersion, recipe) {
+        await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+        const stat = await fs.lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()))
+            throw new Error('Unsafe estimate directory');
+        let history = { ffmpegVersion, recipe, buckets: [] };
+        try {
+            const handle = await fs.open(path.join(directory, 'estimates.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const s = await handle.stat();
+                if (s.isFile() && s.size <= 1024 * 1024) {
+                    const data = JSON.parse(await handle.readFile('utf8'));
+                    if (data.ffmpegVersion === ffmpegVersion && data.recipe === recipe && Array.isArray(data.buckets) && data.buckets.length <= 64
+                        && data.buckets.every(b => typeof b.key === 'string' && b.key.length < 1024 && Array.isArray(b.observations) && b.observations.length <= 32 && b.observations.every(valid)))
+                        history = data;
+                }
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch { /* Missing/incompatible history calibrates from the real encode. */ }
+        return new MediaEstimator(directory, history);
+    }
+    bucket(probe) {
+        const mode = probe.preparationPath ?? (probe.kind === 'audio' ? 'audio' : (probe.width ?? 0) > 1280 || (probe.height ?? 0) > 720 ? 'downscale' : 'video');
+        const pixels = (probe.width ?? 0) * (probe.height ?? 0);
+        const pixelClass = pixels === 0 ? 'audio' : pixels <= 1280 * 720 ? '720p' : pixels <= 1920 * 1080 ? '1080p' : pixels <= 3840 * 2160 ? '4k' : 'large';
+        return JSON.stringify([this.history.recipe, mode, pixelClass, probe.codec, probe.audioCodec ?? '', probe.pixelFormat ?? '', (probe.frameRate ?? 0) > 30 ? 'high-fps' : 'standard-fps']);
+    }
+    predict(probe) {
+        if (probe.ffmpegVersion !== this.history.ffmpegVersion || !probe.durationMs || probe.durationMs < 0)
+            return unknown();
+        const observations = this.history.buckets.find(b => b.key === this.bucket(probe))?.observations;
+        if (!observations?.length)
+            return unknown();
+        const encode = p75(observations.map(o => (o.elapsedMs - (o.startupMs ?? 0)) / o.sourceMs));
+        const read = p75(observations.filter(o => o.sourceBytes > 0).map(o => (o.elapsedMs - (o.startupMs ?? 0)) / o.sourceBytes));
+        const startup = p75(observations.map(o => o.startupMs ?? 0));
+        const finish = p75(observations.map(o => o.finalizationMs));
+        const serviceMs = Math.ceil(startup + Math.max(probe.durationMs * encode, Number.isFinite(read) ? probe.sourceBytes * read : 0) + finish);
+        const firstPlayableMs = Math.ceil(startup + Math.min(12000, probe.durationMs) * encode);
+        return { serviceMs, firstPlayableMs, confidence: observations.length >= 2 ? 'high' : 'low', producerSpeed: 1 / encode };
+    }
+    async observe(probe, observation) {
+        if (!valid(observation) || probe.ffmpegVersion !== this.history.ffmpegVersion)
+            throw new Error('Invalid media timing observation');
+        const task = this.queue.then(async () => {
+            const key = this.bucket(probe);
+            let bucket = this.history.buckets.find(b => b.key === key);
+            this.history.buckets = this.history.buckets.filter(b => b !== bucket);
+            bucket ??= { key, observations: [] };
+            bucket.observations.push({ ...observation });
+            bucket.observations = bucket.observations.slice(-32);
+            this.history.buckets.push(bucket);
+            this.history.buckets = this.history.buckets.slice(-64);
+            const temp = path.join(this.directory, `estimates-${randomUUID()}.tmp`);
+            try {
+                await fs.writeFile(temp, JSON.stringify(this.history), { mode: 0o600, flag: 'wx' });
+                await fs.rename(temp, path.join(this.directory, 'estimates.json'));
+            }
+            finally {
+                await fs.unlink(temp).catch(() => { });
+            }
+        });
+        this.queue = task.catch(() => { });
+        return task;
+    }
+}
+export function choosePreparation(estimate, cacheReady, hls, elapsedServiceMs) {
+    if (cacheReady || !hls)
+        return 'range';
+    if (elapsedServiceMs <= 10000) {
+        if (estimate.serviceMs === null)
+            return 'calibrating';
+        if (estimate.serviceMs <= 10000)
+            return 'range';
+    }
+    return estimate.confidence === 'high' && (estimate.producerSpeed ?? 0) >= 1.1 ? 'hls-growing' : 'hls-window';
+}