StreamCap/docs/packaging_en.md

StreamCap Packaging Guide

This document explains how to package the StreamCap desktop app with PyInstaller and how to prepare optional bundled FFmpeg / Node.js executables.

Requirements

• Build on the target platform:
  • Build macOS packages on macOS.
  • Build Windows packages on Windows.
• PyInstaller does not support cross-compiling between macOS and Windows.
• Install project dependencies first and make sure StreamCap can run in the current Python environment.

One-Command Build

Run from the project root:

python scripts/build.py

The script automatically:

• Prepares the Flet desktop runtime archive.
• Bundles config, locales, and assets.
• Bundles streamget data files.
• Bundles optional FFmpeg / Node.js executables when present.
• On macOS, hides the outer PyInstaller Dock icon so only one StreamCap panda icon is shown.

macOS output:

dist/StreamCap.app

Run it with:

open dist/StreamCap.app

Windows output:

dist/StreamCap/
├─ StreamCap.exe
└─ _internal/
   ├─ assets/
   ├─ config/
   ├─ locales/
   └─ ...

Windows uses the PyInstaller one-dir layout: StreamCap.exe stays at the top level as the user entry point, while runtime dependencies, resources, and DLLs live under _internal.

GitHub Actions automatically zips downloaded artifacts, so the workflow uploads the app directory under dist instead of creating an inner zip first. After downloading StreamCap-windows.zip, extracting it once gives a StreamCap folder.

macOS Architecture

By default, the package uses the current Python environment and host architecture. Apple Silicon machines usually produce an arm64 package.

You can specify it explicitly:

python scripts/build.py --target-arch arm64

Avoid universal2 unless all Python and native dependencies are universal2. Otherwise PyInstaller may fail with is not a fat binary.

Bundled FFmpeg

To bundle FFmpeg, prepare it first:

python scripts/download_ffmpeg.py

Download both supported platforms:

python scripts/download_ffmpeg.py --platform all

Files are saved to:

vendor/ffmpeg/macos/ffmpeg
vendor/ffmpeg/windows/ffmpeg.exe

The script extracts only ffmpeg / ffmpeg.exe; it does not keep ffplay or ffprobe.

scripts/build.py automatically bundles the matching file when it exists. To skip bundled FFmpeg:

python scripts/build.py --no-bundle-ffmpeg

Runtime behavior:

• If ffmpeg is already available on PATH, the bundled version is not copied.
• If ffmpeg is not available and a bundled executable exists, it is copied to the user data directory.

Destination:

macOS:   ~/Library/Application Support/StreamCap/ffmpeg/ffmpeg
Windows: %APPDATA%\StreamCap\ffmpeg\ffmpeg.exe

Bundled Node.js

To bundle Node.js, prepare it first:

python scripts/download_nodejs.py

Download both supported platforms:

python scripts/download_nodejs.py --platform all

Specify a version:

python scripts/download_nodejs.py --version 22.12.0

Files are saved to:

vendor/node/macos/node
vendor/node/windows/node.exe

The script extracts only node / node.exe; it does not keep npm, npx, headers, docs, or other files.

scripts/build.py automatically bundles the matching file when it exists. To skip bundled Node.js:

python scripts/build.py --no-bundle-node

Runtime behavior:

• If node is already available on PATH, the bundled version is not copied.
• If node is not available and a bundled executable exists, it is copied to the user data directory.

Destination:

macOS:   ~/Library/Application Support/StreamCap/node/node
Windows: %APPDATA%\StreamCap\node\node.exe

macOS Flet Notes

StreamCap uses Flet desktop mode. On macOS, Flet uses Flet.app as the actual window process.

The packaged app applies the following handling:

• The outer StreamCap.app runs as a background agent and does not show a Dock icon.
• The global Flet cache is not modified directly.
• On first launch, StreamCap creates its own Flet app copy:

~/Library/Application Support/StreamCap/flet_client/<version>/StreamCap Flet.app

• The dedicated Flet copy uses the StreamCap panda icon.

In normal use, the Dock should show only one panda icon.

If macOS keeps showing an old icon after upgrading Flet or changing icons, delete the dedicated Flet cache and restart Dock:

rm -rf "$HOME/Library/Application Support/StreamCap/flet_client"
killall Dock
open dist/StreamCap.app

User Data Directory

In packaged builds, mutable files such as config, logs, FFmpeg, and Node.js are not written into the app bundle or installation directory.

Locations:

macOS:   ~/Library/Application Support/StreamCap
Windows: %APPDATA%\StreamCap

On Windows, the default recording directory is downloads next to StreamCap.exe, so large videos are not written to the C drive user data directory by default. If the user chooses a save directory in Settings, that value takes precedence.

When running from source, StreamCap still uses the project directory for easier development and debugging.

Common Commands

Prepare optional bundled dependencies:

python scripts/download_ffmpeg.py --platform all
python scripts/download_nodejs.py --platform all

Build:

python scripts/build.py

Force re-download of the Flet desktop runtime archive:

python scripts/build.py --refresh-flet

Build without bundled FFmpeg / Node.js:

python scripts/build.py --no-bundle-ffmpeg --no-bundle-node