# ffmpeg-static-electron-v5

**Repository Path**: anzhen9/ffmpeg-static-electron-v5

## Basic Information

- **Project Name**: ffmpeg-static-electron-v5
- **Description**: ffmpeg-static-electron-v5
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-12-25
- **Last Updated**: 2025-11-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ffmpeg-static-electron-v5（中文）

面向 Electron/Node.js 的跨平台 ffmpeg 静态二进制分发包。

本项目 fork 自 [pietrop/ffmpeg-static-electron](https://github.com/pietrop/ffmpeg-static-electron)。
想了解如何在 Electron 中随应用打包 ffmpeg，可参考：
[How to package ffmpeg with the fluent-ffmpeg node library in electron…](https://pietropassarelli.com/ffmpeg-electron.html)

---

## 新特性（v5）

- 采用“按系统/架构拆分子包”的方式发布到 npm。
- 移除了旧的 postinstall 下载方案，安装过程更稳定、可控。

支持的平台/架构：
- darwin：`x64`、`arm64`
- linux：`x64`、`arm64`、`ia32`
- win32：`x64`、`arm64`、`ia32`

---

## 安装

```bash
npm install ffmpeg-static-electron-v5
```

说明：如果安装后找不到二进制，请手动安装对应子包，例如：

```bash
npm install ffmpeg-static-electron-v5-darwin-arm64
```

---

## 安装行为变更与流量/体积风险

- **行为变更说明：** 主包 `ffmpeg-static-electron-v5` 现在声明并会在安装时获取所有平台/架构的子包（`packages/*` 中的每个子包），因此单次 `npm install ffmpeg-static-electron-v5` 可能会下载多个二进制文件，而不再仅限于当前主机的系统/架构。
- **风险提示：** 这会显著增加安装时的网络流量与磁盘占用，尤其在 CI、容器或带宽受限的环境中。请在批量或自动化环境中谨慎使用该默认行为。
- **建议做法：**
  - 在开发或桌面用户场景，直接安装主包通常方便且可用：

```bash
npm install ffmpeg-static-electron-v5
```

  - 在 CI、构建服务器或带宽/存储敏感的环境，推荐只安装目标平台对应的子包以节省流量与空间，例如：

```bash
# 仅为 macOS Apple Silicon 安装对应子包
npm install ffmpeg-static-electron-v5-darwin-arm64
```

  - 另一个可行方式是在打包/发布流程中使用 `npm pack` 打出需要的子包 tgz，然后在构建容器内仅安装这些 tgz 文件，避免拉取全部子包。

如果你希望我为仓库添加一个可通过环境变量控制（例如 `FFMPEG_INSTALL_ALL=0`）的可选行为，我可以按需实现并在 README 中补充使用说明。


---

## 使用示例

获取本机可用的 ffmpeg 二进制路径：

```js
const ffmpeg = require('ffmpeg-static-electron-v5');
console.log(ffmpeg.path);
// /absolute/path/to/node_modules/.../bin/<platform>/<arch>/ffmpeg[.exe]
```

主包仅负责根据 `os+arch` 解析并 `require()` 对应子包，然后导出该子包提供的 `path`。

---

## 开发与发布

仓库的子包位于 `packages/*`，每个子包只包含一个平台/架构的二进制。子包在 `prepack` 阶段会把仓库根目录中的二进制复制到自身 `bin/` 目录，然后再进行打包或发布。

前置要求：
- 请将二进制放在仓库根目录：`bin/<platform>/<arch>/ffmpeg`（Windows 为 `ffmpeg.exe`）。
- 确保所有子包版本与主包版本一致（当前为 `5.2.6`）。

本地验证流程：
```bash
# 1) 打包与你当前系统匹配的子包（prepack 会自动复制二进制）
cd packages/ffmpeg-static-electron-v5-darwin-arm64
npm pack

# 2) 回到仓库根目录，打主包
cd ../../
npm pack

# 3) 在临时项目中安装这两个 tgz，验证主包能解析到子包
mkdir -p /tmp/ffmpeg-test && cd /tmp/ffmpeg-test
npm init -y
npm install \
  /path/to/repo/packages/ffmpeg-static-electron-v5-darwin-arm64/ffmpeg-static-electron-v5-darwin-arm64-5.2.6.tgz \
  /path/to/repo/ffmpeg-static-electron-v5-5.2.6.tgz

node -e "console.log(require('ffmpeg-static-electron-v5').path)"
"$(node -e "console.log(require('ffmpeg-static-electron-v5').path)")" -version
```

发布到 npm：
```bash
# 一键发布所有子包，然后发布主包
npm run publish:all

# 仅打包验证（不发布）
npm run publish:dry

# 使用自定义 dist-tag（例如 beta）
npm run publish:beta
```

发布脚本会检查对应源二进制是否存在，并依次处理 `packages/*` 下的子包。请确保已登录 npm，且有发布权限。

---

## 二进制来源参考

以下是常见的 ffmpeg 静态构建来源（请根据你的合规策略与需求自行选择）：
- [Windows x64 builds](https://www.gyan.dev/ffmpeg/builds/)
- [Windows x86 builds](https://github.com/sudo-nautilus/FFmpeg-Builds-Win32/)
- [Linux x64/x86/ARM/ARM64 builds](https://johnvansickle.com/ffmpeg/)
- macOS [x64 (Intel)](https://evermeet.cx/pub/ffmpeg/) 与 [ARM64 (Apple Silicon)](https://osxexperts.net/) 构建

---

## 许可证

MIT