Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Keep original product ID, use override to get both audio and display working simultaneously

Guilherme Rambo1e7551bc689e
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 0fc17666..c4379b64 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -1,5 +1,21 @@
# Patch Comparison: Regular / Development / Jailbreak / Experimental
+> **HomePod audio-only identity correction (2026-10-23).**
+> An A/B boot of the same installed bundle, changing only the validated donor
+> product token back to its prior virtual value, restores the native red replay;
+> restoring the donor token blacks the same fixture. The donor identity enables
+> HomePodDisplayService's physical gamma path, which requires absent brightness
+> hardware. Audio now selects native B520 route **4** through VirtualAudio's own
+> `ProductIDOverride`, stored by vphoned and set in-process by the HAL plugin.
+> The boot-tree HomePod capability patch retains the original VM product token.
+> `preboot-homepod-exp-audio_product` is now blocked in every preset; its existing
+> inverse restores previously installed guests from the shared Preboot backup.
+> The old repair remains declared for explicit research and reversible migration.
+> No display workaround or new instruction patch. All 88 focused Xcode firmware
+> tests, four audio transport harnesses, the unchanged display adapter harness,
+> the full bundle build and strict signature verification pass. Final install
+> and combined audio/display validation await the owner's availability.
+
> **HomePod audio port (2026-10-22, live routing validation).**
> New `preboot-homepod-exp-audio_product` restores the donor's exact 20-byte
> `/product/product-id` in Preboot through the existing reversible repair
diff --git a/Research/Firmware/homepod_mini_support.md b/Research/Firmware/homepod_mini_support.md
index 98a2ef6b..ed986f6f 100644
--- a/Research/Firmware/homepod_mini_support.md
+++ b/Research/Firmware/homepod_mini_support.md
@@ -42,7 +42,10 @@ family. The HomePod mini uses the existing TVOS-retargeted vphoned executable.
`homepod-mini` selects the existing 27 userland/kernel compatibility patches
and vphoned. GPU injection, iPhone audio/camera/sensor/environment hooks,
Apple TV OTA replacement and plain-arm64 TPRO workarounds stay off. The shared
-virtio-snd driver and donor product identity repair now load on HomePod;
+virtio-snd driver selects B520 routing through VirtualAudio's audio-only
+`ProductIDOverride = 4`; the global VM product token stays unchanged. The donor
+token repair is blocked by default, including on HomePod. The existing Preboot
+inverse restores this VM's original token during an environment update. The
[audio routing and live findings](../Guest/homepod_audio.md) track the remaining
output work. Physical accessory transports require separate validation.
diff --git a/Research/Guest/homepod_audio.md b/Research/Guest/homepod_audio.md
index a9f56a0a..cbc88a0f 100644
--- a/Research/Guest/homepod_audio.md
+++ b/Research/Guest/homepod_audio.md
@@ -12,11 +12,62 @@ The owner authorized live tests. Launchpad installed the final
`2.11.0-local.b284734a`, passed host preflight, and updated `homepod-mini`'s
guest environment. Ordinary AVAudioPlayer playback reaches the Mac's selected
Studio Display speakers, and the owner confirmed **“Yes, clear tones.”**
-Native HomePod identity, B520 routing, the tvOS HAL driver and the 48 kHz
+Donor HomePod identity, B520 routing, the tvOS HAL driver and the 48 kHz
physical endpoint are verified. Both 48 kHz and 44.1 kHz source WAVs play
without a preferred-sample-rate override. The earlier failed iterations and
their discriminating probes are retained below.
+### Product identity regression and audio-only correction (2026-10-23)
+
+The donor product token used by that audio build also changes unrelated
+MobileGestalt clients. An A/B boot using the same bundle and device tree,
+changing exactly its 20-byte product token, restores the red LED replay with
+the original virtual token (RGB/icons 0.749996), and blacks it with the donor
+token. Native animation buffers remain red. `HPDSProductType.hasSiriGammaLUT`
+now selects the physical gamma path; unlike the prior direct color path it
+requires CoreBrightness input that the VM does not provide. The candidate
+physical power-limiter exemption did not fix this and was removed.
+
+Keep the original global token. VirtualAudio already offers a narrower
+boundary: its resolver at `0x26d4ec` reads integer `ProductIDOverride` in
+`com.apple.audio.virtualaudio`, takes the value directly at `0x26d528`, and
+returns it at `0x26dc70` without MobileGestalt/acoustic-ID mapping. **4** is its
+native B520 product enum, distinct from the iPhone's 8010 choice. The wrapper
+at `0xc16f0` caches the result, so the preference must precede initialization
+or audiomxd must restart. Other direct MG queries still exist in VirtualAudio;
+this static evidence needs live playback validation with the original token.
+
+The HAL plugin and vphoned now choose 4 for exactly AudioAccessory5,1, honoring
+the existing explicit override including zero. Other guests retain their prior
+policy. The boot-tree capability patch leaves product-id untouched. Every
+preset blocks the old donor identity repair; updating an existing guest rebuilds
+Preboot from its retained clean backup and reapplies the remaining repairs.
+This VM's backup contains the original virtual token. A boot baseline already
+containing a donor token is not reconstructed by disabling that repair; retain
+its original research tree before migration. No display shim changes remain.
+
+The owner asked to defer further authenticated bundle updates. The installed
+display candidate is not the final audio-only build; final install and cold-boot
+audio/display validation remain pending availability. Research artifacts are
+under `.build/homepod-audio-research/display-regression-*`.
+
+Local verification: all **88** focused Xcode firmware tests pass, including
+the original-token fixture, all-preset donor-repair exclusion, shipped/built-in
+preset agreement, and shared Preboot inverse composition. Four audio transport
+harnesses and the unchanged display identity harness pass. The full `VPhone`
+bundle build and `codesign --verify --deep --strict` pass. The final bundle is
+`.build/XcodeBundle/Build/Products/Debug/VPhone.bundle`; it was not installed.
+
+A guest-only read/write Preboot remount was rejected by automatic approval
+review because it changes boot-volume protection. That probe was not executed
+or retried. Use the normal authorized Launchpad environment update when the
+owner returns. The temporary audio override was restored to its originally
+absent state, other diagnostic preferences were restored, and the VM was
+stopped. Its installed host/guest bundle remains `2.11.0-local.f695af7f` (the
+failed limiter candidate), with the donor token still installed. The final
+source contains no display workaround; the next environment update must
+replace that candidate and apply the newly disabled donor repair's inverse.
+
## Native reveal procedure
The donor filesystem is the already-extracted IPSW image
@@ -67,11 +118,11 @@ The ledger, donor hashes, original disassembly, extracted ASD method encodings,
reproducible product-table probe, native diagnostic records, and closed REA
snapshot are retained under `.build/homepod-audio-research/`.
-## Implementation
+## Initial implementation (superseded identity policy)
`preboot-homepod-exp-audio_product` copies the validated donor product digest
into the restored Preboot device tree. It is declared, optional, HomePod-only,
-27.x-gated, and selected only by `homepod-mini`. It joins the existing Preboot
+27.x-gated, and was selected only by `homepod-mini`. It joins the existing Preboot
repair composition and its inverse rather than overwriting unrelated tree
repairs. New boot trees also receive that digest through the HomePod product
patch. The literal donor digest is never embedded in patch logic.
diff --git a/VPhoneDaemon/Daemon/GuestVirtualAudioProduct.swift b/VPhoneDaemon/Daemon/GuestVirtualAudioProduct.swift
index cf195363..ede57bbb 100644
--- a/VPhoneDaemon/Daemon/GuestVirtualAudioProduct.swift
+++ b/VPhoneDaemon/Daemon/GuestVirtualAudioProduct.swift
@@ -47,12 +47,14 @@ enum GuestVirtualAudioProduct {
}
/// The same answer as the plugin's `VPGuestProductID`: 8010 on an iPad or
- /// iPhone guest, 0 (no override) on anything else, unless one was chosen.
- /// HomePod mini keeps native routing through its donor product identity.
+ /// iPhone guest, native B520 route 4 on HomePod mini, 0 elsewhere unless
+ /// one was chosen. This preference affects only VirtualAudio; the VM keeps
+ /// its original MobileGestalt product token for every other subsystem.
static func product(machine: String, chosen: Int?) -> Int {
if let chosen, chosen >= 0 {
return chosen
}
+ if machine == "AudioAccessory5,1" { return 4 }
return machine.hasPrefix("iPad") || machine.hasPrefix("iPhone") ? 8010 : 0
}
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreeGuestDevicePatches.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreeGuestDevicePatches.swift
index 8bee2b1f..f08a54af 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreeGuestDevicePatches.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreeGuestDevicePatches.swift
@@ -185,8 +185,8 @@ extension DeviceTreePatcher {
edits.append(GuestEdit(nodePath: product, property: name,
action: action, patchID: homePodProductPatch))
}
- edits.append(GuestEdit(nodePath: product, property: "product-id",
- action: .set(try homePodAudioProductID(from: source)), patchID: homePodProductPatch))
+ // Keep the VM product token. Audio uses VirtualAudio's local
+ // ProductIDOverride; a donor token changes unrelated MG clients.
}
for (name, patchID) in copiedProductProperties {
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareDeviceTreePatchSet.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareDeviceTreePatchSet.swift
index 268dcd30..fddc9148 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareDeviceTreePatchSet.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareDeviceTreePatchSet.swift
@@ -218,7 +218,7 @@ public enum FirmwareDeviceTreePatchSet {
property(
"devicetree-cfw-homepod_product",
"HomePod product capabilities",
- "Copies the HomePod mini's horseman, siri-hub, app architecture and concrete 20-byte product-id properties from its own board tree, so MobileGestalt recognizes the accessory and selects its native audio family. Other boards and the restore tree are unchanged.",
+ "Copies the HomePod mini's horseman, siri-hub and app architecture properties from its own board tree, retaining the VM's product-id token. Audio routing uses an audio-only preference. Other boards and the restore tree are unchanged.",
),
// MARK: TV Guest
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
index e8f0845e..760c886a 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
@@ -494,8 +494,8 @@ public enum FirmwareGuestSystemPatchSet {
),
VPhonePatchDeclaration(
identifier: homePodAudioProduct,
- title: "HomePod native audio identity",
- summary: "Copies the HomePod mini donor's concrete 20-byte product-id into its installed Preboot device tree. MobileGestalt then selects the native HomePod audio family instead of the virtual phone's, without an iPhone ProductIDOverride. Rebuilt from the shared Preboot repair backup when disabled.",
+ title: "HomePod donor product identity (experimental)",
+ summary: "Copies the donor's product-id into Preboot, changing MobileGestalt identity system-wide. Off in every preset: audio uses VirtualAudio's local product override instead. Retained for explicit research and to restore the shared Preboot backup when disabled after an earlier install.",
target: .prebootDeviceTree,
applicability: VPhonePatchApplicability(iOSBase: .major(27)),
),
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
index b867110c..f26ae38f 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
@@ -318,14 +318,15 @@ public enum FirmwarePatchSetCatalog {
/// HomePod mini uses its own monolithic arm64e TVOS IPSW. Keep the 27
/// kernel compatibility patches, but never swap in an Apple TV OTA or
/// install the iPhone GPU/routing environment. The shared virtio audio
- /// driver uses HomePod's own product identity and routing implementation.
+ /// driver selects native B520 routing through an audio-only preference,
+ /// retaining the original VM product token for other services.
public static let homePodMiniPreset = VPhonePatchPreset(
identifier: VPhonePatchPreset.homePodMiniIdentifier,
title: "HomePod mini",
- summary: "Research: HomePod mini's own arm64e TVOS IPSW with vphoned, its donor-driven top cap, local setup completion and virtio audio using its native identity, without Apple TV OTA replacement or iPhone display, camera and routing hooks.",
+ summary: "Research: HomePod mini's own arm64e TVOS IPSW with vphoned, its donor-driven top cap, local setup completion and virtio audio using an audio-only B520 route, without changing the VM product token or adding Apple TV OTA replacement or iPhone display, camera and routing hooks.",
patchSets: bundledReferences,
selection: .block(
- manualOnlyPatches.subtracting([FirmwareGuestSystemPatchSet.homePodTopCap, FirmwareGuestSystemPatchSet.homePodSetupBypass, FirmwareGuestSystemPatchSet.homePodAudioProduct])
+ manualOnlyPatches.subtracting([FirmwareGuestSystemPatchSet.homePodTopCap, FirmwareGuestSystemPatchSet.homePodSetupBypass])
.union(tvOSBlockedPatches.subtracting(tvOS27UserlandPatches).subtracting([FirmwareGuestSystemPatchSet.virtioSoundDriver])),
),
)
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/DeviceTreeGuestDeviceTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/DeviceTreeGuestDeviceTests.swift
index e8b5d0da..84cb9531 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/DeviceTreeGuestDeviceTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/DeviceTreeGuestDeviceTests.swift
@@ -311,8 +311,13 @@ struct DeviceTreeGuestDeviceTests {
// MARK: - Tests
@Test func `HomePod installed identity copies accessory capabilities and removes placeholder artwork`() throws {
+ let originalToken = Data(0..<20)
+ let originalProduct = Self.tree.children[0]
+ let tree = Node(properties: Self.tree.properties, children: [
+ Node(properties: originalProduct.properties + [Property(name: "product-id", flags: 0, value: originalToken)], children: originalProduct.children),
+ ] + Self.tree.children.dropFirst())
let patcher = DeviceTreePatcher(
- data: Self.tree.serialized(), verbose: false, device: .audioAccessory5_1,
+ data: tree.serialized(), verbose: false, device: .audioAccessory5_1,
role: .installed, sourceTree: Self.homePodBoard().serialized(),
)
let records = try patcher.findAll()
@@ -330,9 +335,9 @@ struct DeviceTreeGuestDeviceTests {
#expect(hub.0 == 0 && hub.1.isEmpty)
#expect(Self.string(product["app-macho-architecture"]) == "arm64")
#expect(product["app-macho-architecture"]?.0 == 0)
- #expect(product["product-id"]?.1 == Data(base64Encoded: "l2aw/kQAaW9zNqWJvWMfJJjJKt0="))
+ #expect(product["product-id"]?.1 == originalToken)
#expect(product["product-id"]?.0 == 0)
- #expect(records.filter { $0.patchID == DeviceTreePatcher.homePodProductPatch }.count == 4)
+ #expect(records.filter { $0.patchID == DeviceTreePatcher.homePodProductPatch }.count == 3)
#expect(!records.contains { $0.patchID == DeviceTreePatcher.tvAppArchitecturePatch })
// Restore sees the same virtual board and product as before HomePod support.
let restore = DeviceTreePatcher(
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
index fe3be52d..2b39faf0 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
@@ -35,6 +35,7 @@ struct FirmwareGuestPatchResolutionTests {
iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion("26.4"),
)
#expect(plan.isEnabled(identifier) == (base.hasPrefix("27.")
+ && identifier != FirmwareGuestSystemPatchSet.homePodAudioProduct
&& preset.identifier == VPhonePatchPreset.homePodMiniIdentifier))
}
}
@@ -151,7 +152,7 @@ struct FirmwareGuestPatchResolutionTests {
}
@Test
- func `HomePod audio uses its native identity and shared driver without iPhone routing patches`() throws {
+ func `HomePod audio uses its shared driver without global identity or iPhone routing patches`() throws {
let driver = FirmwareGuestSystemPatchSet.virtioSoundDriver
let product = FirmwareGuestSystemPatchSet.homePodAudioProduct
let plan = try VPhonePatchPlan.resolve(
@@ -160,7 +161,7 @@ struct FirmwareGuestPatchResolutionTests {
iOSBase: VPhoneVersion("27.0"), cloudOS: VPhoneVersion("26.4"),
)
#expect(plan.isEnabled(driver))
- #expect(plan.isEnabled(product))
+ #expect(!plan.isEnabled(product))
#expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [driver, product]).isEmpty)
#expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [driver]) == [driver])
#expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [driver], arm64eUserland: true) == [driver])
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
index 7e467865..e8605f91 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
@@ -94,6 +94,7 @@
<string>preboot-cfw-devicetree_haptics</string>
<string>preboot-cfw-devicetree_iphone_product</string>
<string>preboot-cfw-devicetree_microphone_array</string>
+ <string>preboot-homepod-exp-audio_product</string>
<string>restoreramdisk-boot-apfs_sha3_hash</string>
<string>system-apps-cfw-attitude</string>
<string>system-backboardd-cfw-gyroscope</string>
@@ -128,7 +129,7 @@
</array>
</dict>
<key>Summary</key>
- <string>Research: HomePod mini's own arm64e TVOS IPSW with vphoned, its donor-driven top cap, local setup completion and virtio audio using its native identity, without Apple TV OTA replacement or iPhone display, camera and routing hooks.</string>
+ <string>Research: HomePod mini's own arm64e TVOS IPSW with vphoned, its donor-driven top cap, local setup completion and virtio audio using an audio-only B520 route, without changing the VM product token or adding Apple TV OTA replacement or iPhone display, camera and routing hooks.</string>
<key>Title</key>
<string>HomePod mini</string>
</dict>
diff --git a/VPhoneGuestComponents/VirtIOSound/VPVirtIOSoundPlugin.m b/VPhoneGuestComponents/VirtIOSound/VPVirtIOSoundPlugin.m
index b516435e..6f234387 100644
--- a/VPhoneGuestComponents/VirtIOSound/VPVirtIOSoundPlugin.m
+++ b/VPhoneGuestComponents/VirtIOSound/VPVirtIOSoundPlugin.m
@@ -264,8 +264,9 @@ static const char *VPMachine(void) {
}
/// A VirtualAudio routing override, or 0 to retain native product selection.
-/// HomePod mini selects its own routing from the donor product digest; only
-/// its output device UID is adapted below, without using an iPhone override.
+/// HomePod mini uses native B520 route 4 through this audio-only preference.
+/// Keep the original VM product token: its donor replacement also changes
+/// unrelated services, including HomePodDisplayService's physical gamma path.
///
/// VirtualAudio derives its ProductID from a MobileGestalt class answer, and
/// vphone600 lands on a simulator class — 196 presenting an iPad, 195 an
@@ -288,6 +289,7 @@ static int VPGuestProductID(void) {
dispatch_once(&once, ^{
const char *machine = VPMachine();
product = strncmp(machine, "iPad", 4) == 0 || strncmp(machine, "iPhone", 6) == 0 ? 8010 : 0;
+ if (strcmp(machine, "AudioAccessory5,1") == 0) product = 4;
id chosen = CFBridgingRelease(CFPreferencesCopyAppValue(CFSTR("VPhoneVirtIOSoundProductID"), kSettingsDomain));
if ([chosen isKindOfClass:NSNumber.class] && [chosen intValue] >= 0) {
product = [chosen intValue];
@@ -315,13 +317,12 @@ static NSString *VPDeviceUID(ASDStreamDirection direction, unsigned index) {
// Only where the route is set up: a speaker route on a VirtualAudio that
// was not deadlocked audiomxd and crash-looped it across launches.
// HomePod mini's native B238 routing also claims PuffinOutput. Its
- // ProductID comes from the donor product digest in the installed tree,
- // not the iPhone routing override. Leave its input unclaimed: microphone
+ // ProductID uses the audio-only B520 override. Leave its input unclaimed: microphone
// routing needs the physical array and is not part of this output port.
if (!input && index == 0 && strcmp(VPMachine(), "AudioAccessory5,1") == 0) {
return @"PuffinOutput";
}
- if (index == 0 && VPGuestProductID() != 0) {
+ if (index == 0 && VPGuestProductID() != 0 && strcmp(VPMachine(), "AudioAccessory5,1") != 0) {
return input ? @"Digital Mic" : @"PuffinOutput";
}
return [NSString stringWithFormat:@"VPhoneVirtIOSound%s:%u", input ? "Input" : "", index];