Spectra

Spectra is a desktop-wide GPU visual effects engine for macOS. It captures your displays in real time with ScreenCaptureKit, runs them through a Metal shader pipeline, and presents the processed result through a fullscreen, click-through overlay. Think ReShade and RetroArch shader presets, applied to the whole Mac desktop, with a native studio for building and stacking effects.

What it does

• Captures every connected display at native resolution and refresh rate (60Hz and 120Hz ProMotion).
• Processes frames entirely on the GPU. There is no CPU image processing and the capture-to-texture path is zero-copy through a CVMetalTextureCache.
• Renders the result back through a per-display overlay window that clicks through to the real desktop beneath it. The overlay presents through a Metal layer that runs at 16-bit float on EDR-capable displays, so bright effect output maps to real HDR luminance; it follows the user across Spaces, and shades native-fullscreen Spaces by elevating to the shielding window level for the duration of the fullscreen Space.
• When a display's stack is made up entirely of per-channel color operations (brightness, contrast, exposure, gamma, black/white point, invert, posterize, solarize, levels), Spectra bakes it into a scanout transfer LUT and applies it through CGSetDisplayTransferByTable instead of the overlay. The grade then holds across every Space, swipe, and full-screen app without any window involved, and the original profile is restored on stop.
• Ships 209 built-in effects across 17 categories, almost all real Metal fragment shaders (plus the desktop-level system effects and the MAOE interaction, window-chrome, and cursor layers).
• Stacks effects in any order, with per-effect strength, opacity, blend amount, and one of 16 blend modes applied to every effect for free.
• Stores presets, and includes a curated library (Golden Hour, Fuji-Film, Noir, Cyberpunk, The Matrix, VHS Tape, Frutiger Aero, Painting, Print Art, Comic Book, Pencil Sketch, and more).
• Lets you build new effects visually by composing existing building blocks, with a live preview, auto-generated controls, exposed parameters, and a generated thumbnail. No graphics programming required.
• Imports and exports .metal, .shader, .json, and .spectra files, compiling and validating imported shaders before they ever touch the renderer. Drop a shader file into the library folder and Spectra imports and hot-reloads it automatically.

The studio

One unified workspace, no modes. Everything lives in a single coherent window, with the desktop itself serving as the live preview behind it:

• Effect Library on the left: the primary interface. Search, filter by category, tag, or favorites, and add effects to the stack. Custom effects can be edited, duplicated, exported, or deleted in place; multi-select adds several at once.
• Effect Stack and Parameters on the right: add, remove, reorder (drag and drop), duplicate, rename, group, enable, and disable layered effects, with universal and effect-specific controls beneath. A segmented switch at the top of the panel swaps the stack for the global Glass desktop treatments (window transparency, layout, and tint).
• Performance in a collapsible drawer pinned to the bottom, hidden by default: frame rate, GPU and CPU time, latency, dropped frames, pipeline analysis, and on-demand per-effect cost profiling.

A menu bar item is always available for quick start/stop (also bound to a global hotkey), preset switching (grouped by category), an intensity slider, a quality slider with an Auto toggle that hands control to the adaptive governor, and a Glass toggle for the yabai-driven window transparency layer (⌘T toggles Window Transparency from anywhere, and ⌘0 moves the focused window to a new Space). Live fps and latency read at a glance, with shortcuts into the Studio and Settings windows. The Dock tile only appears while the Studio window is open; closing it drops the app back to a menu bar plus overlay process.

Authoring effects

There is one editor: a visual composer. You assemble a new effect from a palette of building blocks (color operations, blurs, distortions, noise, blends), tune each with the standard inspector, watch it live, choose which parameters to expose, set its name, category, tags, and description, and save it into the library as a reusable effect. Authored effects can be exported and shared.

Shader authors who prefer to write Metal directly do so in their own editor and drop the .metal or .shader file into the library folder. Spectra compiles it against its shader prelude, infers controls from the parameters it references, validates it, and registers it without a relaunch. A misbehaving shader can never crash the renderer: compile failures report diagnostics, and a GPU fault disables the offending effect automatically.

Effect library

209 effects, grouped into 17 categories:

• Color (26): brightness, contrast, saturation, vibrance, exposure, gamma, highlights, shadows, whites, blacks, black/white point, temperature, tint, sepia, invert, posterize, solarize, color balance, levels, hue shift, channel mixer, tone curve, freehand curves, color LUT, gradient map.
• Sharpen (6): sharpen, unsharp mask, clarity, local contrast, detail enhancement, edge enhancement.
• Blur (8): gaussian (separable), lens, directional, motion, zoom, bokeh, depth, tilt shift.
• Distortion (12): warp, bulge, pinch, fish eye, barrel, chromatic, heat, wave, ripple, swirl, shockwave, perspective.
• Retro / CRT (14): CRT, CRT advanced, scanlines, shadow mask, aperture grille, curvature, bloom, phosphor glow with temporal persistence, composite video, RF signal loss, color bleed, NTSC, PAL, analog television.
• VHS (12): tracking, wrinkle, dropouts, chroma drift, head switch, jitter, vertical roll, noise bands, damage, generation loss, color smear, audio-reactive tracking.
• Camcorder (10): consumer 90s, digital 2000s, MiniDV, Hi8, VHS-C, interlacing, compression, auto-exposure pulse, autofocus hunt, REC on-screen display with ticking timecode, date stamp, and zoom readout.
• Film (16): 16mm, 35mm, 70mm, Kodak, Fuji, grain, dust, scratches, gate weave, debris, light leaks, halation, bloom, glow, flicker, burn.
• Noise (14): white, gaussian, blue, pink, brown, perlin, simplex, cellular, sensor grain, sensor, compression, dust, speckle, digital.
• Pixel (12): pixelation, pixel sort, dithering, ordered dither, bayer, floyd-steinberg, color quantization, retro resolution, Game Boy, PS1, N64, arcade.
• Glitch (13): datamosh, RGB split, scan corruption, frame tearing, signal corruption, digital failure, compression glitch, buffer corruption, bit crush, macroblocking, frame repeat, frame skip, digital rain. Datamosh and the frame repeat/skip effects use a true previous-frame feedback texture.
• Environment (12): rain, fog, snow, dust motes, bubbles, splash, underwater, heat haze, god rays, sun glare, lens flare, cloud overlay.
• Artistic (11): oil paint (colour-region cells), line art (XDoG), flatten, quantize, cel, ink, halftone, cross-hatch, paper, impasto relief, pencil sketch.
• Interaction (27): event-driven cursor and window-lifecycle effects — click pulses and ripples, drag trails (gold dust, liquid, glyph), scroll/motion signatures (CMYK shift, speed lines, light leak), Space-switch transitions (hyperspace streak, glyph rain, iris, film squares), open/close bursts (bubble pop, window glitch, shadow collapse, caption collapse, decode), a draw-on-screen pencil tool, audio-reactive bloom, and a keystroke glyph. Each carries a trigger kind so the renderer skips the pass entirely while idle.
• Cursor (1): a single pointer effect that swaps the system cursor for a built-in sprite or your own images, with an optional press animation.
• Window Chrome (10): per-window borders, an ornate sprite frame, shadows, vignettes, focus dim, title strips, a window-rain mask, a window-punch hole, and in-shader menu-bar and dock styling — all masked from the live window list each frame.
• System / Desktop (5): window transparency, automatic window layout, adaptive desktop tint, menu-bar style, and dock style (driven by yabai and desktop-level overlays rather than fragment shaders; the yabai-backed rows gate gracefully when yabai is absent).

Every effect automatically carries strength, opacity, blend amount, blend mode, and an enable toggle, composited by a single shared helper so the behavior is consistent across the whole library. Curves, gradients, and LUTs are edited with dedicated controls and baked into auxiliary GPU textures.

Multi-monitor

Each display has its own effect stack and its own preset, capturing and rendering independently at its native resolution and refresh rate. Displays can be enabled or disabled individually, and hot-plugging is handled live. Per-display stacks and presets persist across launches.

Performance

Spectra reports per-display and combined frame rate, CPU encode time, GPU time, frame interval, capture-to-present latency, dropped frames, GPU pass count, and VRAM in use. A pipeline analysis panel summarizes the resolved chain, and an on-demand profiler measures each effect's real GPU cost in isolation. When adaptive quality is on and GPU time runs past the display's frame budget, it lowers capture resolution in steps and restores it when headroom returns.

The target is under 16ms latency with minimal CPU use. Rendering is driven by a per-window CAMetalDisplayLink whose callback fires off the main run loop on a dedicated render thread, gated by double buffering to trim a frame of present latency. Intermediate textures are recycled through a pool to avoid per-frame allocation.

Requirements

• macOS 15 or later (built and tested against the macOS 26 SDK).
• Apple Silicon.
• Screen Recording permission, which Spectra requests on first use.

Build and run

See BUILD.md. The short version:

xcodegen generate
open Spectra.xcodeproj   # then run, or:
xcodebuild -project Spectra.xcodeproj -scheme Spectra -configuration Debug \
  -destination 'platform=macOS' build

On first launch, grant Screen Recording access in System Settings when prompted, then click the green Start button in the toolbar to begin rendering. The same button turns red ("Stop") while effects are running, and the menu bar item offers the same Start/Stop toggle plus a global hotkey for it.

Architecture

See technical-spec.md for the module breakdown, the effect contract, and the render pipeline. The codebase is organized into focused modules (Core, Capture, Render, Effects, Shaders, Presets, Storage, Performance, Editor, Engine, Scene, System, Licensing, UI, App) wired together through a single injected SpectraEngine coordinator.

License

MIT. See LICENSE.