Package native installers with bundled ffmpeg

Author: yibailiu

.github/workflows/build-and-release.yml

@@ -22,13 +22,13 @@ jobs:
         include:
           - os: windows-latest
             artifact_name: VideoMergingTool-windows-x64
-            binary_name: VideoMergingTool.exe
+            package_path: dist/installer/VideoMergingTool-Setup.exe
           - os: macos-latest
             artifact_name: VideoMergingTool-macos-arm64
-            binary_name: VideoMergingTool.app
+            package_path: dist/VideoMergingTool.dmg
           - os: ubuntu-latest
             artifact_name: VideoMergingTool-linux-x64
-            binary_name: VideoMergingTool
+            package_path: dist/VideoMergingTool
 
     steps:
       - name: Checkout
@@ -42,58 +42,33 @@ jobs:
       - name: Install build dependencies
         run: python -m pip install -r requirements-build.txt
 
+      - name: Install Inno Setup on Windows
+        if: runner.os == 'Windows'
+        run: choco install innosetup --no-progress -y
+
       - name: Build executable on Windows
         if: runner.os == 'Windows'
-        run: pyinstaller --onefile --windowed --clean --noconfirm --name VideoMergingTool --icon assets/icons/VideoMergingTool.ico --collect-all typer --collect-all click --collect-all rich --collect-all webview --collect-all certifi --hidden-import videomerge.gui --hidden-import tkinter main.py
+        shell: pwsh
+        run: .\scripts\build_windows.ps1
 
       - name: Build app on macOS
         if: runner.os == 'macOS'
-        run: pyinstaller --windowed --clean --noconfirm --name VideoMergingTool --icon assets/icons/VideoMergingTool.icns --collect-all typer --collect-all click --collect-all rich --collect-all webview --collect-all certifi --hidden-import videomerge.gui --hidden-import tkinter main.py
+        run: bash scripts/build_local.sh
 
       - name: Build executable on Linux
         if: runner.os == 'Linux'
-        run: pyinstaller --onefile --windowed --clean --noconfirm --name VideoMergingTool --icon assets/icons/VideoMergingTool.png --collect-all typer --collect-all click --collect-all rich --collect-all webview --collect-all certifi --hidden-import videomerge.gui --hidden-import tkinter main.py
-
-      - name: Prepare artifact on Windows
-        if: runner.os == 'Windows'
-        shell: pwsh
-        run: |
-          New-Item -ItemType Directory -Force package
-          Copy-Item "dist\${{ matrix.binary_name }}" "package\${{ matrix.binary_name }}"
-          Copy-Item README.md package\
-          Compress-Archive -Path package\* -DestinationPath "${{ matrix.artifact_name }}.zip" -Force
-
-      - name: Prepare artifact on Unix
-        if: runner.os == 'Linux'
-        shell: bash
-        run: |
-          mkdir -p package
-          cp "dist/${{ matrix.binary_name }}" "package/${{ matrix.binary_name }}"
-          cp README.md package/
-          tar -czf "${{ matrix.artifact_name }}.tar.gz" -C package .
-
-      - name: Prepare artifact on macOS
-        if: runner.os == 'macOS'
-        shell: bash
-        run: |
-          hdiutil create -volname VideoMergingTool -srcfolder "dist/VideoMergingTool.app" -ov -format UDZO "${{ matrix.artifact_name }}.dmg"
+        run: bash scripts/build_local.sh
 
       - name: Upload build artifact
         uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.artifact_name }}
-          path: |
-            *.zip
-            *.tar.gz
-            *.dmg
+          path: ${{ matrix.package_path }}
           if-no-files-found: error
 
       - name: Upload release asset
         if: startsWith(github.ref, 'refs/tags/v')
         uses: softprops/action-gh-release@v2
         with:
-          files: |
-            *.zip
-            *.tar.gz
-            *.dmg
+          files: ${{ matrix.package_path }}
           generate_release_notes: true

README.md

@@ -4,7 +4,7 @@
 
 本地批量视频智能合并工具。当前版本提供可点击启动的桌面 GUI，同时保留 CLI；内部模块按扫描、探测、分组、转码、合并拆分。
 
-底层依赖 FFmpeg / FFprobe。程序启动时会优先查找已下载的本地二进制和系统已有二进制；缺失时默认尝试下载安装到可写目录，避免普通用户手动配置环境变量。
+桌面安装包内置精简 FFmpeg / FFprobe 二进制，普通用户安装后即可使用，不需要手动配置环境变量。
 
 ## 功能
 
@@ -22,11 +22,11 @@
 
 ## 普通用户用法
 
-推荐直接下载 GitHub Release 里的安装包或压缩包。
+推荐直接下载 GitHub Release 里的安装包。
 
-- Windows：运行 `VideoMergingTool.exe`，或使用 `VideoMergingTool-Setup.exe` 安装后从开始菜单/桌面图标启动。
+- Windows：运行 `VideoMergingTool-Setup.exe` 安装后从开始菜单/桌面图标启动。
 - macOS：打开 `VideoMergingTool.dmg`，将 `VideoMergingTool.app` 拖入 Applications 后从图标启动。
-- Linux：解压后运行 `VideoMergingTool`。
+- Linux：运行 `VideoMergingTool`。
 
 桌面应用和安装包会使用 `assets/icons/VideoMergingTool.*` 中的应用图标。
 
@@ -44,7 +44,7 @@ macOS / Linux CLI 示例：
 ./VideoMergingTool merge ~/Videos --mode fast
 ```
 
-如果当前机器没有 FFmpeg / FFprobe，程序会默认尝试自动下载。源码运行时下载到当前运行目录的 `.tools/ffmpeg`；打包后的桌面应用会下载到用户可写的应用数据目录，避免 macOS app 只读目录报错。
+源码运行时仍会在缺少 FFmpeg / FFprobe 时尝试下载到当前运行目录的 `.tools/ffmpeg`。打包后的桌面应用优先使用应用内置的 FFmpeg / FFprobe。
 
 ## 开发者运行方式
 
@@ -164,21 +164,22 @@ Extreme 模式对全部文件选择一个最终画布和编码策略，消解 ro
 
 如果文件已存在且未传 `--overwrite`，会自动追加 `_1`、`_2` 等后缀。
 
-## 依赖自动检测和下载
+## FFmpeg 检测
 
 默认行为：
 
-1. 查找本地工具目录。源码运行时是 `./.tools/ffmpeg`，打包应用是用户应用数据目录。
-2. 查找系统 `PATH`
-3. 如果缺失，尝试下载静态 FFmpeg/FFprobe。源码运行时使用 `./.tools/ffmpeg`，打包应用使用用户应用数据目录。
+1. 打包应用优先使用应用内置的 `ffmpeg` / `ffprobe`
+2. 源码运行时查找本地工具目录 `./.tools/ffmpeg`
+3. 查找系统 `PATH` 和常见安装路径
+4. 源码运行时如果仍缺失，尝试下载静态 FFmpeg / FFprobe
 
 自动下载地址按平台选择：
 
 - macOS: evermeet.cx FFmpeg builds
 - Windows: gyan.dev FFmpeg essentials build
 - Linux: johnvansickle.com static build
 
-如果网络不可用或下载源不可达，可以手动安装 FFmpeg，或用 `--ffmpeg-path` 和 `--ffprobe-path` 指定二进制路径。
+如果源码运行时网络不可用或下载源不可达，可以手动安装 FFmpeg，或用 `--ffmpeg-path` 和 `--ffprobe-path` 指定二进制路径。
 
 ## 本地打包为独立可执行文件
 
@@ -192,7 +193,7 @@ Windows PowerShell:
 
 ```text
 dist\VideoMergingTool.exe
-dist\installer\VideoMergingTool-Setup.exe   # 已安装 Inno Setup 时生成
+dist\installer\VideoMergingTool-Setup.exe
 ```
 
 macOS / Linux:
@@ -220,7 +221,7 @@ dist/VideoMergingTool       # Linux
 自动行为：
 
 - 推送到 `main`：自动构建 Windows、macOS、Linux 三个平台的可执行文件，并上传到 Actions Artifacts
-- 推送版本 tag，例如 `v0.1.0`：自动构建三个平台，并创建 GitHub Release，附带压缩包
+- 推送版本 tag，例如 `v0.1.0`：自动构建三个平台，并创建 GitHub Release，附带 `.dmg`、Windows 安装 `.exe` 和 Linux 可执行文件
 - 手动触发 workflow：可在 GitHub Actions 页面点击 `Run workflow`
 
 发布新版本：
@@ -232,9 +233,9 @@ git push origin v0.1.0
 
 发布后，用户可以在 GitHub 仓库的 Releases 页面下载：
 
-- `VideoMergingTool-windows-x64.zip`
-- `VideoMergingTool-macos-arm64.tar.gz`
-- `VideoMergingTool-linux-x64.tar.gz`
+- `VideoMergingTool-Setup.exe`
+- `VideoMergingTool.dmg`
+- `VideoMergingTool`
 
 ## 平台说明
 

assets/icons/VideoMergingTool.icns

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import struct
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SOURCE = ROOT / "assets/icons/VideoMergingTool.png"
+ICNS = ROOT / "assets/icons/VideoMergingTool.icns"
+ICO = ROOT / "assets/icons/VideoMergingTool.ico"
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp = Path(temp_dir)
+        icns_chunks = []
+        for size, chunk_type in (
+            (16, b"icp4"),
+            (32, b"icp5"),
+            (64, b"icp6"),
+            (128, b"ic07"),
+            (256, b"ic08"),
+            (512, b"ic09"),
+            (1024, b"ic10"),
+        ):
+            data = _png_at(size, temp / f"icns_{size}.png")
+            icns_chunks.append(chunk_type + struct.pack(">I", len(data) + 8) + data)
+        ICNS.write_bytes(b"icns" + struct.pack(">I", 8 + sum(len(chunk) for chunk in icns_chunks)) + b"".join(icns_chunks))
+
+        ico_blobs = [(size, _png_at(size, temp / f"ico_{size}.png")) for size in (16, 24, 32, 48, 64, 128, 256)]
+        entries = []
+        offset = 6 + 16 * len(ico_blobs)
+        for size, data in ico_blobs:
+            width = 0 if size >= 256 else size
+            height = 0 if size >= 256 else size
+            entries.append(struct.pack("<BBBBHHII", width, height, 0, 0, 1, 32, len(data), offset))
+            offset += len(data)
+        with ICO.open("wb") as file:
+            file.write(struct.pack("<HHH", 0, 1, len(ico_blobs)))
+            for entry in entries:
+                file.write(entry)
+            for _, data in ico_blobs:
+                file.write(data)
+
+
+def _png_at(size: int, output: Path) -> bytes:
+    subprocess.run(
+        [
+            "ffmpeg",
+            "-y",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-i",
+            str(SOURCE),
+            "-vf",
+            f"scale={size}:{size}",
+            "-pix_fmt",
+            "rgba",
+            str(output),
+        ],
+        check=True,
+    )
+    return output.read_bytes()
+
+
+if __name__ == "__main__":
+    main()

assets/icons/VideoMergingTool.ico

@@ -5,6 +5,7 @@ NAME="${1:-VideoMergingTool}"
 PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 ICON_PNG="$PROJECT_ROOT/assets/icons/VideoMergingTool.png"
 ICON_ICNS="$PROJECT_ROOT/assets/icons/VideoMergingTool.icns"
+VENDOR_FFMPEG_DIR="$PROJECT_ROOT/build/vendor/ffmpeg"
 cd "$PROJECT_ROOT"
 
 python3 -m venv .venv
@@ -13,6 +14,8 @@ python3 -m venv .venv
 
 rm -rf build
 
+./.venv/bin/python scripts/prepare_ffmpeg.py --output "$VENDOR_FFMPEG_DIR" --force
+
 PYINSTALLER_ARGS=(
   --clean
   --noconfirm
@@ -27,18 +30,34 @@ PYINSTALLER_ARGS=(
 )
 
 if [[ "$(uname -s)" == "Darwin" ]]; then
-  PYINSTALLER_ARGS+=(--windowed --icon "$ICON_ICNS")
+  PYINSTALLER_ARGS+=(
+    --windowed
+    --icon "$ICON_ICNS"
+    --add-binary "$VENDOR_FFMPEG_DIR/ffmpeg:ffmpeg"
+    --add-binary "$VENDOR_FFMPEG_DIR/ffprobe:ffmpeg"
+  )
 else
-  PYINSTALLER_ARGS+=(--onefile --windowed --icon "$ICON_PNG")
+  PYINSTALLER_ARGS+=(
+    --onefile
+    --windowed
+    --icon "$ICON_PNG"
+    --add-binary "$VENDOR_FFMPEG_DIR/ffmpeg:ffmpeg"
+    --add-binary "$VENDOR_FFMPEG_DIR/ffprobe:ffmpeg"
+  )
 fi
 
 ./.venv/bin/pyinstaller "${PYINSTALLER_ARGS[@]}" main.py
 
 echo
 if [[ "$(uname -s)" == "Darwin" && -d "$PROJECT_ROOT/dist/$NAME.app" ]]; then
   DMG_PATH="$PROJECT_ROOT/dist/$NAME.dmg"
+  DMG_ROOT="$PROJECT_ROOT/build/dmg-root"
   rm -f "$DMG_PATH"
-  hdiutil create -volname "$NAME" -srcfolder "$PROJECT_ROOT/dist/$NAME.app" -ov -format UDZO "$DMG_PATH"
+  rm -rf "$DMG_ROOT"
+  mkdir -p "$DMG_ROOT"
+  cp -R "$PROJECT_ROOT/dist/$NAME.app" "$DMG_ROOT/"
+  ln -s /Applications "$DMG_ROOT/Applications"
+  hdiutil create -volname "$NAME" -srcfolder "$DMG_ROOT" -ov -format UDZO "$DMG_PATH"
   echo "Build complete: $PROJECT_ROOT/dist/$NAME.app"
   echo "Installer image: $DMG_PATH"
 else

scripts/build_icons.py

@@ -7,6 +7,7 @@ $ErrorActionPreference = "Stop"
 $ProjectRoot = Resolve-Path "$PSScriptRoot\.."
 Set-Location $ProjectRoot
 $IconPath = Join-Path $ProjectRoot "assets\icons\VideoMergingTool.ico"
+$VendorFfmpegDir = Join-Path $ProjectRoot "build\vendor\ffmpeg"
 
 if (-not (Test-Path ".venv")) {
     python -m venv .venv
@@ -19,6 +20,8 @@ if (Test-Path "build") {
     Remove-Item -Recurse -Force "build"
 }
 
+& ".\.venv\Scripts\python.exe" "scripts\prepare_ffmpeg.py" --output $VendorFfmpegDir --force
+
 & ".\.venv\Scripts\pyinstaller.exe" `
     --onefile `
     --windowed `
@@ -33,6 +36,8 @@ if (Test-Path "build") {
     --collect-all certifi `
     --hidden-import videomerge.gui `
     --hidden-import tkinter `
+    --add-binary "$VendorFfmpegDir\ffmpeg.exe;ffmpeg" `
+    --add-binary "$VendorFfmpegDir\ffprobe.exe;ffmpeg" `
     main.py
 
 Write-Host ""

scripts/build_local.sh

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import shutil
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from videomerge.env_check import download_ffmpeg_tools
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Download the minimal FFmpeg tools bundled with installers.")
+    parser.add_argument("--output", type=Path, default=Path("build/vendor/ffmpeg"))
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args()
+
+    if args.force and args.output.exists():
+        shutil.rmtree(args.output)
+
+    logger = logging.getLogger("prepare-ffmpeg")
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+    tools = download_ffmpeg_tools(args.output, logger)
+
+    for path in args.output.iterdir():
+        if path.name not in {tools.ffmpeg.name, tools.ffprobe.name}:
+            if path.is_dir():
+                shutil.rmtree(path)
+            else:
+                path.unlink()
+
+    print(f"Bundled ffmpeg: {tools.ffmpeg}")
+    print(f"Bundled ffprobe: {tools.ffprobe}")
+
+
+if __name__ == "__main__":
+    main()

scripts/build_windows.ps1

@@ -22,6 +22,24 @@ def test_find_binary_uses_candidate_paths_when_path_lookup_fails(self) -> None:
 
         self.assertEqual(found, binary)
 
+    def test_find_binary_prefers_bundled_binary_in_frozen_app(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            bundled = Path(temp_dir) / "ffmpeg" / "ffmpeg"
+            bundled.parent.mkdir()
+            bundled.touch()
+
+            with patch("videomerge.env_check.sys.frozen", True, create=True), patch(
+                "videomerge.env_check.sys._MEIPASS",
+                temp_dir,
+                create=True,
+            ), patch("videomerge.env_check.shutil.which", return_value=None), patch(
+                "videomerge.env_check._system_binary_candidates",
+                return_value=[],
+            ):
+                found = _find_binary("ffmpeg", Path(temp_dir) / "missing-tools")
+
+        self.assertEqual(found, bundled)
+
 
 if __name__ == "__main__":
     unittest.main()