feat(lib): add automatic FFmpeg library download mechanism

- Implement download-lib command to fetch FFmpeg libraries for current platform
- Create lib/fetch.go with download, checksum verification, and extraction functionality
- Add comprehensive documentation in README.md and docs/DEVELOPMENT.md
- Update GitHub workflow to include library download step
- Streamline CGO flags for consistent linking across platforms
- Modify .gitignore to handle library files correctly
- Add "just download-lib" command for manual library downloads

Author: flexiondotorg

.github/workflows/go.yml

@@ -29,13 +29,12 @@ jobs:
       fail-fast: false
 
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
+      - uses: actions/checkout@v6
 
-      - name: Set up Go
-        uses: actions/setup-go@v6
+      - uses: actions/setup-go@v6
         with:
           go-version: '1.24'
+          cache: true
 
       - name: Install libclang for generator
         run: |
@@ -46,6 +45,9 @@ jobs:
             brew install llvm
           fi
 
+      - name: Download FFmpeg libraries
+        run: go run ./cmd/download-lib/
+
       - name: Run generator
         run: go run ./internal/generator
         continue-on-error: true

.gitignore

@@ -36,4 +36,7 @@ coverage.html
 result
 result-*
 
-lib/linux_amd64/*.a
+# FFmpeg static libraries
+lib/*/
+!lib/fetch.go
+!lib/README.md

README.md

@@ -22,6 +22,52 @@ Build once, deploy anywhere. No hunting for system FFmpeg. No version mismatches
 
 *Hard fork of the excellent [csnewman/ffmpeg-go](https://github.com/csnewman/ffmpeg-go), modernised with FFmpeg 8.0, Go 1.24, hardware acceleration and a 99.5% smaller git history.*
 
+## Installation
+
+ffmpeg-statigo includes large static libraries (~100MB per platform) that cannot be distributed via `go get`. This requires a simple manual setup:
+
+### Using Git Submodules
+
+For clean project integration, use ffmpeg-statigo as a git submodule:
+
+1. Add ffmpeg-statigo as a submodule in your project
+```bash
+git submodule add https://github.com/linuxmatters/ffmpeg-statigo vendor/ffmpeg-statigo
+```
+
+2. Add a replace directive pointing to the submodule
+```bash
+go mod edit -replace github.com/linuxmatters/ffmpeg-statigo=./vendor/ffmpeg-statigo
+```
+
+3. Get the dependency
+```bash
+go get github.com/linuxmatters/ffmpeg-statigo
+```
+
+4. Download the static libraries
+```bash
+cd vendor/ffmpeg-statigo
+go run ./cmd/download-lib
+cd ../..
+```
+
+5. Build your project
+```bash
+go build
+```
+
+6. Commit only the submodule reference
+
+The static libraries (`lib/*/libffmpeg.a`) won't be committed - they're gitignored
+
+```bash
+git add .gitmodules vendor/ffmpeg-statigo
+git commit -m "Add ffmpeg-statigo as submodule"
+```
+
+**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for alternative installation methods, CI/CD integration, and troubleshooting.**
+
 ## Codec Inclusion Policy
 
 ffmpeg-statigo provides a **curated FFmpeg static library** focused on the core strengths of FFmpeg: **decoding, processing, and encoding** audio and video streams. ffmpeg-statigo is designed for **Go developers building modern streaming applications**. The pattern is:

cmd/download-lib/main.go

@@ -0,0 +1,22 @@
+// download-lib is a utility to download the FFmpeg static libraries
+// Run this program to trigger the automatic download and SHA256 verification
+package main
+
+import (
+	"fmt"
+	"os"
+	"runtime"
+
+	"github.com/linuxmatters/ffmpeg-statigo/lib"
+)
+
+func main() {
+	fmt.Printf("Downloading FFmpeg libraries for %s/%s...\n", runtime.GOOS, runtime.GOARCH)
+
+	if err := lib.DownloadLibs(); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Println("Download complete!")
+}