{"id":13478555,"url":"https://github.com/lucasrla/remarks","last_synced_at":"2025-09-13T16:58:42.916Z","repository":{"id":38385777,"uuid":"282545736","full_name":"lucasrla/remarks","owner":"lucasrla","description":"Extract annotations (highlights and scribbles) from PDF, EPUB, and notebooks marked with reMarkable tablets. Export to Markdown, PDF, PNG, SVG","archived":false,"fork":false,"pushed_at":"2024-05-26T15:23:01.000Z","size":3984,"stargazers_count":371,"open_issues_count":17,"forks_count":24,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-25T08:07:51.886Z","etag":null,"topics":["annotations","epub","highlighting","markdown","obsidian","ocr","ocrmypdf","pdf","pdf-converter","pymupdf","remarkable-tablet","roamresearch","svg-images","zotero"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucasrla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-26T00:08:46.000Z","updated_at":"2025-05-06T12:48:18.000Z","dependencies_parsed_at":"2023-01-31T09:01:17.470Z","dependency_job_id":"46266d5f-5553-40ce-81c6-b316d099a82e","html_url":"https://github.com/lucasrla/remarks","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lucasrla/remarks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasrla%2Fremarks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasrla%2Fremarks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasrla%2Fremarks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasrla%2Fremarks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucasrla","download_url":"https://codeload.github.com/lucasrla/remarks/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasrla%2Fremarks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274997468,"owners_count":25387932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotations","epub","highlighting","markdown","obsidian","ocr","ocrmypdf","pdf","pdf-converter","pymupdf","remarkable-tablet","roamresearch","svg-images","zotero"],"created_at":"2024-07-31T16:01:58.678Z","updated_at":"2025-09-13T16:58:42.867Z","avatar_url":"https://github.com/lucasrla.png","language":"Python","funding_links":[],"categories":["Python","Other","markdown","remarkable-tablet"],"sub_categories":["Launchers"],"readme":"# remarks\n\n\u003e ⚠️ `remarks` does NOT work with annotations created by reMarkable sofware \u003e= 3.0 yet. [Follow issue #58 for updates](https://github.com/lucasrla/remarks/issues/58) ⚠️\n\nExtract annotations (text highlights and scribbles) and convert them to `Markdown`, `PDF`, `PNG`, and `SVG`. \n\n`remarks` works with documents annotated on [reMarkable™ paper tablets](https://remarkable.com) \u0026mdash; both 1st and 2nd generation \u0026mdash; up to software version `2.15.0.1067`.\n\nNote 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.\n\n`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 ;)\n\nMost of the actual heavy lifting has been done by the open source community and PyMuPDF. See [Credits and Acknowledgements](#credits-and-acknowledgements).\n\n\n## Some use cases\n\n- **In: PDF highlighted on reMarkable → Out: PDF with parseable highlights**  \nSomeone who highlights lots of PDFs (e.g., researchers, academics, etc) can export their highlights for processing with a reference management tool, like [Zotero](https://www.zotero.org) (e.g., [issue #2](https://github.com/lucasrla/remarks/issues/2#issuecomment-732166093)).\n\n- **Extract highlighted text from PDF to Markdown**  \nInfovores of the world can export highlighted text to [Markdown](https://en.wikipedia.org/wiki/Markdown) and insert them into their preferred \"tool for networked thought\", like [Obsidian](https://obsidian.md/) or [Roam Research](https://roamresearch.com).\n\n- **Export annotated PDF pages to full-page images**  \nSometimes 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](https://en.wikipedia.org/wiki/Portable_Network_Graphics) image file. Images can be easily uploaded or embedded anywhere, from personal websites to \"tools for networked thought\".\n\n\n## A visual example\n\nHighlight and annotate PDFs with your Marker on your reMarkable tablet: \n\n\u003c!-- How to host images on GitHub but outside your repository? Open an issue, upload your images, and voila! Trick learned from http://felixhayashi.github.io/ReadmeGalleryCreatorForGitHub/ --\u003e\n\n\u003cimg width=\"300\" alt=\"IMG_0642-low.jpg\" src=\"https://user-images.githubusercontent.com/1920195/88480247-3d776680-cf2b-11ea-9c30-061ec0e5cc60.jpg\"\u003e\n\nAnd then use `remarks` to export annotated pages to `Markdown`, `PDF`, `PNG`, or `SVG` on your computer:\n\n\u003cimg width=\"300\" alt=\"demo-remarks-png.png\" src=\"https://user-images.githubusercontent.com/1920195/88480249-410aed80-cf2b-11ea-919b-22fb550ed9d7.png\"\u003e\n\n\u003e \u003cmark\u003eWHAT IS LIFE?\u003c/mark\u003e\n\u003e \n\u003e Based on lectures delivered under the auspices of the \u003cmark\u003eDublin Institute for\u003c/mark\u003e \u003cmark\u003eAdvanced Studies at Trinity College,\u003c/mark\u003e Dublin, in February 1943\n\u003e \n\u003e \u003cmark\u003eTo\u003c/mark\u003e\n\u003e \u003cmark\u003ethe memory of My\u003c/mark\u003e \u003cmark\u003eParents\u003c/mark\u003e\n\n\n## Compatibility and dependencies\n\nBecause `remarks` depends only on [PyMuPDF](https://github.com/pymupdf/PyMuPDF) and [Shapely](https://github.com/shapely/shapely), there is no need to install `imagemagick`, `opencv`, or any additional image library. Both PyMuPDF and Shapely have [pre-built](https://pypi.org/project/PyMuPDF/#files) [wheels](https://pypi.org/project/Shapely/#files) for several platforms (macOS, Linux, Windows) and recent Python 3 versions, so installing them should be smooth and easy for most people.\n\nI currently use `remarks` with [reMarkable 1](https://remarkable.com/store/remarkable) and [reMarkable 2](https://remarkable.com/store/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.\n\nIncidentally, help the community keeping track of `remarks` compatibility across different setups:\n\n- If it is working well for you, [make a quick comment with your setup](https://github.com/lucasrla/remarks/discussions/8)\n- If you run into any problems, [raise an issue](https://github.com/lucasrla/remarks/issues/new/choose)\n\nIf [OCRmyPDF](https://github.com/ocrmypdf/OCRmyPDF) is available on your computer, `remarks` may (optionally) use it to OCR PDFs before extracting their highlighted text.\n\n\n## Setup\n\nTo get `remarks` up and running on your local machine, follow the instructions below:\n\n### 1. Copy reMarkable's \"raw\" document files to your computer\n\nIn 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.\n\nThere are several options for getting them to your computer. Find below some suggestions. Choose whatever fits you:\n\n- **Use `rsync`** ([i](https://en.wikipedia.org/wiki/Rsync))  \n  Check out the repository [@lucasrla/remarkable-utils](https://github.com/lucasrla/remarkable-utils) for the SSH \u0026 `rsync` setup I use (which includes automatic backups based on `cron`). \n\n- **Use `scp`** ([i](https://en.wikipedia.org/wiki/Secure_copy_protocol))  \n  On your reMarkable tablet, go to `Menu \u003e Settings \u003e 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 \u003e Settings \u003e Battery` before transferring your files.\n\n- **Use [@juruen/rmapi](https://github.com/juruen/rmapi) or [@subutux/rmapy](https://github.com/subutux/rmapy)**  \n  Both are free and open source software that allow you to access your reMarkable tablet files through reMarkable's cloud service.\n\n- **Copy from reMarkable's official desktop application**  \n  If you have a [reMarkable's official desktop app](https://support.remarkable.com/s/article/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](https://github.com/lucasrla/remarks/pull/34).\n\n### 2. Clone this repository and install the dependencies\n\n```sh\n### 2.1 Clone\ngit clone https://github.com/lucasrla/remarks.git \u0026\u0026 cd remarks\n\n\n### 2.2 Create and activate a virtual environment\n\n# If you're using poetry, a new virtual env should be created automatically (as set forth in our `poetry.toml`)\n# But feel free to manage your virtual env needs with any of the alternatives (e.g. virtualenv, virtualenvwrapper, etc)\n\n\n### 2.3 Install the dependencies\n\n# Install dependencies with:\npoetry install\n```\n\n\n## Usage and Demo\n\nRun `remarks` and check out what arguments are available:\n\n```sh\npython -m remarks --help\n```\n\nNext, for a quick hands-on experience of `remarks`, run the demo:\n\n```sh\n# Alan Turing's 1936 foundational paper (with a few highlights and scribbles)\n\n# Original PDF file downloaded from:\n# \"On Computable Numbers, with an Application to the Entscheidungsproblem\"\n# https://londmathsoc.onlinelibrary.wiley.com/doi/abs/10.1112/plms/s2-42.1.230\n\npython -m remarks demo/on-computable-numbers/xochitl remarks-example/ --per_page_targets png md pdf --modified_pdf\n```\n\nA few other examples:\n\n```sh\n# Assuming your `xochitl` files are at `~/backups/remarkable/xochitl/`\n\npython -m remarks ~/backups/remarkable/xochitl/ example_1/ --ann_type highlights --per_page_targets md\n\npython -m remarks ~/backups/remarkable/xochitl/ example_2/ --per_page_targets png\n```\n\n\n## Tests\n\nRun `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.\n\nExample:\n\n```sh\npython -m pytest -q remarks/test_initial.py\n..                                         [100%]\n2 passed in 2.51s\n\nls tests/out\n  1936 On Computable Numbers, with an Application to the Entscheidungsproblem - A. M. Turing _highlights.md  \n  Gosper _remarks.pdf\n  1936 On Computable Numbers, with an Application to the Entscheidungsproblem - A. M. Turing _remarks.pdf\n```\n\n\n## Credits and Acknowledgements\n\n- [@JorjMcKie](https://github.com/JorjMcKie) who wrote and maintains the great [PyMuPDF](https://github.com/pymupdf/PyMuPDF)\n\n- [u/stucule](https://www.reddit.com/user/stucule/) who [posted to r/RemarkableTablet](https://www.reddit.com/r/RemarkableTablet/comments/7c5fh0/work_in_progress_format_of_the_lines_files/) the first account (that I could find online) about reverse engineering `.rm` files\n\n- [@ax3l](https://github.com/ax3l) who wrote [lines-are-rusty](https://github.com/ax3l/lines-are-rusty) / [lines-are-beautiful](https://github.com/ax3l/lines-are-beautiful) and also [contributed to reverse engineering of `.rm` files](https://plasma.ninja/blog/devices/remarkable/binary/format/2017/12/26/reMarkable-lines-file-format.html)\n\n- [@edupont, @Liblor, @florian-wagner, and @jackjackk for their contributions to rM2svg](https://github.com/reHackable/maxio/blob/33cdc1706b29698c15aac647619374e895ed3869/tools/rM2svg)\n\n- [@ericsfraga, @jmiserez](https://github.com/jmiserez/maxio/blob/ee15bcc86e4426acd5fc70e717468862dce29fb8/tmp-rm16-ericsfraga-rm2svg.py), [@peerdavid](https://github.com/peerdavid/rmapi/blob/master/tools/rM2svg), [@phill777](https://github.com/phil777/maxio) and [@lschwetlick](https://github.com/lschwetlick/maxio/blob/master/rm_tools/rM2svg.py) for updating rM2svg to the most recent `.rm` format\n\n- [@lschwetlick](https://github.com/lschwetlick) who wrote [rMsync](https://github.com/lschwetlick/rMsync) and also two blog posts about reMarkable-related software [[1](http://lisaschwetlick.de/blog/2018/03/25/reMarkable/), [2](http://lisaschwetlick.de/blog/2019/06/10/reMarkable-Update/)]\n\n- [@soulisalmed](https://github.com/soulisalmed) who wrote [biff](https://github.com/soulisalmed/biff)\n\n- [@benlongo](https://github.com/benlongo) who wrote [remarkable-highlights](https://github.com/benlongo/remarkable-highlights)\n\nFor more reMarkable resources, check out [awesome-reMarkable](https://github.com/reHackable/awesome-reMarkable) and [remarkablewiki.com](https://remarkablewiki.com/).\n\n\n## License\n\n`remarks` is [Free Software](https://www.gnu.org/philosophy/free-sw.html) distributed under the [GNU General Public License v3.0](https://choosealicense.com/licenses/gpl-3.0/).\n\n\n## Disclaimers\n\nThis is a hobby project of an enthusiastic reMarkable user. There is no warranty whatsoever. Use it at your own risk.\n\n\u003e 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasrla%2Fremarks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucasrla%2Fremarks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasrla%2Fremarks/lists"}