feat(clients): codec preference on Windows/Apple/Android clients (Phase 2b)

Rounds out codec negotiation across the last three clients — each advertises what it can decode,
builds its decoder from the resolved Welcome.codec, and exposes a "Video codec" preference picker.

**Windows** (Rust, mirrors Linux): `decodable_codecs()` + `ffmpeg_codec_id()`; the D3D11VA and
software FFmpeg decoders (and the mid-session D3D11VA→software demotion) open the negotiated codec
instead of hardcoding HEVC; settings gain a `codec` field + reactor ComboBox; `--codec` CLI flag.

**Apple** (Swift/C-ABI): AnnexB is now codec-aware — a `VideoCodec` enum drives H.264 vs HEVC NAL
parsing / parameter-set extraction (`CMVideoFormatDescriptionCreateFromH264ParameterSets` for H.264,
no VPS) and AVCC repacking; `PunktfunkConnection` advertises H264|HEVC via `punktfunk_connect_ex7`,
reads `resolvedCodec` (`punktfunk_connection_codec`), and threads `videoCodec` into the stage-1/2
pipelines + `VideoDecoder`; SettingsView "Video codec" Picker (auto/HEVC/H.264). AV1 is left out
(hosts don't emit it on the native path, and it's not an AnnexB codec). Test call sites updated.

**Android** (Kotlin + Rust JNI): the JNI `nativeConnect` gains `preferredCodec`; the native decode
loop picks the AMediaCodec MIME (`video/hevc`|`video/avc`) from `connector.codec` and advertises
H264|HEVC; Settings `codec` field + Compose dropdown.

Core/host/probe/Linux clippy + tests green (unchanged from 2a). Windows/Apple/Android compile on
their platform CI (this Linux box can't build them — Windows toolchain / Xcode / the Android NDK's
opus-cmake toolchain). All follow the Linux client's validated pattern.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -28,10 +28,20 @@ struct ContentView: View {
     @AppStorage(DefaultsKey.gamepadType) private var gamepadType = 0
     @AppStorage(DefaultsKey.bitrateKbps) private var bitrateKbps = 0
     @AppStorage(DefaultsKey.audioChannels) private var audioChannels = 2
+    @AppStorage(DefaultsKey.codec) private var codec = "auto"
     @AppStorage(DefaultsKey.hdrEnabled) private var hdrEnabled = true
     @AppStorage(DefaultsKey.fullscreenWhileStreaming) private var fullscreenWhileStreaming = true
     @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
     @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
+    /// The `codec` setting as a `PUNKTFUNK_CODEC_*` soft-preference byte (`0` = auto).
+    private var preferredCodecByte: UInt8 {
+        switch codec {
+        case "h264": return PunktfunkConnection.codecH264
+        case "hevc": return PunktfunkConnection.codecHEVC
+        case "av1": return PunktfunkConnection.codecAV1
+        default: return 0
+        }
+    }
     @State private var showAddHost = false
     @State private var pairingTarget: StoredHost?
     /// A fresh `pair=required`/unknown host the user tapped: drives the choice between no-PIN
@@ -378,6 +388,7 @@ struct ContentView: View {
             bitrateKbps: UInt32(clamping: bitrateKbps),
             audioChannels: UInt8(clamping: audioChannels),
             hdrEnabled: hdrEnabled,
+            preferredCodec: preferredCodecByte,
             launchID: launchID,
             allowTofu: allowTofu,
             requestAccess: requestAccess)
@@ -521,6 +532,7 @@ struct ContentView: View {
             bitrateKbps: bitrate,
             audioChannels: UInt8(clamping: audioChannels),
             hdrEnabled: hdrEnabled,
+            preferredCodec: preferredCodecByte,
             autoTrust: true)
     }
 }

clients/apple/Sources/PunktfunkClient/SessionModel.swift

@@ -108,6 +108,7 @@ final class SessionModel: ObservableObject {
                  bitrateKbps: UInt32 = 0,
                  audioChannels: UInt8 = 2,
                  hdrEnabled: Bool = true,
+                 preferredCodec: UInt8 = 0,
                  launchID: String? = nil,
                  allowTofu: Bool = false,
                  autoTrust: Bool = false,
@@ -155,12 +156,17 @@ final class SessionModel: ObservableObject {
             if want444, canDecode444 {
                 videoCaps |= PunktfunkConnection.videoCap444
             }
+            // This client's VideoToolbox path decodes H.264 and HEVC (AV1 isn't wired — hosts don't
+            // emit it on the native path yet). The host resolves the emitted codec from these + the
+            // soft `preferredCodec`; `resolvedCodec` reflects what it chose.
+            let videoCodecs = PunktfunkConnection.codecH264 | PunktfunkConnection.codecHEVC
             let result = Result { try PunktfunkConnection(
                 host: host.address, port: host.port,
                 width: width, height: height, refreshHz: hz,
                 pinSHA256: pin, identity: identity, compositor: compositor,
                 gamepad: gamepad, bitrateKbps: bitrateKbps, videoCaps: videoCaps,
-                audioChannels: audioChannels, launchID: launchID,
+                audioChannels: audioChannels,
+                videoCodecs: videoCodecs, preferredCodec: preferredCodec, launchID: launchID,
                 // Delegated approval: the host holds this connect open until the operator approves
                 // it (~180 s) — outwait that window so a slow approval still lands here. Normal
                 // connects keep the snappy default.

clients/apple/Sources/PunktfunkClient/SettingsView.swift

@@ -30,6 +30,7 @@ struct SettingsView: View {
     @AppStorage(DefaultsKey.fullscreenWhileStreaming) private var fullscreenWhileStreaming = true
     @AppStorage(DefaultsKey.micEnabled) private var micEnabled = true
     @AppStorage(DefaultsKey.audioChannels) private var audioChannels = 2
+    @AppStorage(DefaultsKey.codec) private var codec = "auto"
     @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
     @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
     @ObservedObject private var gamepads = GamepadManager.shared
@@ -671,16 +672,22 @@ struct SettingsView: View {
 
     @ViewBuilder private var hdrSection: some View {
         Section {
+            Picker("Video codec", selection: $codec) {
+                Text("Automatic").tag("auto")
+                Text("HEVC (H.265)").tag("hevc")
+                Text("H.264 (AVC)").tag("h264")
+            }
             Toggle("10-bit HDR", isOn: $hdrEnabled)
             Toggle("Full chroma (4:4:4)", isOn: $enable444)
         } header: {
             Text("Video quality")
         } footer: {
-            Text("HDR requests a 10-bit BT.2020 PQ (HDR10) stream — it only engages when the host is "
-                + "sending HDR content AND this display supports HDR. 4:4:4 requests full chroma "
-                + "(sharper text/UI, more bandwidth) — it only engages when this device can "
-                + "hardware-decode it AND the host opted in. Otherwise the stream stays 8-bit "
-                + "4:2:0 SDR. Applies from the next session.")
+            Text("Codec is a preference — the host falls back if it can't encode the one you pick "
+                + "(and 10-bit/4:4:4 are HEVC-only). HDR requests a 10-bit BT.2020 PQ (HDR10) stream — "
+                + "it only engages when the host is sending HDR content AND this display supports HDR. "
+                + "4:4:4 requests full chroma (sharper text/UI, more bandwidth) — it only engages when "
+                + "this device can hardware-decode it AND the host opted in. Otherwise the stream stays "
+                + "8-bit 4:2:0 SDR. Applies from the next session.")
                 .font(.geist(12, relativeTo: .caption))
                 .foregroundStyle(.secondary)
         }

clients/apple/Sources/PunktfunkKit/AnnexB.swift

@@ -10,6 +10,20 @@
 import CoreMedia
 import Foundation
 
+/// The video codec of the host's elementary stream — negotiated in the Welcome and read via
+/// `punktfunk_connection_codec`. Both are Annex-B with in-band parameter sets on every IDR; they
+/// differ only in NAL-header layout and which parameter sets exist (HEVC adds a VPS). AV1 is not an
+/// Annex-B/NAL codec and isn't handled here (hosts don't emit it on the native path yet).
+public enum VideoCodec: Equatable {
+    case h264
+    case hevc
+
+    /// Resolve from the wire `Welcome.codec` byte (`PUNKTFUNK_CODEC_*`; unknown → HEVC).
+    public init(wire: UInt8) {
+        self = wire == 0x01 ? .h264 : .hevc // 0x01 = PUNKTFUNK_CODEC_H264
+    }
+}
+
 public enum AnnexB {
     /// Split an Annex-B stream into NAL units (start codes 00 00 01 / 00 00 00 01 stripped).
     /// All zeros immediately preceding a start code are dropped: they're either the
@@ -47,40 +61,83 @@ public enum AnnexB {
         return (first >> 1) & 0x3F
     }
 
-    /// Build a format description from an IDR AU's in-band VPS(32)/SPS(33)/PPS(34).
-    /// Returns nil when the AU carries no parameter sets (non-IDR).
-    public static func formatDescription(fromIDR au: Data) -> CMVideoFormatDescription? {
+    /// H.264 NAL unit type (bits 0..4 of the first byte).
+    public static func h264NalType(_ nal: Data) -> UInt8 {
+        guard let first = nal.first else { return 0xFF }
+        return first & 0x1F
+    }
+
+    /// True if this NAL is a parameter set for `codec` (dropped from AVCC; kept for the format desc).
+    /// HEVC: VPS 32 / SPS 33 / PPS 34. H.264: SPS 7 / PPS 8 (no VPS).
+    private static func isParameterSet(_ nal: Data, _ codec: VideoCodec) -> Bool {
+        switch codec {
+        case .hevc: let t = hevcNalType(nal); return t == 32 || t == 33 || t == 34
+        case .h264: let t = h264NalType(nal); return t == 7 || t == 8
+        }
+    }
+
+    /// Build a format description from an IDR AU's in-band parameter sets (HEVC: VPS/SPS/PPS;
+    /// H.264: SPS/PPS). Returns nil when the AU carries no parameter sets (non-IDR).
+    public static func formatDescription(fromIDR au: Data, codec: VideoCodec)
+        -> CMVideoFormatDescription?
+    {
+        // Collect the parameter-set NALs in the order VideoToolbox wants them (HEVC: VPS,SPS,PPS;
+        // H.264: SPS,PPS).
         var vps: Data?, sps: Data?, pps: Data?
         for nal in nalUnits(in: au) {
-            switch hevcNalType(nal) {
-            case 32: vps = nal
-            case 33: sps = nal
-            case 34: pps = nal
-            default: break
+            switch codec {
+            case .hevc:
+                switch hevcNalType(nal) {
+                case 32: vps = nal
+                case 33: sps = nal
+                case 34: pps = nal
+                default: break
+                }
+            case .h264:
+                switch h264NalType(nal) {
+                case 7: sps = nal
+                case 8: pps = nal
+                default: break
+                }
             }
         }
-        guard let vps, let sps, let pps else { return nil }
+        guard let sps, let pps else { return nil }
+        let sets: [Data] = codec == .hevc ? [vps, sps, pps].compactMap { $0 } : [sps, pps]
+        guard codec == .h264 || sets.count == 3 else { return nil } // HEVC needs the VPS too
 
         var format: CMVideoFormatDescription?
-        let sets = [vps, sps, pps]
-        let status: OSStatus = sets[0].withUnsafeBytes { v in
-            sets[1].withUnsafeBytes { s in
-                sets[2].withUnsafeBytes { p in
-                    let pointers: [UnsafePointer<UInt8>] = [
-                        v.bindMemory(to: UInt8.self).baseAddress!,
-                        s.bindMemory(to: UInt8.self).baseAddress!,
-                        p.bindMemory(to: UInt8.self).baseAddress!,
-                    ]
-                    let sizes = [vps.count, sps.count, pps.count]
-                    return CMVideoFormatDescriptionCreateFromHEVCParameterSets(
-                        allocator: kCFAllocatorDefault,
-                        parameterSetCount: 3,
-                        parameterSetPointers: pointers,
-                        parameterSetSizes: sizes,
-                        nalUnitHeaderLength: 4,
-                        extensions: nil,
-                        formatDescriptionOut: &format)
-                }
+        // Pin every parameter set's bytes for the duration of the create call, then hand
+        // VideoToolbox parallel pointer/size arrays.
+        var pointers: [UnsafePointer<UInt8>] = []
+        var sizes: [Int] = []
+        func withAll(_ i: Int, _ body: () -> Void) {
+            if i == sets.count { body(); return }
+            sets[i].withUnsafeBytes { raw in
+                pointers.append(raw.bindMemory(to: UInt8.self).baseAddress!)
+                sizes.append(sets[i].count)
+                withAll(i + 1, body)
+            }
+        }
+        var status: OSStatus = -1
+        withAll(0) {
+            switch codec {
+            case .hevc:
+                status = CMVideoFormatDescriptionCreateFromHEVCParameterSets(
+                    allocator: kCFAllocatorDefault,
+                    parameterSetCount: pointers.count,
+                    parameterSetPointers: pointers,
+                    parameterSetSizes: sizes,
+                    nalUnitHeaderLength: 4,
+                    extensions: nil,
+                    formatDescriptionOut: &format)
+            case .h264:
+                status = CMVideoFormatDescriptionCreateFromH264ParameterSets(
+                    allocator: kCFAllocatorDefault,
+                    parameterSetCount: pointers.count,
+                    parameterSetPointers: pointers,
+                    parameterSetSizes: sizes,
+                    nalUnitHeaderLength: 4,
+                    formatDescriptionOut: &format)
             }
         }
         return status == noErr ? format : nil
@@ -88,11 +145,10 @@ public enum AnnexB {
 
     /// Re-pack an Annex-B AU as AVCC (4-byte big-endian length before each NAL), dropping
     /// the parameter-set NALs (they live in the format description).
-    public static func avcc(from au: Data) -> Data {
+    public static func avcc(from au: Data, codec: VideoCodec) -> Data {
         var out = Data(capacity: au.count + 16)
         for nal in nalUnits(in: au) {
-            let t = hevcNalType(nal)
-            if t == 32 || t == 33 || t == 34 { continue } // VPS/SPS/PPS
+            if isParameterSet(nal, codec) { continue }
             var len = UInt32(nal.count).bigEndian
             withUnsafeBytes(of: &len) { out.append(contentsOf: $0) }
             out.append(nal)
@@ -102,9 +158,9 @@ public enum AnnexB {
 
     /// Wrap one AU as a decode-ready CMSampleBuffer.
     public static func sampleBuffer(
-        au: AccessUnit, format: CMVideoFormatDescription
+        au: AccessUnit, format: CMVideoFormatDescription, codec: VideoCodec
     ) -> CMSampleBuffer? {
-        let avccData = avcc(from: au.data)
+        let avccData = avcc(from: au.data, codec: codec)
         var blockBuffer: CMBlockBuffer?
         guard CMBlockBufferCreateWithMemoryBlock(
             allocator: kCFAllocatorDefault, memoryBlock: nil,

clients/apple/Sources/PunktfunkKit/DefaultsKeys.swift

@@ -18,6 +18,9 @@ public enum DefaultsKey {
     /// Requested audio channel count: 2 (stereo), 6 (5.1) or 8 (7.1). The host clamps to what it
     /// can capture; the resolved count drives the in-core decode + AVAudioEngine layout.
     public static let audioChannels = "punktfunk.audioChannels"
+    /// Preferred video codec: `"auto"` (host decides), `"hevc"`, or `"h264"`. A soft preference —
+    /// the host emits it when it can, else falls back. Drives the decoder via `Welcome.codec`.
+    public static let codec = "punktfunk.codec"
     public static let micEnabled = "punktfunk.micEnabled"
     public static let speakerUID = "punktfunk.speakerUID"
     public static let micUID = "punktfunk.micUID"

clients/apple/Sources/PunktfunkKit/PunktfunkConnection.swift

@@ -255,6 +255,13 @@ public final class PunktfunkConnection {
     /// PCM from `nextAudioPcm` is interleaved in the canonical wire order FL FR FC LFE RL RR SL SR.
     public private(set) var resolvedAudioChannels: UInt8 = 2
 
+    /// The video codec the host resolved for this session (`Welcome.codec`, `PUNKTFUNK_CODEC_*`):
+    /// `2` = HEVC (default / older host), `1` = H.264, `4` = AV1. Build the decoder from THIS. The
+    /// resolved value honors the client's `preferredCodec` when the host could emit it.
+    public private(set) var resolvedCodec: UInt8 = 2 // PUNKTFUNK_CODEC_HEVC
+    /// The resolved codec as an `AnnexB.VideoCodec` (H.264 vs HEVC) — drives the NAL parsing.
+    public var videoCodec: VideoCodec { VideoCodec(wire: resolvedCodec) }
+
     /// Connect and start a session at the requested mode (the host creates a native virtual
     /// output at exactly this size/refresh). Blocks up to `timeoutMs`.
     ///
@@ -285,6 +292,8 @@ public final class PunktfunkConnection {
         bitrateKbps: UInt32 = 0,
         videoCaps: UInt8 = 0,
         audioChannels: UInt8 = 2,
+        videoCodecs: UInt8 = 0x02, // PUNKTFUNK_CODEC_HEVC — the codecs this client can decode
+        preferredCodec: UInt8 = 0, // 0 = auto; else PUNKTFUNK_CODEC_* soft preference
         launchID: String? = nil,
         timeoutMs: UInt32 = 10_000
     ) throws {
@@ -300,16 +309,18 @@ public final class PunktfunkConnection {
                     withOptionalCString(launchID) { launch in
                         if let pin = pinSHA256 {
                             return pin.withUnsafeBytes { p in
-                                punktfunk_connect_ex6(
+                                punktfunk_connect_ex7(
                                     cs, port, width, height, refreshHz, compositor.rawValue,
-                                    gamepad.rawValue, bitrateKbps, videoCaps, audioChannels, launch,
+                                    gamepad.rawValue, bitrateKbps, videoCaps, audioChannels,
+                                    videoCodecs, preferredCodec, launch,
                                     p.bindMemory(to: UInt8.self).baseAddress, &observed,
                                     cert, key, timeoutMs)
                             }
                         }
-                        return punktfunk_connect_ex6(
+                        return punktfunk_connect_ex7(
                             cs, port, width, height, refreshHz, compositor.rawValue,
-                            gamepad.rawValue, bitrateKbps, videoCaps, audioChannels, launch,
+                            gamepad.rawValue, bitrateKbps, videoCaps, audioChannels,
+                            videoCodecs, preferredCodec, launch,
                             nil, &observed, cert, key, timeoutMs)
                     }
                 }
@@ -347,6 +358,9 @@ public final class PunktfunkConnection {
         var ac: UInt8 = 2
         _ = punktfunk_connection_audio_channels(handle, &ac)
         resolvedAudioChannels = ac
+        var codec: UInt8 = 2 // PUNKTFUNK_CODEC_HEVC
+        _ = punktfunk_connection_codec(handle, &codec)
+        resolvedCodec = codec
     }
 
     /// A bandwidth speed-test measurement (see `startSpeedTest`). Partial until `done`.
@@ -620,6 +634,11 @@ public final class PunktfunkConnection {
     /// the host then emits 4:4:4 only if it too opted in. `chromaFormat` reflects the real value.
     public static let videoCap444: UInt8 = UInt8(PUNKTFUNK_VIDEO_CAP_444)
 
+    /// Codec bits for `videoCodecs` / `preferredCodec` and the value `resolvedCodec` returns.
+    public static let codecH264: UInt8 = UInt8(PUNKTFUNK_CODEC_H264)
+    public static let codecHEVC: UInt8 = UInt8(PUNKTFUNK_CODEC_HEVC)
+    public static let codecAV1: UInt8 = UInt8(PUNKTFUNK_CODEC_AV1)
+
     /// Static HDR mastering metadata (SMPTE ST.2086 + content light level) the host sent for an HDR
     /// session. Mirrors the wire/ABI `PunktfunkHdrMeta`; primaries are in ST.2086 **G, B, R** order,
     /// 1/50000 units; mastering luminance in 0.0001 cd/m²; MaxCLL/MaxFALL in nits.

clients/apple/Sources/PunktfunkKit/Stage2Pipeline.swift

@@ -119,6 +119,7 @@ public final class Stage2Pipeline {
         // chroma subsampling drives only the decode pixel format (orthogonal to HDR/depth); the HDR
         // config is the Welcome's latched value, which a mid-session flip then overrides per-frame.
         decoder.setChroma444(connection.isChroma444)
+        decoder.setCodec(connection.videoCodec)
         presenter.configure(hdr: connection.isHDR)
 
         let token = token
@@ -159,7 +160,7 @@ public final class Stage2Pipeline {
                     }
                     guard let au = try connection.nextAU(timeoutMs: 100) else { continue }
                     onFrame?(au)
-                    if let f = AnnexB.formatDescription(fromIDR: au.data) {
+                    if let f = AnnexB.formatDescription(fromIDR: au.data, codec: connection.videoCodec) {
                         format = f          // refreshed on every IDR (mode changes included)
                         awaitingIDR = false // a fresh IDR re-anchored decode — recovery complete
                     }

clients/apple/Sources/PunktfunkKit/StreamPump.swift

@@ -95,7 +95,7 @@ final class StreamPump {
 
                     guard let au = try connection.nextAU(timeoutMs: 100) else { continue }
                     onFrame?(au)
-                    let idrFormat = AnnexB.formatDescription(fromIDR: au.data)
+                    let idrFormat = AnnexB.formatDescription(fromIDR: au.data, codec: connection.videoCodec)
                     if let f = idrFormat {
                         format = f          // refreshed on every IDR (mode changes included)
                         if awaitingIDR {
@@ -119,7 +119,7 @@ final class StreamPump {
                     }
                     wasFailed = failed
                     guard let f = format,
-                          let sample = AnnexB.sampleBuffer(au: au, format: f),
+                          let sample = AnnexB.sampleBuffer(au: au, format: f, codec: connection.videoCodec),
                           token.isLive // don't enqueue a stale frame after a restart
                     else { continue }
                     layer.enqueue(sample)

clients/apple/Sources/PunktfunkKit/VideoDecoder.swift

@@ -54,6 +54,10 @@ public final class VideoDecoder: @unchecked Sendable {
     /// depth / HDR). Read inside `createSessionLocked` under `lock`.
     private var chroma444 = false
 
+    /// The negotiated codec (`connection.videoCodec`), set once at session start. Drives the AnnexB
+    /// NAL parsing (H.264 vs HEVC parameter sets). Read under `lock`.
+    private var codec: VideoCodec = .hevc
+
     public init(
         onDecoded: @escaping @Sendable (ReadyFrame) -> Void,
         onDecodeError: @escaping @Sendable (OSStatus) -> Void = { _ in }
@@ -73,6 +77,14 @@ public final class VideoDecoder: @unchecked Sendable {
         lock.unlock()
     }
 
+    /// Select the negotiated codec (H.264 vs HEVC). Call once at session start, before decoding,
+    /// from `connection.videoCodec`. Thread-safe.
+    public func setCodec(_ c: VideoCodec) {
+        lock.lock()
+        codec = c
+        lock.unlock()
+    }
+
     /// Submit one AU for asynchronous decode, (re)creating the session if `format` changed. The
     /// caller resolves `format` from the IDR exactly as stage-1 does (`AnnexB.formatDescription`).
     /// Returns false if the session couldn't be created or the frame couldn't be submitted.
@@ -93,7 +105,7 @@ public final class VideoDecoder: @unchecked Sendable {
         // invalidate the session between here and DecodeFrame. The VT output callback takes the
         // ring lock, not this one, so there's no re-entrancy. DecodeFrame is async — non-blocking.
         guard let session,
-              let sample = AnnexB.sampleBuffer(au: au, format: newFormat)
+              let sample = AnnexB.sampleBuffer(au: au, format: newFormat, codec: codec)
         else { lock.unlock(); return false }
         var infoOut = VTDecodeInfoFlags()
         let status = VTDecompressionSessionDecodeFrame(