feat: Add Apple Silicon support with VideoToolbox hardware encoding (#15) by ebbbang · Pull Request #18 · JMS1717/8mb.local

ebbbang · 2025-12-16T10:39:07Z

Closes #15

Summary

Adds hardware-accelerated video encoding support for Apple Silicon Macs (M1/M2/M3/M4)
Uses VideoToolbox via a hybrid setup: Docker for services, native macOS worker for GPU access
Supports H.264 and HEVC encoding (AV1 falls back to CPU as VideoToolbox doesn't support it)

Architecture

Since Docker Desktop on macOS runs in a Linux VM without GPU passthrough, this uses a hybrid approach:

Docker: Runs Redis, frontend, and backend API
Native worker: Runs on macOS with VideoToolbox access for hardware encoding
Redis: Exposed on port 6380 to avoid conflicts with native Redis installations

Changes

worker/app/hw_detect.py: Added _check_videotoolbox() and encoder mappings
worker/app/startup_tests.py: Added VideoToolbox test configuration
backend-api/app/models.py: Added VideoToolbox codec literals
backend-api/app/settings_manager.py: Added VideoToolbox visibility settings
docker-compose.macos.yml: New compose file for macOS hybrid setup
scripts/macos-setup.sh: Setup script for native worker dependencies
docs/GPU_SUPPORT.md: Added VideoToolbox documentation
README.md: Updated macOS section with hybrid setup instructions
.github/copilot-instructions.md: Added VideoToolbox references
.gitignore: Added venv/

Usage

# Start Docker services
docker-compose -f docker-compose.macos.yml up -d

# Run setup script (installs FFmpeg/Python if needed)
./scripts/macos-setup.sh

# Start native worker
source venv/bin/activate
export REDIS_URL=redis://localhost:6380/0
celery -A worker.celery_app worker --loglevel=info

Test plan

- Verify VideoToolbox detection on Apple Silicon Mac
- Test H.264 encoding with h264_videotoolbox
- Test HEVC encoding with hevc_videotoolbox
- Verify AV1 falls back to CPU encoding
- Confirm setup script works on fresh macOS install
- Test hybrid setup with Docker services + native worker

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **New Features**
* Added Apple VideoToolbox hardware encoding support for macOS with H.264 and HEVC codecs
* Introduced hybrid Docker + native worker setup for macOS with GPU acceleration

* **Documentation**
* Updated macOS installation guide with two options: CPU-only and hardware-accelerated paths
* Expanded GPU support documentation with VideoToolbox capabilities and limitations

* **Chores**
* Added macOS environment setup script and Docker configuration for Apple Silicon

<sub>✏️ Tip: You can customize this high-level summary in your review settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Add hardware-accelerated video encoding for macOS using VideoToolbox. This enables H.264 and HEVC encoding on M1/M2/M3/M4 Macs via a hybrid setup where Docker runs services and a native worker uses the GPU. - Add _check_videotoolbox() detection in hw_detect.py - Add h264_videotoolbox and hevc_videotoolbox encoder mappings - Add VideoToolbox startup tests - Create docker-compose.macos.yml (exposes Redis on port 6380) - Create scripts/macos-setup.sh for easy setup - Update models.py and settings_manager.py with new codecs - Update documentation (README, GPU_SUPPORT.md, copilot-instructions)

coderabbitai · 2025-12-16T10:39:16Z

Walkthrough

This PR introduces Apple Silicon and macOS support with VideoToolbox hardware acceleration. Changes include backend model expansion for VideoToolbox codecs, new hardware detection logic, a macOS-specific Docker Compose file, a native worker setup script, and comprehensive documentation updates.

Changes

Cohort / File(s)	Summary
Documentation & Configuration `.github/copilot-instructions.md`, `README.md`, `docs/GPU_SUPPORT.md`	Added macOS and Apple Silicon setup guidance, hardware option descriptions, VideoToolbox encoder mapping, and hybrid setup workflow documentation.
Build & Environment Configuration `.gitignore`, `docker-compose.macos.yml`	Added Python virtual environment directory to gitignore; introduced macOS-specific Docker Compose configuration with 8mblocal service, port mappings, and Redis setup for Apple Silicon.
Backend API Models & Settings `backend-api/app/models.py`, `backend-api/app/settings_manager.py`	Expanded `CompressRequest`, `DefaultPresets`, and `PresetProfile` video codec Literals to include `h264_videotoolbox` and `hevc_videotoolbox`; added `phase` field to `JobMetadata`; added VideoToolbox codec visibility flags and environment variable mappings.
Worker Hardware Detection & Tests `worker/app/hw_detect.py`, `worker/app/startup_tests.py`	Added `_check_videotoolbox()` detection function and VideoToolbox support path in `detect_hw_accel()`; extended `map_codec_to_hw()` to recognize and map VideoToolbox encoders; added corresponding VideoToolbox test cases.
Setup & Configuration Scripts `scripts/macos-setup.sh`	Added new macOS setup script verifying Homebrew, Apple Silicon, Python 3.10+, and FFmpeg with VideoToolbox support; installs dependencies and provides guidance for native worker deployment with environment variable configuration.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

worker/app/hw_detect.py: Verify VideoToolbox detection robustness (_check_videotoolbox() function) and correct encoding test; ensure codec mapping handles all VideoToolbox variants correctly; validate that AV1 properly falls back to CPU.
Hybrid setup workflow: Confirm that the Docker Compose macOS file and native worker setup script integrate seamlessly; verify environment variable exports match backend expectations.
Model backward compatibility: Confirm new codec options and phase field in JobMetadata maintain backward compatibility with existing clients and don't break API contracts.

Possibly related PRs

Fix: AMD APU (And GPU?) Hardware Acceleration #16: Modifies worker/app/hw_detect.py and worker/app/startup_tests.py similarly; may involve overlapping hardware detection and codec mapping logic for multiple platforms.

Poem

🐰 Hop along to the Mac, with Silicon bright,
VideoToolbox encoders now taking flight!
From Docker containers to native workers so keen,
Apple's acceleration has finally been seen!
🎬✨ The M1 hums a merry tune,
8mb.local shall bloom this June!

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding Apple Silicon support with VideoToolbox hardware encoding, which matches the primary objective of the PR.
Linked Issues check	✅ Passed	The PR fully addresses issue #15 by implementing VideoToolbox support for Apple Silicon hardware encoding, native worker setup, hybrid Docker+native workflow, and H.264/HEVC acceleration with CPU fallback for AV1.
Out of Scope Changes check	✅ Passed	All changes are scoped to Apple Silicon VideoToolbox support: hardware detection, codec models, documentation, setup scripts, and Docker macOS configuration. No unrelated changes detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (2)

scripts/macos-setup.sh (1)
112-112: Consider adding concurrency flag for consistency.

The Celery worker command omits the concurrency flag. Based on coding guidelines, the supervisord pattern includes --concurrency=4. Consider adding it for consistency:
-     celery -A worker.celery_app worker --loglevel=info
+     celery -A worker.celery_app worker --loglevel=info --concurrency=4
This ensures consistent behavior with the Docker-based worker.

Based on coding guidelines, worker startup should follow the supervisord pattern with concurrency specified.
docs/GPU_SUPPORT.md (1)
128-146: Optional: Add language specifier to code fence.

The ASCII diagram would be more semantically correct with a language identifier:
-```
+```text
 ┌─────────────────────────────────────────────────────┐
 │              Docker (Linux containers)               │
This addresses the static analysis hint while clarifying the content type.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 013c276 and 40cf5ad.

📒 Files selected for processing (10)

.github/copilot-instructions.md (2 hunks)
.gitignore (1 hunks)
README.md (1 hunks)
backend-api/app/models.py (4 hunks)
backend-api/app/settings_manager.py (2 hunks)
docker-compose.macos.yml (1 hunks)
docs/GPU_SUPPORT.md (4 hunks)
scripts/macos-setup.sh (1 hunks)
worker/app/hw_detect.py (7 hunks)
worker/app/startup_tests.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (4)

**/{backend-api,worker}/app/**/*.py

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/{backend-api,worker}/app/**/*.py: Job/task IDs: backend generates job_id and worker uses Celery task_id. Redis keys must follow the pattern: job:{task.id}, progress:{task_id} and cancel:{task_id}
File naming convention: uploads must be saved to /app/uploads with jobid_filename format; outputs to /app/outputs with _8mblocal_{taskid} suffix to avoid collisions
When editing worker or backend code, preserve Redis key names (job:{task.id}, progress:{task_id}, cancel:{task_id}) and published event formats (type, task_id, progress fields)

Files:

backend-api/app/settings_manager.py
worker/app/startup_tests.py
backend-api/app/models.py
worker/app/hw_detect.py

backend-api/app/**/*.py

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Backend API: use celery_app.send_task('worker.worker.compress_video', ...) pattern to enqueue Celery tasks with proper task kwargs; output naming must follow file naming conventions

Files:

backend-api/app/settings_manager.py
backend-api/app/models.py

worker/app/**/*.py

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

worker/app/**/*.py: Progress messages published to Redis must be JSON events with type field (log, progress, done, or error) and include task_id and progress fields for frontend consumption
Hardware encoder detection and testing: do not assume a listed hardware encoder will initialize successfully; prefer reading the startup test cache or respecting ENCODER_TEST_CACHE logic in worker/app/worker.py

Files:

worker/app/startup_tests.py
worker/app/hw_detect.py

worker/app/{hw_detect,worker}.py

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Encoder mapping: requested codec is mapped to hardware encoder in worker/app/hw_detect.py via map_codec_to_hw function; when startup test marks encoder unavailable, fall back to CPU encoders

Files:

worker/app/hw_detect.py

🧠 Learnings (9)