SPB Git

Repository Public

README.md 38.5 KB

SP Lecture Studio logo



SP Lecture Studio icon

# 🎓 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

version platforms offline license author

Swift SwiftUI Xcode XcodeGen SwiftPM PDFKit PencilKit AVFoundation video audio dependencies

commits last commit activity language languages size branches tags clones

Swift files Swift lines modules unit tests integration tests UI tests strings long test

bundle macOS bundle iOS signing universal sandbox App Store Connect


# Table of contents


# 🎯 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
PDF 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

  1. 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.
  2. The audio sample clock is the authority. RecordingClock is re-anchored on every audio buffer, so events cannot drift from audio however long the session. Without audio it runs on the host clock.
  3. State is a function of time. TimelineIndex answers "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.
  4. Edits are data. An EditDecisionList with a persisted undo / redo history. TimeMap converts between source and output time. Nothing ever rewrites media.
  5. Preview = export. The editor preview draws with FrameCompositor and plays audio pulled from EditedAudioRenderer, the same objects the exporter uses.
  6. 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.
  7. 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

text
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 results
Size 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

bash
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:

text
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 rebuilt
erDiagram
  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. Never Double seconds 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 audio only.
  • 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):

bash
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 → staple

State 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):

bash
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

  1. scripts/build-all.sh && scripts/test-all.sh --long --ui, and scripts/test-ui.sh mac with the screen unlocked.
  2. The hardware checks listed in docs/QA.md ("Never verified").
  3. Bump versions, archive both platforms, notarize, upload.

Details: docs/RELEASE.md.

# 🧯 Gotchas

  • macOS 27: List(selection:) does not select rows, and NavigationSplitView / HSplitView mis-size their detail column → the app uses button rows and plain HStack + Divider. Pass models as parameters; @Environment(Model.self) crashes in sheets, toolbars and menus.
  • A system type named LibraryItem exists: always write LectureStorage.LibraryItem in the app.
  • AVAudioFile finalizes its header only on close(); a checksum taken before that is wrong.
  • AVAssetWriter writes 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. PKStroke has no identifier: strokes are matched by (creation date, random seed, point count, transform).
  • Recording state callbacks from RecordingEngine arrive asynchronously on the main queue; ProjectSession mirrors engine.state immediately after pause / 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 View per row (thumbnails stayed blank otherwise).
  • set -o pipefail + grep -q on 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 to scripts/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.

Files main
Menu

Theme