🎓 SP Lecture Studio
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.
Author: Simon-Pierre Boucher
Table of contents
- Overview
- Features
- Architecture
- Stack
- Repository layout
- Quick start
- Configuration
- Screens and shortcuts
- Project format (
.slecture) - Recording pipeline
- Export pipeline
- Security and privacy
- Testing
- Release
- Gotchas
- Status and known limitations
- Documentation
- Author
- License
🎯 Overview
SP Lecture Studio is built for a university instructor who records PDF-based lectures. The central workflow: import a PDF; present it; annotate live; capture the microphone and, optionally, the camera; pause or stop automatically when configured; review a nondestructive edit; export a polished MP4 with synchronized annotations, plus an annotated PDF, captions and chapters.
Every device performs the complete workflow without any other device or server. Everything works offline, on the device; nothing is uploaded unless you explicitly ask.
| Platforms | macOS 15+, iPadOS 18+, iOS 18+ (built with Xcode 27.2, Swift 6.4) |
| Bundle IDs | ai.spboucher.splecturestudio (macOS), ai.spboucher.splecturestudio.ios (iOS / iPadOS) |
| Dependencies | none (Apple frameworks only) |
| Project format | .slecture package — see docs/PROJECT_FORMAT.md |
| Status | see PROGRESS.md (what was actually built and tested, and what was not) |
The video is never a screen recording: every frame is recomputed from the PDF, the time-coded vector ink and the event log. The same code draws the editor preview and the export.
One repository holds everything: the shared Swift package LectureKit, the macOS app, the iOS / iPadOS app, the tests and
the release scripts. It is a standalone project among the git.spboucher.ai applications and has
no backend.
✨ Features
| Area | What the code does |
|---|---|
| import (the original file is never touched; an immutable copy is kept), view, navigate, search, zoom and pan, presenter notes per page | |
| Ink | time-coded vector strokes in page-normalized coordinates: pen, marker, pencil, line, arrow, rectangle, ellipse; eraser and undo / redo as events; laser pointer |
| Input | PencilKit canvas on iPad and iPhone (Apple Pencil or finger); AppKit canvas on Mac (mouse, trackpad, tablet) |
| Recording | real microphone, page / ink / pointer / viewport events, pause / resume / stop, markers (generic, chapter, retake), pre-roll on resume |
| 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 |
| Interruptions | calls and Siri pause the session (never resume by themselves); route changes (headset, Bluetooth) restart on the new route |
| Automatic pause / stop | silence, inactivity, maximum duration, end time, end phrase, retake phrase — all off by default, every decision logged |
| PDF-only mode | with the microphone denied the same pipeline runs without audio |
| Editing | nondestructive timeline: cut, split, ripple delete, trim, mute, undo / redo; long-silence and retake suggestions with before / after audition and approval |
| Audio finishing | fades, equal-power crossfade at joins, loudness normalization to −16 LUFS, cleanup (80 Hz high-pass, gentle expander), gain |
| 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 |
| 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) |
| Verification | an exported video is reopened, its tracks and duration are checked and its first frame is decoded before it is listed |
| Transcription | provider protocol: on-device speech recognition, or an optional user-configured remote endpoint used only after explicit consent |
| Optional upload | explicit, per file, to a user-configured resumable (tus) endpoint over HTTPS |
| Library | projects with course code, session number, date; archive, trash (restorable), integrity check |
| Presentation | a separate "presentation" window scene shows a clean stage |
| Languages | French (source) and English: 503 strings |
🏗 Architecture
flowchart TB
subgraph App["App (SwiftUI) — Apps/LectureStudio"]
Session["ProjectSession<br/>(live lecture)"]
Editor["EditorModel<br/>timeline · preview"]
Export["ExportSheet<br/>export coordinator"]
Mac["macOS adapter<br/>AppKit ink canvas"]
Pencil["iOS / iPadOS adapter<br/>PencilKit canvas"]
end
subgraph Kit["LectureKit (SwiftPM)"]
Capture["LectureCapture<br/>RecordingClock · RecordingEngine<br/>SegmentedAudioWriter · CameraRecorder · Preflight"]
Render["LectureRender<br/>FrameCompositor · EditedAudioRenderer<br/>VideoExporter · MediaVerifier"]
PDF["LecturePDF<br/>SlideDocument · StrokeRenderer<br/>AnnotatedPDFExporter"]
Trans["LectureTranscription"]
Sync["LectureSync"]
Storage["LectureStorage<br/>ProjectPackage · EventLog<br/>Recovery · Library · ZipArchive"]
Core["LectureCore<br/>MediaTime · Stroke · TimelineEvent<br/>TimelineIndex · EditDecisionList · TimeMap"]
end
Mac --> Session
Pencil --> Session
Session --> Capture
Editor --> Render
Export --> Render
Capture --> Storage
Render --> PDF
Render --> Storage
Trans --> Render
Sync --> Storage
PDF --> Core
Storage --> Core
Capture --> Core
Storage --> Disk[(".slecture package<br/>manifest · events · edits · media")]
Dependencies point downward only. LectureCore depends on Foundation alone and is fully unit-tested.
sequenceDiagram
autonumber
participant U as Instructor
participant S as ProjectSession
participant E as RecordingEngine
participant C as RecordingClock
participant W as SegmentedAudioWriter
participant L as EventLogWriter
participant X as VideoExporter
U->>S: start recording
S->>E: start
loop every audio buffer
E->>W: buffer, host time
W-->>E: timeline time of the first sample
E->>C: anchor(host, timeline)
end
U->>S: page change, stroke, pointer, zoom, marker
S->>E: record(event)
E->>C: timeline time now
E->>L: append event (fsync within 1 s)
W->>W: close segment, SHA-256, manifest checkpoint
U->>S: stop
E->>L: sessionEnd, manifest, waveform cache
U->>X: export
X->>X: TimeMap(duration, cuts): output time to source time
X->>X: frame i at i/fps: page + ink + pointer + camera (FrameCompositor)
X->>X: edited audio (kept ranges, crossfades, gain)
X-->>U: MP4 verified by decoding (MediaVerifier)
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. - The audio sample clock is the authority.
RecordingClockis re-anchored on every audio buffer, 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 read that one model. - Edits are data. An
EditDecisionListwith 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 its own renderer. PencilKit is the input device on iPad and iPhone; replay, export and PDF use
StrokeRenderer(Core Graphics), 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 and loudness metering are implemented in the packages.
🧱 Stack
| Layer | Technology | Value read in the repository | Role |
|---|---|---|---|
| Toolchain | Xcode / Swift | Xcode 27.2, Swift 6.4.2 (docs/ARCHITECTURE.md) |
build |
| Package | Swift Package Manager | swift-tools-version: 6.0, package LectureKit |
shared domain, storage, PDF, capture, render, transcription, sync |
| 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 |
| Deployment targets | macOS, iOS | .macOS(.v15), .iOS(.v18); project.yml 15.0 / 18.0 |
minimum systems |
| Project | XcodeGen | Apps/LectureStudio/project.yml |
one Xcode project: macOS app, iOS / iPadOS app, UI test targets |
| UI | SwiftUI, Observation | shared by all platforms | library, workspace, editor, export, settings |
| Slides | PDFKit | — | pages, search |
| Ink input | PencilKit (iOS / iPadOS), AppKit (macOS) | — | strokes |
| Capture and export | AVFoundation, CoreMedia, VideoToolbox | H.264 High / HEVC, Rec. 709, AAC 48 kHz mono | recording, MP4 |
| Speech | Speech | on-device recognition | transcription, phrase spotting |
| Crypto | CryptoKit / CommonCrypto | AES-256-GCM, PBKDF2-HMAC-SHA256, SHA-256 | segment checksums, optional encrypted bundle |
| Compression | zlib | linkedLibrary("z") |
ZIP archives |
| Third-party dependencies | — | none | — |
📁 Repository layout
Package.swift one SwiftPM package (LectureKit)
Packages/LectureCore timeline time, ink model, event stream, edit decision list, analysis, auto-pause, captions
Packages/LectureStorage .slecture package, atomic manifest, event log, crash recovery, ZIP archives, library
Packages/LecturePDF PDF pages, vector ink renderer, annotated PDF export
Packages/LectureCapture recording clock, microphone, segmented audio, recording engine, camera, preflight
Packages/LectureRender frame compositor, edited-audio renderer, MP4 exporter, media verifier
Packages/LectureTranscription provider protocol, on-device speech, optional remote endpoint, phrase spotting
Packages/LectureSync encrypted bundles, resumable (tus) upload, Keychain, biometric gate
Packages/LectureTesting fixtures (generated PDFs, synthetic audio, synthetic timelines, pixel probes)
Apps/LectureStudio/Shared SwiftUI app shared by all platforms (App, Library, Workspace, Editor, Export, Support)
Apps/LectureStudio/macOS AppKit ink canvas (mouse / trackpad / tablet), entitlements
Apps/LectureStudio/iOS PencilKit canvas (Apple Pencil / finger)
Apps/LectureStudio/Resources asset catalog (app icons), Localizable.xcstrings, InfoPlist.xcstrings
Apps/LectureStudio/project.yml XcodeGen definition
Tests/Unit, Tests/Integration, Tests/UITests, Tests/Tools/CrashSim
scripts/ build, test, archive, notarize, localize, icon
docs/ architecture, formats, pipelines, security, QA, release (+ brand/ for this README)
CLAUDE.md mission, nonnegotiable rules, working rules, pitfalls
PROGRESS.md phase checklist, commands actually run and their resultsSize of each part (Swift files · lines)
| Part | Files | Lines | Part | Files | Lines |
|---|---|---|---|---|---|
Apps/LectureStudio |
17 | 4 891 | LectureRender |
4 | 907 |
LectureCore |
9 | 1 374 | LectureStorage |
5 | 877 |
LectureCapture |
6 | 1 121 | LecturePDF |
3 | 411 |
Tests |
9 | 1 676 | LectureTranscription |
2 | 401 |
LectureSync |
2 | 298 | LectureTesting |
1 | 195 |
🚀 Quick start
scripts/build-all.sh # Swift packages + macOS app + iOS app (simulator and device)
scripts/test-all.sh # 44 unit + 16 integration tests
scripts/test-all.sh --long # adds the 90-minute export / sync test (~2 min, ~600 MB temporary disk)
scripts/test-all.sh --ui # adds the UI tests on dedicated iPhone and iPad simulators
scripts/test-ui.sh mac # UI test on the Mac (takes over the pointer; screen must be unlocked)
open Apps/LectureStudio/LectureStudio.xcodeproj # after: (cd Apps/LectureStudio && xcodegen generate)Requirements: Xcode 27.2 and XcodeGen. Run xcodegen generate after adding files.
Builds go outside ~/Desktop (~/Library/Developer/SPLectureStudio/DerivedData); logs land in build/logs/ (not committed).
Release: scripts/archive-macos.sh && scripts/notarize-macos.sh (Developer ID + notarization) and
scripts/archive-ios.sh all|validate|upload (App Store Connect). Details in docs/RELEASE.md.
Debug-only launch arguments (compiled out of Release builds):
| Argument | Effect |
|---|---|
-LectureDemoPDF YES |
adds a generated 20-page lecture to an empty library (used by the UI tests) |
-LectureSelfTest YES |
runs the scripted end-to-end test, writes selftest-report.json, then exits |
-LectureSelfTestSeconds N |
length of the recording (default 14) |
-LectureSelfTestSilent YES |
never ask for the microphone: run in PDF-only mode |
⚙️ Configuration
No credential, identity or secret is stored in the repository. Names only:
| Name | Read by | Purpose |
|---|---|---|
DERIVED_DATA |
scripts/build-all.sh |
DerivedData location |
LECTURE_LONG_TESTS |
integration tests | set to 1 to run the 90-minute export |
LECTURE_LIBRARY_ROOT (or the LectureLibraryRoot default) |
the app | override of the library folder |
NOTARY_PROFILE |
scripts/notarize-macos.sh |
keychain profile created with xcrun notarytool store-credentials |
ASC_ENV |
scripts/archive-ios.sh |
path of the env file holding ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_PATH (outside the repository) |
In-app settings (stored per device): automatic pause policy, segment length, voice processing, microphone and camera choice,
camera placement, planned duration, export options, silence detection, transcription locale (default fr-CA), optional remote
transcription endpoint and its consent toggle, optional upload endpoint, biometric gate for credentials.
🖥 Screens and shortcuts
| Screen | Source | Purpose |
|---|---|---|
| Library | Shared/Library/LibraryView.swift |
projects, import, archive, trash |
| Workspace | Shared/Workspace/ |
slide stage, ink tools, thumbnails, record bar, inspector panels |
| Editor | Shared/Editor/ |
timeline, preview, cuts, suggestions, chapters |
| Export | Shared/Export/ExportSheet.swift |
video and artifact options, progress, exported files |
| Settings | Shared/App/SettingsView.swift |
recording, automation, transcription, upload |
| Presentation | window scene presentation |
clean stage for a second display |
| Shortcut | Action | Shortcut | Action |
|---|---|---|---|
| ⌘N | import a PDF (library) | Space | play / pause (editor) |
| ⌘R or ⇧⌘R | record / pause / resume | I / O | mark in / mark out |
| ⌘. or ⇧⌘. | stop recording | ⌫ | cut the selection |
| ⌘M | add a marker | ⌘B | split at the playhead |
| ⌘K | mark a chapter | ⌘Z / ⇧⌘Z | undo / redo an edit |
| ⌘T | mark a retake (nothing is erased) | ⌥⌘Z / ⌥⇧⌘Z | undo / redo a stroke |
| ⌘← ⌘→ / ⌘↑ ⌘↓ | previous / next page | ⌘0 | fit the page |
| ⌘Home | first page |
📦 Project format (.slecture)
A lecture is a package directory (UTI ai.spboucher.slecture), schema 2:
Title.slecture/
manifest.json metadata, PDF reference, recording sessions, media segments with SHA-256, export history
events.jsonl append-only event stream, one JSON object per line
edits.json EditHistory: current edit decision list + undo and redo stacks
transcript.json optional transcript (source timeline)
pdf/source.pdf immutable copy of the imported PDF
media/audio-<session8>-<index5>.caf 16-bit PCM mono CAF, one bounded segment each
media/camera-<session8>-<index5>.mov optional camera segments (fragmented QuickTime, video only)
cache/waveform.json loudness envelope (10 ms hop); can be rebuilterDiagram
MANIFEST ||--|| PDF : references
MANIFEST ||--o{ SESSION : contains
SESSION ||--o{ SEGMENT : contains
MANIFEST ||--o{ EXPORT : records
EVENTLOG ||--o{ EVENT : appends
EVENT ||--o| STROKE : "strokeAdded carries"
EDITHISTORY ||--|| EDL : current
EDITHISTORY ||--o{ EDL : "undo / redo stacks"
MANIFEST {
int schemaVersion
uuid id
string title
string courseCode
int duration "nanoseconds"
}
SESSION {
uuid id
date startedAt
date endedAt "null = did not end cleanly"
int timelineStart
bool recovered
}
SEGMENT {
string kind "audio or camera"
string path
int start
int duration
string sha256
bool finalized
}
EVENT {
int seq "strictly increasing"
int t "timeline nanoseconds"
int wall "audit only"
string kind
}
STROKE {
uuid id
int page
string tool
string color "#RRGGBBAA"
float width "normalized to page width"
int begin
}
EDL {
list cuts
list suggestions "pending until approved"
list muted
list chapters
float gainDB
}
- Timebase:
MediaTime= signed 64-bit nanoseconds on the project timeline. Video frame i is at i/fps exactly; audio sample n at n/48000. NeverDoubleseconds for stored or accumulated time. - Manifest: replaced atomically (temporary file, then rename). Migrations run on the raw JSON; a package with a newer schema than the app supports is refused with an explicit error and is not modified.
- Events:
sessionStart,sessionEnd,page,strokeAdded,strokesRemoved,strokesRestored,viewport,pointer,pointerHidden,marker,pause,resume,camera,segment,auto,note. Erase and undo are events, never deletions. A line that cannot be decoded is skipped, counted and left in the file. - Edits: all times are source timeline times; source media, the PDF copy and the event log are never rewritten by editing or exporting.
- Portability: the package can be copied as is (Finder, Files, AirDrop). The project archive is a ZIP with caches excluded; importing always makes a copy and gives it a new id when that id already exists.
Full specification: docs/PROJECT_FORMAT.md.
🎙 Recording pipeline
- Pause freezes the clock at the end of the written audio and closes the open segment, so everything is finalized before waiting. Resume writes the pre-roll (the last 0.3 s heard before resuming, configurable) and restarts the clock.
- Checkpoints: the manifest is rewritten atomically when a session starts, at every finalized segment, at every pause and at stop. The event log is appended with an fsync at most 1 s apart.
- Low disk: warning under 1 GB, automatic pause (everything finalized) under 200 MB. Thermal / battery: warnings only.
- Sleep: idle timer disabled on iOS, an activity assertion on macOS while a session is open.
| Automatic policy (all off by default) | Trigger | What happens |
|---|---|---|
| Silence | no voice for N s (6 dB hysteresis, 0.6 s hangover) | a suggestion banner; never an action |
| Inactivity | no voice and no slide / ink interaction for N s | countdown; any activity cancels it |
| Maximum duration | recorded time reaches the limit | countdown; "continue" snoozes 15 min |
| End time | wall clock reaches the chosen time | countdown; "continue" snoozes 15 min |
| End phrase / retake phrase | recognized on device, only if the language model is installed | short countdown / a retake marker |
At the end of a countdown the session is paused (default) or stopped and saved (option). Every decision is written to the
event log as an auto event: that is the audit log.
Crash recovery: on opening a project, ProjectRecovery runs when a session has no end date, a segment is not finalized,
or a media file is not in the manifest. It probes each file by decoding it, patches a CAF header whose data size was never
written, re-attaches readable segments in order, closes the session and reports what it found. Unreadable files are kept and
listed. It only states what can be decoded.
Details: docs/RECORDING_PIPELINE.md.
🎬 Export pipeline
- Determinism: every frame is computed from the event log; the same project and settings give the same pictures. A frame whose signature equals the previous one reuses the rendered pixel buffer (160 606 of 162 000 frames in the 90-minute test).
- Cuts are removed by the time map; slide changes and ink that happened inside a cut take effect at the join. Missing or unreadable audio segments render as silence and are reported.
- Crossfade: equal-power, 30 ms by default, centred on the cut, so the programme duration is exactly the sum of the kept ranges.
- Loudness (optional): one measurement pass (ITU-R BS.1770 K-weighting, gated), then a single gain to −16 LUFS, capped at +20 dB and at a −1 dBFS peak.
- Robustness: free space is checked first; exports run in a private scratch folder; cancellation and failures leave no partial file; the destination is replaced only by a complete file. An interrupted export is restarted, not resumed.
| Measured (MacBook Pro, 2026-11-18) | Result |
|---|---|
| 12 s, 640×360 | ink appears within one frame of its recorded time; clicks at 2 / 5 / 9 s found within 3 ms |
| 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 |
| 16 s real recording, 1920×1080 | exported in 1.0–2.9 s on the simulators, verified by decoding every frame |
1080p export of a real 90-minute lecture and 4K export have not been timed. Details:
docs/EXPORT_PIPELINE.md.
🔐 Security and privacy
- Everything is local: no account, no analytics, no network use in the record → edit → export path. Projects live in the
app container (macOS) or in
Documents/Lectures, visible in the Files app (iOS). - iOS file protection:
completeUntilFirstUserAuthentication, so a recording can continue with the screen locked. - Nothing is silently deleted: deleting a project moves it to the library trash, restorable until explicitly emptied.
- Integrity: SHA-256 of every finalized segment and of the PDF copy is stored in the manifest and can be re-verified.
- Permissions just in time: microphone, camera and speech recognition are requested only when the feature that needs them starts. A denied microphone leads to an explanation and the PDF-only mode, never to a silent failure.
- Visible recording state at all times. The app records only its own PDF canvas, the chosen microphone and, if enabled, the chosen camera. It never captures other apps or the screen.
- macOS: App Sandbox + hardened runtime; entitlements
device.audio-input,device.camera,files.user-selected.read-write,network.client(only used by the optional upload and remote transcription). - iOS / iPadOS: background mode
audioonly. - Optional network features, all off until configured: upload to a user-configured tus endpoint (HTTPS required, bearer token in the Keychain, optional Face ID / Touch ID gate); remote transcription on a user-configured OpenAI-compatible endpoint (HTTPS required, explicit consent, 16 kHz WAV chunks).
- Encrypted bundle (library code, not yet exposed in the UI): AES-256-GCM in 1 MB chunks, key from PBKDF2-HMAC-SHA256 (310 000 iterations), truncation, reordering and tampering detected.
- Parsers: ZIP import refuses absolute paths,
..components and paths escaping the destination, and verifies CRCs. - Not done: third-party security audit, fuzzing of the PDF / ZIP / event parsers, privacy manifest review for App Store submission.
Details: docs/SECURITY.md.
🧪 Testing
| Suite | Command | Count | Covers |
|---|---|---|---|
| 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) |
| 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 |
| 90-minute export | scripts/test-all.sh --long |
1 (skipped by default) | A/V sync and resources over a full-length synthetic lecture |
| 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 |
| In-app self-test | -LectureSelfTest YES (Debug) |
— | the whole chain on each platform, with the real microphone on the Mac |
Tests per file
| File | Tests | File | Tests |
|---|---|---|---|
Tests/Unit/CoreTests.swift |
22 | Tests/Integration/CaptureTests.swift |
11 |
Tests/Unit/TranscriptionSyncTests.swift |
7 | Tests/Integration/ExportTests.swift |
5 |
Tests/Unit/RenderTests.swift |
6 | Tests/UITests/WorkflowUITests.swift |
3 |
Tests/Unit/StorageTests.swift |
6 | ||
Tests/Unit/PDFTests.swift |
3 |
Tests/Tools/CrashSim is an executable (lecture-crashsim) used by the recovery test to kill a real recorder process.
Never claim a platform has been tested unless it was actually built and tested: the acceptance table and the list of what was
never verified are in docs/QA.md.
🚢 Release
macOS (Developer ID, outside the App Store):
scripts/archive-macos.sh # Release archive, universal, signed with the Developer ID identity found in the keychain
scripts/notarize-macos.sh # notarytool → staple app → DMG → sign → notarize → stapleState on 2026-11-18: version 1.0.0 (1), universal (arm64 + x86_64), sandbox + hardened runtime, notarized and stapled.
Artifacts: dist/SP Lecture Studio.app, dist/SPLectureStudio-1.0.0.dmg (+ .sha256). Not published anywhere.
scripts/archive-macos.sh fails if get-task-allow is present or the runtime flag is missing.
iOS / iPadOS (App Store Connect; notarization does not apply):
scripts/archive-ios.sh all # archive with automatic signing + export of the IPA → dist/ios-export/
scripts/archive-ios.sh validate # altool --validate-app
scripts/archive-ios.sh upload # altool --upload-app (TestFlight)State on 2026-11-18: app record 6836594820 "SP Lecture Studio", primary language fr-CA, categories Education /
Productivity; build 1.0.0 (1) validated, uploaded and processed (state VALID). Left to the owner: add the build to an
internal TestFlight group and install it on a real iPhone / iPad; screenshots, age rating, privacy policy URL and App Privacy
answers; confirm the export-compliance answer. Nothing was submitted for review.
Increase CURRENT_PROJECT_VERSION in Apps/LectureStudio/project.yml before each upload.
Checklist before a public release
scripts/build-all.sh && scripts/test-all.sh --long --ui, andscripts/test-ui.sh macwith the screen unlocked.- The hardware checks listed in
docs/QA.md("Never verified"). - Bump versions, archive both platforms, notarize, upload.
Details: docs/RELEASE.md.
🧯 Gotchas
- macOS 27:
List(selection:)does not select rows, andNavigationSplitView/HSplitViewmis-size their detail column → the app uses button rows and plainHStack+Divider. Pass models as parameters;@Environment(Model.self)crashes in sheets, toolbars and menus. - A system type named
LibraryItemexists: always writeLectureStorage.LibraryItemin the app. AVAudioFilefinalizes its header only onclose(); a checksum taken before that is wrong.AVAssetWriterwrites side files next to its output; exports run in a private scratch folder that is removed afterwards.- PencilKit: the tool palette floats above sheets unless it is hidden; on iPhone it reports no obscured frame, so 72 pt is
reserved; on iPad page navigation sits above the slide.
PKStrokehas no identifier: strokes are matched by (creation date, random seed, point count, transform). - Recording state callbacks from
RecordingEnginearrive asynchronously on the main queue;ProjectSessionmirrorsengine.stateimmediately afterpause/resume/start. - Sandboxed Mac debug builds must always be signed by the team (never ad hoc): a signature change on the same bundle ID makes macOS hold the launch behind an app-data consent prompt. GUI launches and UI tests also hang while the Mac screen is locked.
- Lazy rows on macOS: a helper function does not observe the session → one real
Viewper row (thumbnails stayed blank otherwise). set -o pipefail+grep -qon a pipe gives false failures in scripts (SIGPIPE): capture into a variable first.- Build outside
~/Desktop. - UI strings are French in code; after adding strings run a build, then
scripts/localize.py, and add the English toscripts/translations-en.json.
🗺 Status and known limitations
From PROGRESS.md and docs/QA.md (session of 2026-11-18).
| Phase | State |
|---|---|
| 0 — audit · 1 — scaffold · 2 — PDF and ink · 3 — recording · 4 — render · 5 — editing | done |
| 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 |
| 7 — release | partial: macOS notarized; iOS uploaded to App Store Connect; French + English; accessibility labels on controls. Not done: VoiceOver pass, real-device stress |
Not implemented: Mac screen / window capture, device-to-device sync UI (only the encrypted bundle and upload building blocks), transcript-based AI cut suggestions.
Never verified (needs hardware or a person): any real iPhone or iPad; Apple Pencil (pressure, tilt, hover, palm rejection); device microphones and cameras; lock screen and background recording on a device; incoming-call interruption and Bluetooth route changes on a device; thermal and battery behaviour over a long session; the camera path end to end; on-device speech recognition; the remote transcription and upload clients against real servers; on macOS the shape tools, eraser, laser pointer, zoom / pan gestures, menus and keyboard shortcuts, a second window, the presentation window on a second display; VoiceOver; Dynamic Type at large sizes; the Intel slice of the universal binary; 1080p / 4K export time on a real 90-minute lecture; disk-full during export.
Platform limits: on iOS / iPadOS recording continues in the background through the audio background mode; the camera
cannot run in the background; 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.
Next actions for the owner: record a real 10-minute lecture on the Mac with the notarized app; install the TestFlight build on a real iPad with Apple Pencil and a real iPhone; try the camera, on-device transcription and the lock-screen / phone-call cases; decide whether to publish the Mac DMG.
📚 Documentation
| Document | Content |
|---|---|
docs/ARCHITECTURE.md |
capability matrix, layers, key decisions, honest limits of the platforms |
docs/PROJECT_FORMAT.md |
the .slecture package, timebase, manifest, events, edits |
docs/RECORDING_PIPELINE.md |
capture chain, automatic pause and stop, crash recovery |
docs/EXPORT_PIPELINE.md |
render chain, determinism, audio finishing, measurements |
docs/SECURITY.md |
data, permissions, sandbox and signing, optional network features |
docs/QA.md |
what was tested, how, and what was not |
docs/RELEASE.md |
macOS notarization, App Store Connect, checklist |
PROGRESS.md |
phase checklist, commands and results, bugs found by the tests |
CLAUDE.md |
mission, rules, pitfalls |
👤 Author
Simon-Pierre Boucher — design, development, operations
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
📄 License
All rights reserved © 2026 Simon-Pierre Boucher.