Skip to content

FAQ.md

Latest commit

 

History

History
298 lines (200 loc) · 10 KB

FAQ.md

File metadata and controls

298 lines (200 loc) · 10 KB
Raw

Frequently Asked Questions (FAQ)

General Questions

What is Legible?

Legible is a tool that synchronizes documents from your reMarkable tablet to your computer and optionally adds OCR (Optical Character Recognition) to make handwritten notes searchable.

Do I need a reMarkable subscription?

You need reMarkable's free cloud sync feature enabled on your tablet. A reMarkable Connect subscription is not required, only the standard cloud sync that comes with every device.

Is this an official reMarkable product?

No, this is an independent open-source project. It uses the reMarkable cloud API but is not affiliated with or endorsed by reMarkable AS.

Does this work with reMarkable 1 and reMarkable 2?

Yes, it works with both reMarkable 1 and reMarkable 2 tablets, as long as cloud sync is enabled.

Installation and Setup

Do I need to install anything on my reMarkable tablet?

No! This tool runs entirely on your computer and syncs through the reMarkable cloud. No tablet modifications required.

Can I use this without Ollama?

Yes! OCR is optional. You can sync and convert documents without OCR by using the --no-ocr flag. However, without OCR, your handwritten notes won't be searchable. Ollama is only required if you want searchable PDFs with text layers.

How do I authenticate with my reMarkable account?

  1. Run legible auth
  2. The tool will prompt you to visit https://my.remarkable.com/device/desktop/connect
  3. Copy the 8-character one-time code displayed on the website
  4. Enter the code when prompted in the terminal
  5. Your device will be registered and the token saved automatically

Where are my authentication credentials stored?

By default, credentials are stored in ~/.legible/token.json. This file contains your device token and should be kept secure.

Usage Questions

How often does the daemon sync?

By default, every 5 minutes. You can change this with --interval:

legible daemon --interval 15m  # Every 15 minutes
legible daemon --interval 1h   # Every hour

Can I sync only specific documents?

Yes! Use labels in the reMarkable app to organize your documents, then sync specific labels:

legible sync --labels "work,personal"

Does syncing modify my reMarkable documents?

No, syncing is read-only. It downloads copies of your documents but never modifies or uploads anything back to your reMarkable.

What format are the synced documents?

Documents are converted to PDF format. OCR-enabled PDFs have an invisible text layer that makes them searchable while preserving the original appearance.

Can I sync to Dropbox/Google Drive/etc?

Yes! Just specify your cloud storage folder as the output directory:

legible sync --output ~/Dropbox/ReMarkable

How much disk space do I need?

Typically 2-3x the size of your reMarkable documents. OCR adds a text layer which increases file size. A 1MB handwritten notebook might become a 2-3MB searchable PDF.

Technical Questions

How does OCR work?

  1. The PDF pages are rendered as images
  2. Images are sent to Ollama's vision models (like llava) which analyze and extract text
  3. The AI model provides superior handwriting recognition compared to traditional OCR
  4. The extracted text with positional information is added as an invisible layer to the PDF
  5. The result is a searchable PDF that looks identical to the original

Why Ollama instead of Tesseract?

Ollama uses modern vision-language models (VLMs) that provide significantly better handwriting recognition compared to Tesseract, which is optimized for printed text:

  • Accuracy: 85-95% for handwriting vs 40-60% with Tesseract
  • Context awareness: Models understand document structure
  • Language flexibility: Handles multiple languages without explicit configuration
  • Local processing: All OCR happens on your machine, preserving privacy

Why is syncing slow?

OCR is CPU-intensive and processes each page individually. Factors affecting speed:

  • Document size (more pages = longer processing)
  • System resources (CPU speed, available RAM)
  • OCR complexity (handwriting is slower than typed text)

Typical speeds: 2-5 seconds per page on a modern laptop.

Can I speed up syncing?

Yes:

  • Skip OCR: --no-ocr (much faster, but not searchable)
  • Use incremental sync: Only new/modified documents are processed
  • Reduce sync frequency in daemon mode
  • Run on a faster machine with more CPU cores

What languages does OCR support?

Ollama vision models automatically detect and handle multiple languages without explicit configuration. The models support:

  • All major European languages (English, Spanish, French, German, Italian, etc.)
  • Asian languages (Chinese, Japanese, Korean)
  • And many more

No additional language packs or configuration needed! The model handles language detection automatically.

Can I use a different Ollama model?

Yes! Configure the model in ~/.legible.yaml:

ollama:
  model: llava        # Default: fast and good quality
  # model: llava:13b  # Larger model, better accuracy, slower
  # model: mistral    # Alternative vision model

Available models:

  • llava - Recommended, good balance of speed and accuracy
  • llava:13b - Larger model for best accuracy
  • mistral - Alternative vision model
  • Any Ollama model with vision capabilities

Download a new model: ollama pull llava:13b

How much disk space does Ollama need?

Approximately 8-10GB for Ollama + a vision model like llava. This is a one-time download that's cached locally.

Does this work offline?

No, Legible requires internet access to sync with the reMarkable cloud. However, once documents are synced, you can view them offline.

Privacy and Security

Is my data secure?

  • Your authentication token is stored locally with restricted permissions (0600)
  • Communication with reMarkable cloud uses HTTPS
  • No data is sent to third parties
  • Documents are stored locally on your computer

What data does this tool collect?

None. This tool does not collect, transmit, or store any analytics or telemetry. All data stays on your computer.

Can I audit the code?

Yes! This is open-source software. You can review the code on GitHub: https://github.com/platinummonkey/legible

Troubleshooting

"Authentication failed" error

Solution:

  1. Ensure cloud sync is enabled on your reMarkable (Settings → Storage → Connect)
  2. Get a fresh authentication code
  3. Clear old credentials: rm -rf ~/.legible
  4. Re-authenticate: legible auth

OCR produces garbage text or low-quality results

Possible causes:

  • Model not suited for the handwriting style
  • Complex or unclear handwriting
  • Very small text or dense writing

Solutions:

  • Try a more capable model: mistral-small3.1 or llava:13b for better accuracy 
    # Download better model
ollama pull mistral-small3.1

# Update config
# ~/.legible.yaml:
#   ollama:
#     model: mistral-small3.1
  • Verify Ollama is running properly: ollama list
  • Check Ollama logs for errors
  • Try without OCR if quality is unacceptable: --no-ocr

Daemon keeps stopping

Common causes:

  1. Out of memory: OCR is memory-intensive
    • Solution: Reduce sync frequency or skip OCR
  2. Permission errors: Can't write to output directory
    • Solution: Check directory permissions
  3. Disk full: No space for new documents
    • Solution: Free up disk space

Check logs:

legible daemon --log-level debug

Syncing takes forever on first run

This is normal! The first sync processes all your documents. Subsequent syncs are much faster as only new/changed documents are processed.

Estimates:

  • 10 documents: 30-60 seconds
  • 50 documents: 3-5 minutes
  • 100+ documents: 10-20 minutes

Use --no-ocr for a much faster first sync, then enable OCR later.

"document not found" error

Causes:

  • Document was deleted from reMarkable cloud
  • Sync state is out of date
  • Document hasn't synced to cloud yet

Solutions:

  • Force re-sync: legible sync --force
  • Wait for cloud sync to complete on your tablet
  • Check document still exists in reMarkable app

Advanced Usage

Can I run multiple instances?

Yes, but use different output directories and state files:

# Instance 1: Work documents
legible daemon --output ~/work-remarkable --labels work

# Instance 2: Personal documents
legible daemon --output ~/personal-remarkable --labels personal

How do I run as a system service?

See examples/systemd/legible.service for a systemd service file template.

Can I customize the output filenames?

Currently, filenames match your reMarkable document names. Customization would require forking the project.

Is there an API or library I can use?

The internal packages in internal/ are available for use, but they are not considered a stable public API and may change between versions.

Can I contribute features?

Yes! See CONTRIBUTING.md for guidelines on contributing.

Comparison with Other Tools

How is this different from rmapi?

rmapi is a lower-level tool for accessing the reMarkable cloud. Legible builds on rmapi to provide:

  • Automatic PDF conversion
  • OCR text layer addition
  • Daemon mode for continuous sync
  • State tracking for incremental updates

Why not use the reMarkable desktop app?

The official reMarkable desktop app is great, but doesn't offer:

  • OCR for searchable text
  • Automated background sync
  • Bulk export
  • Label-based filtering
  • Command-line interface for automation

Still Have Questions?

Useful Links