# LuminaCast Windows sender

This directory contains the portable LuminaLink v1 protocol implementation,
the Windows networking and capture pipeline, a controller, and an operable
native Win32 desktop shell. The Windows baseline is Windows 10 version 1809 or
newer, x64.

Two product shells share the same native sender core:

- `LuminaCast.exe` is the dependency-free Direct2D/DirectWrite Legacy shell. It
  provides the branded five-page navigation and remains the portable fallback.
- `modern/` contains the Windows 10/11 WinUI 3 client. It calls the exported
  `sender_api.dll` C ABI and is distributed as a self-contained package.

The shared C API is declared in `include/luminalink/sender_api.h`; protocol,
networking, capture, and encoding remain native C++ and are not duplicated.

## Build

Portable protocol and golden-vector tests (macOS, Linux, or Windows):

```sh
cmake -S apps/luminalink/sender-windows \
  -B build/luminalink-sender-windows \
  -DBUILD_TESTING=ON
cmake --build build/luminalink-sender-windows
ctest --test-dir build/luminalink-sender-windows --output-on-failure
```

Windows x64, from a Visual Studio developer shell:

```powershell
cmake -S apps/luminalink/sender-windows `
  -B build/luminalink-sender-windows -A x64 -DBUILD_TESTING=ON
cmake --build build/luminalink-sender-windows --config Release
ctest --test-dir build/luminalink-sender-windows -C Release --output-on-failure
```

`luminalink_protocol` and its tests are generated on every platform.
`luminalink_sender_controller` and its fake-session tests are also portable.
`luminalink_windows` and the `LuminaCast.exe` GUI are generated only when
CMake's `WIN32` condition is true, and configuration rejects 32-bit Windows
builds. Visual Studio 2022 with the Desktop development with C++ workload and a
Windows 10/11 SDK is required. MSVC builds use the static C/C++ runtime so the
portable zip does not require a separately installed Visual C++ redistributable.

## Run

Start the compatible receiver first, then run:

```powershell
.\build\luminalink-sender-windows\Release\LuminaCast.exe
```

The application scans the LAN at startup. Select a discovered receiver, or type
an IPv4/IPv6/DNS name in **Manual IP / DNS** (manual input takes precedence),
select a display, and use the single action button to start or stop. Discovery
uses UDP port 48200. Sessions use TLS on TCP 48211 whenever the receiver's
certificate fingerprint is known, and fall back to plaintext TCP 48210 only for
receivers without TLS (old firmware); see **Connection security** below.

Allow LuminaCast on **Private networks** when Windows Firewall prompts. If
discovery is blocked by a corporate/VPN firewall, use the manual address.
Outbound TCP 48210-48212 and UDP broadcast 48200 must be permitted. Desktop
Duplication can fail on secure desktops, at the sign-in screen, in some Remote
Desktop sessions, or for protected video.

## Packaging

Build Release x64 first. To produce an unsigned test MSIX:

```powershell
.\scripts\package-msix.ps1 `
  -BuildDirectory .\build\luminalink-sender-windows
```

The manifest publisher defaults to `CN=LuminaCast.Test`. For a signed package,
the `-Publisher` value must exactly match the signing certificate subject:

```powershell
$password = Read-Host "PFX password" -AsSecureString
.\scripts\package-msix.ps1 `
  -BuildDirectory .\build\luminalink-sender-windows `
  -Publisher "CN=Your Publisher" `
  -CertificatePath .\YourCertificate.pfx `
  -CertificatePassword $password
```

No certificate password is stored in the repository. The script locates
`MakeAppx.exe`/`SignTool.exe` from the installed Windows SDK and generates
placeholder PNG package logos from the concept artwork. Install an unsigned
package only after trusting a matching test certificate. Create a portable zip
with:

```powershell
.\scripts\package-zip.ps1 `
  -BuildDirectory .\build\luminalink-sender-windows
```

The zip has no installer; extract it and run the executable. Both package
outputs are written under `dist` by default.

Build the WinUI 3 self-contained package (requires the .NET 8 SDK) with:

```powershell
.\scripts\package-modern.ps1 `
  -BuildDirectory .\build
```

The Modern archive includes `sender_api.dll`. Both portable packages include
`configure-firewall.ps1`; run it elevated only when automatic discovery is
blocked on a Private network.

## Connection security

Matches the phone senders (`docs/62` §6); the receiver and the protocol are
unchanged.

- **Discovery** sends `DISCOVER` with the name field set to `LMX-EXT1`. New
  receivers answer with an extended `OFFER` carrying a TLV (tag 1) with the
  certificate fingerprint; old receivers ignore the marker and answer the legacy
  format. An `OFFER` whose session port is 0 means the receiver's casting service
  is not running (shell not in the foreground); the controller reports that
  instead of connecting.
- **Fingerprint** = SHA-256 of the whole certificate (DER), base64url without
  padding (`fingerprint.h`, portable, unit-tested). Identical to the receiver's
  `LinkTlsIdentity.certFingerprint` and the Android `LinkTlsClient`.
- **Trust** (`receiver_trust.h`, portable, unit-tested): a fingerprint from
  discovery updates the pin for that host; otherwise the remembered pin is used;
  otherwise the sender performs a trust-on-first-use handshake against the
  always-on control port 48212, records the fingerprint, and from then on pins it.
  Pins live in `%LOCALAPPDATA%\LuminaCast\known_receivers.tsv`
  (`known_receivers.h`). Without any fingerprint (control port unreachable, old
  firmware) the session falls back to plaintext 48210 and only mirroring works.
- **TLS** (`stream_transport.h`, Windows): Schannel client, TLS 1.2, system
  chain validation disabled (the receiver is self-signed), manual fingerprint
  pinning after the handshake; a mismatch raises `FingerprintMismatchError`
  and the connection is dropped. `LinkClient` talks to a `StreamTransport`
  and does not know whether the stream is encrypted; the status line shows
  the outcome, e.g. `Casting to X (TLS, certificate pinned)`.
- Not yet implemented: mDNS browsing (`_luminalink._tcp` TXT `fp`),
  `luminalink://` scan links, and the control session itself (remote control,
  content casting, annotation); TLS is the prerequisite for all of them.

## Controller and failure behavior

`SenderController` owns the Idle, Scanning, Ready, Connecting, Casting, and
Error state machine. Its backend/session interfaces are fakeable in portable
tests. The Windows session composes `DiscoveryClient`, `LinkClient`,
`WinVideoCapture`, and `WinAudioCapture`. Receiver key-frame requests call
`WinVideoCapture::ForceKeyframe`. Any transport disconnect first stops and
releases both capture pipelines, then reports Error; explicit stop also closes
the link and returns to Ready.

## Architecture

- `protocol.h/.cpp` owns all wire constants, network-byte-order codecs,
  per-message payload limits, discovery and HELLO payloads, and the incremental
  `FrameDecoder` used for partial TCP reads.
- `DiscoveryClient` broadcasts a nonce-bearing `DISCOVER`, validates matching
  `OFFER` packets, deduplicates receivers, and also creates manual DNS/IP
  targets.
- `StreamTransport` (`stream_transport_win.cpp`) is the byte stream under
  `LinkClient`: plaintext Winsock TCP or Schannel TLS with fingerprint pinning,
  same interface, connect timeout, `Shutdown()` callable from any thread.
- `LinkClient` owns the session over a `StreamTransport`. It performs
  `HELLO/HELLO_ACK` and `START/START_ACK`, then runs reader, writer, and
  heartbeat threads. It sends `PING` every two seconds, requires inbound
  traffic within ten seconds, answers `PING`, and handles key-frame requests,
  `STOP`, and `ERROR`.
- `CaptureSink`, `AvcConfig`, `AacConfig`, and `EncodedPacket` are the boundary
  between capture/encoding and transport.
- `QpcClock` is the shared audio/video monotonic timestamp source. Video reads
  QPC directly; WASAPI packet QPC positions are converted from 100-nanosecond
  units into the same microsecond domain.
- `WinVideoCapture` enumerates attached DXGI outputs by enumeration index,
  remembers the selected DXGI device name across recovery, creates a D3D11
  device on that output's adapter, and captures changed frames with Desktop
  Duplication. `DXGI_ERROR_ACCESS_LOST` rebuilds the device, duplication
  session, and encoder. An acquire timeout emits no frame, so a static desktop
  is not repeatedly encoded. Capture timestamps use `QueryPerformanceCounter`
  and are expressed in microseconds.
- `VideoEncoderMF` uses the D3D11 video processor to rotate the duplication
  surface to its normal viewing direction, scale it within 1920x1080, and
  convert BGRA to NV12. D3D11-aware hardware MFTs receive the DXGI surface
  directly; the software-MFT fallback copies NV12 through a staging texture
  into a system-memory sample. The normalized stream always advertises
  `rotation=0`. Media Foundation hardware H.264 MFTs are tried first, followed
  by installed synchronous/asynchronous software MFTs if hardware activation
  or configuration fails. Defaults are at most 60 fps, 8 Mbps CBR, progressive
  low-latency encoding, no B-frames, and a one-second GOP. Output is normalized
  to Annex-B and SPS/PPS are sent in `VIDEO_CONFIG` before media once the
  encoder exposes them.
- Display rotation or source-size changes reconfigure the video processor and
  encoder, produce a fresh `VIDEO_CONFIG`, and request an IDR. Wire
  `WinVideoCapture::ForceKeyframe` to
  `LinkClientOptions::on_keyframe_requested` to handle receiver requests.
- `WinAudioCapture` uses event-driven WASAPI shared-mode loopback on the
  current default `eRender`/`eConsole` endpoint. `AudioEncoderMF` converts the
  endpoint mix format through the system Audio Resampler DSP to signed
  48 kHz stereo PCM, then uses the system AAC encoder for AAC-LC at 128 kbps.
  It sends `AUDIO_CONFIG` with AudioSpecificConfig `11 90` and sends raw AAC
  access units in `AUDIO_FRAME` without ADTS.

The outbound queue is bounded to 120 messages and 8 MiB including headers.
When full, stale non-key video is removed first. Codec configurations,
keyframes, and heartbeat control messages may evict other non-priority media;
they are never allowed to make the queue unbounded.

## Video usage

Call `WinVideoCapture::EnumerateDisplays()`, select a returned `index`, then
construct `WinVideoCapture` with a connected `LinkClient` as its `CaptureSink`.
`Start`, `Stop`, and `ForceKeyframe` are thread-safe. Desktop Duplication acquire
and recovery waits are capped at one frame interval so `Stop` can join promptly;
MF, DXGI, D3D11, and COM resources are released on the capture thread.

Desktop Duplication may either include the hardware cursor in the desktop image
or report it independently through pointer metadata. Included cursors pass
through normally. Independent pointer-shape capture and compositing is
**not implemented**: `GetFramePointerShape` is not called, and monochrome,
masked-color, or color pointer shapes are not blended into the frame. In those
driver modes the transmitted video can omit the cursor.

## Audio usage

Construct `WinAudioCapture` with the same connected `CaptureSink` used by
video, then call `Start`; `Start`, `Stop`, and `IsRunning` are thread-safe.
Audio and video have independent workers, so a missing or muted endpoint does
not stop video or disconnect the session.

“Local speakers” means the audio stream being rendered to Windows' current
default **Console** playback endpoint (the endpoint returned by
`GetDefaultAudioEndpoint(eRender, eConsole)`). This captures the post-mix
speaker/headphone/Bluetooth system mix, including application/session audio
processing. It does not capture microphones, the separate Communications-role
endpoint, or an application explicitly routed to another playback device.
Endpoint hardware volume/mute placement is driver-dependent and must not be
used as a privacy boundary.

Default-device changes and removal/invalidation of the active endpoint signal
the audio worker to tear down and rebuild WASAPI plus both MF transforms. If
Windows has no render endpoint, the worker stays alive and retries every
500 ms; it sends no synthetic AAC during that period. Muting does not stop the
worker; any packet WASAPI marks with `AUDCLNT_BUFFERFLAGS_SILENT` is encoded
from zero PCM. Packet discontinuities flush queued transform state and mark
the next MF input sample.
All COM and MF objects are created and released on the audio worker thread, and
the stop event interrupts both capture waits and no-device retry waits.

## Current limitations

- Building the Modern shell requires the .NET 8 SDK and Windows App SDK package
  restore. The Legacy shell builds with the existing MSVC/CMake toolchain.
- The Windows 7 GDI capture source produces I420 frames, but still requires a
  Windows 7-compatible H.264 encoder bridge before it can replace the DXGI
  backend in production.
- MSIX assets are generated placeholders. The checked-in SVG is the editable
  concept source; the executable currently uses the standard Windows fallback
  icon rather than embedding a binary `.ico`.
- No per-application audio capture or independent Desktop Duplication
  pointer-shape compositor is included.
- The standalone `ORIENTATION` payload layout is not specified by protocol v1,
  so rotation changes are carried by a new `VIDEO_CONFIG` rather than an
  invented payload format.
- macOS verifies portable protocol/controller tests and cross-compiles the full
  Win32 source with MinGW. Windows CI is configured to compile with MSVC and run
  CTest, but its result is not available from the local run. D3D11/DXGI/WASAPI/MF hardware behavior, rotation on
  portrait displays, endpoint mix-format coverage, firewall prompts, generated
  MSIX installation/signing, and live receiver interoperability still require
  Windows 10/11 x64 machines.
- The Schannel transport is cross-compiled with MinGW on macOS but has not yet
  completed a live TLS handshake against a receiver; verify item 9 below first.
- Only the mirroring session is encrypted and pinned. The control session
  (remote control, content, annotation, reverse control) is not implemented yet.
- Disconnect callbacks must not destroy the `LinkClient` synchronously from
  inside the callback; schedule ownership changes on the caller's event loop.

## Windows real-device checklist

1. Build Release x64 with MSVC and run all CTest tests.
2. Launch with one and multiple attached displays; verify the selected output.
3. Test landscape plus 90/180/270-degree display rotations and hot unplug.
4. Verify hardware H.264 and software-MFT fallback on different GPUs.
5. Play speaker, headphone, Bluetooth, mute, and default-device-switch audio;
   confirm the receiver gets the current Console endpoint mix and no microphone.
6. Start/stop repeatedly, close the receiver mid-cast, unplug networking, and
   confirm audio/video workers release and the UI reaches Error or Ready.
7. Test LAN discovery, manual IPv4/IPv6/DNS, Windows Firewall private/public
   profiles, VPN enabled/disabled, heartbeat timeout, and key-frame requests.
8. Build unsigned and signed MSIX packages, verify certificate publisher match,
   install/uninstall, and test the portable zip on a clean Windows 10 and 11 x64
   machine.
9. TLS: against a current receiver, confirm the status line says `TLS` after
   discovery (fingerprint from `LMX-EXT1`), after a manual IP (fingerprint via
   first-use handshake on 48212, then stored in `known_receivers.tsv`), and that
   a receiver reinstalled with a new certificate is accepted again only after a
   fresh discovery updates the pin. Against old firmware without TLS, confirm the
   plaintext fallback still mirrors.
