- Swift 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
A Pro Max iPhone in landscape is wider than 900 points, so once the rotation finished first the test expected a two-page spread the app only shows on iPad. |
||
| docs | ||
| Resources | ||
| ScoreReader.xcodeproj | ||
| scripts | ||
| Sources | ||
| Tests | ||
| UITests | ||
| .gitignore | ||
| Info.plist | ||
| project.yml | ||
| README.md | ||
eaScore
Native iPad-first, iPhone-compatible offline PDF score reader. iOS 17+, SwiftUI + UIKit + PDFKit + PencilKit. English and Simplified Chinese. No packages, cloud services or accounts.
Build and test
Open ScoreReader.xcodeproj, select the ScoreReader scheme and an iPad or iPhone simulator, then Run/Test. Simulator builds require no signing. Signing is disabled in the shared configuration. Configure your own development team and provisioning locally for physical-device or distribution builds. The project and target retain their internal ScoreReader names. The checked-in project is ready to use; regeneration is optional (xcodegen generate, if already installed).
xcodebuild -project ScoreReader.xcodeproj -scheme ScoreReader \
-destination 'platform=iOS Simulator,id=<SIMULATOR_UDID>' \
-derivedDataPath build CODE_SIGNING_ALLOWED=NO build
xcodebuild -project ScoreReader.xcodeproj -scheme ScoreReader \
-destination 'platform=iOS Simulator,id=<SIMULATOR_UDID>' \
-derivedDataPath build CODE_SIGNING_ALLOWED=NO -parallel-testing-enabled NO test
Use xcodebuild -project ScoreReader.xcodeproj -scheme ScoreReader -showdestinations to choose a simulator and replace <SIMULATOR_UDID> above. Xcode 27.1 was used for validation. See docs/VALIDATION.md for actual results and limits.
This repository contains the authored application through 0.1.0 (3), including ordinary spreads, large bottom controls and the full-screen crop editor. Build 3 passed internal TestFlight processing on October 18, 2026; this Git publication creates no new release. Current recorded validation: 49/49 iPad and 13/13 selected iPhone UI cases passed. See docs/CROP-EDITOR.md, docs/VALIDATION.md and docs/TESTFLIGHT.md.
Source, project, localizations, tests, the generated app icon and technical documentation are included. Signing files, private account/distribution records, Library identifiers, local build/test artifacts and user PDFs are excluded and remain outside this checkout. See docs/REPOSITORY.md.
Use
- Add (+) imports from Files, from Photos, or scans pages with the camera. From Files, each PDF becomes its own score and the selected images (JPEG, HEIC, PNG) become one score in file-name order (page2 before page10). Photos keep the order they were picked in. The camera uses Apple's document scanner, which finds the page edges, straightens each shot and captures several pages into one score. Open In / Share to ScoreReader is also supported. An original generated five-page sample exercises the same copy/validation path.
- Photos and scans are converted to a PDF as they come in: each image becomes one page, reduced to at most 2800 pixels on its long edge, flattened onto white and stored as JPEG. Cropping, notes, spreads, previews and pedals then work exactly as on any PDF. Automatic trim on photos of grey paper or with shadows may keep the full page; scans trim better.
- The library shows a grid, a list, or a list with details (source, pages, date added, last page read and bookmarks); the choice is remembered. Long-press a score to rename it.
- Reading mode menu: single page, two pages, continuous scroll. Landscape iPad shows 1 left / 2 right, then 3 / 4. One-page scores and odd final pages are centered and fitted using the full reading area. iPhone and portrait use one page. Switching modes preserves the physical anchor page and its notes.
- Tap anywhere in the left/right bottom control regions to turn backward/forward; the centered page counter and separate performance × never turn pages. Subtle regions adapt to light/dark appearance, show pressed/disabled states, and provide at least 44pt targets above the home indicator. Small arrows remain visible. Swipes also turn pages. Pinch to zoom. In annotation mode, draw with Apple Pencil and pan with two fingers. Finger drawing is an explicit Settings option (on automatically in UI tests). The red pen, whole-stroke eraser and per-resident-page undo use PencilKit.
- Settings maps previous/next to keyboard HID keys. Duplicate assignments swap. Separate rapid key presses each count; repeat down events while held do not. This supports keyboard-style pedals without assuming a preferred foot.
- Bookmark saves the current anchor page; bookmark list jumps to it. Preview shows the next page outside the score surface. Perform hides editing tools and keeps the display awake while active. The visible × exits; page controls remain in a slim footer.
- Language: follow system (default), English, 简体中文. Updates immediately; imported titles keep their original text.
Storage and architecture
Application Support/Scores/library.json is an atomically written index. A library from the first builds in Documents/Scores is moved there once at launch, so Files shows only the user's own documents. Each UUID directory holds unchanged original.pdf and page-N.drawing PencilKit sidecars (zero-based N). PDFs are coordinated/copied/validated off the UI thread; metadata commits on the main actor. Password-locked and invalid PDFs are rejected. A corrupt drawing is preserved and its page is protected from editing. A damaged index is copied aside (library.damaged-*.json) and rebuilt from readable entries and the score folders; an index that cannot be read at all is never overwritten, and imports pause until it can be. Missing newer fields in an older index fall back to defaults.
Ink is saved after every stroke: the drawing is serialized on the main actor and written by one ordered background writer. A page whose ink is not yet on disk is never evicted, crop protection only runs against saved ink, and closing the reader with unsaved ink asks to retry or discard. Continuous-scroll position is written once scrolling settles; page turns, closing and backgrounding write it immediately.
Each page uses fixed 768-point-wide coordinates derived from its crop box and intrinsic PDF rotation. PDF vector tiles and PencilKit share those bounds. The containing scroll view fits/transforms/zooms the entire surface, so ink data is independent of view mode and device size. Paged modes retain at most four page surfaces, including nearby pages; continuous mode retains only visible pages plus a 35% viewport neighbor margin so short trimmed pages never disappear; thumbnail NSCache is capped at 12 MiB / 16 images. Memory warnings clear the thumbnail cache. Undo is in-memory and scoped to retained pages; drawings persist independently.
Originals and sidecars are local files (included in normal device backups). There is no cloud sync, annotated PDF export, library deletion, audio following, OMR, recording or scoring yet. IMSLP is an official link; users choose and import their own authorized PDFs.
The sample PDF is newly generated in DemoScore.swift, with no external sheet-music assets. Tests generate their own fixtures. No personal or paid sheet-music files are included.
Trim margins / 裁白边
Open the crop icon for a full-screen editor. The complete original page and saved notes stay visible, with a translucent mask outside the proposed area. Drag any of four edge handles or four corner handles; 48pt touch regions and an offset magnified detail help precise positioning. The page selector identifies the physical page being edited and leaves the reader's stored anchor unchanged.
Detection, manual moves and restoration are drafts. Apply to page saves only the selected page. Apply to score uses the same percentages for all pages, or the staged per-page areas after a score-wide detection/restore. The … menu contains Auto trim score and Restore all pages. Detection and score application show progress and can be cancelled. Closing with Cancel discards unapplied work; already applied changes remain saved. Restoring is also a draft until applied.
裁边会进入全屏编辑器,显示完整原谱和已有批注。直接拖动四边或四角,裁去部分以半透明遮罩显示,拖动时提供偏离手指的放大细节。上方页码明确当前编辑哪一页,不改变阅读位置。手动调整、自动检测和还原均先作为草稿,应用本页只保存当前页,应用全谱保存全谱范围;全谱自动检测和全部还原在“…”菜单中。取消关闭不会保存尚未应用的修改。
Trimming stores an independent versioned cropping.json beside each original. It does not edit the PDF crop box or rewrite drawings. Existing v1 PDF-to-canvas mapping is preserved exactly, including its centered layout for small PDFs, so older notes need no migration. The reader clips a window in that unchanged coordinate space, then uniformly scales the selected area. The next-page thumbnail maps from canonical canvas coordinates back to the actual PDF thumbnail coordinates.
Automatic suggestions use one grayscale raster of at most 1536 pixels on its long edge (<=2.25 MiB), generated off the UI actor. Include gray values below 250/255, including isolated components, and pad bounds by at least 2% per edge / 12 raster pixels. Blank or ambiguous/background-filled scans fall back to the full view. Very faint/tiny details can still be missed: review the preview and adjust manually. Saved ink bounds expand every crop with 8 canonical points of padding; unreadable notes block new cropping, while restoring the full view remains safe. New ink extending outside a trimmed window also expands it when the tool lifts.
Each page is fitted independently without changing aspect ratio. Screen/page proportions may leave dark surrounding space; removing all such space would require stretching or cutting content. No empty cover slot is reserved. Performance mode reduces the external margin to 2 points and the spread gutter to 4 points.
See docs/CROP-EDITOR.md for the full-screen editor acceptance, implementation and final 49/49 iPad + 13/13 selected iPhone UI validation. docs/CROPPING.md retains the earlier crop-storage work.
See docs/SPREAD-FIX.md for the build 2 first-spread correction, the reproduced black-half screen, and actual rendered-page regression checks.