# macOS Platform Guide

This document provides macOS-specific information for MPV.Rocks Installer development and deployment.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Building](#building)
- [Installation](#installation)
- [Code Signing](#code-signing)
- [Troubleshooting](#troubleshooting)

---

## Prerequisites

### Development Tools

**Required:**
- Go 1.25 or later
- Xcode 13+ or Command Line Tools
- Git (optional, for version info)

**Recommended:**
- Visual Studio Code with Go extension
- Xcode (for CGO compilation)

### Build Dependencies

```bash
# Install Go (if not already installed)
brew install go

# Verify version
go version  # Should be 1.25 or later
```

### macOS SDK

**Required for CGO:**
- Command Line Tools for Xcode
- Minimum: Xcode 13
- Includes: clang, video framework headers

**Installation:**
```bash
# Install via Terminal
xcode-select --install
```

---

## Building

### Architecture Targets

**Available Architectures:**
- **x86_64 (Intel Macs)**
- **arm64 (Apple Silicon)**
- **universal** (both x86_64 and arm64)

### Build Commands

**x86_64 (Intel):**
```bash
GOOS=darwin GOARCH=amd64 go build \
  -ldflags="-s -w -X main.version=$(git describe --tags --always --dirty)" \
  -o dist/mpv-manager-darwin-x86_64 ./cmd/mpv-manager
```

**arm64 (Apple Silicon):**
```bash
GOOS=darwin GOARCH=arm64 go build \
  -ldflags="-s -w -X main.version=$(git describe --tags --always --dirty)" \
  -o dist/mpv-manager-darwin-arm64 ./cmd/mpv-manager
```

**universal (both):**
```bash
# Build both architectures
GOOS=darwin GOARCH=amd64 go build -o dist/mpv-manager-darwin-amd64 ./cmd/mpv-manager
GOOS=darwin GOARCH=arm64 go build -o dist/mpv-manager-darwin-arm64 ./cmd/mpv-manager

# Create universal binary
lipo -create -output dist/mpv-manager-darwin-universal \
  dist/mpv-manager-darwin-amd64 \
  dist/mpv-manager-darwin-arm64
```

### Using CGO

**Required for VideoToolbox detection:**
```bash
# Build with CGO enabled
CGO_ENABLED=1 go build \
  -ldflags="-s -w -X main.version=$(git describe --tags --always --dirty)" \
  -o dist/mpv-manager-darwin-arm64 ./cmd/mpv-manager
```

**Note:** CGO builds produce native-arm64 binaries only (cannot cross-compile).

---

## Installation

### Application Bundles

**Structure:**
```
mpv-manager.app/
├── Contents/
│   ├── MacOS/
│   │   └── mpv-manager
│   ├── Resources/
│   │   ├── Assets.xcassets
│   │   └── Info.plist
│   └── _CodeSignature (if signed)
└── mpv-manager (symlink to MacOS/mpv-manager)
```

**Info.plist Configuration:**
```xml
<key>CFBundleDisplayName</key>
<string>MPV.Rocks Installer</string>

<key>CFBundleIdentifier</key>
<string>io.mpvrocks.installer</string>

<key>NSHighResolutionCapable</key>
<true/>

<key>NSAppleEventsUsageDescription</key>
<string>MPV installation and configuration</string>

<key>LSUIElementUsesFullScreenContentView</key>
<true/>
```

### Installation Locations

**User Applications:**
- `/Applications/mpv-manager.app`

**User Config:**
- `~/.config/mpv/`

**Logs:**
- `~/.config/mpv/mpv-manager.log`

### Homebrew Integration

**Formula:**
```ruby
class InstallMpv < Formula
  url "https://gitgud.io/mike/mpv-manager/releases/download/v1.2.3/mpv-manager-darwin-universal.tar.xz"
  sha256 "checksum-value"
  version "1.2.3"

  def install
    bin.install "mpv-manager"
  end
end
```

**Installation:**
```bash
brew install mpv-manager
```

---

## Code Signing

### Development vs Distribution

**Development:**
- Can run without code signing
- May show "app is damaged" warning on first launch

**Distribution:**
- Requires Apple Developer certificate
- Code signature required for distribution outside App Store
- Notarization required for unsigned apps

### Code Signing Commands

**Sign with Developer Certificate:**
```bash
# Sign the app bundle
codesign --deep --force --verify --verbose --sign "Developer ID Application: io.mpvrocks.installer" mpv-manager.app

# Verify signature
codesign --verify --verbose mpv-manager.app
```

**Ad-hoc Signing (Testing Only):**
```bash
# Ad-hoc signature (self-signed)
codesign --deep --force --sign - mpv-manager.app

# Note: Gatekeeper will show warning for ad-hoc signed apps
```

### Removing Quarantine Attribute

**After download:**
```bash
# Remove quarantine attribute
xattr -d com.apple.quarantine mpv-manager-app

# Or clear all extended attributes
xattr -c mpv-manager.app
```

---

## GPU Detection

### VideoToolbox Detection (CGO)

**CGO Build:**
```bash
CGO_ENABLED=1 go build \
  -ldflags="-s -w -X main.version=$(git describe --tags --always --dirty)" \
  -o dist/mpv-manager-darwin-arm64 ./cmd/mpv-manager
```

**Supported Codecs (M1/M2):**
- HEVC
- AVC
- ProRes

**Supported Codecs (M3/M4):**
- AV1
- HEVC
- AVC
- ProRes

### Model-Based Fallback (Cross-Compilation)

**Apple Silicon Specifications:**

| Chip | Architecture | Supported Codecs |
|-------|---------------|-------------------|
| M1 | ARMv8.4-A | HEVC, AVC, ProRes |
| M1 Pro/Max/Ultra | ARMv8.4-A | HEVC, AVC, ProRes |
| M2 | ARMv8.4-A | HEVC, AVC, ProRes |
| M2 Pro/Max/Ultra | ARMv8.4-A | HEVC, AVC, ProRes |
| M3 | ARMv8.4-A | AV1, HEVC, AVC, ProRes |
| M3 Pro/Max/Ultra | ARMv8.4-A | AV1, HEVC, AVC, ProRes |
| M4 | ARMv8.4-A | AV1, HEVC, AVC, ProRes |
| Unknown/Future | ARMv8.4-A | AV1, HEVC, AVC, ProRes (optimistic) |

**Fallback Implementation:**
- GPU model detected via `sysctl -n machdep.cpu.brand_string`
- Model mapped to Apple Silicon generation
- Codec support returned based on generation
- Logs: "CGO detection unavailable, using model-based fallback"

---

## Hardware Acceleration

### Supported Methods

**macOS VideoToolbox Methods:**
- `videotoolbox` - Apple VideoToolbox
- `videotoolbox-copy` - Apple VideoToolbox with copy
- `auto` - Automatic selection
- `no` - Disable hardware decoding

### Configuration

**MPV Configuration Key:** `hwdec`

**Available Options:**
- `videotoolbox` (recommended)
- `videotoolbox-copy`
- `auto`
- `no`

### Example Configuration

```ini
# Use VideoToolbox
hwdec=videotoolbox
```

---

## Troubleshooting

### Gatekeeper Issues

**Symptom:** "mpv-manager.app is damaged and can't be opened" or "unidentified developer".

**Solutions:**

**1. Remove Quarantine:**
```bash
xattr -d com.apple.quarantine mpv-manager.app
```

**2. Enable App from Anywhere:**
```bash
# System Settings → Security & Privacy → General
# "Allow apps downloaded from: App Store and identified developers"
# Add terminal to allowed apps if needed
```

**3. Right-click and Open:**
```bash
# Right-click mpv-manager.app → Open
```

### Apple Silicon Issues

**Symptom:** App won't launch or crashes.

**Possible Causes:**
1. Running x86_64 binary under Rosetta
2. Missing VideoToolbox frameworks
3. Code signing issues

**Solutions:**

**1. Check Architecture:**
```bash
# Check if running natively
uname -m
# Should show: arm64 (not x86_64)
```

**2. Disable Rosetta (if applicable):**
```bash
# Remove Rosetta translation
# Applications → mpv-manager.app → Get Info → Open in Rosetta → Disable
```

**3. Reinstall with Correct Architecture:**
- Download arm64 binary for Apple Silicon
- Download universal binary

---

## Quick Reference

### Common Commands

```bash
# Build for current architecture
make build-macos

# Build for all architectures
make build-macos-all

# Build for specific architecture
make build-macos-arm64
make build-macos-x86_64
make build-macos-universal

# Run with debug mode
./mpv-manager --debug

# Run with verbose mode
./mpv-manager --verbose

# Check version
./mpv-manager --version
```

### File Locations

| Type | Location |
|------|-----------|
| Application | `/Applications/mpv-manager.app` |
| Config | `~/.config/mpv/` |
| Log | `~/.config/mpv/mpv-manager.log` |
| Shortcuts | `~/Library/Application Support/com.apple.sharedfilelist/com.apple.LSSharedFileList.ApplicationRecentDocuments/mpv-manager.ln` |

### Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `HOME` | User home directory | `/Users/username` |
| `XDG_CONFIG_HOME` | Config directory | `/Users/username/.config` |
| `DISPLAY` | X11 display | `:0` |

---

## Conclusion

This macOS platform guide provides comprehensive information for building, signing, installing, and troubleshooting MPV.Rocks Installer on macOS.

For additional information, see:
- [Architecture](../ARCHITECTURE.md) - System architecture and design
- [Features](../FEATURES.md) - Comprehensive feature documentation
- [Build & Deployment](../BUILD_DEPLOYMENT.md) - Build procedures and deployment guide
- [Troubleshooting](../TROUBLESHOOTING.md) - Common issues and solutions