feat(server): transcode bitrate and thread settings

server/immich-openapi-specs.json

@@ -5342,6 +5342,9 @@
           "crf": {
             "type": "string"
           },
+          "threads": {
+            "type": "string"
+          },
           "preset": {
             "type": "string"
           },
@@ -5354,6 +5357,9 @@
           "targetResolution": {
             "type": "string"
           },
+          "maxBitrate": {
+            "type": "string"
+          },
           "transcode": {
             "type": "string",
             "enum": [
@@ -5366,10 +5372,12 @@
         },
         "required": [
           "crf",
+          "threads",
           "preset",
           "targetVideoCodec",
           "targetAudioCodec",
           "targetResolution",
+          "maxBitrate",
           "transcode"
         ]
       },

server/libs/domain/src/media/media.service.ts

@@ -221,10 +221,9 @@ export class MediaService {
 
   private getFfmpegOptions(stream: VideoStreamInfo, ffmpeg: SystemConfigFFmpegDto) {
     const options = [
-      `-crf ${ffmpeg.crf}`,
-      `-preset ${ffmpeg.preset}`,
       `-vcodec ${ffmpeg.targetVideoCodec}`,
       `-acodec ${ffmpeg.targetAudioCodec}`,
+      `-threads ${ffmpeg.threads}`,
       // Makes a second pass moving the moov atom to the beginning of
       // the file for improved playback speed.
       `-movflags faststart`,
@@ -241,6 +240,47 @@ export class MediaService {
       options.push(`-vf scale=${scaling}`);
     }
 
+    const isVP9 = ffmpeg.targetVideoCodec === 'vp9';
+    const isH264 = ffmpeg.targetVideoCodec === 'h264';
+    const isH265 = ffmpeg.targetVideoCodec === 'hevc';
+
+    if (isH264 || isH265) {
+      options.push(`-preset ${ffmpeg.preset}`);
+
+      // x264 and x265 handle threads differently than one might expect
+      // https://x265.readthedocs.io/en/latest/cli.html#cmdoption-pools
+      options.push(`-${isH265 ? 'x265' : 'x264'}-params "pools=none"`);
+      options.push(`-${isH265 ? 'x265' : 'x264'}-params "frame-threads=${ffmpeg.threads}"`);
+    }
+
+    if (isVP9) {
+      // vp9 doesn't have presets, but does have a similar setting -cpu-used, from 0-5, 0 being the slowest
+      const presets = ['veryslow', 'slower', 'slow', 'medium', 'fast', 'faster', 'veryfast', 'superfast', 'ultrafast'];
+      const speed = Math.min(presets.indexOf(ffmpeg.preset), 5); // values over 5 require realtime mode, which is its own can of worms since it overrides -crf and -threads
+      if (speed >= 0) {
+        options.push(`-cpu-used ${speed}`);
+      }
+      options.push('-row-mt 1'); // better multithreading
+    }
+
+    const twoPass = process.env.ENABLE_TWO_PASS?.toLowerCase() === 'true';
+
+    const maxBitrateValue = Number.parseInt(ffmpeg.maxBitrate);
+    const validMaxRate = maxBitrateValue && maxBitrateValue > 0;
+    const bitrateUnit = ffmpeg.maxBitrate.substring(maxBitrateValue.toString().length) || 'k'; // use inputted unit if provided, else default to kbps
+
+    if (validMaxRate && twoPass) {
+      const targetBitrateValue = maxBitrateValue / 1.45; // recommended by https://developers.google.com/media/vp9/settings/vod
+      const minBitrateValue = targetBitrateValue / 2;
+
+      options.push(`-b:v ${targetBitrateValue}${bitrateUnit}`);
+      options.push(`-minrate ${minBitrateValue}${bitrateUnit}`);
+      options.push(`-maxrate ${maxBitrateValue}${bitrateUnit}`);
+    } else if (validMaxRate) {
+      options.push(`-crf ${ffmpeg.crf}`);
+      options.push(`${isVP9 ? '-b:v' : '-maxrate'} ${maxBitrateValue}${bitrateUnit}`);
+    }
+
     return options;
   }
 }

server/libs/domain/src/system-config/dto/system-config-ffmpeg.dto.ts

@@ -5,6 +5,9 @@ export class SystemConfigFFmpegDto {
   @IsString()
   crf!: string;
 
+  @IsString()
+  threads!: string;
+
   @IsString()
   preset!: string;
 
@@ -17,6 +20,9 @@ export class SystemConfigFFmpegDto {
   @IsString()
   targetResolution!: string;
 
+  @IsString()
+  maxBitrate!: string;
+
   @IsEnum(TranscodePreset)
   transcode!: TranscodePreset;
 }

server/libs/domain/src/system-config/system-config.core.ts

@@ -10,10 +10,12 @@ export type SystemConfigValidator = (config: SystemConfig) => void | Promise<voi
 const defaults: SystemConfig = Object.freeze({
   ffmpeg: {
     crf: '23',
+    threads: '2',
     preset: 'ultrafast',
     targetVideoCodec: 'h264',
     targetAudioCodec: 'aac',
     targetResolution: '720',
+    maxBitrate: '4500k',
     transcode: TranscodePreset.REQUIRED,
   },
   oauth: {

server/libs/domain/src/system-config/system-config.service.spec.ts

@@ -14,10 +14,12 @@ const updates: SystemConfigEntity[] = [
 const updatedConfig = Object.freeze({
   ffmpeg: {
     crf: 'a new value',
+    threads: '2',
     preset: 'ultrafast',
     targetAudioCodec: 'aac',
     targetResolution: '720',
     targetVideoCodec: 'h264',
+    maxBitrate: '4500k',
     transcode: TranscodePreset.REQUIRED,
   },
   oauth: {

server/libs/domain/test/fixtures.ts

@@ -431,10 +431,12 @@ export const systemConfigStub = {
   defaults: Object.freeze({
     ffmpeg: {
       crf: '23',
+      threads: '2',
       preset: 'ultrafast',
       targetAudioCodec: 'aac',
       targetResolution: '720',
       targetVideoCodec: 'h264',
+      maxBitrate: '4500k',
       transcode: TranscodePreset.REQUIRED,
     },
     oauth: {

server/libs/infra/src/entities/system-config.entity.ts

@@ -14,10 +14,12 @@ export type SystemConfigValue = any;
 // dot notation matches path in `SystemConfig`
 export enum SystemConfigKey {
   FFMPEG_CRF = 'ffmpeg.crf',
+  FFMPEG_THREADS = 'ffmpeg.threads',
   FFMPEG_PRESET = 'ffmpeg.preset',
   FFMPEG_TARGET_VIDEO_CODEC = 'ffmpeg.targetVideoCodec',
   FFMPEG_TARGET_AUDIO_CODEC = 'ffmpeg.targetAudioCodec',
   FFMPEG_TARGET_RESOLUTION = 'ffmpeg.targetResolution',
+  FFMPEG_MAX_BITRATE = 'ffmpeg.maxBitrate',
   FFMPEG_TRANSCODE = 'ffmpeg.transcode',
   OAUTH_ENABLED = 'oauth.enabled',
   OAUTH_ISSUER_URL = 'oauth.issuerUrl',
@@ -43,10 +45,12 @@ export enum TranscodePreset {
 export interface SystemConfig {
   ffmpeg: {
     crf: string;
+    threads: string;
     preset: string;
     targetVideoCodec: string;
     targetAudioCodec: string;
     targetResolution: string;
+    maxBitrate: string;
     transcode: TranscodePreset;
   };
   oauth: {

server/libs/infra/src/repositories/media.repository.ts

@@ -3,6 +3,7 @@ import { exiftool } from 'exiftool-vendored';
 import ffmpeg, { FfprobeData } from 'fluent-ffmpeg';
 import sharp from 'sharp';
 import { promisify } from 'util';
+import * as fs from 'fs/promises';
 
 const probe = promisify<string, FfprobeData>(ffmpeg.ffprobe);
 
@@ -86,13 +87,39 @@ export class MediaRepository implements IMediaRepository {
   }
 
   transcode(input: string, output: string, options: string[]): Promise<void> {
+    if (!(process.env.ENABLE_TWO_PASS?.toLowerCase() === 'true')) {
+      return new Promise((resolve, reject) => {
+        ffmpeg(input, { niceness: 10 })
+          .outputOptions(options)
+          .output(output)
+          .on('error', reject)
+          .on('end', resolve)
+          .run();
+      });
+    }
+
+    // two-pass allows for precise control of bitrate at the cost of running twice
+    // recommended for vp9 for better quality and compression
     return new Promise((resolve, reject) => {
       ffmpeg(input, { niceness: 10 })
-        //
         .outputOptions(options)
-        .output(output)
+        .addOptions('-pass', '1')
+        .addOptions('-passlogfile', output)
+        .addOptions('-f null')
+        .output('/dev/null') // first pass output is not saved as only the .log file is needed
         .on('error', reject)
-        .on('end', resolve)
+        .on('end', () => {
+          // second pass
+          ffmpeg(input, { niceness: 10 })
+            .outputOptions(options)
+            .addOptions('-pass', '2')
+            .addOptions('-passlogfile', output)
+            .output(output)
+            .on('error', reject)
+            .on('end', () => fs.unlink(`${output}-0.log`))
+            .on('end', resolve)
+            .run();
+        })
         .run();
     });
   }