Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

HomePod Sound Glow

Guilherme Rambo9a9d688b79a2
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index f2a80fd3..2ce28421 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -1,5 +1,26 @@
# Patch Comparison: Regular / Development / Jailbreak / Experimental
+> **HomePod 27.2 OTA and native Sound Glow (2026-10-23, offline candidate).**
+> The 27.0 donor lacks the artwork/color extraction and native media animation
+> cases introduced in 27.2. `system-homepod-exp-ota_userland` stages the full
+> Apple HomePod mini OTA over the same device's 27.0 IPSW, retaining its restore
+> identity and cloudOS boot chain, as the Apple TV OTA pairing does.
+> `system-homepod-exp-sound_glow` injects the existing guest adapter into
+> NowPlayingCap and generates `/usr/share/vphone/HomePodSoundGlow.plist`.
+> Its narrow native `AccessorySettingProvider.mediaUI` getter selects value 1;
+> Apple's artwork service, color extractor and CAPAnimationEffect.media remain
+> responsible for rendering. Opt-out restores the original app and removes the
+> policy. Both declarations are HomePod-only, require 27.2 or later, and are
+> selected by default only by `homepod-mini`. Original product identity and
+> existing audio/Siri behavior are retained. Local validation and native
+> evidence are recorded in [Sound Glow](Firmware/homepod_sound_glow.md).
+> Live 27.2 boot and clear Music/AirPlay audio are verified. Initial playback
+> exposed an unresolved own-device endpoint in the native artwork request.
+> A scoped request adapter selects MediaRemote's local destination only for
+> that own-device UID; native request/response and artwork processing remain
+> intact. Remote requests and opt-out pass through. The routing correction,
+> artwork changes and animation synchronization still need live validation.
+
> **HomePod Siri speech policy (2026-10-23, live speech verified).**
> New optional `system-homepod-exp-siri_speech` generates
> `/usr/share/vphone/HomePodSiriSpeech.plist` with `Enabled=true`, restricted to
diff --git a/Research/Firmware/homepod_mini_support.md b/Research/Firmware/homepod_mini_support.md
index ed986f6f..8337e9fe 100644
--- a/Research/Firmware/homepod_mini_support.md
+++ b/Research/Firmware/homepod_mini_support.md
@@ -81,6 +81,61 @@ For the manual prepare/restore pipeline, select `homepod-mini` with
`fw set-patches` before preparing. The guest family and preset ship in the
2.11 bundle/Launchpad series; Launchpad's minimum bundle version is 2.11.0.
+## HomePod Software 27.2 from a full OTA
+
+The 27.2 catalog entry uses HomePod mini's full OTA (`24K120`) over its own
+27.0 (`24J361`) restore IPSW, following the Apple TV 4K userland staging path.
+The original HomePod model, cloudOS 26.4 kernel and boot chain remain the base.
+Apple's update metadata calls the OTA `24K6120`; the archive's BuildManifest
+and extracted SystemVersion identify the installed software as `24K120`.
+The [AppleDB record](https://api.appledb.dev/ios/HomePod%20Software;24K120.json)
+lists the same active Apple CDN archive: 3,051,441,612 bytes, SHA-256
+`72830cc7ea154fbb6fa26904d6b527977a5d35fe8130e1fcd027ae9e0243507a`.
+
+The historical `--iphone-source` may name the catalog OTA URL. Preparation
+then resolves the 27.0 restore base and stages the OTA. For existing local
+downloads, pass the restore IPSW and full ZIP separately:
+
+```zsh
+"$cli" vm create homepod-mini-27-2 --device AudioAccessory5,1 \
+ --iphone-source '/absolute/path/to/AudioAccessory5,1_27.0_24J361_Restore.ipsw' \
+ --ota-source '/absolute/path/to/HomePod-mini-27.2-OTA.zip' \
+ --cloudos-source '/absolute/path/to/cloudOS_23E5207q_Restore.ipsw' \
+ --cpu 4 --memory 4096 --disk-size 32
+```
+
+This creates a separate machine; it does not update or erase an existing
+HomePod. The journaled `fw ota` migration workflow remains qualified only for
+iPhone/iPad. A stopped clone of an existing machine can be used for subsequent
+controlled installation research, retaining its Data and identity, but that
+is not a verified HomePod migration path.
+
+`VPhoneOTAArchive` reads HomePod's ZIP with the bundled libarchive, without
+Homebrew or an external unzip tool. It reads identity and prerequisite
+metadata before staging payload, even though `AssetData/Info.plist` occurs
+after the payload in this ZIP. It bounds in-memory metadata, rejects duplicate
+ZIP records and requires a full update. All Apple Archive payload paths and
+the separate hard-link manifest are validated before publication. The
+resulting `OTAUserland/Version.plist` records `Device`, `Version` and `Build`;
+the restore tree's `OTA-SystemVersion.plist` carries `ProductVersion` and
+`ProductBuildVersion` for patch-plan resolution. The HomePod preset selects
+`system-homepod-exp-ota_userland` only on 27.2 or later; other presets leave
+the HomePod replacement off.
+
+Offline fixture tests cover ZIP staging, late metadata, duplicate records,
+metadata bounds, existing payload traversal/symlink checks and the catalog's
+same-device restore-base pairing. The production bundle's native `fw prepare`
+also completed against the actual OTA: 51 payload chunks and 6,721 separate
+hard-link destinations passed full path validation, both target-version
+records identify 27.2/24K120, and the base IPSW manifest remains 27.0/24J361.
+`fw patch` resolved the 27.2 HomePod preset and processed all 11 components,
+applying 241 patches without an undeclared patch warning. The stopped,
+unrestored candidate is under
+`.build/homepod-sound-glow-research/machines/homepod-27-2`; preparation and
+patch logs are beside it in the research artifact directory. No VM was
+launched and no privileged installation was performed during these checks.
+Boot, migration and native Sound Glow still need live validation.
+
## Validation
Validated on 2026-10-22 with four CPUs, 4 GiB memory and a 32 GB disk:
diff --git a/Research/Firmware/homepod_sound_glow.md b/Research/Firmware/homepod_sound_glow.md
new file mode 100644
index 00000000..1a7bb489
--- /dev/null
+++ b/Research/Firmware/homepod_sound_glow.md
@@ -0,0 +1,170 @@
+# HomePod 27.2 and native Sound Glow
+
+The candidate follows the Apple TV OTA approach: restore the HomePod mini's
+27.0 IPSW, use the full 27.2 OTA for System, then apply the selected guest patches
+to that System. Nothing has been installed into the running 27.0 VM. Live boot
+and Sound Glow verification remain pending administrator availability.
+
+## Donor identity and acquisition
+
+Apple's Pallas metadata advertises a full, unencrypted ZIP OTA for
+`AudioAccessory5,1` / `B520AP`, version 27.2. It reports asset build `24K6120`;
+the archive's own SystemVersion is **24K120**. The catalogue and staged target
+identity use that actual OS build. The original same-device 27.0 / 24J361 IPSW
+supplies the restore base; there is no 27.2 HomePod mini IPSW in the catalogue.
+
+The Apple URL is
+`https://updates.cdn-apple.com/2026FallFCS/b191c01c-8e6e-4b74-8b84-015131f696b8/com_apple_MobileAsset_SoftwareUpdate/861a9e7426795ddb3eac86cd0b089e5bf7939258.zip`.
+The downloaded 3,051,441,612 bytes have SHA-256
+`72830cc7ea154fbb6fa26904d6b527977a5d35fe8130e1fcd027ae9e0243507a`, matching
+Apple's metadata. Native catalogue/archive code supports this ZIP; the external
+`ipsw` tool used to extract analysis artifacts is not a runtime dependency.
+
+## Why 27.0 cannot enable this with a preference
+
+The current 24J361 `NowPlayingCap` SHA-256 is
+`213c5c236ac0dacecf0cca35dca28b743abe59a56303431ccccf29d5dbda977b`.
+Its exposed settings contain `depictNonGroupLeaders`, but it has no accessory
+media UI setting provider, artwork-fetch service or color extractor. Its CapKit
+`CAPAnimationEffect` description handles Siri, pulse, intercom and off; it lacks
+the media and soundscape cases used by the later app. Donor REA evidence:
+`ev_6d68dc5a122be207d422ad766cb85318570434b8259bd4012f117347bf6acfd7`.
+The old app's pulse selection is recorded as
+`ev_302f2ba4359e26acda6210e7b142d028577fb98d6e9c10ca960483780672127f`.
+
+The 24K120 app SHA-256 is
+`b5f33c09cbc46b973ff5799ff0a192792e54d4390a2005ac14e322a9fb5a5525`.
+It adds `ArtworkService`, `ArtworkFetcher`, `ColorService`, `ColorCache`,
+`MediaColors` and `AccessorySettingProvider`, plus native CapKit media and
+soundscape effects. The extracted CapKit SHA-256 is
+`344968deda3cd5d81c272133c341085b9222b5677099a3ad2815835edcb168a1`.
+This is a matched complete userland, not a cross-version app/framework graft.
+
+## Native enable path
+
+`_TtC13NowPlayingCap24AccessorySettingProvider` owns an NSInteger `mediaUI`
+property, initially zero. Its getter and setter are ordinary Objective-C
+entry points. HomePodSettings updates for `HPSKeyPathMediaUI` flow through the
+setter; native Now Playing model initialization and updates compare the getter
+to exactly **1** to enable expressive media UI. Evidence:
+
+- Getter: `ev_7290a7682be1da8faddf0b7d3705eca45c221524ced0574336c451dac306c976`.
+- Initialization: `ev_e8137e7f3167abfe4aa689a5face6a38c7ac0bc965a5dab4bec0a522dfc6c3b4`.
+- Home setting delivery: `ev_48e261439e6344b529203e398bb151bf5b761c93f6b195a2521c3026d53266b3`.
+- Model initialization: `ev_0c99db6bbc5e6bac99ab2d7404ee88da7912e7d20b7130e4ed0634a589f27e33`.
+- Model update: `ev_fd1d7a9257b0593d548a5ddb37da606fecec2d5742012c50a075d10e6113e25b`.
+- Native rendering: `ev_27f1ff4748bf169c4b5e3828643dbec305487df8d6d25c3f90b591eef8c55db8`.
+
+The rendering function builds `CAPAnimationEffect.media` from extracted UIColor
+arrays, or a native soundscape effect, and assigns `currentLEDEffect`. Its
+expressive branch acquires the native brightness assertion. The observed
+CAPAnimation initializer passes `audioTapping=false`; merely forcing the old
+SoundBoard audio-tapping flag is not an implementation of this feature.
+The app's Swift feature enum names `Home.homePodTopCap`; the 24K120
+`FeatureFlags/Domain/Home.plist` marks `HomePodTopCap` FeatureComplete. The
+candidate leaves that native flag intact.
+
+## Selected patches and guest ownership
+
+Both patches are optional, HomePod-only, version-gated to 27.2 or later, and
+selected by default only in the `homepod-mini` preset. Standard, Experimental
+and the TV presets exclude them. `system-homepod-exp-sound_glow` requires
+`system-vphoned-boot-install` and `system-homepod-exp-top_cap`.
+
+The Sound Glow installer writes an Enabled policy and injects the existing
+`libvphonehomepoddisplay.dylib` into **NowPlayingCap**. Its constructor recognizes
+that process and installs only the narrow `mediaUI` getter adapter after checking
+the getter/setter ABI. Other process initialization retains the existing
+SoundBoard display, Siri speech and welcome behavior. A missing or changed
+native class refuses installation rather than inventing frames or calling an
+unknown ABI.
+
+While enabled, the getter returns native value 1. The original setter still
+receives Home updates; disabling policy exposes the actual setting again.
+Deselection restores the backed-up native executable, reseals the app and
+removes the policy. No Home account or accessory preferences are rewritten.
+There is no host scheduler, synthesized LED animation, artwork scraper, global
+MobileGestalt change or audio-session modification.
+
+## Verification boundary
+
+Native policy tests cover process isolation, absent/changed ABIs, idempotent
+installation, native setter preservation and opt-out. The existing display
+identity harness passes with the new source linked. Firmware catalogue and
+resolution checks cover version gating, default selection, TV rejection and
+missing prerequisites. Archive tests cover ZIP metadata ordering and rejection
+of duplicate entries; existing archive path/size bounds remain in force.
+
+Static native control flow establishes the candidate's enable mechanism; it
+does not prove real AirPlay artwork delivery, brightness, animation timing or
+27.2 boot compatibility. A live candidate must establish all of those, then
+verify pause/resume, a change between distinctly colored album covers, Siri
+interruption and return to music, policy opt-out and restart persistence. The
+original 27.0 VM and its once-only welcome claim must remain recoverable.
+
+Analysis artifacts and saved REA snapshots live locally under
+`.build/homepod-sound-glow-research/`. They are not shipped runtime resources.
+
+### Completed offline checks
+
+- Xcode MCP: 24 OTA archive tests, 12 firmware catalogue report tests, and 46
+ firmware declaration/resolution tests pass. The latter include 27.2 preset
+ selection and Sound Glow dependency checks.
+- Native state/welcome, Siri speech, Sound Glow and display harnesses pass.
+- The complete Debug `VPhone` bundle builds and passes bundle admission. Xcode
+ MCP omits the aggregate scheme, so the full bundle uses the repository's
+ documented xcodebuild fallback with `/Applications/Xcode.app`.
+- Real native `fw prepare` succeeds in the repository-only scratch library,
+ streaming 51 chunks and validating all 6,721 hard-link destinations. It writes
+ `OTAUserland/Version.plist` as AudioAccessory5,1 / 27.2 / 24K120. The base
+ `iPhone-BuildManifest.plist` remains 27.0 / 24J361, as required for restore.
+- Real `fw patch` succeeds across all 11 components with 241 patches and no
+ undeclared-patch warnings. The plan records 27.2 over cloudOS 26.4 and selects
+ both new patches along with the existing cap, audio, Siri and welcome patches.
+- Read-only dry runs of all five selected shared-cache patchers pass against
+ 24K120: IOMFB finds 10 retargetable trampolines; lsd and libxpc find their
+ semantic gates; maxSlide already fits; the missing lockdown function is an
+ explicit supported no-op. No cache bytes were changed by these probes.
+- The production Mach-O injector successfully adds the weak guest adapter load
+ command to a separate copy of the 24K120 NowPlayingCap executable.
+
+The prepared candidate is
+`.build/homepod-sound-glow-research/machines/homepod-27-2`. Its Disk.img is a
+new, unrestored VM. Firmware preparation/patching and raw payload staging are
+complete; restore, CFW installation, boot and playback have **not** run. Logs
+are `prepare.log`, `patch.log`, `bundle-build.log` and `*-dry-run.log` beside it
+in the research artifact folder. The original running `homepod-mini` remains
+bound to `2.11.0-local.3f1d474e` and software 27.0; it was not stopped or updated.
+
+### Live continuation
+
+On 2026-10-23 the separate candidate was moved into the normal machine library
+as `homepod-27-2`, bound to `2.11.0-local.f2cd5cbf`, restored and installed through
+Launchpad. Native SystemVersion and device.info confirm 27.2 / 24K120 and
+AudioAccessory5,1. The display receives valid native frames, and the owner
+confirmed clear Music/AirPlay audio. Initial playback remained white:
+NowPlayingCap's ArtworkFetcher failed with MediaRemote error 47, because
+`MRDestination.initWithOutputDeviceUID:` addressed the own device UID from
+`MRDeviceInfoRequest.localDeviceInfo`, which had no discoverable endpoint.
+The exact call flow is recorded by REA
+`ev_d726ad0f2fbd4dfc638d64c09cff9cb19c9e36ccf3e0b3dae3b09e39148f5ecf`.
+
+The candidate adapter now also intercepts NowPlayingCap's native
+`MRPlaybackQueueRequest.performRequestForDestination:completion:`. Only a
+request whose output UID equals that same native local-device UID is routed
+to `MRDestination.localDestination`. Identifiers, dimensions, completion and
+native artwork decoding/color extraction remain untouched. Other destinations
+and policy opt-out retain the original call. All participating method ABIs
+are checked before installation; the harness verifies local/remote/nil targets,
+completion preservation and opt-out. This routing change still needs live
+verification. No host artwork fetching or generated frames are involved.
+
+Install the prepared bundle through Launchpad when authorization is available.
+Use the returned installed version, preserving the default bundle and all other
+VM bindings. Restore and install the prepared 27.2 candidate as a separate VM,
+then verify boot, exact device/OS identity, audio and native top-cap delivery
+before sending Music/AirPlay to it. Confirm native artwork colors change with
+tracks and the animation reacts during playback, pauses/resumes, yields to Siri
+and returns to music. Exercise Sound Glow opt-out through the patch selection
+and environment update, then re-enable and reboot. Keep the original 27.0 VM
+until the candidate passes these live checks.
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift
index 6b588de2..17087700 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift
@@ -54,6 +54,7 @@ public enum FirmwareGuestPatchResolution {
.union([FirmwareGuestSystemPatchSet.homePodTopCap, FirmwareGuestSystemPatchSet.homePodSetupBypass,
FirmwareGuestSystemPatchSet.homePodAudioProduct, FirmwareGuestSystemPatchSet.homePodWelcome,
FirmwareGuestSystemPatchSet.homePodSiriSpeech,
+ FirmwareGuestSystemPatchSet.homePodOTAUserland, FirmwareGuestSystemPatchSet.homePodSoundGlow,
FirmwareGuestSystemPatchSet.virtioSoundDriver])
.union(FirmwarePatchSetCatalog.tvOS27UserlandPatches)
@@ -88,6 +89,16 @@ public enum FirmwareGuestPatchResolution {
return homePodSiriSpeechDependencies.subtracting(enabled).sorted()
}
+ public static let homePodSoundGlowDependencies: Set<String> = [
+ "system-vphoned-boot-install",
+ FirmwareGuestSystemPatchSet.homePodTopCap,
+ ]
+
+ public static func missingHomePodSoundGlowDependencies(enabled: Set<String>) -> [String] {
+ guard enabled.contains(FirmwareGuestSystemPatchSet.homePodSoundGlow) else { return [] }
+ return homePodSoundGlowDependencies.subtracting(enabled).sorted()
+ }
+
/// Every bundled-set patch whose bytes the guest half of an install writes —
/// the dyld shared cache, a guest Mach-O, its entitlements, a guest file, or
/// the Preboot device tree. The complement is the boot chain, which `fw
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
index 50671b16..c08593a9 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
@@ -42,6 +42,9 @@ public enum FirmwareGuestSystemPatchSet {
/// Replaces the restored System volume with an Apple TV 4K userland
/// staged from its OTA. Research only: no IPSW exists for that device.
public static let tvOTAUserland = "system-tv-exp-ota_userland"
+ public static let homePodOTAUserland = "system-homepod-exp-ota_userland"
+ public static let homePodSoundGlow = "system-homepod-exp-sound_glow"
+ public static let homePodSoundGlowPath = "/usr/share/vphone/HomePodSoundGlow.plist"
public static let otaUserland = "system-exp-ota_userland"
private static let ios27 = VPhonePatchApplicability(iOSBase: .major(27))
@@ -67,6 +70,20 @@ public enum FirmwareGuestSystemPatchSet {
name: "Guest System",
summary: "Shared-cache policy gates, patched system daemons and the vphone guest payload",
patches: [
+ VPhonePatchDeclaration(
+ identifier: homePodOTAUserland,
+ title: "HomePod userland from OTA",
+ summary: "Research: replaces the restored HomePod mini System volume with its full 27.2 or later OTA, retaining the HomePod restore identity and cloudOS boot chain. The staged payload is verified before installation.",
+ target: .guestFile(path: "/"),
+ applicability: VPhonePatchApplicability(iOSBase: .atLeast(major: 27, minor: 2)),
+ ),
+ VPhonePatchDeclaration(
+ identifier: homePodSoundGlow,
+ title: "HomePod Sound Glow",
+ summary: "Enables the native HomePod 27.2 media display through a process-local accessory setting adapter. Requires vphoned and the donor-driven HomePod top cap; keeps the original product token.",
+ target: .guestFile(path: "/usr/share/vphone/HomePodSoundGlow.plist"),
+ applicability: VPhonePatchApplicability(iOSBase: .atLeast(major: 27, minor: 2)),
+ ),
VPhonePatchDeclaration(
identifier: otaUserland,
title: "Full OTA system update",
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
index 7d4182f9..7e371450 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
@@ -61,7 +61,7 @@ public enum FirmwarePatchSetCatalog {
Set(FirmwareKernelFridaPatchSet.manifest.patches.map(\.identifier))
.union(hypervisorConcealmentPatches)
.union(experimentalIdentityPatches)
- .union([FirmwareGuestSystemPatchSet.otaUserland, FirmwareGuestSystemPatchSet.homePodTopCap, FirmwareGuestSystemPatchSet.homePodSetupBypass, FirmwareGuestSystemPatchSet.homePodAudioProduct, FirmwareGuestSystemPatchSet.homePodWelcome, FirmwareGuestSystemPatchSet.homePodSiriSpeech])
+ .union([FirmwareGuestSystemPatchSet.otaUserland, FirmwareGuestSystemPatchSet.homePodTopCap, FirmwareGuestSystemPatchSet.homePodSetupBypass, FirmwareGuestSystemPatchSet.homePodAudioProduct, FirmwareGuestSystemPatchSet.homePodWelcome, FirmwareGuestSystemPatchSet.homePodSiriSpeech, FirmwareGuestSystemPatchSet.homePodOTAUserland, FirmwareGuestSystemPatchSet.homePodSoundGlow])
.union([FirmwareKernelCustomFirmwarePatchSet.tvTPROPagers, misTrustAuthPatch, FirmwareGuestSystemPatchSet.settingsRootRows, FirmwareGuestSystemPatchSet.settingsSoftwareUpdate, FirmwareGuestSystemPatchSet.tvTPRO, FirmwareGuestSystemPatchSet.tvOTAUserland])
/// ProMotion: the 120 Hz timing for the paravirtual display.
@@ -219,7 +219,7 @@ public enum FirmwarePatchSetCatalog {
freshly restored 26.4 guest does not survive. The HomePod-only top cap is off.
""",
patchSets: bundledReferences,
- selection: .block([FirmwareGuestSystemPatchSet.homePodTopCap, FirmwareGuestSystemPatchSet.homePodSetupBypass, FirmwareGuestSystemPatchSet.homePodAudioProduct, FirmwareGuestSystemPatchSet.homePodWelcome, FirmwareGuestSystemPatchSet.homePodSiriSpeech]),
+ selection: .block([FirmwareGuestSystemPatchSet.homePodTopCap, FirmwareGuestSystemPatchSet.homePodSetupBypass, FirmwareGuestSystemPatchSet.homePodAudioProduct, FirmwareGuestSystemPatchSet.homePodWelcome, FirmwareGuestSystemPatchSet.homePodSiriSpeech, FirmwareGuestSystemPatchSet.homePodOTAUserland, FirmwareGuestSystemPatchSet.homePodSoundGlow]),
)
/// The iOS payloads, hooks and shared-cache patches an Apple TV guest has no
@@ -326,7 +326,7 @@ public enum FirmwarePatchSetCatalog {
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.homePodWelcome, FirmwareGuestSystemPatchSet.homePodSiriSpeech])
+ manualOnlyPatches.subtracting([FirmwareGuestSystemPatchSet.homePodTopCap, FirmwareGuestSystemPatchSet.homePodSetupBypass, FirmwareGuestSystemPatchSet.homePodWelcome, FirmwareGuestSystemPatchSet.homePodSiriSpeech, FirmwareGuestSystemPatchSet.homePodOTAUserland, FirmwareGuestSystemPatchSet.homePodSoundGlow])
.union(tvOSBlockedPatches.subtracting(tvOS27UserlandPatches).subtracting([FirmwareGuestSystemPatchSet.virtioSoundDriver])),
),
)
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
index 9ce8ea71..ff438a04 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
@@ -12,6 +12,38 @@ import VPhonePatchKit
@Suite("Guest patch resolution")
struct FirmwareGuestPatchResolutionTests {
+ @Test(arguments: [FirmwareGuestSystemPatchSet.homePodOTAUserland, FirmwareGuestSystemPatchSet.homePodSoundGlow])
+ func `HomePod OTA and Sound Glow require 27 point 2 and stay out of other presets`(identifier: String) throws {
+ for version in ["26.6", "27.0", "27.1", "27.2", "27.3"] {
+ for preset in FirmwarePatchSetCatalog.builtInPresets {
+ let plan = try VPhonePatchPlan.resolve(
+ preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
+ iOSBase: VPhoneVersion(version), cloudOS: VPhoneVersion("26.4"),
+ )
+ #expect(plan.isEnabled(identifier) == (VPhoneVersion(version)! >= VPhoneVersion(major: 27, minor: 2)
+ && preset.identifier == VPhonePatchPreset.homePodMiniIdentifier))
+ }
+ }
+ #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [identifier]).isEmpty)
+ #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier], arm64eUserland: true) == [identifier])
+ #expect(FirmwareGuestPatchResolution.guestPatchesOff(selectionEnabled: []).contains(identifier))
+ }
+
+ @Test func `Sound Glow requires native cap delivery but not speech or welcome`() throws {
+ let glow = FirmwareGuestSystemPatchSet.homePodSoundGlow
+ let dependencies = FirmwareGuestPatchResolution.homePodSoundGlowDependencies
+ #expect(dependencies == ["system-vphoned-boot-install", FirmwareGuestSystemPatchSet.homePodTopCap])
+ let enabled = dependencies.union([glow])
+ #expect(FirmwareGuestPatchResolution.missingHomePodSoundGlowDependencies(enabled: enabled).isEmpty)
+ for dependency in dependencies {
+ #expect(FirmwareGuestPatchResolution.missingHomePodSoundGlowDependencies(enabled: enabled.subtracting([dependency])) == [dependency])
+ }
+ #expect(FirmwareGuestPatchResolution.missingHomePodSoundGlowDependencies(enabled: []).isEmpty)
+ let declaration = try #require(FirmwarePatchSetCatalog.allDeclarations.first { $0.identifier == glow })
+ #expect(declaration.target == .guestFile(path: FirmwareGuestSystemPatchSet.homePodSoundGlowPath))
+ #expect(!declaration.bootEssential)
+ }
+
@Test func `only the HomePod preset selects the top cap and TV rejects explicit selection`() throws {
let identifier = FirmwareGuestSystemPatchSet.homePodTopCap
for preset in FirmwarePatchSetCatalog.builtInPresets {
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
index e588c520..80515ccd 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
@@ -179,7 +179,7 @@ struct FirmwarePatchSetCatalogTests {
@Test
func `Extended adds the applicable manual patches except the HomePod-only device`() throws {
- for base in ["18.6.2", "26.4", "27.0", "27.1"] {
+ for base in ["18.6.2", "26.4", "27.0", "27.1", "27.2"] {
let version = VPhoneVersion(base)
let cloud = VPhoneVersion("26.4")
let standard = try VPhonePatchPlan.resolve(
@@ -201,6 +201,8 @@ struct FirmwarePatchSetCatalogTests {
&& $0.identifier != FirmwareGuestSystemPatchSet.homePodWelcome
&& $0.identifier != FirmwareGuestSystemPatchSet.homePodSiriSpeech
&& $0.identifier != FirmwareGuestSystemPatchSet.homePodAudioProduct
+ && $0.identifier != FirmwareGuestSystemPatchSet.homePodOTAUserland
+ && $0.identifier != FirmwareGuestSystemPatchSet.homePodSoundGlow
&& $0.applicability.matches(iOSBase: version, cloudOS: cloud)
}.map(\.identifier))
#expect(experimental.enabled.subtracting(standard.enabled) == applicableManual)
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index 2cc23ecd..5906fab1 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -215,6 +215,16 @@ struct VPhoneCustomFirmwareInstaller {
if effectiveEnabled.contains(FirmwareGuestSystemPatchSet.homePodSiriSpeech), device.family != .homePod {
throw ValidationError("The HomePod Siri-speech patch is supported only for a HomePod guest.")
}
+ if effectiveEnabled.contains(FirmwareGuestSystemPatchSet.homePodSoundGlow), device.family != .homePod {
+ throw ValidationError("The HomePod Sound Glow patch is supported only for a HomePod guest.")
+ }
+ if effectiveEnabled.contains(FirmwareGuestSystemPatchSet.homePodOTAUserland), device.family != .homePod {
+ throw ValidationError("The HomePod OTA userland patch is supported only for a HomePod guest.")
+ }
+ let missingGlowDependencies = FirmwareGuestPatchResolution.missingHomePodSoundGlowDependencies(enabled: effectiveEnabled)
+ guard missingGlowDependencies.isEmpty else {
+ throw ValidationError("The HomePod Sound Glow patch requires these selected guest patches: \(missingGlowDependencies.joined(separator: ", ")).")
+ }
let missingSpeechDependencies = FirmwareGuestPatchResolution.missingHomePodSiriSpeechDependencies(enabled: effectiveEnabled)
guard missingSpeechDependencies.isEmpty else {
throw ValidationError("The HomePod Siri-speech patch requires these selected guest patches: \(missingSpeechDependencies.joined(separator: ", ")).")
@@ -226,9 +236,9 @@ struct VPhoneCustomFirmwareInstaller {
// Research: an Apple TV 4K userland staged from its OTA, which
// `system-tv-exp-ota_userland` puts in place of the restored one.
let hasOTAUserland = (try? bundleDirectory.isDirectory(VPhoneOTAArchive.userlandDirectoryName)) == true
- let isOTAUpdate = device.family != .appleTV && mode == .full && hasOTAUserland
+ let isOTAUpdate = device.family != .appleTV && device.family != .homePod && mode == .full && hasOTAUserland
&& effectiveEnabled.contains(FirmwareGuestSystemPatchSet.otaUserland)
- let otaUserland = (device.family == .appleTV || isOTAUpdate) && hasOTAUserland
+ let otaUserland = (device.family == .appleTV || device.family == .homePod || isOTAUpdate) && hasOTAUserland
? try bundleDirectory.directory(VPhoneOTAArchive.userlandDirectoryName)
: nil
if isOTAUpdate {
@@ -1252,13 +1262,18 @@ struct VPhoneCustomFirmwareInstaller {
}
// First, so every later step patches the userland that will boot.
- if guestDevice.family == .appleTV {
- let identifier = FirmwareGuestSystemPatchSet.tvOTAUserland
+ if guestDevice.family == .appleTV || guestDevice.family == .homePod {
+ let identifier = guestDevice.family == .homePod
+ ? FirmwareGuestSystemPatchSet.homePodOTAUserland : FirmwareGuestSystemPatchSet.tvOTAUserland
if on(identifier) {
guard let otaUserland else {
throw ValidationError("\(identifier) is on, but the VM has no OTAUserland folder with the staged payload chunks.")
}
- try replaceTVUserland(system: system, ota: otaUserland, work: work)
+ if guestDevice.family == .homePod {
+ try replaceHomePodUserland(system: system, ota: otaUserland, work: work, plan: plan, device: guestDevice)
+ } else {
+ try replaceTVUserland(system: system, ota: otaUserland, work: work)
+ }
live.insert(identifier)
} else if priorGuest.contains(identifier) {
print(" [!] \(identifier): off now, but the swapped userland cannot be reverted without a restore")
@@ -1422,6 +1437,23 @@ struct VPhoneCustomFirmwareInstaller {
// survives opt-out, re-enabling and bundle/environment updates.
try system.removeItem(welcomePath)
}
+ let glow = FirmwareGuestSystemPatchSet.homePodSoundGlow
+ let glowPath = String(FirmwareGuestSystemPatchSet.homePodSoundGlowPath.dropFirst())
+ if plan?.isEnabled(glow) == true {
+ guard guestDevice.family == .homePod else {
+ throw ValidationError("HomePod Sound Glow requires a HomePod guest.")
+ }
+ _ = try system.directory("usr/share/vphone", create: true, mode: 0o755)
+ let policy = try PropertyListSerialization.data(fromPropertyList: ["Enabled": true], format: .binary, options: 0)
+ try updateHomePodNowPlaying(system: system, work: work, enabled: true)
+ try system.writeFile(glowPath, contents: policy, mode: 0o644, owner: Self.guestOwner)
+ live.insert(glow)
+ } else {
+ if guestDevice.family == .homePod || priorGuest.contains(glow) {
+ try updateHomePodNowPlaying(system: system, work: work, enabled: false)
+ }
+ try system.removeItem(glowPath)
+ }
for (identifier, library) in [
(FirmwareGuestSystemPatchSet.gyroscope, "libvphonegyro.dylib"),
(FirmwareGuestSystemPatchSet.accelerometer, "libvphoneaccelerometer.dylib"),
@@ -2300,7 +2332,7 @@ struct VPhoneCustomFirmwareInstaller {
) throws {
let marker = ".vphone-ota-userland"
let chunkList = try ota.readData(VPhoneOTAArchive.chunkListName)
- if identifier == FirmwareGuestSystemPatchSet.tvOTAUserland,
+ if [FirmwareGuestSystemPatchSet.tvOTAUserland, FirmwareGuestSystemPatchSet.homePodOTAUserland].contains(identifier),
try system.isRegularFile(marker), try system.readData(marker) == chunkList {
print(" [·] \(identifier): userland already in place")
return
@@ -2325,7 +2357,7 @@ struct VPhoneCustomFirmwareInstaller {
} else {
linkList = nil
}
- if identifier == FirmwareGuestSystemPatchSet.otaUserland {
+ if identifier == FirmwareGuestSystemPatchSet.otaUserland || identifier == FirmwareGuestSystemPatchSet.homePodOTAUserland {
// Root extracts only pinned private copies. Reject traversal and
// any later member beneath an archive-created symlink first.
guard let linkList else {
@@ -2351,6 +2383,55 @@ struct VPhoneCustomFirmwareInstaller {
print(" [+] \(identifier): userland extracted")
}
+ /// The OTA supplies the complete HomePod System; its original 27.0 IPSW
+ /// still supplies the restore identity. Verify the target independently of
+ /// that base manifest, including on an idempotent environment redeploy.
+ private func replaceHomePodUserland(
+ system: VPhoneConfinedDirectory,
+ ota: VPhoneConfinedDirectory,
+ work: WorkDirectory,
+ plan: VPhoneVirtualMachinePatchPlan?,
+ device: VPhoneGuestDevice
+ ) throws {
+ guard let metadata = try PropertyListSerialization.propertyList(from: ota.readData("Version.plist"), format: nil) as? [String: String],
+ metadata["Device"] == device.productType,
+ let version = metadata["Version"], version == plan?.iOSBaseVersion,
+ let parsed = VPhoneVersion(version), parsed >= VPhoneVersion("27.2")!,
+ let build = metadata["Build"], !build.isEmpty else {
+ throw ValidationError("The HomePod OTA device/version does not match the patch plan. Prepare the matching full HomePod OTA before installation.")
+ }
+ // Chunk names alone can be identical across releases. A prior marker
+ // may skip extraction only when the actual System has this identity.
+ let marker = ".vphone-ota-userland"
+ if try system.isRegularFile(marker),
+ let actual = try? PropertyListSerialization.propertyList(from: system.readData("System/Library/CoreServices/SystemVersion.plist"), format: nil) as? [String: Any],
+ actual["ProductVersion"] as? String != version || actual["ProductBuildVersion"] as? String != build {
+ try system.removeItem(marker)
+ }
+ try replaceTVUserland(system: system, ota: ota, work: work,
+ identifier: FirmwareGuestSystemPatchSet.homePodOTAUserland)
+ guard let actual = try PropertyListSerialization.propertyList(from: system.readData("System/Library/CoreServices/SystemVersion.plist"), format: nil) as? [String: Any],
+ actual["ProductVersion"] as? String == version,
+ actual["ProductBuildVersion"] as? String == build else {
+ throw ValidationError("The extracted HomePod SystemVersion does not match its staged OTA. The private disk clone was discarded.")
+ }
+ }
+
+ private func updateHomePodNowPlaying(system: VPhoneConfinedDirectory, work: WorkDirectory, enabled: Bool) throws {
+ let app = "Applications/NowPlayingCap.app"
+ let executable = "\(app)/NowPlayingCap"
+ if enabled {
+ guard try system.isRegularFile(executable) else {
+ throw ValidationError("HomePod Sound Glow requires the native 27.2 NowPlayingCap app.")
+ }
+ try patchMachO(system: system, work: work, path: executable,
+ preserveEntitlements: true, injectedDylibPath: "/usr/lib/libvphonehomepoddisplay.dylib")
+ try sealGuestBundle(system: system, bundle: app, preserveEntitlements: true)
+ } else if try revertMachO(system: system, work: work, path: executable) {
+ try sealGuestBundle(system: system, bundle: app, preserveEntitlements: true)
+ }
+ }
+
/// The paravirtual GPU driver and its compiler plugin are built for iOS.
/// An arm64e tvOS process loads them once they say tvOS: dyld refuses a
/// library whose platform is not the process's. Each is re-signed after
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift
index f04f9cb0..27f59529 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift
@@ -235,7 +235,7 @@ struct VPhoneFirmwarePrepareCommand: ParsableCommand {
))
var device: String?
@Option(help: ArgumentHelp(
- "Full OTA (.aea) URL or local path for a device Apple ships no IPSW for (AppleTV14,1), restored over its base's IPSW of the same build (default: the catalog's OTA of that build)",
+ "Full OTA (.aea or .zip) URL or local path for an OTA userland guest, including Apple TV 4K and HomePod mini (default: the catalog's OTA when required)",
valueName: "ota",
))
var otaSource: String?
@@ -259,8 +259,10 @@ struct VPhoneFirmwarePrepareCommand: ParsableCommand {
if let device, VPhoneGuestDevice.named(device) == nil {
throw ValidationError("vphone runs \(VPhoneGuestDevice.known.map(\.productType).joined(separator: ", ")) guests, not \(device).")
}
- if otaSource != nil || otaKey != nil, VPhoneGuestDevice.named(device)?.restoreBase == nil {
- throw ValidationError("--ota-source and --ota-key are for a device Apple ships no IPSW for, such as --device AppleTV14,1.")
+ if otaSource != nil || otaKey != nil,
+ VPhoneGuestDevice.named(device)?.restoreBase == nil,
+ VPhoneGuestDevice.named(device)?.family != .homePod {
+ throw ValidationError("--ota-source and --ota-key require an OTA userland device, such as --device AppleTV14,1 or AudioAccessory5,1.")
}
guard (1 ... 16).contains(downloadConnections) else {
throw ValidationError("--download-connections takes 1 to 16, not \(downloadConnections).")
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swift
index 2ca6f71d..be869e20 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swift
@@ -47,7 +47,8 @@ enum VPhoneFirmwarePreparer {
// A source naming a catalog OTA, such as a tvOS the Apple TV HD never
// got, restores the OTA's base IPSW and stages that OTA.
var iPhoneSource = iPhoneSource, otaSource = otaSource, productType = productType
- if let release = VPhoneFirmwareCatalog.otaRelease(source: iPhoneSource) {
+ let requestedOTA = VPhoneFirmwareCatalog.otaRelease(source: iPhoneSource)
+ if let release = requestedOTA {
guard let base = VPhoneFirmwareCatalog.restoreBaseURL(for: release) else {
throw ValidationError("The firmware catalog has no \(release.baseVersion) IPSW to restore the \(release.productType) OTA \(release.version) over.")
}
@@ -92,18 +93,19 @@ enum VPhoneFirmwarePreparer {
device: productType,
downloadConnections: downloadConnections,
)
- let ota = try device.restoreBase.map { _ in
- try resolveOTA(
+ let ota: (file: URL, key: String?, version: String, build: String)?
+ if device.restoreBase != nil || (device.family == .homePod && otaSource != nil) {
+ ota = try resolveOTA(
otaSource,
key: otaKey,
device: device,
- build: phone.build,
+ build: requestedOTA?.build ?? phone.build,
ipswCacheDirectory: ipswCacheDirectory,
downloadConnections: downloadConnections,
)
- }
+ } else { ota = nil }
if ota == nil, otaSource != nil || otaKey != nil {
- throw ValidationError("--ota-source and --ota-key are for a device Apple ships no IPSW for, such as AppleTV14,1, not \(device.productType).")
+ throw ValidationError("--ota-source and --ota-key require an OTA userland device, such as AppleTV14,1 or HomePod mini.")
}
// Such a device is restored from its base's IPSW, so the tree and its
// manifest are the base's; the VM records the device itself.
@@ -232,6 +234,12 @@ enum VPhoneFirmwarePreparer {
device productType: String? = nil,
downloadConnections: Int = VPhoneIPSWCache.defaultDownloadConnections,
) throws -> (phone: VPhoneIPSWCache.Archive, cloud: VPhoneIPSWCache.Archive, device: VPhoneGuestDevice) {
+ let ota = VPhoneFirmwareCatalog.otaRelease(source: iPhoneSource)
+ if let ota, let productType, ota.productType != productType {
+ throw Error.deviceNotInSource(productType, available: [ota.productType])
+ }
+ let iPhoneSource = ota.flatMap(VPhoneFirmwareCatalog.restoreBaseURL(for:)) ?? iPhoneSource
+ let productType = productType ?? ota?.productType
// Remote IPSWs go to one cache shared by every machine; keeping them
// inside the machine downloaded both again for each new one (#513).
// Local IPSWs are read in place and are never copied into the cache.
@@ -297,7 +305,16 @@ enum VPhoneFirmwarePreparer {
bar.finish()
// A local file of the catalog's build takes the catalog's key too.
let key = key ?? release?.key
- let identity = try VPhoneOTAArchive.checkIdentity(of: file, key: key, device: device, build: build)
+ // A HomePod owner may supply a renamed local full OTA over the last
+ // restore IPSW. Its manifest gives the target identity; catalog sources
+ // remain pinned to the catalog build. Staging checks that identity again.
+ let expectedBuild: String? = device.family == .homePod && release == nil ? nil : build
+ let identity = try VPhoneOTAArchive.checkIdentity(of: file, key: key, device: device, build: expectedBuild)
+ if device.family == .homePod {
+ guard let version = VPhoneVersion(identity.version), version.major == 27, version.minor >= 2 else {
+ throw ValidationError("HomePod OTA userland preparation requires HomePod Software 27.2 or later in the 27 series.")
+ }
+ }
print("[+] \(device.productType) OTA \(identity.version) (\(identity.build)): \(file.path)")
return (file, key, identity.version, identity.build)
}
@@ -323,11 +340,17 @@ enum VPhoneFirmwarePreparer {
build: ota.build,
deviceTreeDirectory: flash,
userlandDirectory: userland,
+ requireFullUpdate: device.family == .homePod,
) { name in
if VPhoneOTAArchive.isChunkName(name) {
print(" \(name)")
}
}
+ if device.family == .homePod {
+ let metadata = ["Device": device.productType, "Version": staged.version, "Build": staged.build]
+ try PropertyListSerialization.data(fromPropertyList: metadata, format: .xml, options: 0)
+ .write(to: userland.appendingPathComponent("Version.plist"), options: .atomic)
+ }
print("[+] \(staged.deviceTree.lastPathComponent) and \(staged.chunks.count) payload chunks staged")
}
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift
index 8c5d7688..f373a935 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift
@@ -54,7 +54,7 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {
))
var device: String?
@Option(help: ArgumentHelp(
- "Full OTA (.aea) URL or local path for a device Apple ships no IPSW for (AppleTV14,1) (default: the catalog's OTA of the IPSW's build)",
+ "Full OTA (.aea or .zip) URL or local path for an OTA userland guest, including Apple TV 4K and HomePod mini (default: the catalog's OTA when required)",
valueName: "ota",
))
var otaSource: String?
@@ -135,8 +135,10 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {
if noTemplate, try !slimming.request.isEmpty {
throw ValidationError("The slimming switches shape a template; --no-template builds the VM without one.")
}
- if otaSource != nil || otaKey != nil, VPhoneGuestDevice.named(device)?.restoreBase == nil {
- throw ValidationError("--ota-source and --ota-key are for a device Apple ships no IPSW for, such as --device AppleTV14,1.")
+ if otaSource != nil || otaKey != nil,
+ VPhoneGuestDevice.named(device)?.restoreBase == nil,
+ VPhoneGuestDevice.named(device)?.family != .homePod {
+ throw ValidationError("--ota-source and --ota-key require an OTA userland device, such as --device AppleTV14,1 or AudioAccessory5,1.")
}
if usesTVOS {
// Templates and their setup boot drive iOS Setup Assistant and its apps.
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/experimental.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/experimental.plist
index cbb44136..eb3828a2 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/experimental.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/experimental.plist
@@ -91,6 +91,8 @@
<string>system-homepod-exp-setup_bypass</string>
<string>system-homepod-exp-welcome</string>
<string>system-homepod-exp-siri_speech</string>
+ <string>system-homepod-exp-ota_userland</string>
+ <string>system-homepod-exp-sound_glow</string>
<string>preboot-homepod-exp-audio_product</string>
</array>
</dict>
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
index 1dbdab4f..7c408836 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
@@ -71,6 +71,8 @@
<string>system-homepod-exp-setup_bypass</string>
<string>system-homepod-exp-welcome</string>
<string>system-homepod-exp-siri_speech</string>
+ <string>system-homepod-exp-ota_userland</string>
+ <string>system-homepod-exp-sound_glow</string>
<string>preboot-homepod-exp-audio_product</string>
<string>kernel-exp-frida_thread_set_state_entitlement_flag</string>
<string>kernel-exp-frida_vm_map_delete_immutable_code</string>
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
index 00e5da51..21018d07 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
@@ -71,6 +71,8 @@
<string>system-homepod-exp-setup_bypass</string>
<string>system-homepod-exp-welcome</string>
<string>system-homepod-exp-siri_speech</string>
+ <string>system-homepod-exp-ota_userland</string>
+ <string>system-homepod-exp-sound_glow</string>
<string>preboot-homepod-exp-audio_product</string>
<string>system-exp-ota_userland</string>
<string>kernel-exp-frida_thread_set_state_entitlement_flag</string>
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
index 02ecf8ba..80a385f9 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
@@ -71,6 +71,8 @@
<string>system-homepod-exp-setup_bypass</string>
<string>system-homepod-exp-welcome</string>
<string>system-homepod-exp-siri_speech</string>
+ <string>system-homepod-exp-ota_userland</string>
+ <string>system-homepod-exp-sound_glow</string>
<string>preboot-homepod-exp-audio_product</string>
<string>kernel-exp-frida_thread_set_state_entitlement_flag</string>
<string>kernel-cfw-paravirt_gpu_task3</string>
diff --git a/VPhoneGuestComponents/HomePodDisplay/VPHomePodSoundGlow.m b/VPhoneGuestComponents/HomePodDisplay/VPHomePodSoundGlow.m
new file mode 100644
index 00000000..ccc64e9b
--- /dev/null
+++ b/VPhoneGuestComponents/HomePodDisplay/VPHomePodSoundGlow.m
@@ -0,0 +1,112 @@
+#import <Foundation/Foundation.h>
+#import <objc/runtime.h>
+#import <objc/message.h>
+
+// 24K120 adds native artwork extraction and CAPAnimationEffect.media to
+// NowPlayingCap. Its Home accessory setting defaults to off on an unpaired VM.
+// Select that existing renderer in this process only; never generate frames or
+// change MobileGestalt identity, shared audio sessions or Home preferences.
+static NSInteger (*VPSoundGlowOriginalMediaUI)(id, SEL);
+static void (*VPSoundGlowOriginalArtworkRequest)(id, SEL, id, id);
+
+static BOOL VPSoundGlowEnabled(void) {
+#ifdef VP_HOMEPOD_SOUND_GLOW_TESTING
+ extern BOOL VPSoundGlowTestEnabled;
+ return VPSoundGlowTestEnabled;
+#else
+ return [[NSDictionary dictionaryWithContentsOfFile:@"/usr/share/vphone/HomePodSoundGlow.plist"][@"Enabled"] isEqual:@YES];
+#endif
+}
+
+static BOOL VPSoundGlowIsNowPlaying(void) {
+#ifdef VP_HOMEPOD_SOUND_GLOW_TESTING
+ extern BOOL VPSoundGlowTestNowPlaying;
+ return VPSoundGlowTestNowPlaying;
+#else
+ return [NSProcessInfo.processInfo.processName isEqualToString:@"NowPlayingCap"];
+#endif
+}
+
+static BOOL VPSoundGlowSignature(Class cls, SEL selector, const char *result,
+ NSArray<NSString *> *arguments) {
+ Method method = class_getInstanceMethod(cls, selector);
+ if (!method) return NO;
+ NSMethodSignature *signature = [NSMethodSignature signatureWithObjCTypes:method_getTypeEncoding(method)];
+ if (signature.numberOfArguments != arguments.count + 2 || strcmp(signature.methodReturnType, result)) return NO;
+ for (NSUInteger i = 0; i < arguments.count; i++) {
+ if (strcmp([signature getArgumentTypeAtIndex:i + 2], arguments[i].UTF8String)) return NO;
+ }
+ return YES;
+}
+
+static BOOL VPSoundGlowNativeABI(Class cls) {
+ return VPSoundGlowSignature(cls, NSSelectorFromString(@"mediaUI"), @encode(NSInteger), @[]) &&
+ VPSoundGlowSignature(cls, NSSelectorFromString(@"setMediaUI:"), @encode(void), @[@(@encode(NSInteger))]);
+}
+
+static NSInteger VPSoundGlowMediaUI(id receiver, SEL selector) {
+ // Native 24K120 compares this setting to exactly 1 before fetching artwork
+ // and choosing its expressive media/soundscape effects. Opt-out exposes the
+ // real accessory setting again, including updates received from Home.
+ return VPSoundGlowEnabled() ? 1 : VPSoundGlowOriginalMediaUI(receiver, selector);
+}
+
+static id VPSoundGlowObject(id receiver, NSString *selector) {
+ return ((id (*)(id, SEL))objc_msgSend)(receiver, NSSelectorFromString(selector));
+}
+
+static void VPSoundGlowArtworkRequest(id receiver, SEL selector, id destination, id completion) {
+ id target = destination;
+ if (VPSoundGlowEnabled()) {
+ // Native 24K120 ArtworkFetcher addresses MRDeviceInfoRequest's own UID.
+ // An unpaired virtual accessory has no discoverable endpoint for that
+ // UID. Use MediaRemote's local origin for this one local request; keep
+ // Apple's identifiers, dimensions, response and artwork pipeline.
+ id info = VPSoundGlowObject(NSClassFromString(@"MRDeviceInfoRequest"), @"localDeviceInfo");
+ id ownUID = VPSoundGlowObject(info, @"deviceUID");
+ id requestedUID = [destination respondsToSelector:NSSelectorFromString(@"outputDeviceUID")]
+ ? VPSoundGlowObject(destination, @"outputDeviceUID") : nil;
+ if ([ownUID isKindOfClass:NSString.class] && [ownUID length] && [ownUID isEqual:requestedUID]) {
+ id local = VPSoundGlowObject(NSClassFromString(@"MRDestination"), @"localDestination");
+ if (local) target = local;
+ }
+ }
+ VPSoundGlowOriginalArtworkRequest(receiver, selector, target, completion);
+}
+
+static BOOL VPSoundGlowArtworkABI(void) {
+ Class request = NSClassFromString(@"MRPlaybackQueueRequest");
+ Class destination = NSClassFromString(@"MRDestination");
+ Class infoRequest = NSClassFromString(@"MRDeviceInfoRequest");
+ Class info = NSClassFromString(@"MRDeviceInfo");
+ return VPSoundGlowSignature(request, NSSelectorFromString(@"performRequestForDestination:completion:"),
+ @encode(void), @[@(@encode(id)), @"@?"]) &&
+ VPSoundGlowSignature(object_getClass(destination), NSSelectorFromString(@"localDestination"), @encode(id), @[]) &&
+ VPSoundGlowSignature(destination, NSSelectorFromString(@"outputDeviceUID"), @encode(id), @[]) &&
+ VPSoundGlowSignature(object_getClass(infoRequest), NSSelectorFromString(@"localDeviceInfo"), @encode(id), @[]) &&
+ VPSoundGlowSignature(info, NSSelectorFromString(@"deviceUID"), @encode(id), @[]);
+}
+
+BOOL VPHomePodSoundGlowInstall(void) {
+ static BOOL installed;
+ if (!VPSoundGlowIsNowPlaying() || !VPSoundGlowEnabled()) return NO;
+ Class provider = NSClassFromString(@"_TtC13NowPlayingCap24AccessorySettingProvider");
+ if (!VPSoundGlowNativeABI(provider)) {
+ NSLog(@"vphone HomePod Sound Glow: native accessory-setting ABI unavailable");
+ return NO;
+ }
+ if (installed) return YES;
+ Method getter = class_getInstanceMethod(provider, NSSelectorFromString(@"mediaUI"));
+ VPSoundGlowOriginalMediaUI = (void *)method_setImplementation(getter, (IMP)VPSoundGlowMediaUI);
+ if (VPSoundGlowArtworkABI()) {
+ Method request = class_getInstanceMethod(NSClassFromString(@"MRPlaybackQueueRequest"),
+ NSSelectorFromString(@"performRequestForDestination:completion:"));
+ VPSoundGlowOriginalArtworkRequest = (void *)method_setImplementation(request, (IMP)VPSoundGlowArtworkRequest);
+ NSLog(@"vphone HomePod Sound Glow: local artwork request adapter ready");
+ } else {
+ NSLog(@"vphone HomePod Sound Glow: native artwork request ABI unavailable");
+ }
+ installed = YES;
+ NSLog(@"vphone HomePod Sound Glow: native media renderer enabled");
+ return YES;
+}
diff --git a/VPhoneGuestComponents/HomePodDisplay/libvphonehomepoddisplay.m b/VPhoneGuestComponents/HomePodDisplay/libvphonehomepoddisplay.m
index 2518165b..036897c2 100644
--- a/VPhoneGuestComponents/HomePodDisplay/libvphonehomepoddisplay.m
+++ b/VPhoneGuestComponents/HomePodDisplay/libvphonehomepoddisplay.m
@@ -4,6 +4,7 @@
#import "VPHomePodSiriSpeech.h"
void VPHomePodWelcomeInstall(void);
+BOOL VPHomePodSoundGlowInstall(void);
// IOHIDUserDevice deliberately rejects reserved IOKit properties, including
// IOClass. MiniDisplay's HW3 path tests that property before reading MDHWVersion.
@@ -163,6 +164,10 @@ bool VPHomePodInstallDisplayIdentity(void) {
#ifndef VP_HOMEPOD_DISPLAY_TESTING
__attribute__((constructor)) static void VPHomePodDisplayInitialize(void) {
@autoreleasepool {
+ if ([NSProcessInfo.processInfo.processName isEqualToString:@"NowPlayingCap"]) {
+ VPHomePodSoundGlowInstall();
+ return;
+ }
// The executable load command limits this library to SoundBoard. dlopen ensures
// its MiniDisplay class is registered before we install the adapter.
void *framework = dlopen("/System/Library/PrivateFrameworks/MiniDisplay.framework/MiniDisplay", RTLD_NOW);
diff --git a/VPhoneGuestComponents/Makefile b/VPhoneGuestComponents/Makefile
index 3b7d1714..2d25b734 100644
--- a/VPhoneGuestComponents/Makefile
+++ b/VPhoneGuestComponents/Makefile
@@ -169,6 +169,13 @@ test-homepod-siri-speech:
-o $(OUT)/HomePodSiriSpeechTests Tests/HomePodSiriSpeechTests.m -framework Foundation
@$(OUT)/HomePodSiriSpeechTests
+.PHONY: test-homepod-sound-glow
+test-homepod-sound-glow:
+ @mkdir -p $(OUT)
+ xcrun --sdk macosx clang -fobjc-arc -Wall -Wextra -Werror \
+ -o $(OUT)/HomePodSoundGlowTests Tests/HomePodSoundGlowTests.m -framework Foundation
+ @$(OUT)/HomePodSoundGlowTests
+
gpu: $(GPU_PLUGIN)
package: all
diff --git a/VPhoneGuestComponents/Tests/HomePodSoundGlowTests.m b/VPhoneGuestComponents/Tests/HomePodSoundGlowTests.m
new file mode 100644
index 00000000..b4340f38
--- /dev/null
+++ b/VPhoneGuestComponents/Tests/HomePodSoundGlowTests.m
@@ -0,0 +1,101 @@
+#define VP_HOMEPOD_SOUND_GLOW_TESTING 1
+#import "../HomePodDisplay/VPHomePodSoundGlow.m"
+#include <assert.h>
+
+BOOL VPSoundGlowTestEnabled;
+BOOL VPSoundGlowTestNowPlaying;
+
+@interface _TtC13NowPlayingCap24AccessorySettingProvider : NSObject
+@property (nonatomic) NSInteger mediaUI;
+@end
+@implementation _TtC13NowPlayingCap24AccessorySettingProvider
+@end
+
+@interface WrongSoundGlowABI : NSObject
+- (BOOL)mediaUI;
+- (void)setMediaUI:(BOOL)value;
+@end
+@implementation WrongSoundGlowABI
+- (BOOL)mediaUI { return NO; }
+- (void)setMediaUI:(BOOL)value { (void)value; }
+@end
+
+@interface MRDestination : NSObject
+@property (nonatomic, copy) NSString *outputDeviceUID;
++ (id)localDestination;
+@end
+@implementation MRDestination
++ (id)localDestination {
+ static MRDestination *local;
+ if (!local) { local = [self new]; local.outputDeviceUID = @"local-origin"; }
+ return local;
+}
+@end
+
+@interface MRDeviceInfo : NSObject
+- (id)deviceUID;
+@end
+@implementation MRDeviceInfo
+- (id)deviceUID { return @"own-accessory"; }
+@end
+
+@interface MRDeviceInfoRequest : NSObject
++ (id)localDeviceInfo;
+@end
+@implementation MRDeviceInfoRequest
++ (id)localDeviceInfo { return [MRDeviceInfo new]; }
+@end
+
+@interface MRPlaybackQueueRequest : NSObject
+@property (nonatomic, strong) id receivedDestination;
+@property (nonatomic) NSUInteger calls;
+- (void)performRequestForDestination:(id)destination completion:(void (^)(id, id))completion;
+@end
+@implementation MRPlaybackQueueRequest
+- (void)performRequestForDestination:(id)destination completion:(void (^)(id, id))completion {
+ self.receivedDestination = destination;
+ self.calls++;
+ if (completion) completion(@"native-artwork", nil);
+}
+@end
+
+int main(void) { @autoreleasepool {
+ Class provider = _TtC13NowPlayingCap24AccessorySettingProvider.class;
+ assert(!VPSoundGlowNativeABI(Nil)); // 27.0 has no accessory-setting provider.
+ assert(!VPSoundGlowNativeABI(WrongSoundGlowABI.class));
+ assert(VPSoundGlowNativeABI(provider));
+ assert(VPSoundGlowArtworkABI());
+ assert(!VPHomePodSoundGlowInstall());
+ VPSoundGlowTestEnabled = YES;
+ assert(!VPHomePodSoundGlowInstall()); // SoundBoard must not get this hook.
+ VPSoundGlowTestNowPlaying = YES;
+ assert(VPHomePodSoundGlowInstall());
+ assert(VPHomePodSoundGlowInstall()); // No recursion or double replacement.
+ _TtC13NowPlayingCap24AccessorySettingProvider *settings = [provider new];
+ assert(settings.mediaUI == 1);
+ settings.mediaUI = 7; // Native Home updates still reach the original setter.
+ assert(settings.mediaUI == 1);
+ VPSoundGlowTestEnabled = NO;
+ assert(settings.mediaUI == 7); // Opt-out restores the actual setting.
+ settings.mediaUI = 0;
+ assert(settings.mediaUI == 0);
+ VPSoundGlowTestEnabled = YES;
+ assert(settings.mediaUI == 1);
+ MRPlaybackQueueRequest *request = [MRPlaybackQueueRequest new];
+ MRDestination *own = [MRDestination new]; own.outputDeviceUID = @"own-accessory";
+ __block id reply;
+ [request performRequestForDestination:own completion:^(id value, id error) {
+ assert(!error); reply = value;
+ }];
+ assert(request.receivedDestination == [MRDestination localDestination]);
+ assert([reply isEqual:@"native-artwork"] && request.calls == 1);
+ MRDestination *remote = [MRDestination new]; remote.outputDeviceUID = @"another-device";
+ [request performRequestForDestination:remote completion:nil];
+ assert(request.receivedDestination == remote);
+ [request performRequestForDestination:nil completion:nil];
+ assert(request.receivedDestination == nil);
+ VPSoundGlowTestEnabled = NO;
+ [request performRequestForDestination:own completion:nil];
+ assert(request.receivedDestination == own && request.calls == 4);
+ puts("HomePod Sound Glow native setting, process isolation, opt-out and ABI tests passed");
+} return 0; }
diff --git a/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneOTAArchive.swift b/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneOTAArchive.swift
index 0b2c535e..73477962 100644
--- a/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneOTAArchive.swift
+++ b/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneOTAArchive.swift
@@ -1,4 +1,5 @@
import AppleArchive
+import ArchiveKit
import CryptoKit
import Darwin
import Foundation
@@ -8,7 +9,7 @@ import VPhoneCoreKit
/// A full OTA update, read with the system AppleArchive framework: no `ipsw`,
/// no `aea` or `aa` process, nothing from Homebrew.
///
-/// An OTA is an AEA file (`AEA1`): an Apple Archive encrypted and
+/// Newer TV OTAs are AEA files (`AEA1`): an Apple Archive encrypted and
/// authenticated with a symmetric key that Apple does not publish and AppleDB
/// records. The archive inside is segmented: its top-level entries are
/// metadata (`TYP=M`), and each one whose `YOP` is `E` (extract) carries in its
@@ -17,6 +18,7 @@ import VPhoneCoreKit
/// fix-ups applied after extraction, neither of which staging needs. An
/// archive that `aea decrypt` already wrote out (`AA01`, or a `pbz*`
/// compressed one) is read the same way, without a key.
+/// HomePod full OTAs may instead use ZIP, read through bundled libarchive.
///
/// Members stream from the file to their destination in fixed-size blocks,
/// so a multi-gigabyte OTA is read once and never held in memory.
@@ -42,7 +44,7 @@ public enum VPhoneOTAArchive {
case let .missingFile(file):
"OTA not found at \(file.path). Check the path and try again."
case let .notAnOTA(file):
- "\(file.lastPathComponent) is not an OTA: it is neither an AEA file nor an Apple Archive. Choose the device's full OTA (.aea)."
+ "\(file.lastPathComponent) is not an OTA: choose the device's full OTA (.aea, .zip or decrypted Apple Archive)."
case .invalidKey:
"The OTA key must be 32 bytes in base64, as AppleDB lists it under the OTA's decryptionKey."
case let .keyRequired(file):
@@ -124,6 +126,10 @@ public enum VPhoneOTAArchive {
select: (String) throws -> Disposition,
received: (String, Data?) throws -> Void,
) throws {
+ if try isZIP(ota) {
+ try readZIPMembers(ota, select: select, received: received)
+ return
+ }
let opened = try openArchive(ota, key: key)
let outer = opened.archive
var buffer = [UInt8](repeating: 0, count: blockSize)
@@ -160,6 +166,91 @@ public enum VPhoneOTAArchive {
}
}
+ /// HomePod full OTAs still use ZIP. Their Info.plist may follow the
+ /// payload physically, so visit the two identity/policy records first.
+ /// libarchive seeks over skipped ZIP members; no temporary full extraction
+ /// and no archive-provided pathname is ever used as a destination.
+ private static func readZIPMembers(
+ _ ota: URL,
+ select: (String) throws -> Disposition,
+ received: (String, Data?) throws -> Void
+ ) throws {
+ let metadata: Set = ["AssetData/Info.plist", manifestPath]
+ for metadataPass in [true, false] {
+ try withArchiveLocale {
+ guard let reader = archive_read_new() else { throw Error.unreadable(ota, "cannot create ZIP reader") }
+ defer { archive_read_free(reader) }
+ archive_read_support_format_zip(reader)
+ guard archive_read_open_filename(reader, ota.path, blockSize) == ARCHIVE_OK else {
+ throw Error.unreadable(ota, archiveErrorString(reader))
+ }
+ var seen: Set<String> = []
+ var buffer = [UInt8](repeating: 0, count: blockSize)
+ while true {
+ var entry: OpaquePointer?
+ let status = archive_read_next_header(reader, &entry)
+ if status == ARCHIVE_EOF { break }
+ guard status == ARCHIVE_OK, let entry,
+ let rawPath = archive_entry_pathname(entry) else {
+ throw Error.unreadable(ota, archiveErrorString(reader))
+ }
+ let path = String(cString: rawPath)
+ guard seen.insert(path).inserted else { throw Error.unreadable(ota, "duplicate ZIP member \(path)") }
+ guard metadata.contains(path) == metadataPass,
+ mode_t(archive_entry_filetype(entry)) == S_IFREG,
+ archive_entry_hardlink(entry) == nil else {
+ archive_read_data_skip(reader)
+ continue
+ }
+ let disposition = try select(path)
+ if case .skip = disposition {
+ archive_read_data_skip(reader)
+ continue
+ }
+ let declaredSize = archive_entry_size(entry)
+ guard declaredSize >= 0 else { throw Error.unreadable(ota, "negative ZIP member size") }
+ var data: Data?
+ let output: FileHandle?
+ switch disposition {
+ case .skip: preconditionFailure()
+ case .memory:
+ guard UInt64(declaredSize) <= memoryLimit else { throw Error.unreadable(ota, "\(path) exceeds the metadata limit") }
+ data = Data()
+ output = nil
+ case let .file(destination):
+ guard FileManager.default.createFile(atPath: destination.path, contents: nil) else {
+ throw Error.unreadable(ota, "cannot create \(destination.path)")
+ }
+ output = try FileHandle(forWritingTo: destination)
+ }
+ defer { try? output?.close() }
+ var total: Int64 = 0
+ while true {
+ let count = buffer.withUnsafeMutableBytes { archive_read_data(reader, $0.baseAddress, $0.count) }
+ if count == 0 { break }
+ guard count > 0 else { throw Error.unreadable(ota, archiveErrorString(reader)) }
+ total += Int64(count)
+ guard total <= declaredSize else { throw Error.unreadable(ota, "\(path) exceeds its ZIP size") }
+ let chunk = Data(buffer.prefix(Int(count)))
+ if output != nil { try output?.write(contentsOf: chunk) } else { data?.append(chunk) }
+ }
+ guard total == declaredSize else { throw Error.unreadable(ota, "\(path) is truncated") }
+ try output?.close()
+ try received(path, data)
+ }
+ guard archive_read_close(reader) == ARCHIVE_OK else { throw Error.unreadable(ota, archiveErrorString(reader)) }
+ }
+ }
+ }
+
+ private static func isZIP(_ file: URL) throws -> Bool {
+ try readMagic(file) == Data([0x50, 0x4b, 0x03, 0x04])
+ }
+
+ private static func isDownloadMagic(_ data: Data) -> Bool {
+ data == Data("AEA1".utf8) || data == Data([0x50, 0x4b, 0x03, 0x04])
+ }
+
private struct OpenedArchive {
let archive: ArchiveStream
/// The file, then any decryption or decompression over it.
@@ -448,7 +539,7 @@ public enum VPhoneOTAArchive {
of ota: URL,
key: String?,
device: VPhoneGuestDevice,
- build: String,
+ build: String? = nil,
) throws -> (version: String, build: String) {
struct Found: Swift.Error {}
var identity: (version: String, build: String)?
@@ -633,7 +724,7 @@ public enum VPhoneOTAArchive {
_ data: Data,
of ota: URL,
device: VPhoneGuestDevice,
- build expected: String,
+ build expected: String?,
) throws -> (version: String, build: String) {
guard let manifest = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],
let version = manifest["ProductVersion"] as? String,
@@ -645,7 +736,7 @@ public enum VPhoneOTAArchive {
guard types.contains(device.productType) else {
throw Error.wrongDevice(ota, productTypes: types, expected: device.productType)
}
- guard build == expected else { throw Error.wrongBuild(ota, build: build, expected: expected) }
+ if let expected, build != expected { throw Error.wrongBuild(ota, build: build, expected: expected) }
return (version, build)
}
@@ -724,7 +815,7 @@ public enum VPhoneOTAArchive {
if let expectedSize, actual != expectedSize {
throw Error.unexpectedSize(remote, expected: expectedSize, actual: actual)
}
- guard try readMagic(pending).starts(with: Data("AEA1".utf8)) else { throw Error.notAnOTA(remote) }
+ guard try isDownloadMagic(readMagic(pending)) else { throw Error.notAnOTA(remote) }
if fm.fileExists(atPath: cache.path) {
try fm.removeItem(at: cache)
}
@@ -744,7 +835,7 @@ public enum VPhoneOTAArchive {
try fm.removeItem(at: cache)
return false
}
- return magic.starts(with: Data("AEA1".utf8))
+ return isDownloadMagic(magic)
}
static func cacheName(for url: URL) -> String {
@@ -755,7 +846,7 @@ public enum VPhoneOTAArchive {
})
let digest = SHA256.hash(data: Data(url.absoluteString.utf8))
let suffix = digest.prefix(6).map { String(format: "%02x", $0) }.joined()
- return "\(safe.isEmpty ? "ota" : safe)-\(suffix).aea"
+ return "\(safe.isEmpty ? "ota" : safe)-\(suffix).\(url.pathExtension.lowercased() == "zip" ? "zip" : "aea")"
}
}
diff --git a/VPhoneKit/VPhoneArchiveKitTests/OTAArchiveTests.swift b/VPhoneKit/VPhoneArchiveKitTests/OTAArchiveTests.swift
index 67c2fbe4..608cc2a3 100644
--- a/VPhoneKit/VPhoneArchiveKitTests/OTAArchiveTests.swift
+++ b/VPhoneKit/VPhoneArchiveKitTests/OTAArchiveTests.swift
@@ -1,4 +1,5 @@
import AppleArchive
+import ArchiveKit
import CryptoKit
import Foundation
import System
@@ -158,6 +159,28 @@ struct OTAArchiveTests {
return file
}
+ private func makeZIP(in root: URL, _ members: [(String, Data)]) throws -> URL {
+ let file = root.appendingPathComponent("HomePod.zip")
+ let writer = try #require(archive_write_new())
+ defer { archive_write_free(writer) }
+ try #require(archive_write_set_format_zip(writer) == ARCHIVE_OK)
+ try #require(archive_write_open_filename(writer, file.path) == ARCHIVE_OK)
+ for (path, data) in members {
+ let entry = try #require(archive_entry_new())
+ defer { archive_entry_free(entry) }
+ archive_entry_set_pathname(entry, path)
+ archive_entry_set_filetype(entry, UInt32(S_IFREG))
+ archive_entry_set_perm(entry, 0o644)
+ archive_entry_set_size(entry, Int64(data.count))
+ try #require(archive_write_header(writer, entry) == ARCHIVE_OK)
+ try data.withUnsafeBytes { bytes in
+ try #require(archive_write_data(writer, bytes.baseAddress, bytes.count) == bytes.count)
+ }
+ }
+ try #require(archive_write_close(writer) == ARCHIVE_OK)
+ return file
+ }
+
private func stage(_ ota: URL, in root: URL, key: String?, build: String = "23L773") throws -> VPhoneOTAArchive.StagedUserland {
let flash = root.appendingPathComponent("restore/Firmware/all_flash", isDirectory: true)
try FileManager.default.createDirectory(at: flash, withIntermediateDirectories: true)
@@ -180,6 +203,56 @@ struct OTAArchiveTests {
// MARK: - Staging
+ @Test func `HomePod ZIP staging reads late metadata before payload and ignores unrelated paths`() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let flash = root.appendingPathComponent("flash")
+ try FileManager.default.createDirectory(at: flash, withIntermediateDirectories: true)
+ let manifest = try PropertyListSerialization.data(fromPropertyList: [
+ "ProductVersion": "27.2", "ProductBuildVersion": "24K120",
+ "SupportedProductTypes": ["AudioAccessory5,1"],
+ ], format: .xml, options: 0)
+ let info = try PropertyListSerialization.data(fromPropertyList: ["OSVersion": "27.2"], format: .xml, options: 0)
+ let payload = try encode([.directory("System"), .file("System/source", Data("native".utf8))], in: root)
+ let ota = try makeZIP(in: root, [
+ ("../outside", Data("unselected".utf8)),
+ ("AssetData/payloadv2/payload.000", payload),
+ ("AssetData/payloadv2/payload.000.ecc", Data("ecc".utf8)),
+ ("AssetData/payloadv2/payload_chunks.txt", Data("0: 1000\n".utf8)),
+ ("AssetData/payloadv2/links.txt", Data("=System/source\n+System/copy\n".utf8)),
+ ("AssetData/boot/Firmware/all_flash/DeviceTree.b520ap.im4p", Data("b520".utf8)),
+ ("AssetData/boot/BuildManifest.plist", manifest),
+ ("AssetData/Info.plist", info),
+ ])
+ let identity = try VPhoneOTAArchive.checkIdentity(of: ota, key: nil, device: .audioAccessory5_1, build: "24K120")
+ #expect(identity.version == "27.2")
+ let userland = root.appendingPathComponent("OTAUserland")
+ let result = try VPhoneOTAArchive.stageUserland(from: ota, key: nil, device: .audioAccessory5_1,
+ build: "24K120", deviceTreeDirectory: flash, userlandDirectory: userland, requireFullUpdate: true)
+ #expect(result.chunks == ["payload.000"])
+ #expect(try Data(contentsOf: userland.appendingPathComponent("payload.000")) == payload)
+ #expect(!FileManager.default.fileExists(atPath: root.appendingPathComponent("outside").path))
+ }
+
+ @Test func `ZIP duplicate metadata is refused`() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let ota = try makeZIP(in: root, [("AssetData/Info.plist", Data()), ("AssetData/Info.plist", Data())])
+ #expect(throws: VPhoneOTAArchive.Error.self) {
+ try VPhoneOTAArchive.readMembers(ota, key: nil, select: { _ in .skip }, received: { _, _ in })
+ }
+ }
+
+ @Test func `ZIP metadata has the same bounded memory admission as Apple Archive`() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let oversized = Data(repeating: 0, count: Int(VPhoneOTAArchive.memoryLimit) + 1)
+ let ota = try makeZIP(in: root, [("AssetData/Info.plist", oversized)])
+ #expect(throws: VPhoneOTAArchive.Error.self) {
+ try VPhoneOTAArchive.readMembers(ota, key: nil, select: { _ in .memory }, received: { _, _ in Issue.record("oversized metadata delivered") })
+ }
+ }
+
@Test func `hard-link lists preserve spaces and reject unsafe or ambiguous records`() throws {
let links = try VPhoneOTAArchive.parseHardLinks(Data("=System/source file\n+System/copy file\n+System/another\n".utf8))
#expect(links.count == 2)
@@ -448,7 +521,7 @@ struct OTAArchiveTests {
}
}
- @Test func `a file that is neither AEA nor Apple Archive is not an OTA`() throws {
+ @Test func `a truncated ZIP is refused before any OTA chunk is written`() throws {
let root = try makeRoot()
defer { try? FileManager.default.removeItem(at: root) }
let zip = root.appendingPathComponent("AppleTV5,3_26.6_23L773_Restore.ipsw")
@@ -457,7 +530,7 @@ struct OTAArchiveTests {
#expect {
try stage(zip, in: root, key: keyText)
} throws: { error in
- if case .notAnOTA? = error as? VPhoneOTAArchive.Error { true } else { false }
+ if case .unreadable? = error as? VPhoneOTAArchive.Error { true } else { false }
}
}
diff --git a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swift b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swift
index 2bc4b5e1..944ffa12 100644
--- a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swift
+++ b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swift
@@ -50,14 +50,15 @@ public struct VPhoneOTARelease: Sendable, Equatable {
public let url: String
/// The `.aea` file's length, which a cached copy must have.
public let size: Int64
- /// The AEA archive's symmetric key, base64, as AppleDB records it.
- public let key: String
+ /// The AEA archive's symmetric key, base64, as AppleDB records it; nil
+ /// for an unencrypted ZIP OTA.
+ public let key: String?
/// The version of the base device's IPSW the OTA is restored over. The
/// same as `version` while the base still gets releases; a later OTA goes
/// over the base's last one, since only the userland is taken from it.
public let baseVersion: String
- public init(productType: String, version: String, build: String, url: String, size: Int64, key: String, baseVersion: String? = nil) {
+ public init(productType: String, version: String, build: String, url: String, size: Int64, key: String? = nil, baseVersion: String? = nil) {
self.productType = productType
self.version = version
self.build = build
@@ -72,7 +73,7 @@ public struct VPhoneOTARelease: Sendable, Equatable {
/// The name the IPSW cache keeps it under, in its `ota` folder.
public var fileName: String {
- "\(productType)_\(version)_\(build)_OTA.aea"
+ "\(productType)_\(version)_\(build)_OTA.\(URL(string: url)?.pathExtension.lowercased() == "zip" ? "zip" : "aea")"
}
}
@@ -462,6 +463,17 @@ public enum VPhoneFirmwareCatalog {
key: "L3wZrfSYx2pFDbJSYtEteNDspB26qBv0lxLlkWrKTYk=",
baseVersion: "26.6",
),
+ // HomePod's newer software ships as a full ZIP OTA. Keep its own
+ // 27.0 restore IPSW as the base; the OTA supplies only the userland
+ // and board tree, while the boot chain remains cloudOS 26.4.
+ .init(
+ productType: "AudioAccessory5,1",
+ version: "27.2",
+ build: "24K120",
+ url: "https://updates.cdn-apple.com/2026FallFCS/b191c01c-8e6e-4b74-8b84-015131f696b8/com_apple_MobileAsset_SoftwareUpdate/861a9e7426795ddb3eac86cd0b089e5bf7939258.zip",
+ size: 3_051_441_612,
+ baseVersion: "27.0",
+ ),
]
/// The full OTA of `productType` at `build`, or nil when the catalog has none.
@@ -478,7 +490,8 @@ public enum VPhoneFirmwareCatalog {
/// The URL of the base device's IPSW `release` is restored over.
public static func restoreBaseURL(for release: VPhoneOTARelease) -> String? {
- guard let base = VPhoneGuestDevice.named(release.productType)?.restoreBase else { return nil }
+ guard let device = VPhoneGuestDevice.named(release.productType) else { return nil }
+ let base = device.restoreBase ?? device
let releases = (iPhoneReleases + iPadReleases + tvReleases + homePodReleases).first { $0.devices.contains(base.productType) }?.releases
return releases?.first { $0.version == release.baseVersion }?.url
}
@@ -501,6 +514,11 @@ public enum VPhoneFirmwareCatalog {
guard let base = releases.first(where: { $0.version == ota.baseVersion }) else { return nil }
return (version: ota.version, url: ota.version == base.version ? base.url : ota.url)
}
+ } else if guest.family == .homePod {
+ releases += otaReleases.filter { $0.productType == guest.productType }.compactMap { ota in
+ guard restoreBaseURL(for: ota) != nil else { return nil }
+ return (version: ota.version, url: ota.url)
+ }
}
return releases.map { release in
let cloudOS = guest.usesTVOS
diff --git a/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareCatalogReportTests.swift b/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareCatalogReportTests.swift
index 760e9b19..3172b6e7 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareCatalogReportTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareCatalogReportTests.swift
@@ -59,16 +59,17 @@ struct FirmwareCatalogReportTests {
#expect(ota.version == "26.6")
#expect(ota.url.hasPrefix("https://updates.cdn-apple.com/") && ota.url.hasSuffix(".aea"))
#expect(ota.size == 4_764_729_344)
- #expect(Data(base64Encoded: ota.key)?.count == 32)
+ #expect(Data(base64Encoded: try #require(ota.key))?.count == 32)
#expect(ota.fileName == "AppleTV14,1_26.6_23L773_OTA.aea")
#expect(VPhoneFirmwareCatalog.otaRelease(for: "AppleTV14,1", build: "23L760") == nil)
#expect(VPhoneFirmwareCatalog.otaRelease(for: "AppleTV5,3", build: "23L773") == nil)
// Every OTA has a base release to be restored over.
for release in VPhoneFirmwareCatalog.otaReleases {
- let base = try #require(VPhoneGuestDevice.named(release.productType)?.restoreBase)
+ let guest = try #require(VPhoneGuestDevice.named(release.productType))
+ let base = guest.restoreBase ?? guest
#expect(VPhoneFirmwareCatalog.pairings(for: base.productType).contains { $0.iosName.hasSuffix(" \(release.baseVersion)") })
#expect(VPhoneFirmwareCatalog.restoreBaseURL(for: release) != nil)
- #expect(Data(base64Encoded: release.key)?.count == 32)
+ if let key = release.key { #expect(Data(base64Encoded: key)?.count == 32) }
}
}
@@ -90,7 +91,7 @@ struct FirmwareCatalogReportTests {
@Test func `HomePod mini pairs its native 27 IPSW with cloudOS without an OTA base`() throws {
let pairings = VPhoneFirmwareCatalog.pairings(for: "AudioAccessory5,1")
- #expect(pairings.count == 1)
+ #expect(pairings.count == 2)
let pairing = try #require(pairings.first)
#expect(pairing.device == "AudioAccessory5,1")
#expect(pairing.iosName == "HomePod Software 27.0")
@@ -110,6 +111,20 @@ struct FirmwareCatalogReportTests {
#expect(entry.recommendedCloudOS.url == VPhoneFirmwareCatalog.cloud264)
}
+ @Test func `HomePod 27 point 2 takes its full ZIP OTA over its own 27 IPSW`() throws {
+ let release = try #require(VPhoneFirmwareCatalog.otaRelease(for: "AudioAccessory5,1", build: "24K120"))
+ #expect(release.version == "27.2" && release.baseVersion == "27.0")
+ #expect(release.key == nil && release.size == 3_051_441_612)
+ #expect(release.fileName == "AudioAccessory5,1_27.2_24K120_OTA.zip")
+ let pairings = VPhoneFirmwareCatalog.pairings(for: release.productType)
+ #expect(VPhoneFirmwareCatalog.restoreBaseURL(for: release) == pairings[0].iosURL)
+ #expect(pairings[1].iosURL == release.url)
+ #expect(VPhoneFirmwareCatalog.otaRelease(source: "/cache/ota/\(release.fileName)") == release)
+ let device = try #require(VPhoneFirmwareCatalog.report.devices.first { $0.productType == release.productType })
+ #expect(device.pairings[1].ios.build == "24K120")
+ #expect(device.pairings[1].ios.files == ["ota/\(release.fileName)", (pairings[0].iosURL as NSString).lastPathComponent])
+ }
+
@Test func `i pad pairings come from an IPSW that covers the device`() {
for guest in VPhoneGuestDevice.known where guest.isPad {
let pairings = VPhoneFirmwareCatalog.pairings(for: guest.productType)