Architecture & Interface
Built on System Semantics
Upstream had eleven literal colour values in one file alone, font sizes typed at the call site, and corner radii that landed wherever they landed.
MacLC replaces ad-hoc styling with MacLCDesign: a single token layer defining every colour, type style, spacing step, corner radius, material, icon configuration, and animation duration — all mapped to the system's own semantics.
One Window, Eight Panes
Eight categorized panes. A search field indexing labels, descriptions, and keywords. Every setting explains what you will see or hear.
General
Playback behavior, hardware decoding, interface preferences, and engine options.
Startup & Playback
Opens your recent file at the exact timestamp when the app starts.
Floats the video canvas above all other open application windows.
Checks GitHub releases for verified updates without sending device identifiers.
Hardware & Media Engines
Routes AV1, HEVC, and H.264 streams directly through Apple Silicon media engines.
Handles damaged video streams but increases CPU temperature and battery draw.
Replaces scalar loops with SIMD vector instructions on the software-decode path.
Interface & Control
Controls fade out when the cursor rests idle over the video canvas.
Numbers hold steady on the timeline so the layout does not jitter as seconds advance.
Advanced Engine Options 240 guarded options
All 240 configuration reads in the settings panes pass through guarded wrappers. Missing options no longer trigger engine assertions.
Network and disk read-ahead window for smooth scrubbing.
Pins text to standard luminance to prevent blinding subtitles over HDR video.
Interface reconstruction.
The Anatomy of a Setting
Every row in MacLC's settings window is built on three elements: a plain label, an unambiguous system control, and an explanation of what you will actually see or hear.
The House Style Contrast
“highlights keep detail but the picture is dimmer overall”
Tells you what changes on screen. Written in plain English for anyone watching a film.
“applies a BT.2390 EETF”
Exposes internal shader parameters without explaining what your eyes will perceive.
The Token Layer
MacLCDesign maps every visual attribute to semantic tokens. No arbitrary numbers, no hand-typed colours at the call site.
Colour Ramp & Semantic Surfaces
Dark is the default canvas, engineered for extended dynamic range. Light mode maps to equivalent system luminances.
Typographic Hierarchy
Every step scales smoothly via viewport clamps with strict line-heights and negative optical tracking.
--font-display-size clamp(3.5rem, 9vw, 9rem) The quick brown fox jumps over the lazy dog
--font-section-size clamp(2rem, 4.5vw, 3.75rem) The quick brown fox jumps over the lazy dog
--font-subhead-size clamp(1.25rem, 2vw, 1.75rem) The quick brown fox jumps over the lazy dog
--font-body-size clamp(1.0625rem, 1.2vw, 1.1875rem) The quick brown fox jumps over the lazy dog
--font-caption-size 13px The quick brown fox jumps over the lazy dog
--font-mono ui-monospace (tabular-nums) 00:41:12 · 0.53 ms · 6.15×
The 8-Point Grid
All margins, paddings, gaps and dimensions derive strictly from an eight-point geometric progression.
Six Changed Metrics
Six structural layout metrics were pulled off arbitrary numbers and placed onto the 8-point grid. None mattered more than the sidebar row height.
Row Height to Scale: 25 pt vs 32 pt
Below a comfortable click target. Requires precision pointer control on a trackpad and produces cramped vertical rhythm.
Comfortable, forgiving hit target. Ample vertical clearance for text baselines, matching native macOS source lists.
The Complete Metric Audit
| Interface Metric | Upstream VLC | MacLC | Design Rationale |
|---|---|---|---|
| Small sidebar row height | 25 pt | 32 pt | 25 pt was below a comfortable click target on trackpads. 32 pt aligns with Apple Human Interface Guidelines. |
| Window frame corner radius | 10 px | 16 px / 20 px | Replaced arbitrary corner radii with system-aligned squircle geometry. |
| Pane padding and content gutters | 14 px / 18 px | 16 px / 24 px | Snaps irregular margin numbers onto the strict 8-point layout rhythm. |
| HUD transport button hit target | 28 px | 36 px / 40 px | Enlarges clickable boundaries so transport controls are effortlessly selected. |
| Section header spacing | 19 px | 24 px | Restores typographic breathing room for small-caps category titles. |
| Unified titlebar height | 38 px | 48 px | Standard macOS unified toolbar height accommodating search and traffic lights. |
Engineered, Not Just Drawn
In upstream VLC, opening the Interface pane could instantly kill the entire application on specific build configurations.
A missing configuration option hit an assert() deep inside the core engine. It was a hard process termination — a SIGABRT that no error handler could intercept.
The fix routed all 240 configuration reads in the settings panes through guarded wrappers. If an option is absent from a custom build, the wrapper supplies a safe default and logs a diagnostic note. The row simply doesn't draw.
To guarantee stability, MacLC runs an automated startup self-check that instantiates all eight panes and validates every view, control, and symbol.
[MacLCPrefs] Initializing settings controller...
[MacLCPrefs] Auditing 240 guarded configuration reads
[MacLCPrefs] Pane 1/8 (General): OK
[MacLCPrefs] Pane 2/8 (Playback): OK
[MacLCPrefs] Pane 3/8 (Video): OK
[MacLCPrefs] Pane 4/8 (HDR & Colour): OK
[MacLCPrefs] Pane 5/8 (Audio): OK
[MacLCPrefs] Pane 6/8 (Subtitles): OK
[MacLCPrefs] Pane 7/8 (Interface): OK (0 assertions tripped)
[MacLCPrefs] Pane 8/8 (Shortcuts): OK
[MacLCPrefs] Verification complete: 8 panes, 8 ok, 0 failed.Guarded configuration reads replacing raw engine access
Preference categories verified on startup self-test
Uncaught assertion terminations across all supported macOS releases
Accessibility as Architecture
Accessibility here is a consequence of the architecture, not a feature bolted on after the fact.
MacLC follows your system accent colour, light and dark appearance, Reduce Transparency, Reduce Motion, Increase Contrast, VoiceOver, and full keyboard access — because it never hardcoded around them in the first place.
Page-Local System Setting Simulation
Toggle these buttons to test the behavior directly in the demo area below. In the MacLC app, these respond automatically to real macOS system preferences.
App Identity & System Integrity
A native macOS app is defined by the conventions it respects when nobody is looking.
Vector superellipse generated by committed code on Apple's 824/1024 grid.
A Superellipse, Not a Rounded Rectangle
Circular corners look visibly jarring next to system icons. macOS uses a Lamé curve squircle (degree $n = 4.5$). At 16 points in the Dock, that subtle curvature difference is most of what makes an icon look truly native.
Drawn on Apple's standard 824-of-1024 pixel grid. The warm amber bloom behind the play triangle is the only place saturated colour appears — allowing it to read as pure light rather than decorative orange.
The Bundle Identifier Trap
While MacLC initially shared upstream VLC's bundle identifier, macOS resolved the running process to /Applications/VLC.app. Stage Manager drew the cone icon on MacLC windows, and both apps fought over the same preference domain and media library.
MacLC uses its own identifier: org.maclc.MacLC. On first launch, it safely copies preferences, Application Support directories, and defaults across. It never moves or overwrites them. Your existing VLC installation remains untouched and continues to work.
Preserving Every Translation
Forking an internationalized application usually breaks language catalogs. MacLC handles brand renaming downstream of translation lookup: the string resolves "Hide VLC" through existing gettext catalogs, then substitutes the application name to yield "Masquer MacLC" in French.
Built on the System
A media player should disappear into the film when you watch, and behave like standard macOS software when you touch it.
Interface reconstruction. Floating HUD on system material. Timecodes render in tabular-nums so numerals hold steady without layout jitter as playback advances.
No Media Loaded
Drop any video file onto this window, or select a source from the library sidebar.