Add detailed comments to scripts and comprehensive README

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

README.md

@@ -0,0 +1,146 @@
+# MacBook OBS Linux
+
+Two scripts for getting a MacBook set up for screen recording and streaming on Linux:
+
+1. **facetimehd-installer.sh** — Install the FaceTime HD camera driver
+2. **obs-performance-script.sh** — Optimize OBS performance on Linux Mint
+
+## FaceTime HD Camera Installer
+
+Gets the built-in FaceTime HD camera working on Linux for older MacBooks (2012-2017 models with the Broadcom 1570 PCIe camera).
+
+### Compatible Models
+
+- MacBook Air (A1466, A1369, and similar)
+- MacBook Pro (2012-2017 models)
+- iMac (2012-2017 models)
+
+> **Note:** Newer MacBooks with T2 chip or Apple Silicon are NOT supported.
+
+### Supported Distros
+
+- Ubuntu 20.04+
+- Linux Mint 20+
+- Debian 11+
+- Fedora 36+
+
+### Usage
+
+```bash
+chmod +x facetimehd-installer.sh
+./facetimehd-installer.sh
+```
+
+Do **NOT** run with sudo — the script uses sudo internally where needed.
+
+### What It Does
+
+| Step | Action |
+|------|--------|
+| 1 | Detects your distro and kernel version |
+| 2 | Checks Secure Boot status (driver won't load with SB enabled) |
+| 3 | Installs build tools (gcc, kernel headers, DKMS) |
+| 4 | Removes any previous facetimehd installations |
+| 5 | Downloads and extracts camera firmware from Apple's driver |
+| 6 | Downloads, patches (for kernel 6.x), and builds the kernel module |
+| 7 | Installs via DKMS (auto-rebuilds on kernel updates) |
+| 8 | Blacklists conflicting `bdc_pci` module |
+| 9 | Loads the module and verifies camera appears at `/dev/videoN` |
+
+### Secure Boot
+
+The facetimehd kernel module is unsigned. If Secure Boot is enabled, the module won't load. Options:
+
+1. **Disable Secure Boot** in BIOS/UEFI (recommended)
+2. Sign the module yourself (advanced)
+3. Try anyway (will likely fail)
+
+### Troubleshooting
+
+```bash
+# Check if module is loaded
+lsmod | grep facetimehd
+
+# Check kernel messages
+sudo dmesg | grep -i facetime
+
+# Check for video device
+ls /dev/video*
+
+# Test with a camera app
+cheese
+```
+
+## OBS Performance Script
+
+Temporarily optimizes your Linux Mint system for OBS recording/streaming by disabling compositor effects and setting performance-mode CPU/GPU.
+
+### Usage
+
+```bash
+chmod +x obs-performance-script.sh
+./obs-performance-script.sh
+```
+
+This launches OBS with optimizations applied. When you close OBS, all settings are automatically restored.
+
+### What It Optimizes
+
+| Setting | Change | Why |
+|---------|--------|-----|
+| Compositor | Disabled | Frees GPU from rendering shadows, transparency, animations |
+| Fullscreen unredirect | Enabled | Bypasses compositor for fullscreen apps |
+| VSync | Disabled | Reduces GPU overhead and input lag |
+| CPU governor | Performance | Maximum clock speed for encoding |
+| GL threading | Enabled | Better OpenGL performance |
+| PulseAudio latency | 30ms | Better audio/video sync |
+
+### How It Works
+
+1. Saves your current desktop settings
+2. Applies performance optimizations
+3. Launches OBS with GPU-friendly environment variables
+4. **Waits for OBS to close**
+5. Restores all original settings
+
+Your desktop will look plain while OBS is running (no effects/transparency) but returns to normal the moment you close OBS.
+
+### Works With
+
+- OBS installed via apt (`obs-studio`)
+- OBS installed via Flatpak (`com.obsproject.Studio`)
+
+## Uninstalling
+
+### FaceTime HD Camera Driver
+
+```bash
+# Unload module
+sudo modprobe -r facetimehd
+
+# Remove DKMS module
+sudo dkms remove facetimehd/0.6.13 --all
+
+# Remove files
+sudo rm -rf /usr/src/facetimehd*
+sudo rm -f /etc/modprobe.d/blacklist-facetimehd.conf
+sudo sed -i '/facetimehd/d' /etc/modules
+
+# Remove firmware
+sudo rm -rf /lib/firmware/facetimehd
+```
+
+### OBS Performance Script
+
+Just delete the script — it doesn't install anything permanently.
+
+## Credits
+
+- [patjak/facetimehd](https://github.com/patjak/facetimehd) - FaceTime HD camera driver
+- [patjak/facetimehd-firmware](https://github.com/patjak/facetimehd-firmware) - Firmware extractor
+- [OBS Studio](https://obsproject.com/) - Open source streaming/recording
+- [Linux Mint](https://linuxmint.com/) - Target distribution for OBS script
+
+## License
+
+This project is provided as-is.

facetimehd-installer.sh

@@ -1,10 +1,34 @@
 #!/bin/bash
-
-# FaceTime HD Camera Installation Script for Linux Kernel 6.8+
-# Compatible with MacBook Air A1466 EMC 3178 and similar models
-# Author: System Script
-# Version: 1.0
-# Last Updated: 2025
+# ==============================================================================
+# FaceTime HD Camera Driver Installer for Linux
+#
+# Installs the FaceTime HD camera driver on Linux for MacBook Air, MacBook Pro,
+# and iMac models that have the Broadcom 1570 FaceTime HD camera (connected
+# via PCIe, not USB like newer models).
+#
+# Compatible with MacBook Air A1466 EMC 3178 and similar models.
+#
+# What this script does:
+#   1. Detects your distro (Ubuntu/Mint/Debian/Fedora) and kernel version
+#   2. Checks for Secure Boot (the unsigned module won't load with SB enabled)
+#   3. Installs build dependencies (gcc, kernel headers, DKMS, etc.)
+#   4. Cleans up any previous facetimehd installations
+#   5. Downloads and installs the camera firmware from Apple's macOS driver
+#   6. Downloads, patches, and installs the facetimehd kernel module via DKMS
+#   7. Blacklists the conflicting bdc_pci module
+#   8. Loads the module and verifies the camera appears as /dev/videoN
+#
+# DKMS ensures the module is automatically rebuilt when the kernel is updated.
+#
+# The firmware extraction step downloads Apple's Boot Camp driver package,
+# extracts the camera firmware binary, and places it where the kernel module
+# expects to find it (/lib/firmware/facetimehd/).
+#
+# Usage:
+#   chmod +x facetimehd-installer.sh
+#   ./facetimehd-installer.sh
+#   (Do NOT run with sudo — the script uses sudo internally where needed)
+# ==============================================================================
 
 set -e
 

obs-performance-script.sh

@@ -1,6 +1,26 @@
 #!/bin/bash
-# OBS Performance Script for Linux Mint Cinnamon
-# Fixed version for newer Cinnamon versions
+# ==============================================================================
+# OBS Performance Optimizer for Linux Mint (Cinnamon)
+#
+# Temporarily disables desktop effects and compositor overhead while OBS is
+# running, then restores everything when OBS closes. This frees up GPU
+# resources for encoding and reduces frame drops during recording/streaming.
+#
+# What it does while OBS is running:
+#   - Disables the Cinnamon compositor (no transparency, shadows, animations)
+#   - Enables fullscreen unredirect (bypasses compositor for fullscreen apps)
+#   - Disables VSync (reduces input lag, frees GPU cycles)
+#   - Sets CPU governor to performance (maximum clock speed)
+#   - Sets GPU-friendly environment variables (threaded GL, no vsync)
+#   - Reduces PulseAudio latency for better audio sync
+#
+# When OBS closes, ALL settings are automatically restored to their
+# original values. Your desktop goes back to normal.
+#
+# Usage:
+#   chmod +x obs-performance-script.sh
+#   ./obs-performance-script.sh
+# ==============================================================================
 
 # Color codes for output
 GREEN='\033[0;32m'