iMirror

iMirror is a Windows AirPlay mirroring receiver for local development and real-device validation.

The product path is now centered on native GPU video: AirPlay control and media are handled in-process, H.264 is decoded through Media Foundation with D3D11 surfaces when hardware support is available, and frames are presented through the WPF host. The FFmpeg software decoder remains as a compatibility fallback. AirPlay audio is received over RTP, decrypted, decoded with FFmpeg AAC-ELD support, and played through WASAPI.

Status

• AirPlay discovery, pairing, pair-verify, FairPlay setup, mirror setup, and record handling are implemented.
• Mac and iPhone screen mirroring have been validated on real devices.
• The default video engine is Media Foundation/D3D11 when hardware decode is available.
• FFmpeg remains required for the software video fallback and AAC-ELD audio decode.
• Known limitation: the FFmpeg software-decode fallback exceeds the 150ms latency target (real-device B3: Mac p95 ~228ms, iPhone p95 ~174ms) while staying functional; the GPU path meets the target. Tracked in #32.
• Local diagnostic dumps can contain private screen content or session material and must not be committed.

Repository Layout

The solution contains one SDK-style application project, MacMirrorReceiver.csproj, which compiles the MacMirrorReceiver* source folders into the iMirror assembly. The only other project is MacMirrorReceiver.Tests.

• MacMirrorReceiver/ - WPF application shell, app logging, settings, and main session orchestration.
• MacMirrorReceiver.Networking/ - AirPlay RTSP/RAOP, mDNS, pairing, FairPlay, mirror data, timing, and audio RTP receive paths.
• MacMirrorReceiver.Video/ - H.264 stream gate, FFmpeg fallback decoder, Media Foundation/D3D11 decoder, GPU presenters, and latency windows.
• MacMirrorReceiver.Audio/ - WASAPI PCM output.
• MacMirrorReceiver.Protocol/ - Shared protocol models for mirror/auth/status/config messages.
• ThirdParty/playfair/ - FairPlay reference sources used for validation.
• tools/ - Focused diagnostics and acceptance helpers.
• docs/ - Product architecture and validation notes.

Build

dotnet build .\MacMirrorReceiver.csproj -c Release

The project targets net10.0-windows, x64, and WPF.

Publish

Create a self-contained Windows x64 zip package:

powershell -ExecutionPolicy Bypass -File .\scripts\publish-win-x64.ps1

The package is written under artifacts\. Public release zips bundle FFmpeg Essentials under tools\ffmpeg\bin; see docs/release.md for package smoke-test steps.

Runtime Dependencies

FFmpeg is intentionally not committed. Public release packages bundle a pinned Gyan.FFmpeg.Essentials build, not the larger full_build variant. Confirm the exact FFmpeg license obligations from ffmpeg -version and the matching source package before redistribution.

winget install Gyan.FFmpeg.Essentials

Or place a Windows FFmpeg build manually here:

tools\ffmpeg\bin\ffmpeg.exe

FFmpeg is used by:

• the software video fallback
• AAC-ELD audio decode
• local dump validation

Run

.\bin\Release\net10.0-windows\iMirror.exe

Then open Control Center on the sender, choose Screen Mirroring, and select iMirror.

If Windows Firewall prompts on first launch, allow iMirror.exe for both Private and Public networks. Video uses fixed AirPlay ports, but audio uses dynamic UDP ports negotiated during SETUP; allow the app itself rather than only opening fixed ports. If the prompt was missed or audio is blocked, click Allow in Firewall in iMirror and approve the Windows UAC prompt. This adds an inbound program rule for the currently running iMirror.exe; repeat it after running iMirror from a new extracted folder.

For long-running iPhone validation, keep the iPhone awake and unlocked. iMirror is an AirPlay receiver, not Apple's iPhone Mirroring remote-control feature, so it cannot keep private iPhone content visible after iOS locks the device.

Video Engine Controls

The normal product path chooses Media Foundation/D3D11 automatically when hardware decode is available.

Useful overrides:

$env:IMIRROR_FORCE_SOFTWARE_VIDEO = "1"  # force FFmpeg software video
$env:IMIRROR_RENDER_MODE = "stable"      # request the 1080p compatibility display
$env:IMIRROR_RENDER_MODE = "quality"     # request the native GPU display

Legacy validation override:

$env:IMIRROR_EXPERIMENTAL_QUALITY = "1"  # force the GPU path for local validation

Diagnostics

Logs are written under %LOCALAPPDATA%\iMirror\Logs\iMirror.log.

Private diagnostic capture is opt-in:

$env:IMIRROR_WRITE_DIAGNOSTICS = "1"
$env:IMIRROR_DUMP_H264 = "1"
$env:IMIRROR_DUMP_AUDIO = "1"
$env:IMIRROR_AUDIO_DISCOVERY = "1"  # verbose data-stream logging only

Generated logs, H.264 dumps, audio dumps, and diagnostic snapshots can contain private screen content or key material. They are ignored by git and should stay local.

Validation Tools

Common checks:

dotnet run --project .\tools\LatencyAcceptanceReport\LatencyAcceptanceReport.csproj -c Release -- .\bin\Release\net10.0-windows\iMirror.log 150 10

dotnet run --project .\tools\MediaFoundationH264Probe\MediaFoundationH264Probe.csproj -c Release -- C:\temp\capture.d01.submitted.h264

dotnet run --project .\tools\HighResolutionProbeReport\HighResolutionProbeReport.csproj -c Release -- C:\temp\capture.d01.submitted.h264 600

See docs/validation.md for the recommended release gate.

Documentation

• docs/architecture.md - current product architecture.
• docs/release.md - self-contained Windows zip packaging flow.
• docs/validation.md - validation and acceptance workflow.

License

iMirror is licensed under the GNU General Public License v3 (the verbatim license text is in LICENSE; iMirror's copyright and combined-work statement are in NOTICE). The project is GPLv3 because it combines required GPLv3 components: the ThirdParty/playfair FairPlay sources (read at runtime; mandatory for real-device mirroring) and a bundled GPLv3 FFmpeg build. See THIRD_PARTY_NOTICES.txt for per-component provenance and corresponding-source offers, and docs/specs/open-source-strategy.md for the licensing rationale and distribution strategy.

Contributing

Contributions are welcome under GPLv3 (inbound = outbound). See CONTRIBUTING.md for the workflow, testing requirements, and real-device validation procedure, and CODE_OF_CONDUCT.md for community expectations.