feat: add macOS support and update documentation

- Add macOS-specific FFmpeg paths (Apple Silicon and Intel)
- Add macOS to CI/CD workflow testing matrix
- Update README.md platform badge and description to include macOS
- Update all documentation files to mention macOS alongside Windows/Linux
- Update CONTRIBUTING.md to include macOS testing
- Update ROADMAP.md and DEVELOPMENT_GOALS.md to reflect macOS support
- Add macOS-specific troubleshooting guidance

Author: VoxHash

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ['3.9', '3.10', '3.11', '3.12']
 
     steps:
@@ -37,6 +37,11 @@ jobs:
       run: |
         choco install ffmpeg -y || echo "FFmpeg installation skipped (may need manual setup)"
     
+    - name: Install system dependencies (macOS)
+      if: matrix.os == 'macos-latest'
+      run: |
+        brew install ffmpeg || echo "FFmpeg installation skipped (may need manual setup)"
+    
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

CONTRIBUTING.md

@@ -28,7 +28,7 @@ python -m handforge.app
 
 Currently, HandForge is primarily tested manually. When contributing:
 
-- Test your changes on both Windows and Linux if possible
+- Test your changes on Windows, Linux, and macOS if possible
 - Test with various audio and video formats
 - Verify UI changes work correctly
 - Check for any regressions

DEVELOPMENT_GOALS.md

@@ -44,7 +44,7 @@ This document outlines short-term and mid-term technical goals for HandForge.
 ## Long-Term Vision (2027+)
 
 ### Platform Expansion
-- **macOS Support**: Full macOS compatibility
+- **macOS Enhancements**: Additional macOS-specific optimizations and features
 - **Mobile Apps**: Companion mobile apps for remote control
 - **Web Interface**: Optional web-based interface
 

README.md

@@ -3,9 +3,9 @@
 [![CodeQL Analysis](https://github.com/VoxHash/HandForge/actions/workflows/codeql.yml/badge.svg)](https://github.com/VoxHash/HandForge/actions/workflows/codeql.yml)
 [![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg)]()
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
 
-> A cross-platform audio and video converter GUI (Windows/Linux) built with PyQt6 + FFmpeg. Features a modern Glassmorphism UI design.
+> A cross-platform audio and video converter GUI (Windows/Linux/macOS) built with PyQt6 + FFmpeg. Features a modern Glassmorphism UI design.
 
 ## ✨ Features
 

ROADMAP.md

@@ -25,15 +25,15 @@ High-level milestones and planned features for HandForge.
 - Plugin system architecture for extensibility
 
 ### Platform & Integration
-- macOS support
+- Enhanced macOS compatibility and testing
 - Cloud storage integration
 - Distributed processing capabilities
 - Performance analytics and monitoring
 
 ## Future (2027+)
 
 ### Platform Expansion
-- Full macOS compatibility
+- Enhanced macOS features and optimizations
 - Companion mobile apps
 - Optional web-based interface
 

docs/quick-start.md

@@ -11,6 +11,7 @@ pip install -r requirements.txt
 # Ensure FFmpeg is installed
 # Windows: winget install ffmpeg
 # Linux: sudo apt install ffmpeg
+# macOS: brew install ffmpeg
 ```
 
 ## Run

docs/troubleshooting.md

@@ -13,6 +13,7 @@ Common issues and solutions when using HandForge.
 2. Ensure FFmpeg is in your system PATH
 3. Restart terminal/command prompt after installing FFmpeg
 4. On Windows, restart the computer if PATH changes don't take effect
+5. On macOS, ensure Homebrew paths are in PATH: `echo $PATH | grep -q /opt/homebrew/bin || export PATH="/opt/homebrew/bin:$PATH"`
 
 ### PyQt6 Installation Fails
 

handforge/util/ffmpeg.py

@@ -19,6 +19,8 @@ def find_ffmpeg() -> Optional[str]:
         "C:\\Program Files\\ffmpeg\\bin\\ffmpeg.exe",
         "/usr/bin/ffmpeg",
         "/usr/local/bin/ffmpeg",
+        "/opt/homebrew/bin/ffmpeg",  # macOS (Apple Silicon)
+        "/usr/local/opt/ffmpeg/bin/ffmpeg",  # macOS (Intel via Homebrew)
     ]
 
     for path in common_paths:
@@ -40,6 +42,8 @@ def find_ffprobe() -> Optional[str]:
         "C:\\Program Files\\ffmpeg\\bin\\ffprobe.exe",
         "/usr/bin/ffprobe",
         "/usr/local/bin/ffprobe",
+        "/opt/homebrew/bin/ffprobe",  # macOS (Apple Silicon)
+        "/usr/local/opt/ffmpeg/bin/ffprobe",  # macOS (Intel via Homebrew)
     ]
 
     for path in common_paths: