Clarify QSV support and housekeeping. (#93)

Author: hjdhjd

README.md

@@ -16,7 +16,8 @@ This project provides static FFmpeg binaries for multiple platforms and architec
 Specifically, we provide:
 
 * Audio support using `libfdk-aac`.
-* Hardware-accelerated encoding support on Intel platforms using `h264_qsv` and hardware-accelerated encoding on Raspberry Pi 4+ using `h264_v4l2m2m`.
+* Hardware-accelerated encoding support on Intel platforms using `h264_qsv` **(Windows only)**.
+* Hardware-accelerated encoding support on Raspberry Pi 4+ using `h264_v4l2m2m`.
 * Hardware-accelerated encoding support on Apple platforms using `videotoolbox`.
 
 ## Supported Platforms
@@ -29,6 +30,7 @@ Specifically, we provide:
 | Windows 10 or newer                 | x86_64                         |
 
 > [!NOTE]
+> * **Intel Quick Sync Video is only supported on Windows. There are multiple known issues with `libva` that make it incompatible with static builds of FFmpeg. If you need QSV on Linux, we recommend looking at the [Jellyfin FFmpeg distribution](https://repo.jellyfin.org/?path=/ffmpeg) for distribution-specific releases. We hope to support QSV on Linux once these issues are addressed.**
 > * **Raspberry Pi 5 is currently unsupported. There are multiple known issues with FFmpeg and Raspberry Pi 5 that will hopefully be addressed by the respective teams in the future.**
 > * **Currently (October 2024), FFmpeg v7.1 appears to be somewhat broken for HEVC and H.264 decoding in some scenarios. We hope to support future FFmpeg LTS releases as they stabilize and mature.**
 

build-ffmpeg

@@ -801,12 +801,6 @@ if ${NONFREE_AND_GPL}; then
   CONFIGURE_OPTIONS+=("--enable-libx264")
 fi
 
-#TARGET_OS = alpine
-#TARGET_ARCH = arm32v7
-#OSTYPE = linux-musleabihf
-#
-# if ${NONFREE_AND_GPL} && [[ ! "${TARGET_ARCH}" == "arm"* ]]; then
-#if ${NONFREE_AND_GPL}; then
 if ${NONFREE_AND_GPL} && (isAppleSilicon || [[ ! "${TARGET_ARCH}" == "arm"* ]]) ; then
 
   if build "x265" "latest"; then
@@ -818,16 +812,6 @@ if ${NONFREE_AND_GPL} && (isAppleSilicon || [[ ! "${TARGET_ARCH}" == "arm"* ]])
 
       clone "https://bitbucket.org/multicoreware/x265_git.git" "x265-latest"
     fi
-#    if [[ "${TARGET_OS}" == "darwin" && "${TARGET_ARCH}" == "arm64" ]]; then
-#
-#      download "https://bitbucket.org/multicoreware/x265_git/get/931178347b3f73e40798fd5180209654536bbaa5.tar.gz" "x265-3.5.tar.gz" # This is actually 3.4 if looking at x265Versio
-#    elif [[ "${TARGET_ARCH}" == "arm"* ]]; then
-#
-#      download "https://github.com/videolan/x265/archive/Release_3.5.tar.gz" "x265-3.5.tar.gz" # This is actually 3.4 if looking at x265Version.txt
-#    else
-#
-#      clone "https://bitbucket.org/multicoreware/x265_git.git" "x265-latest"
-#    fi
 
     cd build/linux || exit
     execute cmake -G "Unix Makefiles" ../../source
@@ -957,7 +941,6 @@ if ${NONFREE_AND_GPL}; then
 fi
 
 if [[ ! "${TARGET_ARCH}" == "arm"* ]]; then
-#if [[ ! "${TARGET_OS}" == "raspbian" ]]; then
 
   if build "av1" "bcfe6fb"; then
 
@@ -1341,38 +1324,39 @@ fi
 
 if isLinux && [[ "${TARGET_ARCH}" == "x86_64" ]]; then
 
-  # Intel QSV support.
-  if build "oneVPL" "v2023.3.1"; then
-
-    download "https://github.com/oneapi-src/oneVPL/archive/refs/tags/v2023.3.1.tar.gz" "oneVPL-v2023.3.1.tar.gz"
-
-    make_dir build
-    cd build || exit
-
-    execute cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="${WORKSPACE}" -DCMAKE_INSTALL_BINDIR=bin -DCMAKE_INSTALL_LIBDIR=lib \
-      -DBUILD_DISPATCHER=ON -DBUILD_DEV=ON -DBUILD_PREVIEW=OFF -DBUILD_TOOLS=OFF -DBUILD_TOOLS_ONEVPL_EXPERIMENTAL=OFF -DINSTALL_EXAMPLE_CODE=OFF \
-      -DBUILD_SHARED_LIBS=OFF -DBUILD_TESTS=OFF ..
-    execute cmake --build . --config Release
-    execute cmake --build . --config Release --target install
-
-    build_done "oneVPL" "v2023.3.1"
-  fi
-
-  CONFIGURE_OPTIONS+=("--enable-libvpl")
-
-  # Libva support.
-  if build "libva" "latest"; then
-
-    download "https://github.com/intel/libva/archive/refs/tags/2.20.0.tar.gz" "libva-2.20.0.tar.gz"
-    
-    execute env LIBTOOLIZE="${WORKSPACE}/bin/libtoolize" ./autogen.sh --prefix="${WORKSPACE}" --with-drivers-path="/usr/lib/x86_64-linux-gnu/dri" --enable-static --disable-shared
-    execute make -j ${MJOBS}
-    execute make install
-
-    build_done "libva" "2.20.0"
-  fi
-
-  CONFIGURE_OPTIONS+=("--enable-vaapi")
+#  Unfortunately, libva is broken in static builds of FFmpeg, making QSV out of reach for the time being.
+#  # Intel QSV support.
+#  if build "oneVPL" "v2023.3.1"; then
+#
+#    download "https://github.com/oneapi-src/oneVPL/archive/refs/tags/v2023.3.1.tar.gz" "oneVPL-v2023.3.1.tar.gz"
+#
+#    make_dir build
+#    cd build || exit
+#
+#    execute cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="${WORKSPACE}" -DCMAKE_INSTALL_BINDIR=bin -DCMAKE_INSTALL_LIBDIR=lib \
+#      -DBUILD_DISPATCHER=ON -DBUILD_DEV=ON -DBUILD_PREVIEW=OFF -DBUILD_TOOLS=OFF -DBUILD_TOOLS_ONEVPL_EXPERIMENTAL=OFF -DINSTALL_EXAMPLE_CODE=OFF \
+#      -DBUILD_SHARED_LIBS=OFF -DBUILD_TESTS=OFF ..
+#    execute cmake --build . --config Release
+#    execute cmake --build . --config Release --target install
+#
+#    build_done "oneVPL" "v2023.3.1"
+#  fi
+#
+#  CONFIGURE_OPTIONS+=("--enable-libvpl")
+#
+#  # Libva support.
+#  if build "libva" "latest"; then
+#
+#    download "https://github.com/intel/libva/archive/refs/tags/2.20.0.tar.gz" "libva-2.20.0.tar.gz"
+#    
+#    execute env LIBTOOLIZE="${WORKSPACE}/bin/libtoolize" ./autogen.sh --prefix="${WORKSPACE}" --with-drivers-path="/usr/lib/x86_64-linux-gnu/dri" --enable-static --disable-shared
+#    execute make -j ${MJOBS}
+#    execute make install
+#
+#    build_done "libva" "2.20.0"
+#  fi
+#
+#  CONFIGURE_OPTIONS+=("--enable-vaapi")
 
   if command_exists "nvcc"; then
 

install.js

@@ -26,21 +26,21 @@ function makeFfmpegCacheDir() {
 
 function ensureFfmpegCacheDir() {
 
-  if (!fs.existsSync(ffmpegCache())) {
+  if(!fs.existsSync(ffmpegCache())) {
 
     return makeFfmpegCacheDir();
   }
 }
 
 async function getDownloadFileName() {
 
-  switch (os.platform()) {
+  switch(os.platform()) {
 
     case "darwin":
 
-      if (parseInt(os.release()) >= 22) {
+      if(parseInt(os.release()) >= 22) {
 
-        switch (process.arch) {
+        switch(process.arch) {
 
           case "x64":
 
@@ -59,16 +59,25 @@ async function getDownloadFileName() {
 
       let osReleaseEnv = {};
 
-      if (fs.existsSync("/etc/os-release")) {
+      if(fs.existsSync("/etc/os-release")) {
 
         osReleaseEnv = dotenv.parse(fs.readFileSync("/etc/os-release"));
       }
 
-      switch (process.arch) {
+      switch(process.arch) {
 
-        case "x64": 
+        case "x64":
+
+          switch(osReleaseEnv.VERSION_ID) {
+
+            case "24.04":
+
+              return "ffmpeg-ubuntu-24.04-x86_64.tar.gz";
+
+            default:
 
-          return "ffmpeg-alpine-x86_64.tar.gz";
+              return "ffmpeg-alpine-x86_64.tar.gz";
+          }
 
         case "arm":
 
@@ -85,7 +94,7 @@ async function getDownloadFileName() {
 
     case "freebsd":
 
-      switch (process.arch) {
+      switch(process.arch) {
 
         case "x64":
 
@@ -98,10 +107,10 @@ async function getDownloadFileName() {
 
     case "win32":
 
-      if (process.arch === "x64") {
+      if(process.arch === "x64") {
 
         return "ffmpeg.exe"
-      } 
+      }
 
       return null;
 
@@ -113,7 +122,7 @@ async function getDownloadFileName() {
 
 async function downloadFfmpeg(downloadUrl, ffmpegDownloadPath) {
 
-  // open write stream to download location
+  // Open a write stream to the download location.
   const tempFile = path.resolve(ffmpegCache(), ".download");
   const file = fs.createWriteStream(tempFile);
 
@@ -125,7 +134,7 @@ async function downloadFfmpeg(downloadUrl, ffmpegDownloadPath) {
       url: downloadUrl,
     }, (err, res) => {
 
-      if (err || res.statusCode !== 200) {
+      if(err || res.statusCode !== 200) {
 
         return reject(err);
       }
@@ -139,7 +148,7 @@ async function downloadFfmpeg(downloadUrl, ffmpegDownloadPath) {
         const percent = Math.round((downloadedBytes / totalBytes) * 100) + "%";
         process.stdout.write("\r" + percent);
       });
-      
+
       file.on("finish", () => {
 
         console.log(" - Download Complete");
@@ -183,17 +192,17 @@ function displayErrorMessage() {
 // Attempt to install a working version of FFmpeg for the system we are running on.
 async function install() {
 
-  // ensure the ffmpeg npm cache directory exists
+  // Ensure the FFmpeg npm cache directory exists.
   ensureFfmpegCacheDir();
 
-  // work out the download file name for the current platform
+  // Determine the download file name for the current platform.
   const ffmpegDownloadFileName = await getDownloadFileName();
 
-  if (!ffmpegDownloadFileName) {
+  if(!ffmpegDownloadFileName) {
 
-    if (os.platform() === "darwin" && parseInt(os.release()) < 22) {
+    if(os.platform() === "darwin" && parseInt(os.release()) < 24) {
 
-      console.log("ffmpeg-for-homebridge: macOS versions older than 13 (Ventura) are not supported, you will need to install a working version of FFmpeg manually.");
+      console.log("ffmpeg-for-homebridge: macOS versions older than 15 (Sequoia) are not supported, you will need to install a working version of FFmpeg manually.");
     } else {
 
       console.log("ffmpeg-for-homebridge: %s %s is not supported, you will need to install a working version of FFmpeg manually.", os.platform, process.arch);
@@ -202,62 +211,62 @@ async function install() {
     process.exit(0);
   }
 
-  // the file path where the download should go
+  // The file path where the download will be located.
   const ffmpegDownloadPath = path.resolve(ffmpegCache(), targetFfmpegRelease() + "-" + ffmpegDownloadFileName);
 
-  // construct the download url
+  // Construct the download url.
   const downloadUrl = "https://github.com/homebridge/ffmpeg-for-homebridge/releases/download/" + targetFfmpegRelease() + "/" + ffmpegDownloadFileName;
 
-  // download if not cached
-  if (!fs.existsSync(ffmpegDownloadPath)) {
+  // Download the latest release if it's not been previously cached.
+  if(!fs.existsSync(ffmpegDownloadPath)) {
 
     await downloadFfmpeg(downloadUrl, ffmpegDownloadPath);
   }
 
-  // contruct the path of the temporary ffmpeg binary
+  // Contruct the path of the temporary FFmpeg binary.
   const ffmpegTempPath = path.resolve(ffmpegCache(), os.platform() === "win32" ? "ffmpeg.exe" : "ffmpeg");
   const ffmpegTargetPath = path.resolve(__dirname, os.platform() === "win32" ? "ffmpeg.exe" : "ffmpeg");
 
-  // extract ffmpeg binary from the downloaded tar.gz on non-windows platforms
-  if (os.platform() !== "win32") {
+  // Extract the FFmpeg binary from the downloaded tar.gz bundle on non-windows platforms.
+  if(os.platform() !== "win32") {
 
     try {
 
       await tar.x({
 
         file: ffmpegDownloadPath,
         C: ffmpegCache(),
-        strip: 4, // tar.gz packs ffmpeg into /usr/local/bin - this strips that out
+        strip: 4, // tar.gz packs ffmpeg into /usr/local/bin - this strips that out.
       });
     } catch (e) {
 
       console.error(e);
-      console.error("An error occured while extracting the downloaded ffmpeg binary.");
+      console.error("An error occured while extracting the downloaded FFmpeg binary.");
       displayErrorMessage();
-      
-      // delete the cached download if it failed to extract
+
+      // Delete the cached download if it failed to extract for some reason.
       fs.unlinkSync(ffmpegDownloadPath);
 
       process.exit(0);
     }
 
-    if (fs.existsSync(ffmpegTempPath)) {
+    // Set the execute permissions for FFmpeg.
+    if(fs.existsSync(ffmpegTempPath)) {
 
       fs.chmodSync(ffmpegTempPath, 0o755);
     }
-  }
+  } else {
 
-  // no need to extract for windows - just copy the downloaded binary to the temp path on windows
-  if (os.platform() === "win32") {
+    // There's no need to extract for Windows - we just copy the downloaded binary to the temp path.
 
     fs.renameSync(ffmpegDownloadPath, ffmpegTempPath)
   }
 
   // check if the downloaded binary works
-  if (!binaryOk(ffmpegTempPath)) {
+  if(!binaryOk(ffmpegTempPath)) {
 
     displayErrorMessage();
-    
+
     // delete the cached download if it failed the test
     fs.unlinkSync(ffmpegDownloadPath);
 
@@ -273,14 +282,14 @@ async function install() {
 // Bootstrap the installation process.
 async function bootstrap() {
 
-  console.log("Building for version: %s", targetFfmpegRelease());
+  console.log("Building for version: %s.", targetFfmpegRelease());
 
   try {
 
     await install();
   } catch (e) {
 
-    if (e && e.code && e.code === "EACCES") {
+    if(e && e.code && e.code === "EACCES") {
 
       console.log("Unable to download FFmpeg.\nIf you are installing this plugin as a global module (-g) make sure you add the --unsafe-perm flag to the install command.");
     }

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-for-homebridge",
-  "version": "2.1.4",
+  "version": "2.1.5",
   "description": "Static FFmpeg binaries for Homebridge with support for audio (libfdk-aac) and hardware encoding (h264_v4l2m2m and h264_qsv).",
   "author": {
     "name": "The Homebridge Team",