open-standards/wai/wai-sink-swift

wai-sink-swift — the native sink for the platform player, in Swift

The native sink of extensions/native-sink.md for phones and tablets, televisions and set-top boxes, and desktops whose native player an application reaches from Swift. The player is not changed and decodes on the platform's media engine; the sink sits on the path of its requests and, for one playback session:

• verifies a media playlist against its playlist receipt and the chain of its live revisions (http-delivery §8.6), and every object whose name states its content hash against that hash, and withholds from the player whatever does not verify;
• signs, under a fresh key per session, stream-audit's acknowledgements of every object received, a presentation claim for each marked ad, and the session record, and posts the bundle to the owner's collector (wai-audit serve), with its Event-mode CMCD while it plays;
• ends a session nobody can see, or whose viewer has gone idle, and stops the player's requests.

Everything that decides is libwai's C interface (native-sink §9), the same on every native platform; this package is the platform's half: the loopback relay, the player, and the signals of who can see it.

Layout

path	what
Package.swift	the package: library WaiSink, binary target WaiFFI (the C interface): a release's framework by URL and checksum, or the one built here
Sources/WaiSink/Sink.swift	WaiSink: one session, every call of the C interface, JSON in and out
Sources/WaiSink/Relay.swift	WaiRelay: the loopback server the player is given (native-sink §4.4)
Sources/WaiSink/PlayerSession.swift	WaiPlayerSession: the platform player through the relay, observed every 200 ms (§5, §6)
Sources/WaiSink/Attention.swift	WaiViewAttention: whether the application is shown, the player view's area in view, the viewer's input (§6.2); WaiFixedAttention for hosts that decide it themselves
Sources/WaiSink/Collector.swift	WaiCollector: v1/sessions and v1/cmcd (stream-audit §12)
scripts/build-xcframework.sh	builds build/WaiFFI.xcframework from ../wai-rs
scripts/package-release.sh	the framework zipped, and the copy of the package that names the zip by URL and checksum, for a release
scripts/check-release-package.sh	that copy resolved, built and run as an application uses it, and refused with a wrong checksum
scripts/test-simulator.sh	runs the tests hosted in TestHost/ in a fresh simulator it creates, boots and deletes, every step under a hard limit
Tests/WaiSinkTests	the corpus through the wrapper; the relay over the reference package's floor; the player end to end
TestHost/	a minimal application the same tests run inside on a phone or tablet, where no tool-hosted test bundle runs: an Xcode project that depends on this package by its path; consumers never see it

Use

import WaiSink

let cfg = WaiSink.Config(channel: "news-east", owner: "<the collector's key, 64 hex>")
let session = try WaiPlayerSession(url: URL(string: "https://media.example/ch/7/v.m3u8")!,
                                   config: cfg,
                                   attention: WaiViewAttention(view: playerView),
                                   collector: WaiCollector(base: URL(string: "https://collector.example/")!))
playerLayer.player = session.player     // the host shows the player as it always has
session.onEnd = { bundle, ended in /* posted already; kept here if the host wants it */ }
session.start()

For a stream the owner's packager seals (playlist receipts, segments named by their SHA-256, packaging §7), set requireSigned: true (or contentAddressed: true), and nothing the publisher did not sign reaches the decoder. For a stream another service delivers, leave both off: it is acknowledged and evidenced, never refused for what its names look like.

Build and test

On the build host (Xcode with the phone, television and desktop SDKs; Rust with the targets scripts/build-xcframework.sh names):

cd wai/wai-sink-swift
scripts/build-xcframework.sh                 # every slice; WAI_SINK_SLICES="macos ios-sim" for some
swift test                                   # the desktop: corpus, relay, player end to end
scripts/test-simulator.sh ios                # the same tests, hosted in TestHost, in a fresh phone simulator
scripts/test-simulator.sh tvos               # and in a fresh television simulator

On a phone or tablet, the tests run hosted in TestHost/ (signed with the team configured in Xcode):

xcodebuild build-for-testing -project TestHost/WaiSinkTestHost.xcodeproj -scheme WaiSinkTestHost \
  -destination 'generic/platform=iOS' -allowProvisioningUpdates DEVELOPMENT_TEAM=<team>
xcodebuild test-without-building -xctestrun <the .xctestrun it wrote> -destination 'platform=iOS,id=<device>'

The player tests make their presentation at run time with the platform's own encoder (AVC, ISO/IEC 14496-10, in fragmented MP4, a segment a second), serve it from an origin on loopback, and play it through the relay with a video output attached, since no layer is on screen in a test.

Distribution

A release attaches WaiFFI-<version>.xcframework.zip, the framework with every slice, and wai-sink-swift-<version>.zip, this package with its Package.swift naming that zip by its download URL and its SwiftPM checksum (.binaryTarget(name: "WaiFFI", url: …, checksum: …), the archive's SHA-256, as swift package compute-checksum gives it). scripts/package-release.sh writes both. An application adds the package from that folder, as a local package or a copy in a repository of its own; SwiftPM fetches the framework from the URL and refuses it unless its checksum is the one named.

Before the release attaches them, scripts/check-release-package.sh resolves, builds and runs an application that depends on the package, the framework served from the release's own files through a mirror of its URL, and requires the package with one digit of its checksum changed to be refused; once they are attached, it does both again from the URL itself. In this repository, Package.swift names build/WaiFFI.xcframework while scripts/build-xcframework.sh has built it there, so the tests run against the libwai of their checkout.

The library holds no codec: the platform's player decodes, and its codecs are the platform's, licensed with it.

Energy

The platform's player decodes in a process of the platform's, on its fixed-function decoder, which no counter an application can read covers. The session therefore states the sink decode and the display as the unmetered marker (native-sink §7), never the application's own counter as either.