Skip to content
SYYANIPublic

About

Freddie is a macOS paper reader with LLM translate

Resources

Stars

22 stars

Watchers

0 watching

Forks

Repository files navigation

Freddie

Freddie is a macOS paper reader built with SwiftUI. The app bundle name is Freddie, while the project name remain ReadPaper.

It focuses on three practical reading workflows:

  • import local PDFs with conservative metadata extraction
  • import arXiv papers by ID or URL and prefer HTML reading when available
  • translate papers through semantic HTML blocks or full-PDF BabelDOC output

Features

  • Local-first paper library backed by SwiftData
  • Local PDF import with lightweight metadata detection from PDF info and early pages
  • arXiv import with step-by-step progress feedback
  • arXiv HTML fallback chain: arxiv.org/html/{id} first, then ar5iv
  • Readability-based HTML extraction and localization for a cleaner reading view
  • Reversible region editing for imported HTML: hide leftover navigation, share bars, or other clutter one block at a time or a whole run with Shift-click, and restore it any time
  • Incremental HTML translation with per-block persistence and refresh
  • Multi-provider, multi-model OpenAI-compatible routing
  • Full PDF translation via BabelDOC with structured progress reporting
  • PDF, HTML, and dual-PDF reading modes in one app

Library sync

Mac, iPad and the cross-platform Freddie for Windows, Linux and macOS can sync the same paper library through a self-hosted Freddie Sync Server. Freddie ships without a default server: whoever deploys the server issues a credential file for each device, and you import it in Settings → Sync. Freddie shows the server address and asks before uploading anything. See the sync guide for setup, conflict handling, and what is synced.

Screenshots

Image

Requirements

  • macOS 14.0+
  • Xcode with Swift 6 support
  • xcodegen

Xcode resolves the Swift packages from their GitHub repositories. The selected branches are declared in project.yml; no sibling repository checkouts are required. The scripts/build command also downloads or builds the manifest-verified BabelDOC native runtime assets in Xcode's package checkout. Core ML conversion checks its pinned inputs and output structure, then records the generated model's SHA-256 in the bundled runtime manifest. The conversion output does not need to match a precomputed artifact hash.

create-dmg is only needed if you want to build a distributable DMG locally.

Getting Started

Clone the repository:

git clone <your-repo-url>
cd read-paper

Generate the Xcode project:

xcodegen generate

Open the project:

open ReadPaper.xcodeproj

Or build from the command line:

./scripts/build

The build script performs an unsigned Release build, verifies the embedded BabelDOC runtime and helper, and writes the app to build/Release/Freddie.app; compilation intermediates remain under /tmp/read-paper-derived-data, so the repository and release directory stay free of compilation intermediates. Run ./scripts/build --help for Debug builds, custom output paths, optional XcodeGen project regeneration, and Xcode signing options.

Run tests:

xcodebuild -project ReadPaper.xcodeproj -scheme ReadPaper -destination 'platform=macOS' -derivedDataPath /tmp/read-paper-derived-data test

Enable the repository's Git hooks once per clone:

git config core.hooksPath .githooks

The pre-commit hook increments the marketing version and build number together, then stages only those version fields in project.yml and the generated Xcode project. The patch component runs from 0 through 20, and the minor component runs from 0 through 9: 0.3.19 becomes 0.3.20, 0.3.20 becomes 0.4.0, and 0.9.20 becomes 1.0.0. To set an explicit version, change MARKETING_VERSION and CURRENT_PROJECT_VERSION together in project.yml; the hook preserves and stages that change even if project.yml was not staged yet.

Project Structure

  • ReadPaper/Models: SwiftData models and enums
  • ReadPaper/Views: app UI, library, inspector, settings
  • ReadPaper/Readers: PDF, HTML, and dual-PDF readers
  • ReadPaper/Services: import, arXiv, HTML localization, translation, BabelDOC, storage
  • ReadPaperTests: unit tests for import, storage, translation, routing, and subprocess behavior
  • project.yml: XcodeGen project definition

Notes on Scope

ReadPaper does not treat arbitrary PDF text extraction as a reliable full-document structure source.

  • Local PDFs are used for reading and lightweight metadata identification
  • arXiv papers prefer HTML as the structured reading and translation carrier
  • full PDF translation is delegated to BabelDOC

Data

Primary application data is stored under:

~/Library/Application Support/ReadPaper/

Key locations there:

  • ReadPaper.store: the SwiftData store for papers, attachments, translation cache, provider/model profiles, and app settings
  • Library/{paper UUID}/: per-paper files such as paper.pdf, paper.html, Resources/, translations/, and notes/
  • Tools/: legacy or optional app-managed external tool files

The native BabelDOC helper and its manifest-pinned MuPDF, zstd, layout model, and font runtime are bundled with the app; no separate runtime install step is required.

Even though the app bundle name is Freddie, the on-disk application support directory currently remains ReadPaper.

License

Copyright (c) 2026 SYYANI.

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). See LICENSE for the full license text.

Acknowledgements

Special thanks to the projects and ideas that helped shape ReadPaper:

About

Freddie is a macOS paper reader with LLM translate

Resources

Stars

22 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages