# FFmpeg CI Guide

This file describes how to provide a vetted FFmpeg build to the CI workflow and how the workflow expects archive layouts.

## Secrets (recommended)
- `FFMPEG_URL` — primary URL the workflow will download. Use a stable URL to a signed/hosted FFmpeg build.
- `FFMPEG_URL_LINUX` — optional override for Linux runners.
- `FFMPEG_URL_WINDOWS` — optional override for Windows runners.
- `FFMPEG_URL_MACOS` — optional override for macOS runners.

If per-OS secrets are present, they take precedence over `FFMPEG_URL`.

## Recommended FFmpeg sources
- Use official static builds from a trusted provider (example):
  - Windows (ffmpeg.exe): https://www.gyan.dev/ffmpeg/builds/
  - Linux (static): https://johnvansickle.com/ffmpeg/
  - macOS (static): https://evermeet.cx/ffmpeg/

Prefer hosting a copy in your own artifact store (S3, GitHub Releases) so you control the binary used in CI.

## Expected archive layouts
The workflow will attempt to extract common archive formats. Recommended layouts:

- Zip containing `ffmpeg.exe` at the archive root
  - Example: `ffmpeg-2025-01-01.zip` -> `ffmpeg.exe` (root)

- Tar.gz or tar.xz containing an `ffmpeg` binary at the archive root or inside a single top-level folder
  - Example: `ffmpeg-2025/ffmpeg` or `ffmpeg`

- Raw binary: a direct link to the `ffmpeg` executable is also supported (the workflow will make it executable).

If your archive nests the binary deep inside several folders, consider publishing a trimmed archive that places `ffmpeg` at the root for easier CI extraction.

## Verifying locally
To test the workflow steps locally, download your chosen archive and ensure running the binary prints version information:

```bash
# on Linux/macOS
./ffmpeg -version

# on Windows (PowerShell)
.\ffmpeg.exe -version
```

## Notes for maintainers
- If you need the workflow to handle a custom archive layout, I can update the extraction step (`.github/workflows/ffmpeg-preflight.yml`) to locate the binary path inside the archive and move it to `src-tauri/resources/ffmpeg(.exe)`.
- After adding secrets, open a PR to trigger the workflow and verify the `FFmpeg preflight OK` message in the CI logs.