Device resources: Android controls, snapshots and audio¶
Part of device resources.
Automation capabilities¶
Resource state does not establish whether screenshots, interaction, notifications, purchases, or other automation capabilities work. Continue to report capabilities separately using AutoMobile’s existing supported/partial/unavailable/unsupported conventions. Only mark a capability unavailable because of a disabled resource when its dependency is known for the device and app context.
Android controls¶
Android emulator controls are independent and opt-in. Optional-app groups disable only installed system packages in a fixed catalog for the current Android user. They preserve ContactsProvider, CalendarProvider, MediaProvider, DocumentsUI, SystemUI, the launcher, credentials, networking and automation packages. Active apps, default role holders, the selected keyboard and enabled accessibility services are protected. If role inspection is unavailable, package disablement fails closed; older Android versions can still support individual settings.
animationssets the three system animation scales to zero or one.screensaverscontrols dream activation, separately from wallpaper and widgets.backupcontrols Backup Manager for the current user.mailApp,calendarApp,contactsApp,mapsApp,videoApp,musicApp,photosApp,assistantApp,digitalWellbeing,printing,accessibilityApps,textToSpeech, andwallpaperAppscontrol optional applications. Disabling an app removes its integrations and intent handlers. Wallpaper picker removal is not equivalent to disabling wallpaper rendering.healthConnect,adServices,onDevicePersonalization,storeApp,dialerApp,messagesApp,googlePlayServicesandgoogleServicesFrameworkare explicit feature tradeoffs. Shared Google infrastructure must remain enabled for workloads that depend on its notifications or authentication. Mainline/APEX containers are never removed.
An Android response can include a restore receipt. Pass it back as
setDeviceResources({restore: receipt, ...deviceTargeting}), without resources,
to restore the exact previous overrides. Receipts are restricted to the same
emulator serial, boot ID and user. This prevents accidental restoration onto a
recycled emulator. They preserve default package state and absent settings;
enabled is an explicit enable operation, not a substitute for restoration.
Default override restoration may report observed state unknown while returning
success: true: the original override was verified, but the runtime’s effective
default was not inferred. Save the receipt from partial-error responses too.
A request cancelled before returning a response may have made partial changes;
inspect/reconcile state rather than assuming rollback. Receipts are not a durable
transaction journal and do not promise restoration across reboot or lost responses.
Android changed records targets for which a native write was attempted. Each
successful target is re-read; failed or ignored writes produce an error result.
No package availability observation proves it consumes CPU, and no resource
configuration result promises measured performance gains.
Android provisioning hardware¶
provisionDevice.device.spec.configuration accepts memoryMb, cpuCores,
gpuMode, screenWidth, screenHeight, screenDensity, cameraFront,
cameraBack, audioInput, and audioOutput. These persist in the AVD configuration
before boot. GPU modes are auto, host, software, swiftshader, lavapipe,
and swangle; actual backend availability depends on the installed emulator and
host. Camera values are none or emulated. Existing modern Play-image minimum
memory checks remain in effect. Replay can reconcile hardware only while the
AVD is stopped; a mismatched running device is an identity conflict.
Headless launch controls the window independently of audio.
AUTOMOBILE_EMULATOR_AUDIO=false passes -no-audio; otherwise the emulator and
AVD audio settings apply. AUTOMOBILE_EMULATOR_HEADLESS retains its existing
platform defaults, so audio-dependent workflows can run headless.
Further Android work and the measurement protocol are tracked in Android emulator optimization.
Provisioned Android transport retirement uses a process-wide fence in src/utils.
Its store contract lives beside the fence; the DB layer constructs the durable
default with ProvisionedDeviceTransportTombstoneRepository. Daemon construction,
MCP tool registration (including direct/stdio startup), and CLI tool registration
install it before device-session use. Installation preserves an existing fence
and does not open the DB until use, retaining startup ownership and migration
ordering. An unwired production holder throws; only tests default/reset to an
in-memory fence. Durable tombstones survive process restart and prevent a retired
emulator transport from identifying a later device.
VM snapshot incarnation lifecycle¶
An Android VM restore advances the pooled incarnation and synchronously calls
the registry’s reconnect primitive to retire the old deviceSessionUuid and
mint its successor before any post-load incarnation listener runs. Same or
older incarnation inputs return the current record, so a later readiness
callback cannot mint twice or move identity backwards. The owning tool
sessionUuid and serial assignment survive; direct mode and pooled devices
without a live registry epoch mint nothing during restore.
The deviceSnapshot restore result includes the new deviceSessionUuid when
one exists. The old epoch’s ended frame carries successorSessionUuid and the
typed reason superseded-by-restore; reconnect/disconnect frames retain their
existing shape. All-device subscribers see ended/started; old-UUID subscribers
see ended and must subscribe again to the successor. Frames pushed for the
restored serial are stamped with the new UUID. Restore-retired UUIDs fail
validated stream requests with DEVICE_SESSION_SUPERSEDED_BY_RESTORE and
recovery instructions shared through the device-session resolver. Device-control
replay rejects the old epoch through its existing typed transport failure and
uses the same restore-specific message.
The registry keeps at most 256 restore tombstones (UUID, serial, immediate successor, reason), evicting oldest first and clearing a serial’s tombstones on disconnect. Tombstones diagnose retirement; they never resolve as live and an immediate successor may itself later retire, so clients must discover the current UUID from the result, started frame, session listing, or device runtime. Definitive pre-load failures leave identity untouched. Once load succeeds, a readiness failure still re-mints because the guest has already rewound; an ambiguous load failure retains the existing conservative invalidation policy.
Per-device host-state owners register a DeviceIncarnationListener.
prepareForIncarnationChange(deviceId) runs before the VM load;
onDeviceIncarnationChanged(deviceId) invalidates caches immediately after loading.
The optional onIncarnationChangeSettled(deviceId, { ready }) hook runs once on
all exits after preparation, including preparation, load, and readiness failures.
ready: true means the restore provider’s guest readiness wait resolved. All
three phases are independently best-effort, and rejected listeners are logged.
Installed-app owners invalidate in-memory and persisted caches after load, but send their resource-updated notification only at ready settlement. Subscribers interpret this notification as an invitation to re-read; load/readiness failures therefore invalidate without notifying, so an unready guest cannot supply a fresh-looking empty app list in response to the notification.
Recording preparation fences new starts for that device before listing or stopping existing recordings. Settlement releases the fence on success or failure, after the readiness wait. A replaceable, injected Timer expiry defaults to ten minutes (well above the default 30-second load plus 30-second readiness budgets) to recover from abandoned restore flows. Custom restores longer than that bound may outlive the fence. A start already reserved before preparation can still finish after the active-recording inventory was taken; the fence rejects new reservations and does not drain starts already in flight.
Persistent Android provenance failure (including a missing cmdline-tools installation) returns
enrichment: { complete: false, missing: ["provenance"], retryable: false, reason } from
listDevices. The booted list remains usable without provenance; clients should address the
reported cause instead of polling. Successful provenance omits enrichment.
Hot presence, disconnect and lifecycle-notification resets clear the 2,500 ms resource,
stage and enrichment caches without aborting shared catalog/provenance fetches. Successful
AVD create/delete/provision, system-image install and daemon shutdown use full invalidation:
obsolete catalog reads report code: "superseded" with retry hints, rather than a timeout.
Only an actual 30,000 ms hard-cap expiry reports that background timeout; real catalog
failures retain code: "failed" with the underlying cause.
All ordinary ADB device-list readers share a 10,000 ms subprocess bound. Inventory callers
wait at most 2,000 ms and return incomplete discovery with code: "timeout", retryable: true
and retryAfterMs: 1000; their timeout leaves the shared read running and able to publish
into the 5,000 ms cache. Bypass readers run a fresh subprocess. Coalesced AVD listings use a
30,000 ms shared cap and independent caller deadlines/signals, so a 2,000 ms waiter cannot
cancel a longer reader’s listing.
Tool preflight: device_service_disabled¶
A scoped provider checks known disabled services before staging or invoking the
simulator operation. The typed dependency map in
src/utils/deviceServiceDependencies.ts registers only shipped tools that use a
catalog resource. The provider enforces the scope; the preflight checks the
registered tool’s resources in stable catalog order.
| Tool | Scope | Resource | Labels | Unavailable |
|---|---|---|---|---|
putAppFile |
iOS Simulator, target.domain=media_library |
mediaTranscoding |
com.apple.photos.ImageConversionService, com.apple.photos.VideoConversionService |
Photo/video media-library import and transcoding |
Any catalog label with the boolean override true disables its resource. The
first disabled resource produces an ActionableError with this wire payload:
{
code: "device_service_disabled",
tool: "putAppFile",
resource: "mediaTranscoding",
labels: ["com.apple.photos.ImageConversionService", "com.apple.photos.VideoConversionService"],
disabledLabels: ["com.apple.photos.ImageConversionService"],
unavailable: "iOS Simulator photo/video media-library import and transcoding",
howToEnable: "Call setDeviceResources with {resources:{mediaTranscoding:\"enabled\"}} (enable this default-disabled tool with setToolEnabled or --enable-tool setDeviceResources), or provision/start the simulator without {resources:{mediaTranscoding:\"disabled\"}}.",
retryable: false,
deviceId: "<simulator UDID>"
}
The single source for this fast-path check is the host launchd disabled database,
/private/var/tmp/com.apple.CoreSimulator.SimDevice.<UDID>/disabled.plist, read
through PlistReader.readJsonFile. Both launchctl disable and pre-first-boot
writes feed this per-UDID database, which survives reboot and erase. Application
DB state is unsuitable here: it requires runtime/device-type identity and extra
simctl calls, and may not reflect external changes. Each call reads once without
caching. A missing file means no known disabled labels; other read failures log a
warning and pass. Unknown state never blocks the tool. This check is not a
service-health guarantee. Physical devices, Android devices and unmapped tools
skip the read; cancellation remains cancellation.
A new tool that uses a catalog resource registers a dependency and a scoped preflight call (for example Siri (#14892), dictation, HealthKit, widgets and Spotlight lookups).
Audio capabilities (#13626)¶
The capabilityInventory of a device reports whether it can record or play audio, so a scheduler can
keep audio tests off hosts that can never pass them.
| id | supported when |
|---|---|
ios.simulator.audioInput |
the host’s CoreAudio default input has at least one input stream |
ios.simulator.audioOutput |
the host’s CoreAudio default output has at least one output stream |
ios.simulator.audioOutputCapture |
the default output is virtual or a known loopback driver, so its signal can be read back (#13629) |
android.emulator.audioInput |
hw.audioInput=yes, no -no-audio (AUTOMOBILE_EMULATOR_AUDIO=false), and a host input exists |
android.emulator.audioOutput |
hw.audioOutput=yes and no -no-audio |
android.emulator.audioInputInjection |
the supplied emulator gRPC probe result is reachable |
android.emulator.audioOutputCapture |
the supplied emulator gRPC probe result is reachable |
The two Android gRPC entries use source platform and are omitted when no probe result is supplied.
A reachable result makes both available; unreachable makes both unavailable with the probe’s
reason; not_configured makes both unsupported with the supplied reason or a default naming the
missing emulator gRPC port. Blank reasons use a non-empty default. These entries are independent of
the host audio probe, AVD audio settings, and -no-audio; the latter still makes the existing
android.emulator.audioInput and android.emulator.audioOutput entries unsupported.
An unsupported entry carries an actionable reason, for example “No host audio input device;
install a virtual loopback device and make it the default input”. A supported host entry names the
default device and its transport (built-in, virtual, usb, …) in its reason, so “real mic”
and “virtual loopback” can be told apart.
audio_input_unavailable(#13627).src/utils/audio/audioInputDiagnostic.tsderives the diagnostic from a non-available*.audioInputentry, so there is no second detection path. An iOS simulator reads the live cached host probe (not an inventory captured at discovery). An Android emulator uses its inventory, read from its AVD config by name when the device arrives without one (the daemon session path builds a bare device). Physical devices never get it.observeadds it to its own served copy only, so cached observations reused by action tools never carry it; a microphone grant keepssuccessand adds it underdiagnostics.- Probe.
src/utils/audio/coreAudioHal.tsreads the CoreAudio HAL throughbun:ffi(AudioObjectGetPropertyDataon the system object, then the default device’s streams, name and transport). HAL property queries need no GUI session, so the probe runs the same from a LaunchDaemon service user or an SSH session; it never usessystem_profileror ScreenCaptureKit. - Cache. The answer is cached for the daemon’s lifetime and re-probed whenever either default
device id changes (one cheap HAL query each per read);
refreshHostAudio()forces a re-probe. - Not probed. On a host without a probe (Linux; ALSA/PulseAudio/PipeWire is not implemented) iOS
audio entries are left out and Android input follows the AVD config alone, so the inventory never
over-claims. Under
bun testthe default probe reports “not probed”; tests inject a fake HAL. - Evidence. The unit tests run the interpretation over a CoreAudio capture from a MacBook Pro
(
test/fixtures/host-audio/coreaudio-macbook-pro.json) and an Androidconfig.inicapture (test/fixtures/android-avd-audio/config.ini). A host with no input or a loopback default is a fake HAL scenario, not a capture; a LaunchDaemon run with no Aqua session is not yet verified on a device (needs-device-verify).