Skip to content

Install the CS4208 speaker driver on 12-inch MacBooks - #6921

Open
sunoxen-lab wants to merge 4 commits into
omacom:quattrofrom
sunoxen-lab:fix-macbook12-cs4208-audio
Open

sunoxen-lab wants to merge 4 commits into
omacom:quattrofrom
sunoxen-lab:fix-macbook12-cs4208-audio

Conversation

@sunoxen-lab

Copy link
Copy Markdown

Summary

On the 12-inch MacBook (MacBook9,1 / 2016 and MacBook10,1 / 2017), mainline snd_hda_codec_cs420x detects the Cirrus Logic CS4208 and PipeWire plays to it, but the speaker amplifier is never enabled. The OS thinks audio is working; the speakers stay silent. Headphones can still work because they use a different path.

This is the same gap as #2101. Grok diagnosed it on a MacBook10,1 running Omarchy 4, installed leifliddy/macbook12-audio-driver via DKMS, and speakers came up. This PR is that fix paid forward to the next installer.

What it does

  • New hardware leaf install/hardware/apple/fix-cs4208-audio.sh, same shape as the SPI keyboard fix: detect MacBook9,1 / MacBook10,1, then omarchy-pkg-add macbook12-audio-driver-dkms.
  • MacBook8,1 (2015) is left alone; that model is not supported by this driver.
  • Migration 1786719479.sh for existing installs. No-ops if the package is already present or if the same DKMS module was installed by hand.
  • Cached in install/omarchy-other.packages so the ISO can ship it.
  • Manual note in manual/44-mac-support.md.

Omarchy already applies software volume globally, so the extra WirePlumber soft-mixer step from the driver README is not needed here.

Package

This needs macbook12-audio-driver-dkms in pkgs.omarchy.org, built from https://github.com/leifliddy/macbook12-audio-driver — the same source that restored speakers on the machine this was written on.

It is not in the repo yet. Land the package with this PR (or immediately before), the way macbook12-spi-driver-dkms already is. The DKMS PRE_BUILD downloads matching kernel HD-audio headers on the target, so the package only needs to ship the driver source and dkms.conf.

Test plan

  • test/shell.d/cs4208-audio-test.sh — leaf and migration fire only on MacBook9,1 / MacBook10,1, skip 2015 / Pro / non-Apple, skip when the package or a hand-installed DKMS module is already there
  • Verified on a 2017 12-inch MacBook (MacBook10,1): after the DKMS module, speakers play; jack switch still works

Mainline detects the codec on MacBook9,1 and MacBook10,1 but never
enables the speaker amp, so PipeWire plays to a silent analog path.
Copilot AI balanced review requested due to automatic review settings August 15, 2026 05:13

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds automatic installation and migration support for the CS4208 speaker driver on 12-inch MacBooks (2016/2017), plus coverage to validate wiring and behavior.

Changes:

  • Wire a new Apple hardware setup leaf to install the CS4208 DKMS driver on supported MacBook models.
  • Add a migration to retrofit existing installs while skipping machines already configured.
  • Add shell tests asserting setup wiring, model matching, and migration behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
test/shell.d/cs4208-audio-test.sh Adds integration-style shell tests for the new leaf + migration behavior.
migrations/1786719479.sh Introduces a migration to install the CS4208 driver on eligible machines and request reboot.
manual/44-mac-support.md Documents that the installer applies the CS4208 speaker driver fix on supported models.
install/omarchy-other.packages Ensures the ISO caches macbook12-audio-driver-dkms.
install/hardware/apple/fix-cs4208-audio.sh Adds the install-time hardware fix leaf for CS4208 audio.
install/hardware/all.sh Wires the new CS4208 fix into the hardware setup pipeline.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment on lines +1 to +14
# Enable speakers on 12-inch MacBooks (MacBook9,1 / 2016 and MacBook10,1 / 2017).
# Mainline snd_hda_codec_cs420x detects the CS4208 but never runs the macOS
# init that powers the speaker amplifier, so PipeWire plays to a silent analog
# path. The out-of-tree module replays that init.
# MacBook8,1 (2015) is not supported by this driver.
# https://github.com/leifliddy/macbook12-audio-driver
# https://github.com/basecamp/omarchy/issues/2101

product_name="${OMARCHY_MACBOOK12_AUDIO_MODEL:-$(cat /sys/class/dmi/id/product_name 2>/dev/null)}"
if [[ $product_name == "MacBook9,1" || $product_name == "MacBook10,1" ]]; then
echo "Detected 12-inch MacBook with CS4208 audio"

omarchy-pkg-add macbook12-audio-driver-dkms
fi
if [[ $product_name == "MacBook9,1" || $product_name == "MacBook10,1" ]]; then
echo "Detected 12-inch MacBook with CS4208 audio"

omarchy-pkg-add macbook12-audio-driver-dkms
Comment thread migrations/1790562029.sh
Comment on lines +1 to +23
echo "Install the CS4208 speaker driver on 12-inch MacBooks"

# Fresh installs get this from install/hardware/apple/fix-cs4208-audio.sh.
# Existing MacBook9,1 / MacBook10,1 installs still have silent speakers:
# mainline detects the codec and PipeWire plays, but the speaker amp is never
# enabled. Skip machines that already have the packaged module or the same
# DKMS driver installed by hand.

product_name="${OMARCHY_MACBOOK12_AUDIO_MODEL:-$(cat /sys/class/dmi/id/product_name 2>/dev/null)}"
if [[ $product_name != "MacBook9,1" && $product_name != "MacBook10,1" ]]; then
exit 0
fi

if omarchy-pkg-present macbook12-audio-driver-dkms; then
exit 0
fi

if dkms status 2>/dev/null | grep -q '^macbook12-audio/'; then
exit 0
fi

omarchy-pkg-add macbook12-audio-driver-dkms
omarchy-state set reboot-required
grep -Fq $'omarchy-state\tset\treboot-required' "$calls" ||
fail "the migration asks for the reboot that loads the module" "$(cat "$calls")"
pass "the migration installs the CS4208 driver"

fail "the CS4208 audio fix runs during hardware setup"
grep -qx 'macbook12-audio-driver-dkms' "$other_packages" ||
fail "the ISO caches the CS4208 speaker driver"
grep -Fq 'MacBook9,1' "$leaf" && grep -Fq 'MacBook10,1' "$leaf" ||
dhh and others added 2 commits August 15, 2026 03:15
Upstream's dkms.conf sets PACKAGE_NAME="macbook12-audio-driver", so
dkms status prints that, never "macbook12-audio". The skip for a
hand-installed driver never fired, and the test stub printed the same
wrong name so it passed anyway.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The CS4208 clause landed between them and the NVMe fix, which made the
NVMe fix read as 12-inch only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings August 15, 2026 10:15

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

install/hardware/apple/fix-cs4208-audio.sh:13

  • Installing only the DKMS module leaves this hardware setup incomplete. Upstream marks software volume as required because the speaker path has no usable hardware volume control, but this repository only copies alsa-soft-mixer.conf for ASUS ROG machines (install/user/hardware/asus/fix-audio-mixer.sh:3-5). These MacBooks therefore get no soft mixer or persisted mixer initialization, so the volume slider can remain ineffective. Add MacBook-specific user setup and backfill it for existing users.
  omarchy-pkg-add macbook12-audio-driver-dkms

migrations/1786719479.sh:18

  • This matches every DKMS state, including macbook12-audio-driver/0.1: added or a build installed only for an old kernel. In those cases the migration exits even though the running kernel still lacks the driver. Query the running kernel and only skip when DKMS reports installed.
if dkms status 2>/dev/null | grep -q '^macbook12-audio-driver/'; then

linux-ptl
linux-ptl-headers
macbook12-spi-driver-dkms
macbook12-audio-driver-dkms
@doctor

doctor commented Aug 16, 2026

Copy link
Copy Markdown

I validated this approach on the affected hardware: a MacBook10,1 running Omarchy with the CS4208 codec. The internal speakers work, and PipeWire reports the expected two-channel stereo profile.

I found two integration gaps before this can land cleanly:

  1. macbook12-audio-driver-dkms did not yet exist in the Omarchy package repository. I added it in omarchy-pkgs#153.
  2. The CS4208 needs its hardware mixer held at full scale while user volume is handled in software. I opened sunoxen-lab/omarchy#1 directly against this PR's source branch, so you can merge it here without superseding your original contribution. It also makes the migration idempotent, preserves working manual installations, repairs missing current-kernel DKMS builds, and adds 12 focused tests.

The corresponding upstream driver lifecycle fix is macbook12-audio-driver#60.

This keeps #6921 as the main Omarchy PR while giving each repository a focused, reviewable change.

migrations/1786719479.sh already exists on quattro as the Antigravity agent migration. omarchy-migrate records completion by filename, so sharing it would both conflict on merge and skip this migration on every machine that already ran the other one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed at 73d8acca. The approach is right and the size fits the bug, but it can't land yet. Two things block it, and one smaller defect remains.

Pushed: 73d8acca renames the migration to migrations/1790562029.sh and updates the test to match. 1786719479.sh already exists on quattro as the Antigravity agent migration. omarchy-migrate records completion by filename, so keeping that name would conflict on merge and would skip this migration on every machine that already ran the other one. This was the only merge conflict. If sunoxen-lab#1 still edits the old filename, it will need the same rename.

Blocking:

  1. The package doesn't exist yet. pacman -Si macbook12-audio-driver-dkms returns "not found" on a stock Omarchy worker. omarchy-pkg-add exits 1 when pacman fails, so on a MacBook9,1/10,1, install/hardware/apple/fix-cs4208-audio.sh:13 aborts hardware setup on a fresh install. The migration fails the same way during omarchy update, which stays pending and holds up the migrations after it. The ISO builder also downloads everything in install/omarchy-other.packages, so the new entry breaks ISO builds for every machine. This needs Add MacBook12 CS4208 DKMS package omarchy-pkgs#153 (still open) to land first.
  2. Speaker volume won't work. The PR description says Omarchy already applies software volume globally. On quattro it doesn't: alsa-soft-mixer.conf is installed only by install/user/hardware/asus/fix-audio-mixer.sh, behind omarchy-hw-asus-rog. The driver's README says the speaker path has no hardware volume, so once the driver loads, the volume slider will have no effect on the speakers. MacBook9,1 / 10,1 internal speakers silent after install (driver alone isn't enough; EFI chime must be un-muted) #12008, which reports this bug on a MacBook9,1, found the same thing. Complete CS4208 volume and suspend setup for Omarchy #6921 sunoxen-lab/omarchy#1 adds a CS4208-scoped soft-mixer rule, so incorporating it here is the natural fix.

Also: the hand-install guard at migrations/1790562029.sh:18 matches any dkms status line for the module, including added and built. A manual install that never finished therefore counts as present, the migration marks itself done, and the speakers stay silent. Matching : installed would fix it. sunoxen-lab#1 reworks this check as well.

The Copilot notes about missing shebangs and set -euo pipefail don't apply: AGENTS.md on quattro says scripts under install/ and migrations/ are sourced and intentionally leave them out, and omarchy-migrate runs migrations with bash -euo pipefail.

Tested: on a disposable Omarchy worker, test/shell.d/cs4208-audio-test.sh passes 10/10 at this head and on a merge with current quattro. ./test/cli passes at this head. On the merge it has one failure, vscode generated theme references current theme file, which fails identically on bare quattro, so it isn't caused by this PR. No worker has this hardware, so the speaker fix itself is unverified by us. The author and a commenter both report it working on a MacBook10,1 with the driver installed by hand.

Related: #12008 is the open issue for this bug. It also names un-muting the startup chime in NVRAM as a third requirement on some units, which this PR doesn't address, so it isn't linked as fixed. #12689 (draft) folds this PR into a larger Intel Mac audio consolidation. Asked to compare them without being told our view, Codex Medium recommended carrying this one forward as the focused fix, with the software-volume work added, over the consolidation.

Second opinion: Codex Medium reviewed this head. It raised the package, software-volume and DKMS-guard findings above, and I checked each against quattro before including it. Independence isn't guaranteed, because it can read this session's working notes.

Waiting on: the author, for software volume (for example by merging sunoxen-lab#1) and the DKMS guard. It also needs the maintainer to land omacom/omarchy-pkgs#153. After that, it needs a test at the full head SHA on a MacBook9,1 or 10,1.

@martin-irwin

Copy link
Copy Markdown

Heads-up for 12-inch MacBook audio: the out-of-tree driver this installs has no headphone support, so the 3.5 mm jack stops working once it's installed. I posted details and a stock-driver alternative that keeps both speakers and headphones in #12689: https://github.com/martin-irwin/macbook12-cs4208-audio

@omarchybot

Copy link
Copy Markdown
Collaborator

Checked again at 73d8acca, which hasn't moved, against quattro at e19607fc. One new claim on this thread doesn't hold, one of my earlier suggestions needs correcting, and the two blockers are unchanged.

The headphone jack. The comment above says the driver has no headphone support, that its README says so, and that headphones_a1534 is commented out. That isn't true of the code this PR would install. At 04500a12, the commit omacom/omarchy-pkgs#153 pins, and on the driver's current master (bd8bf062), headphones_a1534 is defined in patch_cirrus/patch_cirrus_a1534_setup.h, called from cs_4208_playback_pcm_open when the jack on pin 0x10 is occupied, and called again from a jack callback registered on that pin, which moves a running stream between speakers and headphones. The README at both commits lists the headphone jack and automatic switching as working. That support landed upstream in June (5c3582f4); the description fits the driver before then. This is from reading the source. No worker has this codec, so neither the jack nor the speakers were heard.

Correction to my earlier note on the DKMS guard. I suggested matching : installed at migrations/1790562029.sh:18. On its own that trades one failure for another. Upstream's install.cirrus.driver.sh -i copies the driver into /usr/src/macbook12-audio-driver-0.1 before DKMS builds it, and the package in omacom/omarchy-pkgs#153 installs to the same directory. A hand install that stopped at added or built would then pass the tightened guard, omarchy-pkg-add would fail on files that already exist, and the migration would stay pending on every update. The guard as written still marks that machine done with silent speakers: on the worker, a dkms status of macbook12-audio-driver/0.1: added made the migration exit 0 without installing anything. A fix has to handle the half-installed case on purpose, either by removing the hand registration and its source directory before installing the package, or by stopping with a message that says what to remove.

Still blocking, as before:

  1. The package isn't published. On a stock Omarchy worker today, pacman -Si macbook12-audio-driver-dkms returns "not found". Run as a MacBook10,1, both migrations/1790562029.sh and install/hardware/apple/fix-cs4208-audio.sh exit 1 with target not found. Add MacBook12 CS4208 DKMS package omarchy-pkgs#153 is still open.
  2. Nothing here installs the software-volume rule, and quattro still installs alsa-soft-mixer.conf only on ASUS ROG machines. In MacBook9,1 / 10,1 internal speakers silent after install (driver alone isn't enough; EFI chime must be un-muted) #12008 a MacBook10,1 owner now reports the speakers and the volume slider both working with the driver built by hand plus a 51-macbook-cs4208-softvol.conf rule, and with the startup chime left alone. That supports adding the rule here. It was a hand install of a different driver commit, not this head, so it doesn't stand in for a test of this PR.

Tested: on a disposable Omarchy worker, with this head merged into current quattro (the merge is clean): test/shell.d/cs4208-audio-test.sh passes 10/10 and ./test/cli passes. Run as a MacBookPro11,5 the migration exits 0 and does nothing. The speaker fix itself can't be tested until the package exists.

Second opinion: Codex Medium and muse-wonder (via pi, thinking high) each read the driver source and this head. Both found the headphone claim false at the pinned commit and on master, both found the : installed collision when asked about it, and neither found anything new at this head. Their independence isn't guaranteed, because they can read this session's working notes.

Waiting on: the maintainer, for whether to publish the driver package (omacom/omarchy-pkgs#153); nothing here can be installed or tested without it. Then the author, for the software-volume rule and the guard. After that it needs a test at the full head SHA on a MacBook9,1 or 10,1.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working compatibility Make Omarchy work better on everything!

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants