⚠️
remarks
does NOT work with annotations created by reMarkable sofware >= 3.0 yet. Follow issue #58 for updates ⚠️
Extract annotations (text highlights and scribbles) and convert them to Markdown
, PDF
, PNG
, and SVG
.
remarks
works with documents annotated on reMarkable™ paper tablets — both 1st and 2nd generation — up to software version 2.15.0.1067
.
Note that remarks
not only is highly experimental, it is very likely to break after you update the software of your tablet. I might find some spare time to continue to maintain it, but I make no promises.
remarks
code is fairly straightforward but not elegant at all. It has been put together in a couple of hours. You are free to fork and run with it though ;)
Most of the actual heavy lifting has been done by the open source community and PyMuPDF. See Credits and Acknowledgements.
In: PDF highlighted on reMarkable → Out: PDF with parseable highlights
Someone who highlights lots of PDFs (e.g., researchers, academics, etc) can export their highlights for processing with a reference management tool, like Zotero (e.g., issue #2).
Extract highlighted text from PDF to Markdown
Infovores of the world can export highlighted text to Markdown and insert them into their preferred "tool for networked thought", like Obsidian or Roam Research.
Export annotated PDF pages to full-page images
Sometimes having just the textual content is not enough, sometimes you need the actual (visual) context around your annotation. To help you in such situations, remarks
can export each annotated PDF page to a PNG image file. Images can be easily uploaded or embedded anywhere, from personal websites to "tools for networked thought".
Highlight and annotate PDFs with your Marker on your reMarkable tablet:
And then use remarks
to export annotated pages to Markdown
, PDF
, PNG
, or SVG
on your computer:
WHAT IS LIFE?
Based on lectures delivered under the auspices of the Dublin Institute for Advanced Studies at Trinity College, Dublin, in February 1943
To the memory of My Parents
Because remarks
depends only on PyMuPDF and Shapely, there is no need to install imagemagick
, opencv
, or any additional image library. Both PyMuPDF and Shapely have pre-built wheels for several platforms (macOS, Linux, Windows) and recent Python 3 versions, so installing them should be smooth and easy for most people.
I currently use remarks
with reMarkable 1 and reMarkable 2 tablets running software versions 2.14.3.1047
and 2.15.0.1067
on macOS Ventura (13.2.1
) with CPython 3.10.9
. I don't have other equipment to test it thoroughly, but I expect remarks
to work just fine in all common setups.
Incidentally, help the community keeping track of remarks
compatibility across different setups:
If OCRmyPDF is available on your computer, remarks
may (optionally) use it to OCR PDFs before extracting their highlighted text.
To get remarks
up and running on your local machine, follow the instructions below:
In order to reconstruct your highlights and annotations, remarks
relies on specific files that are created by the reMarkable device as you use it. Because these specific files are internal to the reMarkable device, first we need to transfer them to your computer.
There are several options for getting them to your computer. Find below some suggestions. Choose whatever fits you:
Use rsync
(i)
Check out the repository @lucasrla/remarkable-utils for the SSH & rsync
setup I use (which includes automatic backups based on cron
).
Use scp
(i)
On your reMarkable tablet, go to Menu > Settings > Help
, then under About
tap on Copyrights and licenses
. In General information
, right after the section titled "GPLv3 Compliance", there will be the username (root
), password and IP address needed for SSH
ing into it. Using these credentials, scp
the contents of /home/root/.local/share/remarkable/xochitl
from your reMarkable to a directory on your computer. (Copying may take a while depending on the size of your document collection and the quality of your WiFi network.) To prevent any unintented interruptions, you can (optionally) switch off the Auto sleep
feature in Menu > Settings > Battery
before transferring your files.
Use @juruen/rmapi or @subutux/rmapy
Both are free and open source software that allow you to access your reMarkable tablet files through reMarkable's cloud service.
Copy from reMarkable's official desktop application
If you have a reMarkable's official desktop app installed, most of the files we need are already easily available on your computer. For macOS users, the files are located at ~/Library/Application\ Support/remarkable/desktop
. To avoid interfering with reMarkable's official app, copy and paste all the contents of ~/Library/Application\ Support/remarkable/desktop
to another directory (one that you can safely interact with – say, ~/Documents/remarkable/docs
). Please note that this method won't allow you to use remarks' EPUB functionality. That's because this directory doesn't seem to include the PDF files that reMarkable auto converts your EPUBs to.
### 2.1 Clone
git clone https://github.com/lucasrla/remarks.git && cd remarks
### 2.2 Create and activate a virtual environment
# If you're using poetry, a new virtual env should be created automatically (as set forth in our `poetry.toml`)
# But feel free to manage your virtual env needs with any of the alternatives (e.g. virtualenv, virtualenvwrapper, etc)
### 2.3 Install the dependencies
# Install dependencies with:
poetry install
Run remarks
and check out what arguments are available:
python -m remarks --help
Next, for a quick hands-on experience of remarks
, run the demo:
# Alan Turing's 1936 foundational paper (with a few highlights and scribbles)
# Original PDF file downloaded from:
# "On Computable Numbers, with an Application to the Entscheidungsproblem"
# https://londmathsoc.onlinelibrary.wiley.com/doi/abs/10.1112/plms/s2-42.1.230
python -m remarks demo/on-computable-numbers/xochitl remarks-example/ --per_page_targets png md pdf --modified_pdf
A few other examples:
# Assuming your `xochitl` files are at `~/backups/remarkable/xochitl/`
python -m remarks ~/backups/remarkable/xochitl/ example_1/ --ann_type highlights --per_page_targets md
python -m remarks ~/backups/remarkable/xochitl/ example_2/ --per_page_targets png
Run pytest
in the root directory of the project after installing the dependencies using poetry
. This will create files in the tests/out
directory. The contents of this directory can safely be deleted.
Example:
python -m pytest -q remarks/test_initial.py
.. [100%]
2 passed in 2.51s
ls tests/out
1936 On Computable Numbers, with an Application to the Entscheidungsproblem - A. M. Turing _highlights.md
Gosper _remarks.pdf
1936 On Computable Numbers, with an Application to the Entscheidungsproblem - A. M. Turing _remarks.pdf
@JorjMcKie who wrote and maintains the great PyMuPDF
u/stucule who posted to r/RemarkableTablet the first account (that I could find online) about reverse engineering .rm
files
@ax3l who wrote lines-are-rusty / lines-are-beautiful and also contributed to reverse engineering of .rm
files
@edupont, @Liblor, @florian-wagner, and @jackjackk for their contributions to rM2svg
@ericsfraga, @jmiserez, @peerdavid, @phill777 and @lschwetlick for updating rM2svg to the most recent .rm
format
@lschwetlick who wrote rMsync and also two blog posts about reMarkable-related software [1, 2]
@soulisalmed who wrote biff
@benlongo who wrote remarkable-highlights
For more reMarkable resources, check out awesome-reMarkable and remarkablewiki.com.
remarks
is Free Software distributed under the GNU General Public License v3.0.
This is a hobby project of an enthusiastic reMarkable user. There is no warranty whatsoever. Use it at your own risk.
The author(s) and contributor(s) are not associated with reMarkable AS, Norway. reMarkable is a registered trademark of reMarkable AS in some countries. Please see https://remarkable.com for their products.