Detect media files info using ImageMagick and Ffmpeg

app/support/media-files/detect.ts

@@ -0,0 +1,177 @@
+import util from 'util';
+import { open } from 'fs/promises';
+
+import gm from 'gm';
+
+import { spawnAsync } from '../spawn-async';
+
+import { FfprobeResult, MediaInfo, MediaInfoVideo } from './types';
+
+const im = gm.subClass({ imageMagick: true });
+
+export async function detectMediaType(file: string): Promise<MediaInfo> {
+  // Check by file signature
+  const probablyImage = await hasImageSignature(file);
+
+  if (probablyImage) {
+    // Identify using ImageMagick
+    const image = im(file);
+    const identifyAsync = util.promisify<string, string>(image.identify);
+
+    try {
+      const info = await identifyAsync.call(image, '%m %w %h');
+      const parts = info.split(' ');
+      const fmt = parts[0].toLowerCase();
+
+      // Animated images? Only GIF is supported for now
+      if (fmt === 'gif') {
+        const data = await detectAnimatedImage(file);
+
+        if (data) {
+          return { ...data, isAnimatedImage: true };
+        }
+      }
+
+      return {
+        type: 'image',
+        format: fmt,
+        width: parseInt(parts[1], 10),
+        height: parseInt(parts[2], 10),
+      };
+    } catch {
+      return { type: 'general' };
+    }
+  }
+
+  // Identify other types using ffprobe
+  try {
+    const { format, streams } = await runFfprobe(file);
+    const fmt = format.format_name.split(',')[0].toLowerCase();
+
+    const videoStream = streams.find((s) => s.codec_type === 'video');
+    const audioStream = streams.find((s) => s.codec_type === 'audio');
+
+    if (videoStream && format.duration) {
+      return {
+        type: 'video',
+        format: fmt,
+        vCodec: videoStream.codec_name,
+        aCodec: audioStream?.codec_name,
+        duration: parseFloat(format.duration),
+        width: videoStream.width!,
+        height: videoStream.height!,
+        tags: format.tags,
+      };
+    } else if (audioStream && format.duration) {
+      return {
+        type: 'audio',
+        format: fmt,
+        aCodec: audioStream.codec_name,
+        duration: parseFloat(format.duration),
+        tags: format.tags,
+      };
+    }
+
+    return { type: 'general' };
+  } catch {
+    return { type: 'general' };
+  }
+}
+
+async function detectAnimatedImage(file: string): Promise<MediaInfoVideo | null> {
+  const { format, streams } = await runFfprobe(file);
+  const fmt = format.format_name.split(',')[0].toLowerCase();
+
+  const videoStream = streams.find((s) => s.codec_type === 'video');
+
+  if (
+    videoStream &&
+    format.duration &&
+    videoStream.nb_frames &&
+    parseInt(videoStream.nb_frames) > 1
+  ) {
+    return {
+      type: 'video',
+      format: fmt,
+      vCodec: videoStream.codec_name,
+      width: videoStream.width!,
+      height: videoStream.height!,
+      duration: parseFloat(format.duration),
+    };
+  }
+
+  return null;
+}
+
+async function runFfprobe(file: string): Promise<FfprobeResult> {
+  const out = await spawnAsync('ffprobe', [
+    '-hide_banner',
+    '-loglevel',
+    'warning',
+    '-show_format',
+    '-show_streams',
+    '-print_format',
+    'json',
+    '-i',
+    file,
+  ]);
+  return JSON.parse(out.stdout) as FfprobeResult;
+}
+
+async function hasImageSignature(file: string): Promise<boolean> {
+  const fh = await open(file, 'r');
+
+  try {
+    const fileHead = new Uint8Array(16);
+    await fh.read(fileHead);
+    return checkImageSignature(fileHead);
+  } finally {
+    await fh.close();
+  }
+}
+
+function isStartsWith(buf: Uint8Array, codes: number[] | string, offset = 0): boolean {
+  let prefix: Uint8Array;
+
+  if (typeof codes === 'string') {
+    prefix = new TextEncoder().encode(codes);
+  } else {
+    prefix = new Uint8Array(codes);
+  }
+
+  for (let i = 0; i < prefix.length; i++) {
+    if (buf[i + offset] !== prefix[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * We support only those image types: JPEG/JFIF, PNG, WEBP, AVIF, GIF, HEIC and HEIF
+ *
+ * @see https://en.wikipedia.org/wiki/List_of_file_signatures
+ * @see https://legacy.imagemagick.org/api/MagickCore/magic_8c_source.html
+ */
+function checkImageSignature(x: Uint8Array): boolean {
+  return (
+    // JPEG variants
+    isStartsWith(x, [0xff, 0xd8, 0xff]) ||
+    // PNG
+    isStartsWith(x, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]) ||
+    // WEBP
+    (isStartsWith(x, 'RIFF') && isStartsWith(x, 'WEBP', 8)) ||
+    // GIF
+    isStartsWith(x, 'GIF87a') ||
+    isStartsWith(x, 'GIF89a') ||
+    // HEIC/HEIF
+    isStartsWith(x, 'ftypheic', 4) ||
+    isStartsWith(x, 'ftypheix', 4) ||
+    isStartsWith(x, 'ftypmif1', 4) ||
+    // AVIF
+    isStartsWith(x, 'ftypavif', 4) ||
+    // The end
+    false
+  );
+}

app/support/media-files/types.ts

@@ -0,0 +1,58 @@
+export type MediaInfoVisual = {
+  width: number;
+  height: number;
+};
+
+export type MediaInfoPlayable = {
+  duration: number;
+};
+
+export type MediaInfoCommon = {
+  tags?: Record<string, string>;
+};
+
+export type MediaInfoImage = {
+  type: 'image';
+  format: string;
+} & MediaInfoVisual &
+  MediaInfoCommon;
+
+export type MediaInfoVideo = {
+  type: 'video';
+  format: string;
+  vCodec: string;
+  aCodec?: string;
+  isAnimatedImage?: true;
+} & MediaInfoVisual &
+  MediaInfoPlayable &
+  MediaInfoCommon;
+
+export type MediaInfoAudio = {
+  type: 'audio';
+  format: string;
+  aCodec: string;
+} & MediaInfoPlayable &
+  MediaInfoCommon;
+
+export type MediaInfoGeneral = {
+  type: 'general';
+} & MediaInfoCommon;
+
+export type MediaInfo = MediaInfoImage | MediaInfoVideo | MediaInfoAudio | MediaInfoGeneral;
+
+export type Stream = { codec_name: string } & (
+  | {
+      codec_type: 'video';
+      width: number;
+      height: number;
+      nb_frames: string;
+    }
+  | {
+      codec_type: 'audio';
+    }
+);
+
+export type FfprobeResult = {
+  format: { format_name: string; duration: string; tags?: Record<string, string> };
+  streams: Stream[];
+};

app/support/spawn-async.ts

@@ -0,0 +1,34 @@
+import { spawn, type SpawnOptionsWithoutStdio } from 'child_process';
+
+/**
+ * Spawns a child process and returns a promise resolving with its output
+ *
+ * @param {string} command - The command to run.
+ * @param {Array<string>} args - List of string arguments.
+ * @param {SpawnOptionsWithoutStdio} options - Options to pass to the spawn function.
+ * @returns {Promise<{stdout: string, stderr: string}>} - Promise that resolves with the output.
+ */
+export function spawnAsync(
+  command: string,
+  args: readonly string[] = [],
+  options: SpawnOptionsWithoutStdio = {},
+): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, options);
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (data) => (stdout += data.toString()));
+    child.stderr.on('data', (data) => (stderr += data.toString()));
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+      } else {
+        reject(new Error(`Process exited with code ${code}\n${stderr}`));
+      }
+    });
+
+    child.on('error', (err) => reject(err));
+  });
+}

package.json

@@ -121,6 +121,7 @@
     "@types/bytes": "~3.1.4",
     "@types/cache-manager": "~4.0.6",
     "@types/debug": "~4.1.12",
+    "@types/gm": "~1.25.4",
     "@types/humps": "~2.0.6",
     "@types/jsonwebtoken": "~9.0.6",
     "@types/koa": "~2.15.0",

test/fixtures/media-files/README.txt

@@ -0,0 +1,11 @@
+The "squirrel" image has CC0 license and taken from the Pixabay:
+https://pixabay.com/photos/squirrel-tail-bushy-tail-forest-316426/
+
+The "dodecahedron" image has CC license and taken from Wikimedia Commons:
+https://commons.wikimedia.org/wiki/File:256-XX-dodecahedron.gif
+
+The "music" audio has CC0 license and taken from Wikimedia Commons:
+https://commons.wikimedia.org/wiki/File:Piermic_-_Improvisation_with_Sopranino_Recorder_(2015).mp3
+
+The "polyphon" video has CC0 license and taken from Wikimedia Commons:
+https://commons.wikimedia.org/wiki/File:Polyphon-_Kreuz-Polka.ogv