metamesh-plugin-still-extractor/test/still.test.ts

/**
 * Still Extractor Plugin Tests
 *
 * Pure helpers run anywhere; the extraction tests need ffmpeg and the
 * generated fixtures, so they run in the test container (./test.sh).
 */

import { describe, it, expect, beforeAll } from 'vitest';
import { execSync } from 'child_process';
import { existsSync, mkdirSync } from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';

import {
    manifest,
    process as processFile,
    candidateOffsets,
    frameStats,
    isUsableFrame,
    sanitizeFilename,
    stillFilename,
    computeMidHash256FromBuffer,
    selectPrimaryVideoStream,
    extractStill,
    grabFrame,
} from '../src/plugin.js';
import type { CallbackPayload } from '../src/types.js';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const FIXTURES = path.join(__dirname, 'fixtures');
const TEMP = '/tmp/still-extractor-test';

function hasFfmpeg(): boolean {
    try {
        execSync('ffmpeg -version', { stdio: 'ignore' });
        return true;
    } catch {
        return false;
    }
}

function fixture(name: string): string {
    return path.join(FIXTURES, name);
}

/** Build the `stream/{n}` table exactly the way the ffmpeg plugin writes it. */
function streamTableFor(file: string): Record<string, string> {
    const probe = JSON.parse(
        execSync(`ffprobe -v quiet -print_format json -show_streams "${file}"`, { encoding: 'utf-8' })
    ) as { streams: Array<Record<string, unknown>> };

    const table: Record<string, string> = {};
    let n = 0;
    for (const s of probe.streams) {
        if (s.codec_type !== 'video' && s.codec_type !== 'audio' && s.codec_type !== 'subtitle') continue;
        const entry: Record<string, unknown> = { type: s.codec_type };
        if (s.codec_name) entry.codec = String(s.codec_name);
        if (s.index != null) entry.index = s.index;
        if (s.width) entry.width = s.width;
        if (s.height) entry.height = s.height;
        // The ffmpeg plugin drops avg_frame_rate when it is "0/0" — the very
        // signal we lean on to spot attached cover art.
        if (s.avg_frame_rate && s.avg_frame_rate !== '0/0') entry.frameRate = String(s.avg_frame_rate);
        table[`stream/${n}`] = JSON.stringify(entry);
        n++;
    }
    return table;
}

const ffmpegAvailable = hasFfmpeg();
const fixturesReady = existsSync(fixture('color.mp4'));

describe('manifest', () => {
    it('declares its dependencies and queue', () => {
        expect(manifest.id).toBe('still-extractor');
        expect(manifest.dependencies).toEqual(['file-info', 'ffmpeg']);
        expect(manifest.defaultQueue).toBe('background');
        expect(manifest.schema?.still).toBeDefined();
    });

    it('does not advertise writing poster or stillPath', () => {
        const keys = Object.keys(manifest.schema ?? {});
        expect(keys).toEqual(['still']);
    });
});

describe('candidateOffsets', () => {
    it('spreads candidates through the middle of the file', () => {
        expect(candidateOffsets(100, [20, 45, 70])).toEqual([20, 45, 70]);
    });

    it('keeps away from both ends', () => {
        const offsets = candidateOffsets(10, [1, 50, 99]);
        for (const t of offsets) {
            expect(t).toBeGreaterThanOrEqual(2);
            expect(t).toBeLessThanOrEqual(8);
        }
    });

    it('falls back to a blind attempt when duration is unknown', () => {
        expect(candidateOffsets(undefined)).toEqual([10, 0]);
        expect(candidateOffsets(0)).toEqual([10, 0]);
    });

    it('takes the midpoint of a very short clip', () => {
        expect(candidateOffsets(3)).toEqual([1.5]);
    });

    it('deduplicates offsets that clamp onto each other', () => {
        const offsets = candidateOffsets(6, [10, 12, 14]);
        expect(new Set(offsets).size).toBe(offsets.length);
    });
});

describe('frameStats / isUsableFrame', () => {
    it('measures a flat buffer as zero-variance', () => {
        const stats = frameStats(Buffer.alloc(1024, 128));
        expect(stats.mean).toBe(128);
        expect(stats.stddev).toBe(0);
    });

    it('rejects black, white and flat frames', () => {
        expect(isUsableFrame({ mean: 2, stddev: 1 })).toBe(false);    // black
        expect(isUsableFrame({ mean: 252, stddev: 1 })).toBe(false);  // blown out
        expect(isUsableFrame({ mean: 128, stddev: 2 })).toBe(false);  // flat grey
    });

    it('accepts a frame with real detail', () => {
        expect(isUsableFrame({ mean: 110, stddev: 45 })).toBe(true);
    });
});

describe('filenames', () => {
    it('strips path-hostile characters', () => {
        expect(sanitizeFilename('a/b:c*d?')).toBe('abcd');
    });

    it('carries the source CID so two files cannot collide', () => {
        const a = stillFilename('/files/watch/Show/episode.mkv', 'bafkreiaaaaaaaaaaaa111111');
        const b = stillFilename('/files/watch/Other/episode.mkv', 'bafkreiaaaaaaaaaaaa222222');
        expect(a).not.toBe(b);
        expect(a.endsWith('_still.jpg')).toBe(true);
        expect(a.startsWith('episode[')).toBe(true);
    });
});

describe('computeMidHash256FromBuffer', () => {
    // Vector produced by packages/meta-hash's own computeMidHash256Sync over a
    // file holding exactly this string. This function is a hand-rolled copy of
    // that algorithm; the vector is what pins the copy to the original.
    it('matches meta-hash for a known buffer', () => {
        const cid = computeMidHash256FromBuffer(Buffer.from('metamesh-still-extractor-cid-vector'));
        expect(cid).toBe('bagacbabaecybg7wcyxl7su3dvjleuwgwil5tgeoybrwc35jasqtywb6bnjzk4');
    });
});

describe('selectPrimaryVideoStream', () => {
    it('returns null when there is no video stream', () => {
        expect(selectPrimaryVideoStream({
            'stream/0': JSON.stringify({ type: 'audio', index: 0, codec: 'aac' }),
        })).toBeNull();
        expect(selectPrimaryVideoStream(undefined)).toBeNull();
        expect(selectPrimaryVideoStream({})).toBeNull();
    });

    it('reads the flattened `stream` array form too', () => {
        const picked = selectPrimaryVideoStream({
            stream: JSON.stringify([
                JSON.stringify({ type: 'audio', index: 0 }),
                JSON.stringify({ type: 'video', index: 1, width: 1920, height: 1080, codec: 'h264', frameRate: '24/1' }),
            ]),
        } as unknown as Record<string, string>);
        expect(picked?.index).toBe(1);
    });

    it('prefers the larger of two real video streams', () => {
        const picked = selectPrimaryVideoStream({
            'stream/0': JSON.stringify({ type: 'video', index: 0, width: 640, height: 480, codec: 'h264', frameRate: '24/1' }),
            'stream/1': JSON.stringify({ type: 'video', index: 1, width: 1920, height: 1080, codec: 'h264', frameRate: '24/1' }),
        });
        expect(picked?.index).toBe(1);
    });

    it('ignores a bigger cover art stream in favour of the moving picture', () => {
        const picked = selectPrimaryVideoStream({
            'stream/0': JSON.stringify({ type: 'video', index: 0, width: 320, height: 240, codec: 'h264', frameRate: '24/1' }),
            // attached_pic: no frameRate, still-image codec, but much larger
            'stream/1': JSON.stringify({ type: 'video', index: 1, width: 600, height: 900, codec: 'mjpeg' }),
        });
        expect(picked?.index).toBe(0);
    });

    it('still returns something when nothing looks like moving video', () => {
        const picked = selectPrimaryVideoStream({
            'stream/0': JSON.stringify({ type: 'video', index: 0, width: 600, height: 900, codec: 'mjpeg' }),
        });
        expect(picked?.index).toBe(0);
    });

    it.skipIf(!ffmpegAvailable || !fixturesReady)(
        'picks the film, not the cover, on a real file',
        () => {
            const picked = selectPrimaryVideoStream(streamTableFor(fixture('cover-art.mp4')));
            expect(picked).not.toBeNull();
            expect(picked!.width).toBe(320);
            expect(picked!.height).toBe(240);
        }
    );
});

describe.skipIf(!ffmpegAvailable || !fixturesReady)('extraction', () => {
    beforeAll(() => {
        mkdirSync(TEMP, { recursive: true });
    });

    it('extracts a usable frame from a colourful video', async () => {
        const result = await extractStill(fixture('color.mp4'), 0, 10, TEMP);
        expect(result).not.toBeNull();
        expect(result!.jpeg.subarray(0, 2)).toEqual(Buffer.from([0xff, 0xd8])); // JPEG SOI
        expect(isUsableFrame(result!.stats)).toBe(true);
    });

    it('skips past a black head to a later offset', async () => {
        // 20s file, 6s of black: the 20% candidate (4s) is black and must lose.
        const result = await extractStill(fixture('black-head.mp4'), 0, 20, TEMP);
        expect(result).not.toBeNull();
        expect(result!.offsetSec).toBeGreaterThan(6);
        expect(isUsableFrame(result!.stats)).toBe(true);
    });

    it('returns null for a file with nothing to decode', async () => {
        const frame = await grabFrame(fixture('audio-only.mp3'), 0, 1, path.join(TEMP, 'nope.jpg'));
        expect(frame).toBeNull();
    });

    it('scales the frame down to the configured width', async () => {
        const result = await extractStill(fixture('color.mp4'), 0, 10, TEMP);
        expect(result).not.toBeNull();
        // Source is 320x240, below the 640 cap, so it must come back untouched.
        expect(result!.jpeg.length).toBeGreaterThan(0);
        expect(result!.jpeg.length).toBeLessThan(200_000);
    });
});

describe('process - skip logic', () => {
    const collect = () => {
        const seen: CallbackPayload[] = [];
        return { seen, cb: async (p: CallbackPayload) => { seen.push(p); } };
    };

    const req = (existingMeta: Record<string, string>) => ({
        taskId: 't1',
        cid: 'bafkreitest',
        filePath: '/files/watch/test.mkv',
        callbackUrl: 'http://localhost/callback',
        // Unreachable on purpose: every case here must bail before any I/O.
        metaCoreUrl: 'http://127.0.0.1:9',
        existingMeta,
    });

    it('skips non-video files', async () => {
        const { seen, cb } = collect();
        await processFile(req({ fileType: 'image' }), cb);
        expect(seen[0].status).toBe('skipped');
        expect(seen[0].reason).toBe('Not a video file');
    });

    it('skips a record that already has a still', async () => {
        const { seen, cb } = collect();
        await processFile(req({ fileType: 'video', still: 'bafkreialready' }), cb);
        expect(seen[0].status).toBe('skipped');
        expect(seen[0].reason).toBe('Still already present');
    });

    it('skips when there is no video stream', async () => {
        const { seen, cb } = collect();
        await processFile(
            req({ fileType: 'video', 'stream/0': JSON.stringify({ type: 'audio', index: 0 }) }),
            cb
        );
        expect(seen[0].status).toBe('skipped');
        expect(seen[0].reason).toBe('No video stream');
    });
});