Architecture
Capability matrix (audited 2026-11-18 on the build machine)
| Item | Found | Decision |
|---|---|---|
| Xcode / Swift | Xcode 27.2 (27B52), Swift 6.4.2 | Swift 6 language mode for the pure packages (Core, Storage); Swift 5 mode for the AVFoundation / PDFKit / UI code |
| SDKs | macOS 27.2, iOS 27.2 | Deployment targets macOS 15.0 and iOS 18.0: the newest APIs used (AVAudioFile.close(), onScrollGeometryChange, Observation) exist there, and the only installed simulator runtime (iOS 26.5) can run the app |
| Simulators | iOS 26.5 runtime only | Dedicated devices "SPLecture iPhone" (iPhone 17 Pro) and "SPLecture iPad" (iPad Pro 13" M5) |
| Signing | Developer ID Application + Apple Development identities, team 3YM54G49SN | macOS: Developer ID + notarization; iOS: automatic signing + App Store Connect |
| Notarization | keychain profile MacLustr-Notarize |
used as is by scripts/notarize-macos.sh |
| App Store Connect | API key in ~/.appstoreconnect/private_keys, ids in ~/.config/splecturestudio/asc.env (outside the repo) |
used for provisioning, export, validation, upload |
| Real devices | none attached | Apple Pencil, real iPhone/iPad microphones, lock screen, phone calls: not tested |
Layers
text
App (SwiftUI) ── ProjectSession (live lecture) ── EditorModel ── ExportCoordinator
│ platform adapters: macOS InkCanvasNSView (mouse/tablet) · iOS PencilStageView (PencilKit) · CameraPreview
LectureCapture RecordingClock · MicrophoneSource · SegmentedAudioWriter · RecordingEngine · CameraRecorder · Preflight
LectureRender FrameCompositor · TimelineAudioReader · EditedAudioRenderer · VideoExporter · MediaVerifier
LecturePDF SlideDocument · StrokeRenderer · AnnotatedPDFExporter
LectureTranscription / LectureSync optional services behind protocols
LectureStorage ProjectPackage · EventLogWriter · ProjectRecovery · Library · ZipArchive
LectureCore MediaTime · Stroke · TimelineEvent · TimelineIndex · EditDecisionList · TimeMap · analysis · AutoPauseEngineDependencies point downward only. Core has no framework dependency beyond Foundation and is fully unit-tested.
Key decisions
- One timeline, in recorded time. The timeline advances only while recording. A pause has zero length on the timeline and is
stored as a
pause/resume(gapSeconds)event pair with its exact wall-clock gap. Sessions are appended one after another. - The audio sample clock is the authority.
RecordingClockis re-anchored on every audio buffer (host time of the buffer ↔ timeline position of its first sample), so events cannot drift from audio however long the session. Without audio it runs on the host clock. - State is a function of time.
TimelineIndexanswers "what is on screen at t": page, visible strokes with partial progress, pointer, viewport, camera. The live canvas, the editor preview, the exporter and the annotated PDF all read that one model. - Edits are data. An
EditDecisionList(cuts, suggestions, mutes, fades, gain, chapters, ink adjustments) with a persisted undo/redo history.TimeMapconverts between source and output time. Nothing ever rewrites media. - Preview = export. The editor preview draws with
FrameCompositorand plays audio pulled fromEditedAudioRenderer, the same objects the exporter uses. - Vector ink with our own renderer. Strokes are time-coded points in page-normalized coordinates. PencilKit is the input
device on iPad/iPhone; replay, export and PDF use
StrokeRenderer(Core Graphics), which is identical on every platform. Consequence: PencilKit's live rendering of its ink types differs slightly from the exported look. - No third-party dependency. ZIP (store/deflate, ZIP64), tus upload, loudness metering are implemented in the packages.
Honest limits of the platforms
- iOS/iPadOS: recording continues in the background through the
audiobackground mode; the camera cannot run in the background (its segment is closed and restarted on return). Without audio the app is suspended in the background, so a PDF-only session is paused when the app leaves the foreground. Unrestricted background recording is not promised. - External display: a "presentation" window scene shows a clean stage. On macOS it can be placed on any display; on iPadOS it depends on Stage Manager / external display support of the device. Not tested on hardware.
- Screen / window capture on Mac (ScreenCaptureKit) is not implemented. The canonical video never comes from screen capture.
- Apple Pencil hover, pressure and palm rejection are provided by PencilKit; none of it can be verified in the simulator.