Repository Public
1<div align="center">23<img src="docs/brand/logo.svg" alt="SP Lecture Studio logo" width="560">45<br><br>67<img src="docs/brand/icon.png" alt="SP Lecture Studio icon" width="112" height="112">89# 🎓 SP Lecture Studio1011**Native lecture recording and editing for macOS, iPadOS and iOS. Import a PDF, present and annotate it, record your voice, edit nondestructively, and export an MP4 rebuilt from the PDF, the vector ink and the audio — fully offline, on the device.**1213**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**1415161718192021222324252627282930313233[](https://git.spboucher.ai/sp-lecture-studio/commits)34[](https://git.spboucher.ai/sp-lecture-studio/commits)35[](https://git.spboucher.ai/sp-lecture-studio/insights)36[](https://git.spboucher.ai/sp-lecture-studio)37[](https://git.spboucher.ai/sp-lecture-studio/insights)38[](https://git.spboucher.ai/sp-lecture-studio)39[](https://git.spboucher.ai/sp-lecture-studio/branches)40[](https://git.spboucher.ai/sp-lecture-studio/tags)41[](https://git.spboucher.ai/sp-lecture-studio)424344454647484950515253545556575859</div>6061---6263## Table of contents6465- [Overview](#-overview)66- [Features](#-features)67- [Architecture](#-architecture)68- [Stack](#-stack)69- [Repository layout](#-repository-layout)70- [Quick start](#-quick-start)71- [Configuration](#-configuration)72- [Screens and shortcuts](#-screens-and-shortcuts)73- [Project format (`.slecture`)](#-project-format-slecture)74- [Recording pipeline](#-recording-pipeline)75- [Export pipeline](#-export-pipeline)76- [Security and privacy](#-security-and-privacy)77- [Testing](#-testing)78- [Release](#-release)79- [Gotchas](#-gotchas)80- [Status and known limitations](#-status-and-known-limitations)81- [Documentation](#-documentation)82- [Author](#-author)83- [License](#-license)8485---8687## 🎯 Overview8889**SP Lecture Studio** is built for a university instructor who records PDF-based lectures. The central workflow: import a90PDF; present it; annotate live; capture the microphone and, optionally, the camera; pause or stop automatically when91configured; review a nondestructive edit; export a polished MP4 with synchronized annotations, plus an annotated PDF, captions92and chapters.9394Every device performs the complete workflow without any other device or server. Everything works offline, on the device;95nothing is uploaded unless you explicitly ask.9697| | |98|---|---|99| Platforms | macOS 15+, iPadOS 18+, iOS 18+ (built with Xcode 27.2, Swift 6.4) |100| Bundle IDs | `ai.spboucher.splecturestudio` (macOS), `ai.spboucher.splecturestudio.ios` (iOS / iPadOS) |101| Dependencies | none (Apple frameworks only) |102| Project format | `.slecture` package — see [`docs/PROJECT_FORMAT.md`](docs/PROJECT_FORMAT.md) |103| Status | see [`PROGRESS.md`](PROGRESS.md) (what was actually built and tested, and what was not) |104105The video is **never a screen recording**: every frame is recomputed from the PDF, the time-coded vector ink and the event106log. The same code draws the editor preview and the export.107108One repository holds everything: the shared Swift package `LectureKit`, the macOS app, the iOS / iPadOS app, the tests and109the release scripts. It is a standalone project among the [git.spboucher.ai](https://git.spboucher.ai) applications and has110no backend.111112## ✨ Features113114| Area | What the code does |115|---|---|116| PDF | import (the original file is never touched; an immutable copy is kept), view, navigate, search, zoom and pan, presenter notes per page |117| Ink | time-coded vector strokes in page-normalized coordinates: pen, marker, pencil, line, arrow, rectangle, ellipse; eraser and undo / redo as events; laser pointer |118| Input | PencilKit canvas on iPad and iPhone (Apple Pencil or finger); AppKit canvas on Mac (mouse, trackpad, tablet) |119| Recording | real microphone, page / ink / pointer / viewport events, pause / resume / stop, markers (generic, chapter, retake), pre-roll on resume |120| Reliability | segmented audio (10 / 30 / 60 s segments) with SHA-256, atomic manifest checkpoints, append-only event log, crash recovery, low-disk / thermal / battery warnings, sleep prevention |121| Interruptions | calls and Siri pause the session (never resume by themselves); route changes (headset, Bluetooth) restart on the new route |122| Automatic pause / stop | silence, inactivity, maximum duration, end time, end phrase, retake phrase — all off by default, every decision logged |123| PDF-only mode | with the microphone denied the same pipeline runs without audio |124| Editing | nondestructive timeline: cut, split, ripple delete, trim, mute, undo / redo; long-silence and retake suggestions with before / after audition and approval |125| Audio finishing | fades, equal-power crossfade at joins, loudness normalization to −16 LUFS, cleanup (80 Hz high-pass, gentle expander), gain |126| Video export | deterministic MP4: H.264 or HEVC, 720p / 1080p / 4K, 24 / 30 / 60 fps, automatic or fixed bitrate, recorded zoom replayed, pointer, camera picture-in-picture |127| Other exports | annotated PDF (flattened vector ink, or standard PDF ink annotations), SRT and WebVTT captions, TXT transcript, chapters (JSON and plain list), source assets, project archive (ZIP) |128| Verification | an exported video is reopened, its tracks and duration are checked and its first frame is decoded before it is listed |129| Transcription | provider protocol: on-device speech recognition, or an optional user-configured remote endpoint used only after explicit consent |130| Optional upload | explicit, per file, to a user-configured resumable (tus) endpoint over HTTPS |131| Library | projects with course code, session number, date; archive, trash (restorable), integrity check |132| Presentation | a separate "presentation" window scene shows a clean stage |133| Languages | French (source) and English: 503 strings |134135## 🏗 Architecture136137```mermaid138flowchart TB139 subgraph App["App (SwiftUI) — Apps/LectureStudio"]140 Session["ProjectSession<br/>(live lecture)"]141 Editor["EditorModel<br/>timeline · preview"]142 Export["ExportSheet<br/>export coordinator"]143 Mac["macOS adapter<br/>AppKit ink canvas"]144 Pencil["iOS / iPadOS adapter<br/>PencilKit canvas"]145 end146 subgraph Kit["LectureKit (SwiftPM)"]147 Capture["LectureCapture<br/>RecordingClock · RecordingEngine<br/>SegmentedAudioWriter · CameraRecorder · Preflight"]148 Render["LectureRender<br/>FrameCompositor · EditedAudioRenderer<br/>VideoExporter · MediaVerifier"]149 PDF["LecturePDF<br/>SlideDocument · StrokeRenderer<br/>AnnotatedPDFExporter"]150 Trans["LectureTranscription"]151 Sync["LectureSync"]152 Storage["LectureStorage<br/>ProjectPackage · EventLog<br/>Recovery · Library · ZipArchive"]153 Core["LectureCore<br/>MediaTime · Stroke · TimelineEvent<br/>TimelineIndex · EditDecisionList · TimeMap"]154 end155 Mac --> Session156 Pencil --> Session157 Session --> Capture158 Editor --> Render159 Export --> Render160 Capture --> Storage161 Render --> PDF162 Render --> Storage163 Trans --> Render164 Sync --> Storage165 PDF --> Core166 Storage --> Core167 Capture --> Core168 Storage --> Disk[(".slecture package<br/>manifest · events · edits · media")]169```170171Dependencies point downward only. `LectureCore` depends on Foundation alone and is fully unit-tested.172173```mermaid174sequenceDiagram175 autonumber176 participant U as Instructor177 participant S as ProjectSession178 participant E as RecordingEngine179 participant C as RecordingClock180 participant W as SegmentedAudioWriter181 participant L as EventLogWriter182 participant X as VideoExporter183 U->>S: start recording184 S->>E: start185 loop every audio buffer186 E->>W: buffer, host time187 W-->>E: timeline time of the first sample188 E->>C: anchor(host, timeline)189 end190 U->>S: page change, stroke, pointer, zoom, marker191 S->>E: record(event)192 E->>C: timeline time now193 E->>L: append event (fsync within 1 s)194 W->>W: close segment, SHA-256, manifest checkpoint195 U->>S: stop196 E->>L: sessionEnd, manifest, waveform cache197 U->>X: export198 X->>X: TimeMap(duration, cuts): output time to source time199 X->>X: frame i at i/fps: page + ink + pointer + camera (FrameCompositor)200 X->>X: edited audio (kept ranges, crossfades, gain)201 X-->>U: MP4 verified by decoding (MediaVerifier)202```203204### Key decisions2052061. **One timeline, in recorded time.** The timeline advances only while recording. A pause has zero length on the timeline and207 is stored as a `pause` / `resume(gapSeconds)` event pair with its exact wall-clock gap.2082. **The audio sample clock is the authority.** `RecordingClock` is re-anchored on every audio buffer, so events cannot drift209 from audio however long the session. Without audio it runs on the host clock.2103. **State is a function of time.** `TimelineIndex` answers "what is on screen at t": page, visible strokes with partial211 progress, pointer, viewport, camera. The live canvas, the editor preview, the exporter and the annotated PDF read that one212 model.2134. **Edits are data.** An `EditDecisionList` with a persisted undo / redo history. `TimeMap` converts between source and214 output time. Nothing ever rewrites media.2155. **Preview = export.** The editor preview draws with `FrameCompositor` and plays audio pulled from `EditedAudioRenderer`,216 the same objects the exporter uses.2176. **Vector ink with its own renderer.** PencilKit is the input device on iPad and iPhone; replay, export and PDF use218 `StrokeRenderer` (Core Graphics), identical on every platform. Consequence: PencilKit's live rendering of its ink types219 differs slightly from the exported look.2207. **No third-party dependency.** ZIP (store / deflate, ZIP64), tus upload and loudness metering are implemented in the221 packages.222223## 🧱 Stack224225| Layer | Technology | Value read in the repository | Role |226|---|---|---|---|227| Toolchain | Xcode / Swift | Xcode 27.2, Swift 6.4.2 (`docs/ARCHITECTURE.md`) | build |228| Package | Swift Package Manager | `swift-tools-version: 6.0`, package `LectureKit` | shared domain, storage, PDF, capture, render, transcription, sync |229| Language modes | Swift 6 and Swift 5 | Swift 6 mode for `LectureCore` and `LectureStorage`; Swift 5 mode for the AVFoundation / PDFKit / UI code | concurrency checking where the frameworks allow it |230| Deployment targets | macOS, iOS | `.macOS(.v15)`, `.iOS(.v18)`; `project.yml` 15.0 / 18.0 | minimum systems |231| Project | XcodeGen | `Apps/LectureStudio/project.yml` | one Xcode project: macOS app, iOS / iPadOS app, UI test targets |232| UI | SwiftUI, Observation | shared by all platforms | library, workspace, editor, export, settings |233| Slides | PDFKit | — | pages, search |234| Ink input | PencilKit (iOS / iPadOS), AppKit (macOS) | — | strokes |235| Capture and export | AVFoundation, CoreMedia, VideoToolbox | H.264 High / HEVC, Rec. 709, AAC 48 kHz mono | recording, MP4 |236| Speech | Speech | on-device recognition | transcription, phrase spotting |237| Crypto | CryptoKit / CommonCrypto | AES-256-GCM, PBKDF2-HMAC-SHA256, SHA-256 | segment checksums, optional encrypted bundle |238| Compression | zlib | `linkedLibrary("z")` | ZIP archives |239| Third-party dependencies | — | none | — |240241## 📁 Repository layout242243```244Package.swift one SwiftPM package (LectureKit)245Packages/LectureCore timeline time, ink model, event stream, edit decision list, analysis, auto-pause, captions246Packages/LectureStorage .slecture package, atomic manifest, event log, crash recovery, ZIP archives, library247Packages/LecturePDF PDF pages, vector ink renderer, annotated PDF export248Packages/LectureCapture recording clock, microphone, segmented audio, recording engine, camera, preflight249Packages/LectureRender frame compositor, edited-audio renderer, MP4 exporter, media verifier250Packages/LectureTranscription provider protocol, on-device speech, optional remote endpoint, phrase spotting251Packages/LectureSync encrypted bundles, resumable (tus) upload, Keychain, biometric gate252Packages/LectureTesting fixtures (generated PDFs, synthetic audio, synthetic timelines, pixel probes)253Apps/LectureStudio/Shared SwiftUI app shared by all platforms (App, Library, Workspace, Editor, Export, Support)254Apps/LectureStudio/macOS AppKit ink canvas (mouse / trackpad / tablet), entitlements255Apps/LectureStudio/iOS PencilKit canvas (Apple Pencil / finger)256Apps/LectureStudio/Resources asset catalog (app icons), Localizable.xcstrings, InfoPlist.xcstrings257Apps/LectureStudio/project.yml XcodeGen definition258Tests/Unit, Tests/Integration, Tests/UITests, Tests/Tools/CrashSim259scripts/ build, test, archive, notarize, localize, icon260docs/ architecture, formats, pipelines, security, QA, release (+ brand/ for this README)261CLAUDE.md mission, nonnegotiable rules, working rules, pitfalls262PROGRESS.md phase checklist, commands actually run and their results263```264265<details>266<summary>Size of each part (Swift files · lines)</summary>267268| Part | Files | Lines | Part | Files | Lines |269|---|---:|---:|---|---:|---:|270| `Apps/LectureStudio` | 17 | 4 891 | `LectureRender` | 4 | 907 |271| `LectureCore` | 9 | 1 374 | `LectureStorage` | 5 | 877 |272| `LectureCapture` | 6 | 1 121 | `LecturePDF` | 3 | 411 |273| `Tests` | 9 | 1 676 | `LectureTranscription` | 2 | 401 |274| `LectureSync` | 2 | 298 | `LectureTesting` | 1 | 195 |275276</details>277278## 🚀 Quick start279280```bash281scripts/build-all.sh # Swift packages + macOS app + iOS app (simulator and device)282scripts/test-all.sh # 44 unit + 16 integration tests283scripts/test-all.sh --long # adds the 90-minute export / sync test (~2 min, ~600 MB temporary disk)284scripts/test-all.sh --ui # adds the UI tests on dedicated iPhone and iPad simulators285scripts/test-ui.sh mac # UI test on the Mac (takes over the pointer; screen must be unlocked)286open Apps/LectureStudio/LectureStudio.xcodeproj # after: (cd Apps/LectureStudio && xcodegen generate)287```288289Requirements: Xcode 27.2 and [XcodeGen](https://github.com/yonaskolb/XcodeGen). Run `xcodegen generate` after adding files.290Builds go outside `~/Desktop` (`~/Library/Developer/SPLectureStudio/DerivedData`); logs land in `build/logs/` (not committed).291292Release: `scripts/archive-macos.sh && scripts/notarize-macos.sh` (Developer ID + notarization) and293`scripts/archive-ios.sh all|validate|upload` (App Store Connect). Details in [`docs/RELEASE.md`](docs/RELEASE.md).294295Debug-only launch arguments (compiled out of Release builds):296297| Argument | Effect |298|---|---|299| `-LectureDemoPDF YES` | adds a generated 20-page lecture to an empty library (used by the UI tests) |300| `-LectureSelfTest YES` | runs the scripted end-to-end test, writes `selftest-report.json`, then exits |301| `-LectureSelfTestSeconds N` | length of the recording (default 14) |302| `-LectureSelfTestSilent YES` | never ask for the microphone: run in PDF-only mode |303304## ⚙️ Configuration305306No credential, identity or secret is stored in the repository. Names only:307308| Name | Read by | Purpose |309|---|---|---|310| `DERIVED_DATA` | `scripts/build-all.sh` | DerivedData location |311| `LECTURE_LONG_TESTS` | integration tests | set to `1` to run the 90-minute export |312| `LECTURE_LIBRARY_ROOT` (or the `LectureLibraryRoot` default) | the app | override of the library folder |313| `NOTARY_PROFILE` | `scripts/notarize-macos.sh` | keychain profile created with `xcrun notarytool store-credentials` |314| `ASC_ENV` | `scripts/archive-ios.sh` | path of the env file holding `ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_KEY_PATH` (outside the repository) |315316In-app settings (stored per device): automatic pause policy, segment length, voice processing, microphone and camera choice,317camera placement, planned duration, export options, silence detection, transcription locale (default `fr-CA`), optional remote318transcription endpoint and its consent toggle, optional upload endpoint, biometric gate for credentials.319320## 🖥 Screens and shortcuts321322| Screen | Source | Purpose |323|---|---|---|324| Library | `Shared/Library/LibraryView.swift` | projects, import, archive, trash |325| Workspace | `Shared/Workspace/` | slide stage, ink tools, thumbnails, record bar, inspector panels |326| Editor | `Shared/Editor/` | timeline, preview, cuts, suggestions, chapters |327| Export | `Shared/Export/ExportSheet.swift` | video and artifact options, progress, exported files |328| Settings | `Shared/App/SettingsView.swift` | recording, automation, transcription, upload |329| Presentation | window scene `presentation` | clean stage for a second display |330331| Shortcut | Action | Shortcut | Action |332|---|---|---|---|333| <kbd>⌘N</kbd> | import a PDF (library) | <kbd>Space</kbd> | play / pause (editor) |334| <kbd>⌘R</kbd> or <kbd>⇧⌘R</kbd> | record / pause / resume | <kbd>I</kbd> / <kbd>O</kbd> | mark in / mark out |335| <kbd>⌘.</kbd> or <kbd>⇧⌘.</kbd> | stop recording | <kbd>⌫</kbd> | cut the selection |336| <kbd>⌘M</kbd> | add a marker | <kbd>⌘B</kbd> | split at the playhead |337| <kbd>⌘K</kbd> | mark a chapter | <kbd>⌘Z</kbd> / <kbd>⇧⌘Z</kbd> | undo / redo an edit |338| <kbd>⌘T</kbd> | mark a retake (nothing is erased) | <kbd>⌥⌘Z</kbd> / <kbd>⌥⇧⌘Z</kbd> | undo / redo a stroke |339| <kbd>⌘←</kbd> <kbd>⌘→</kbd> / <kbd>⌘↑</kbd> <kbd>⌘↓</kbd> | previous / next page | <kbd>⌘0</kbd> | fit the page |340| <kbd>⌘Home</kbd> | first page | | |341342## 📦 Project format (`.slecture`)343344A lecture is a package directory (UTI `ai.spboucher.slecture`), schema 2:345346```347Title.slecture/348 manifest.json metadata, PDF reference, recording sessions, media segments with SHA-256, export history349 events.jsonl append-only event stream, one JSON object per line350 edits.json EditHistory: current edit decision list + undo and redo stacks351 transcript.json optional transcript (source timeline)352 pdf/source.pdf immutable copy of the imported PDF353 media/audio-<session8>-<index5>.caf 16-bit PCM mono CAF, one bounded segment each354 media/camera-<session8>-<index5>.mov optional camera segments (fragmented QuickTime, video only)355 cache/waveform.json loudness envelope (10 ms hop); can be rebuilt356```357358```mermaid359erDiagram360 MANIFEST ||--|| PDF : references361 MANIFEST ||--o{ SESSION : contains362 SESSION ||--o{ SEGMENT : contains363 MANIFEST ||--o{ EXPORT : records364 EVENTLOG ||--o{ EVENT : appends365 EVENT ||--o| STROKE : "strokeAdded carries"366 EDITHISTORY ||--|| EDL : current367 EDITHISTORY ||--o{ EDL : "undo / redo stacks"368 MANIFEST {369 int schemaVersion370 uuid id371 string title372 string courseCode373 int duration "nanoseconds"374 }375 SESSION {376 uuid id377 date startedAt378 date endedAt "null = did not end cleanly"379 int timelineStart380 bool recovered381 }382 SEGMENT {383 string kind "audio or camera"384 string path385 int start386 int duration387 string sha256388 bool finalized389 }390 EVENT {391 int seq "strictly increasing"392 int t "timeline nanoseconds"393 int wall "audit only"394 string kind395 }396 STROKE {397 uuid id398 int page399 string tool400 string color "#RRGGBBAA"401 float width "normalized to page width"402 int begin403 }404 EDL {405 list cuts406 list suggestions "pending until approved"407 list muted408 list chapters409 float gainDB410 }411```412413- **Timebase**: `MediaTime` = signed 64-bit **nanoseconds** on the project timeline. Video frame *i* is at *i*/fps exactly;414 audio sample *n* at *n*/48000. Never `Double` seconds for stored or accumulated time.415- **Manifest**: replaced atomically (temporary file, then rename). Migrations run on the raw JSON; a package with a newer416 schema than the app supports is refused with an explicit error and is not modified.417- **Events**: `sessionStart`, `sessionEnd`, `page`, `strokeAdded`, `strokesRemoved`, `strokesRestored`, `viewport`, `pointer`,418 `pointerHidden`, `marker`, `pause`, `resume`, `camera`, `segment`, `auto`, `note`. Erase and undo are events, never419 deletions. A line that cannot be decoded is skipped, counted and left in the file.420- **Edits**: all times are source timeline times; source media, the PDF copy and the event log are never rewritten by editing421 or exporting.422- **Portability**: the package can be copied as is (Finder, Files, AirDrop). The project archive is a ZIP with caches423 excluded; importing always makes a copy and gives it a new id when that id already exists.424425Full specification: [`docs/PROJECT_FORMAT.md`](docs/PROJECT_FORMAT.md).426427## 🎙 Recording pipeline428429- **Pause** freezes the clock at the end of the written audio and closes the open segment, so everything is finalized before430 waiting. **Resume** writes the pre-roll (the last 0.3 s heard before resuming, configurable) and restarts the clock.431- **Checkpoints**: the manifest is rewritten atomically when a session starts, at every finalized segment, at every pause and432 at stop. The event log is appended with an fsync at most 1 s apart.433- **Low disk**: warning under 1 GB, automatic pause (everything finalized) under 200 MB. **Thermal / battery**: warnings only.434- **Sleep**: idle timer disabled on iOS, an activity assertion on macOS while a session is open.435436| Automatic policy (all off by default) | Trigger | What happens |437|---|---|---|438| Silence | no voice for N s (6 dB hysteresis, 0.6 s hangover) | a suggestion banner; never an action |439| Inactivity | no voice **and** no slide / ink interaction for N s | countdown; any activity cancels it |440| Maximum duration | recorded time reaches the limit | countdown; "continue" snoozes 15 min |441| End time | wall clock reaches the chosen time | countdown; "continue" snoozes 15 min |442| End phrase / retake phrase | recognized on device, only if the language model is installed | short countdown / a retake marker |443444At the end of a countdown the session is **paused** (default) or stopped and saved (option). Every decision is written to the445event log as an `auto` event: that is the audit log.446447**Crash recovery**: on opening a project, `ProjectRecovery` runs when a session has no end date, a segment is not finalized,448or a media file is not in the manifest. It probes each file by decoding it, patches a CAF header whose data size was never449written, re-attaches readable segments in order, closes the session and reports what it found. Unreadable files are kept and450listed. It only states what can be decoded.451452Details: [`docs/RECORDING_PIPELINE.md`](docs/RECORDING_PIPELINE.md).453454## 🎬 Export pipeline455456- **Determinism**: every frame is computed from the event log; the same project and settings give the same pictures. A frame457 whose signature equals the previous one reuses the rendered pixel buffer (160 606 of 162 000 frames in the 90-minute test).458- **Cuts** are removed by the time map; slide changes and ink that happened inside a cut take effect at the join. Missing or459 unreadable audio segments render as silence and are reported.460- **Crossfade**: equal-power, 30 ms by default, centred on the cut, so the programme duration is exactly the sum of the kept461 ranges.462- **Loudness** (optional): one measurement pass (ITU-R BS.1770 K-weighting, gated), then a single gain to −16 LUFS, capped at463 +20 dB and at a −1 dBFS peak.464- **Robustness**: free space is checked first; exports run in a private scratch folder; cancellation and failures leave no465 partial file; the destination is replaced only by a complete file. An interrupted export is restarted, not resumed.466467| Measured (MacBook Pro, 2026-11-18) | Result |468|---|---|469| 12 s, 640×360 | ink appears within one frame of its recorded time; clicks at 2 / 5 / 9 s found within 3 ms |470| 90 min synthetic, 640×360, 30 fps | 162 000 frames in 99 s; A/V sync within 3 ms at 7 probes up to 89:59; peak memory 600 MB; file 27.5 MB |471| 16 s real recording, 1920×1080 | exported in 1.0–2.9 s on the simulators, verified by decoding every frame |4724731080p export of a real 90-minute lecture and 4K export have not been timed. Details:474[`docs/EXPORT_PIPELINE.md`](docs/EXPORT_PIPELINE.md).475476## 🔐 Security and privacy477478- **Everything is local**: no account, no analytics, no network use in the record → edit → export path. Projects live in the479 app container (macOS) or in `Documents/Lectures`, visible in the Files app (iOS).480- **iOS file protection**: `completeUntilFirstUserAuthentication`, so a recording can continue with the screen locked.481- **Nothing is silently deleted**: deleting a project moves it to the library trash, restorable until explicitly emptied.482- **Integrity**: SHA-256 of every finalized segment and of the PDF copy is stored in the manifest and can be re-verified.483- **Permissions just in time**: microphone, camera and speech recognition are requested only when the feature that needs them484 starts. A denied microphone leads to an explanation and the PDF-only mode, never to a silent failure.485- **Visible recording state** at all times. The app records only its own PDF canvas, the chosen microphone and, if enabled,486 the chosen camera. It never captures other apps or the screen.487- **macOS**: App Sandbox + hardened runtime; entitlements `device.audio-input`, `device.camera`,488 `files.user-selected.read-write`, `network.client` (only used by the optional upload and remote transcription).489- **iOS / iPadOS**: background mode `audio` only.490- **Optional network features, all off until configured**: upload to a user-configured tus endpoint (HTTPS required, bearer491 token in the Keychain, optional Face ID / Touch ID gate); remote transcription on a user-configured OpenAI-compatible492 endpoint (HTTPS required, explicit consent, 16 kHz WAV chunks).493- **Encrypted bundle** (library code, not yet exposed in the UI): AES-256-GCM in 1 MB chunks, key from PBKDF2-HMAC-SHA256494 (310 000 iterations), truncation, reordering and tampering detected.495- **Parsers**: ZIP import refuses absolute paths, `..` components and paths escaping the destination, and verifies CRCs.496- **Not done**: third-party security audit, fuzzing of the PDF / ZIP / event parsers, privacy manifest review for App Store497 submission.498499Details: [`docs/SECURITY.md`](docs/SECURITY.md).500501## 🧪 Testing502503| Suite | Command | Count | Covers |504|---|---|---:|---|505| Unit | `swift test` | 44 | timebase, ink codec, timeline index, edits and time map, silence / retake / chapters, auto-pause, captions, package and migration, event log, ZIP, library, PDF and ink rendering, annotated PDF, compositor, audio renderer, loudness, transcription helpers, remote client (stubbed HTTP), encrypted bundle, tus upload (stubbed server) |506| Integration | `swift test` | 16 | export decoded and checked for ink timing and A/V sync, edited export + undo + re-export, cancellation, HEVC, missing media, recording engine (segments, pause, pre-roll, route change, interruption, policies, PDF-only), crash recovery (on-disk copy and real SIGKILL), real microphone |507| 90-minute export | `scripts/test-all.sh --long` | 1 (skipped by default) | A/V sync and resources over a full-length synthetic lecture |508| UI | `scripts/test-ui.sh iphone` / `ipad` / `mac` | 3 test methods | annotate → record → edit → export; preflight, policies and search sheets; Mac annotate, navigate and export PDF |509| In-app self-test | `-LectureSelfTest YES` (Debug) | — | the whole chain on each platform, with the real microphone on the Mac |510511<details>512<summary>Tests per file</summary>513514| File | Tests | File | Tests |515|---|---:|---|---:|516| `Tests/Unit/CoreTests.swift` | 22 | `Tests/Integration/CaptureTests.swift` | 11 |517| `Tests/Unit/TranscriptionSyncTests.swift` | 7 | `Tests/Integration/ExportTests.swift` | 5 |518| `Tests/Unit/RenderTests.swift` | 6 | `Tests/UITests/WorkflowUITests.swift` | 3 |519| `Tests/Unit/StorageTests.swift` | 6 | | |520| `Tests/Unit/PDFTests.swift` | 3 | | |521522</details>523524`Tests/Tools/CrashSim` is an executable (`lecture-crashsim`) used by the recovery test to kill a real recorder process.525526Never claim a platform has been tested unless it was actually built and tested: the acceptance table and the list of what was527never verified are in [`docs/QA.md`](docs/QA.md).528529## 🚢 Release530531**macOS** (Developer ID, outside the App Store):532533```bash534scripts/archive-macos.sh # Release archive, universal, signed with the Developer ID identity found in the keychain535scripts/notarize-macos.sh # notarytool → staple app → DMG → sign → notarize → staple536```537538State on 2026-11-18: version 1.0.0 (1), universal (arm64 + x86_64), sandbox + hardened runtime, **notarized and stapled**.539Artifacts: `dist/SP Lecture Studio.app`, `dist/SPLectureStudio-1.0.0.dmg` (+ `.sha256`). Not published anywhere.540`scripts/archive-macos.sh` fails if `get-task-allow` is present or the runtime flag is missing.541542**iOS / iPadOS** (App Store Connect; notarization does not apply):543544```bash545scripts/archive-ios.sh all # archive with automatic signing + export of the IPA → dist/ios-export/546scripts/archive-ios.sh validate # altool --validate-app547scripts/archive-ios.sh upload # altool --upload-app (TestFlight)548```549550State on 2026-11-18: app record **6836594820** "SP Lecture Studio", primary language fr-CA, categories Education /551Productivity; build 1.0.0 (1) validated, uploaded and processed (state `VALID`). Left to the owner: add the build to an552internal TestFlight group and install it on a real iPhone / iPad; screenshots, age rating, privacy policy URL and App Privacy553answers; confirm the export-compliance answer. Nothing was submitted for review.554555Increase `CURRENT_PROJECT_VERSION` in `Apps/LectureStudio/project.yml` before each upload.556557**Checklist before a public release**5585591. `scripts/build-all.sh && scripts/test-all.sh --long --ui`, and `scripts/test-ui.sh mac` with the screen unlocked.5602. The hardware checks listed in `docs/QA.md` ("Never verified").5613. Bump versions, archive both platforms, notarize, upload.562563Details: [`docs/RELEASE.md`](docs/RELEASE.md).564565## 🧯 Gotchas566567- **macOS 27**: `List(selection:)` does not select rows, and `NavigationSplitView` / `HSplitView` mis-size their detail column568 → the app uses button rows and plain `HStack` + `Divider`. Pass models as parameters; `@Environment(Model.self)` crashes in569 sheets, toolbars and menus.570- A system type named `LibraryItem` exists: always write `LectureStorage.LibraryItem` in the app.571- `AVAudioFile` finalizes its header only on `close()`; a checksum taken before that is wrong.572- `AVAssetWriter` writes side files next to its output; exports run in a private scratch folder that is removed afterwards.573- **PencilKit**: the tool palette floats above sheets unless it is hidden; on iPhone it reports no obscured frame, so 72 pt is574 reserved; on iPad page navigation sits above the slide. `PKStroke` has no identifier: strokes are matched by (creation date,575 random seed, point count, transform).576- Recording state callbacks from `RecordingEngine` arrive asynchronously on the main queue; `ProjectSession` mirrors577 `engine.state` immediately after `pause` / `resume` / `start`.578- **Sandboxed Mac debug builds must always be signed by the team** (never ad hoc): a signature change on the same bundle ID579 makes macOS hold the launch behind an app-data consent prompt. GUI launches and UI tests also hang while the Mac screen is580 locked.581- Lazy rows on macOS: a helper function does not observe the session → one real `View` per row (thumbnails stayed blank582 otherwise).583- `set -o pipefail` + `grep -q` on a pipe gives false failures in scripts (SIGPIPE): capture into a variable first.584- Build outside `~/Desktop`.585- UI strings are French in code; after adding strings run a build, then `scripts/localize.py`, and add the English to586 `scripts/translations-en.json`.587588## 🗺 Status and known limitations589590From [`PROGRESS.md`](PROGRESS.md) and [`docs/QA.md`](docs/QA.md) (session of 2026-11-18).591592| Phase | State |593|---|---|594| 0 — audit · 1 — scaffold · 2 — PDF and ink · 3 — recording · 4 — render · 5 — editing | done |595| 6 — advanced | partial: camera picture-in-picture implemented, **never run with a camera**; transcription and captions implemented, **on-device recognition never run**; remote transcription and tus upload tested against stubs only; presentation window untested on a second display |596| 7 — release | partial: macOS notarized; iOS uploaded to App Store Connect; French + English; accessibility labels on controls. Not done: VoiceOver pass, real-device stress |597598**Not implemented**: Mac screen / window capture, device-to-device sync UI (only the encrypted bundle and upload building599blocks), transcript-based AI cut suggestions.600601**Never verified** (needs hardware or a person): any real iPhone or iPad; Apple Pencil (pressure, tilt, hover, palm602rejection); device microphones and cameras; lock screen and background recording on a device; incoming-call interruption and603Bluetooth route changes on a device; thermal and battery behaviour over a long session; the camera path end to end; on-device604speech recognition; the remote transcription and upload clients against real servers; on macOS the shape tools, eraser, laser605pointer, zoom / pan gestures, menus and keyboard shortcuts, a second window, the presentation window on a second display;606VoiceOver; Dynamic Type at large sizes; the Intel slice of the universal binary; 1080p / 4K export time on a real 90-minute607lecture; disk-full during export.608609**Platform limits**: on iOS / iPadOS recording continues in the background through the `audio` background mode; the camera610cannot run in the background; without audio the app is suspended in the background, so a PDF-only session is paused when the611app leaves the foreground. Unrestricted background recording is not promised.612613**Next actions for the owner**: record a real 10-minute lecture on the Mac with the notarized app; install the TestFlight614build on a real iPad with Apple Pencil and a real iPhone; try the camera, on-device transcription and the lock-screen /615phone-call cases; decide whether to publish the Mac DMG.616617## 📚 Documentation618619| Document | Content |620|---|---|621| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | capability matrix, layers, key decisions, honest limits of the platforms |622| [`docs/PROJECT_FORMAT.md`](docs/PROJECT_FORMAT.md) | the `.slecture` package, timebase, manifest, events, edits |623| [`docs/RECORDING_PIPELINE.md`](docs/RECORDING_PIPELINE.md) | capture chain, automatic pause and stop, crash recovery |624| [`docs/EXPORT_PIPELINE.md`](docs/EXPORT_PIPELINE.md) | render chain, determinism, audio finishing, measurements |625| [`docs/SECURITY.md`](docs/SECURITY.md) | data, permissions, sandbox and signing, optional network features |626| [`docs/QA.md`](docs/QA.md) | what was tested, how, and what was not |627| [`docs/RELEASE.md`](docs/RELEASE.md) | macOS notarization, App Store Connect, checklist |628| [`PROGRESS.md`](PROGRESS.md) | phase checklist, commands and results, bugs found by the tests |629| [`CLAUDE.md`](CLAUDE.md) | mission, rules, pitfalls |630631## 👤 Author632633<div align="center">634<img src="docs/brand/icon.png" width="64" height="64" alt=""><br>635636**Simon-Pierre Boucher** — design, development, operations<br>637[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai638639</div>640641## 📄 License642643All rights reserved © 2026 Simon-Pierre Boucher.644