HandNote

by Yanzhe Shao
5
4
3
2
1
Score: 35/100

Description

Obsidian plugin for handwritten notes on iPad with Apple Pencil (also touch and mouse): on-device handwriting-to-text, LaTeX formulas, and hand annotation of PDF, Word, PowerPoint and Excel. Pages are .handnote files in your vault.

Reviews

No reviews yet.

Stats

13
stars
923
downloads
2
forks
28
days
2
days
2
days
1
total PRs
1
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
12
commits

Latest Version

3 days ago

Changelog

HandNote 0.12.3

  • Large PDF imports. The PDF file size limit rises from 200 MiB to 512 MiB. HandNote hashes the file in chunks and releases PDF inspection resources before saving a new copy to reduce peak memory use. A 400 MiB test PDF was successfully imported and opened on iPad. Actual capacity depends on the device and PDF contents.
  • Long PDFs. HandNote imports the full document up to 10,000 pages. Above that limit it asks you to split the PDF. Previous versions could silently stop at 2,000 pages.
  • Clearer errors. HandNote checks the header of a picked file before reading the full file. An all-zero header now gets an explanation about possible placeholders, damage, or incomplete downloads.

Update through Settings → Community plugins → Check for updates.

中文

  • 大 PDF 导入。 PDF 上限从 200 MiB 提升到 512 MiB。分块校验,并在保存新副本前释放 PDF 解析资源,降低导入时的内存峰值。已在 iPad 上成功导入并打开一份 400 MiB 测试 PDF。实际可导入大小取决于设备和 PDF 内容。
  • 长 PDF 完整导入。 最多完整导入 10,000 页。超过上限会提示拆分,修复了旧版在 2,000 页处静默截断的问题。
  • 更清楚的文件提示。 从设备导入时先检查文件头。遇到全零开头会提示可能是占位文件、损坏或下载不完整。

在 Obsidian 的 设置 → 第三方插件 → 检查更新 中升级。


SHA-256

d95dea564e70dee04da180c094b0052e477bb9ae04c982d12e187e140c7e6774  main.js
085ddc705fcecd51d91ad7da571945130b2a5c3c52adb93310452b6525e16162  manifest.json
fd64a31534a8abff75e1800ed57af8837bf61dc022b294caebe863f168af9f5a  styles.css

README file from

Github

HandNote is an Obsidian community plugin for handwritten notes, made first for the iPad and Apple Pencil (a finger, a mouse or a pen tablet work too). Write in notebook pages, select with a lasso, convert handwriting to editable text on your device, write directly on your Markdown notes, and annotate PDF, Word, PowerPoint and Excel files by hand. Every page is a plain .handnote file in your vault. Free and open source (MIT).

Install from the Obsidian community directory · Releases · FAQ · 中文说明 · 中文教程

One-minute tour

https://github.com/user-attachments/assets/a0064f52-7d4f-4fa4-84c1-56af51b359ba

iPad clips: real Apple Pencil recordings of HandNote 0.8.1. Desktop clips: the released 0.8.1 files, with the handwriting played back by a script (marked in the video). A longer tour with the 0.9 document import and a voice-over is on YouTube.

Write like on paper

Pressure-sensitive fountain pen, pencil, highlighter, dashed strokes and a laser pointer. The ink is smoothed without lagging behind the pen, ends in a pointed stroke when you flick, widens when you tilt the Apple Pencil and stays exactly where you wrote it when you lift the pen; zoom in up to 2400 %. Calibrate the pressure from your own writing in one tap. The shape pen turns casual strokes into lines, arrows, curves, rectangles, ellipses (also tilted), triangles and regular polygons, and a nearly straight highlighter stroke becomes a straight line. Pages come in A4, A5, A3 or Letter with blank, ruled, grid or dotted paper.

A handwritten lecture page in Obsidian: title, heading, two equations, Chinese and English lines and a vector sketch, with the pen toolbar open

Lasso, then convert to text

Draw a loop around handwriting and choose Convert → Text. The ink is replaced in place by editable text (Chinese and English), in one undo step, with candidates for uncertain characters and a Restore ink button. Recognition runs on your device: the runtime is built into the plugin, and the text models are downloaded once, when you ask (details).

Four handwritten Chinese characters selected with a lasso loop and converted to text; a bar below shows the candidate characters and Restore ink

Annotate PDF, Word, PowerPoint and Excel

Import document… (command palette or the editor menu), or right-click a file in the file list → Annotate in HandNote. Every page of the document becomes a HandNote page of the same size, and you write on it like on any other page.

  • PDF — rendered by the PDF engine that comes with Obsidian.
  • Word (.docx, and older .doc) — headings, styles, lists, tables, pictures and landscape sections, laid out into fixed pages.
  • PowerPoint (.pptx) — one page per slide: backgrounds, shapes, text, pictures, groups, tables.
  • Excel (.xlsx) — printed on A4 pages like OneNote, cells at their real size, number formats, fills, borders and merged cells. Formulas show the value saved in the file; HandNote does not recalculate.

The original file is kept unmodified in your vault (folder HandNote imports by default) and the note stores only a reference plus your ink. Macros never run, nothing is uploaded. What a file contains that HandNote cannot show (charts, animations, footnotes…) is listed when you import it.

A PowerPoint slide about eigenvalues imported into HandNote, with a highlighted bullet, a circled formula box and handwritten margin notes "exam!", "key idea" and "see page 2"

Write on your Markdown notes

New in 0.12.1: tap the HandNote pen icon at the top right of any Markdown note and write on it with the same pens, highlighter, shape pen, eraser, lasso, text boxes, images and shapes as in a HandNote note, right inside Obsidian's editor. The note stays editable: the Apple Pencil only writes, and a finger tap on the text lets you type there. Pan into the margins and zoom from 50 % to 800 % with the text laid out sharp at every size.

Annotations follow the text: ink, text boxes and images move with their line when you add or delete lines above, and a highlight follows the words it covers. They are saved in a separate file under HandNote annotations/, so your .md file is never changed; an annotation whose line cannot be found stays where it was and is never deleted. The ink shows in the editing view, not in reading view, and there is no PNG / PDF export of annotated Markdown notes yet (details).

Formulas as LaTeX

Convert → Math opens a LaTeX editor with a live preview: type the formula, then insert it next to your handwriting or replace the ink. Formulas stay editable objects you can move, resize and copy as Markdown ($$…$$). Handwritten-math recognition is available through MyScript with your own keys; this plugin has no on-device math recognition.

The formula editor: the handwritten equation on the left, the typed LaTeX and its rendered preview on the right, with buttons to insert beside or replace the handwriting

Pages, paper and objects

Many pages per note, reordered in the page sidebar; bookmark the pages you need often and list only those. Text boxes, images, shapes with connectors and editable formulas sit on the page with your ink; the lasso moves, resizes, rotates, recolours and groups any of them. Long-press the page with a finger (right-click on desktop) to paste, add a text box or insert an image right there.

The page sidebar with three page thumbnails — ruled, grid and dotted paper — next to the open lecture page

Infinite whiteboard

Next to notes with pages, HandNote makes infinite whiteboards (ribbon icon → Infinite whiteboard): one canvas without edges, dotted by default, zoom out to 10 %. A note with pages can be turned into a whiteboard in one step (undo brings it back): its pages become page frames, laid out from left to right with their paper, imported documents and ink, and the lasso moves a whole frame. Export the whole board or the current view as an image, or embed it in Markdown.

Find your way

A hand tool (H) that only moves the page, a command for every tool and page action (give them hotkeys in Settings → Hotkeys), go to page by tapping the page counter, a contents tab for PDFs with bookmarks, and pull past the last page to add a new one.

Plain files in your vault

Every note is a .handnote file in your vault, synced by whatever you already use. Embed a page in any Markdown note with ![[Lecture 3.handnote]]. No account, no server of its own. Saving is careful: it checks the file was not changed by sync first, keeps a recovery journal and backups, and opens damaged or newer-format files read-only.

A Markdown note about linear algebra with the handwritten lecture page embedded below the text

Get started

  1. In Obsidian: Settings → Community plugins → Browse, search for HandNote, then Install and Enable. (Or open the directory page and press Add to Obsidian.)
  2. Create a note: the New handwritten note command, or right-click a folder → New HandNote.
  3. Write. Pick the lasso, circle a few words, press Convert → Text. The first time, HandNote offers to download the text model (size shown first); Chinese also works with the built-in offline engine, without any download.

Manual install: copy main.js, manifest.json and styles.css from the latest release into <vault>/.obsidian/plugins/handnote/ and enable HandNote. The SHA-256 of each file is in the release notes, and releases carry GitHub build-provenance attestations.

Platforms

Platform Status
iPad (Obsidian for iPadOS) with Apple Pencil Primary target: pressure, tilt, palm rejection, finger pan / pinch, two-finger undo
Windows / macOS / Linux Mouse, pen tablet, touch screen, keyboard shortcuts
iPhone / Android Should work (no desktop-only APIs are used) but is not tested

Requires Obsidian 1.11.4 or newer. On-device recognition on iPad / iPhone needs iPadOS / iOS 16.4 or newer.

Quick answers

  • Is HandNote an Obsidian plugin? Yes: a community plugin listed in Obsidian's official directory (id handnote). It is made independently, not by the Obsidian team.
  • Does it work on the iPad with an Apple Pencil? Yes, that is the main target: pressure, palm rejection, finger gestures for pan, zoom and undo.
  • Can it convert handwriting to text? Yes, Chinese and English, on your device, after a one-time model download (15.8 MB / 7.5 MB). A built-in offline engine also reads neat Chinese.
  • Can I annotate documents? Yes, since 0.9.0: PDF, Word (.docx, .doc), PowerPoint (.pptx) and Excel (.xlsx). The original file is not changed and nothing is uploaded.
  • Can I write on my Markdown notes? Yes, since 0.12.1: by hand, in Obsidian's own editor. The .md file is not changed; the ink is saved beside it in HandNote annotations/.
  • Is there an infinite canvas? Yes, since 0.11.0: infinite whiteboards, and any note with pages can be turned into one.
  • Is there on-device handwritten-math recognition? No. Type formulas as LaTeX with a live preview, or use MyScript with your own keys.
  • Is it free? Yes, MIT-licensed, with no account, subscription or telemetry. Optional cloud services use your own keys.
Action Pencil / pen Finger Mouse / keyboard
Write draw — (unless "finger drawing" is on) drag
Pan / zoom hand tool; desktop pen tablet: Space + drag, or a pen button set to middle click one-finger drag / pinch hand tool (H), space + drag, Ctrl + wheel
Undo / redo — two- / three-finger tap Ctrl+Z / Ctrl+Shift+Z
Edit a text tap it (lasso or text tool) tap it click it (lasso or text tool)
Pen ⇄ eraser — double-tap with one finger 1 / E
Paste / add here — long-press the page right-click, Ctrl+V

On-device recognition and model downloads

Settings → HandNote → Recognition and AI → Local recognition. The recognition runtime (ONNX Runtime Web 1.24.2, MIT) is built into the plugin; it is never downloaded and starts only when you convert. The recognition models are not built in: each one is downloaded separately, and only when you ask.

Pack Size Downloaded from (first mirror that answers) Used for Licence
Chinese text — PaddleOCR PP-OCRv5 mobile rec (ONNX) + dictionary 15.8 MB PaddleOCR's official download (Baidu, paddle-model-ecology.bj.bcebos.com), Hugging Face PaddlePaddle/PP-OCRv5_mobile_rec_onnx (or hf-mirror.com); dictionary from the PaddleOCR GitHub repository (or its jsDelivr copy) Chinese and mixed lines Apache-2.0 (model card)
English text — PaddleOCR en_PP-OCRv5 mobile rec (ONNX) + dictionary 7.5 MB as above (en_PP-OCRv5_mobile_rec_onnx) English lines Apache-2.0 (model card)
Hand font — Excalifont + Xiaolai (optional) up to 12.1 MB, loaded per character Excalidraw's npm package / repository (npmmirror, jsDelivr, GitHub, Fastly) hand-lettered look for converted text SIL OFL 1.1
  • When: only after you press a pack's Download button in Local recognition, or accept the offer shown when you convert without the model. The size is shown first. Nothing is downloaded at startup, on install, on update or in the background.
  • Checked: every file has a fixed size and SHA-256 in the plugin; a file that does not match is discarded. There is no automatic model update: new models only come with a new plugin version, and you still press the button.
  • Stored: in this device's app storage (IndexedDB, per device). Never in your vault, never synced. Uninstalling HandNote does not delete them; delete them in Local recognition first.
  • Uploaded: nothing. The download requests are plain file requests (short HEAD requests first to find a mirror that answers). Your notes and your handwriting never leave the device for local recognition.
  • Offline: after the download, recognition works without a connection. Without the models, writing and everything else still works; Convert → Text can use the built-in offline Chinese engine.
  • Blocked mirrors: Import files accepts the same files from disk (same hash check). Run self-test shows what works on this device and which mirrors answer.

Optional cloud services

Nothing is sent anywhere unless you set it up yourself:

  • MyScript (Settings → HandNote → Recognition): your own MyScript keys. The strokes of a selection are sent to MyScript after a confirmation, for text or math. MyScript's terms and pricing apply.
  • AI providers (Settings → HandNote → AI): OpenAI, Anthropic, Google Gemini, DeepSeek, Alibaba Cloud Qwen, or any OpenAI-compatible endpoint, with your own key — to turn a sketch into a mind map or a flowchart, or read text from a picture. A picture of the selection is sent after a confirmation. The provider's pricing applies.

Keys are kept in Obsidian's secret storage, never in settings files or notes.

Privacy

No telemetry, no analytics, no account, no server of its own. Every network request — service, purpose, data sent, cost, offline behaviour — is listed in PRIVACY.md.

Known limitations

  • No on-device math recognition. Type formulas as LaTeX, or use MyScript with your own keys. Notes with formulas made by any HandNote version open and edit normally.
  • Recognition is trained on general handwriting: unusual or very small writing, or several scripts in one line, are read less reliably. Uncertain results come with candidates, and the ink is kept until you choose.
  • A note made with a newer HandNote opens read-only in an older one. Update HandNote on every device that edits the same notes.
  • Imported Word / PowerPoint / Excel files are re-laid out by HandNote, not by Microsoft Office: page breaks and fonts can differ slightly, and charts, SmartArt, animations, headers / footers and footnotes are not shown. Older .ppt / .xls must be saved as .pptx / .xlsx or PDF first. Office files get a small .handnote-layout.json beside them — let your sync tool sync it.
  • Notes with imported pages use file format 6: HandNote 0.8.x opens them read-only. Whiteboards and the curve shapes added in 0.11 use format 7: HandNote 0.10 and older open them read-only.
  • Handwriting written with 0.11 or newer also stores the drawn ink, so those notes are about 1.6–1.9 times larger than before.
  • Ink on Markdown notes shows only in the editing view (not in reading view or embeds), cannot be exported as PNG / PDF yet, and its lasso has no Convert / AI. Ink follows its line, not the shape of the sentence; on a device with another font or width its horizontal position can differ.
  • Phone layouts are not optimised.
  • main.js is about 6.5 MB because the recognition runtime is built in. Obsidian Sync's Standard plan does not sync files over 5 MB, so with that plan install HandNote on each device from Community plugins (your notes sync as usual).

More answers: FAQ.md.

Feedback

Bugs and ideas: GitHub issues (please do not attach private notes or keys). Security problems: SECURITY.md.

Licence

HandNote's own code: MIT. Parts made by others keep their own licences and are not covered by HandNote's licence: ONNX Runtime Web inside main.js (MIT, © Microsoft Corporation), the Chinese stroke data inside main.js (Arphic Public License, vendor/hanzi-mmah/), and the optional downloads (Apache-2.0, SIL OFL 1.1). Details and licence texts: THIRD_PARTY_NOTICES.md.

HandNote is an independent community plugin. It is not made by, affiliated with or endorsed by Obsidian, MyScript, Goodnotes, Xmind, Excalidraw or Microsoft. Screenshots: Obsidian desktop with HandNote 0.8.1 in a demo vault (the import screenshot: HandNote 0.9.0); the handwriting in them is played back by a script.