discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
Joost-8/FineNotes · source
Snapshot 0 · 2026-11-04T12:47:28Z · TypeScript · GPL-3.0
Content fingerprint
f75b96072d329205429cabd57720daa1f9c3a0dea320d7357cb1b1d457502359GitHub description at capture
Handwrite with any stylus in real, paginated notebooks: Apple Pencil, Android tablet pens, or a pen on Windows, macOS and Linux. Paper templates, shapes that snap, PDFs and pictures, all kept as plain files in your own vault.
README at capture
# FineNotes
Handwriting notebooks for any stylus, inspired by Goodnotes: Apple Pencil, Android tablet pens, and pen tablets on Windows, macOS or Linux. Real pages, paper templates, snapping shapes, PDF annotation and pictures, kept as plain files in your vault.
- **Real pages, not an infinite canvas.** A page has a fixed size, as in
Goodnotes, so ink stays exactly where you wrote it on an iPad, a phone and a
laptop, whatever the width of the window.
- **Reads your handwriting on your device** with Grape, for search, titles and
links. Offline, with no account.
- **Free, and plain files in your vault.** No subscription, and no cloud you
did not choose.
**Website:** [finenotes.vercel.app](https://finenotes.vercel.app), with a demo you can [try in your browser](https://finenotes.vercel.app/play/)
**Follow FineNotes:** [X](https://x.com/finenotes_) · [Instagram](https://www.instagram.com/finenotesobsidian/) · [TikTok](https://www.tiktok.com/@finenotesobsidian) · [YouTube](https://www.youtube.com/@FineNotesAtObsidian)
**Ideas and questions:** [Discussions](https://github.com/Joost-8/FineNotes/discussions)
**Support FineNotes:** [GitHub Sponsors](https://github.com/sponsors/Joost-8)
## Features
**Handwriting recognition on your device: Grape (handwriting recognizer model)**
- FineNotes reads your handwriting with its own model, Grape, on your
device and offline. Grape is a one-time 3.5 MB download the first time
you use it; after that nothing leaves the device, and no account or key
is needed.
- Notebook search and Obsidian's search find your handwriting; lassoed
headings and words fill in titles and links; a handwritten `[[Note]]`
becomes a link with a tap.
- Grape learns your handwriting from a practice file you copy once, on the
device, and gets much better for it.
**Notebooks and pages**
- Notebooks with covers (plain, label, spine or linen, in eight colours), and
single pages, from a New notebook dialog.
- A page sidebar with thumbnails and bookmarks. Pages can be moved up and down,
duplicated or deleted.
- Search inside a notebook: typed text and handwriting.
- A table of contents: page titles, and headings inside a page.
- "Go to page", and links straight to a page: `[[Biology.notebook#Page 3]]`.
- A notebook reopens on the page you left. Pull past the last page to add
another.
- Vertical scrolling, or one page at a time sideways.
**Paper**
- Essentials: blank, dotted, ruled (narrow or wide) and squared.
- Writing papers: Cornell, legal, single and three columns, and Title & Date.
- Planners (to-dos, weekly, monthly, accounting), music paper and guitar
tablature.
- White, yellow or dark paper; A4, A5, A6 and A3 sizes, in portrait or
landscape.
**Writing**
- Pen and highlighter in any colour, with widths in millimetres. Ink is laid
down as the pen moves and never redrawn, as in Goodnotes; pens can respond
to pressure (an advanced setting).
- An eraser that rubs out only what it passes over, or one that removes whole
strokes. Either can be set to erase only pen ink or only highlighter.
- Tools for lined paper, after Stylus Labs Write: erase by line, select by
line, and insert space between lines.
- Handwritten links: lasso ink and link it to a note or a web address.
- Pen gestures, as in Goodnotes:
- scribble over something to erase it;
- circle something and hold to select it.
- Palm rejection: the Pencil writes, while fingers scroll and pinch.
- Smooth scrolling and zooming, with momentum and a rubber-band edge.
**Shapes**
- Draw a shape and hold the pen still: it snaps to a clean line, arrow,
rectangle, circle, ellipse, triangle, star or cloud. Keep holding to move and
resize it.
- Or switch on auto shape, and a stroke that is plainly a shape snaps as you
lift the Pencil.
- A Shape tool with connectors, and tables up to 8 × 8.
**Selecting and arranging**
- A freehand or rectangular lasso, with switches for what it picks up:
handwriting, pictures, shapes, arrows and text boxes.
- Move, cut, copy, paste and recolour a selection, between pages and between
notebooks. Resize it by its corners, turn it by the knob below it, or flip
it from its **…** menu. Pictures and text boxes can be resized, and pictures
rotated.
**Text, pictures and PDFs**
- Text boxes with colours, sizes, bold, italic, bullets and numbering.
- Pictures from Photos, the camera or your vault. They can be cropped, rotated,
flipped and locked in place.
- Scan a document with the camera.
- Bring in a PDF, such as lecture slides or a worksheet: every PDF page becomes
a page you can write on.
**Audio**
- Record while you write.
- Afterwards, tap any word you wrote to hear what was being said at that
moment.
**Sharing**
- Export a notebook, or chosen pages, as a PDF, into a folder of your choice.
**AI, optional and with your own key**
- Transcribe your handwriting into the note with a cloud model.
- Ask questions about a page or a whole notebook.
- Generate a picture.
- Transcribe a recording.
## Why I made FineNotes
FineNotes started as a personal project because I was tired of all the paid
note-taking apps on the App Store, such as Goodnotes and Notability, combined
with the bad performance of Apple Notes as an alternative. I was also tired of
companies being the ones responsible for keeping your notes in their cloud,
something that Obsidian fixes. Furthermore, I was struggling with compatibility
issues between my PC, which runs Windows, and my Apple devices, which made
synchronization a very arduous task, to say the least.
The purpose of this plugin is to be a complete alternative to those note-taking
apps. It can't have every feature a native App Store app has, because it runs
as TypeScript inside Obsidian, with the memory limits that come with that. But
I think that with future releases and your feedback it can get very close. For
now it has all the essential features; only some extra, handy ones from those
apps are still missing.
Hope you guys enjoy this and give me some
[feedback](https://github.com/Joost-8/FineNotes/issues)!
— Joost
## Requirements
- Obsidian **1.13** or later.
- A stylus: an Apple Pencil on the iPad, the pen of an Android tablet (such as
an S Pen), or a pen tablet or pen screen on Windows, macOS or Linux. It also
works with a mouse, a trackpad or a finger, and on a phone.
- It is tested most on the iPad. Android and Linux have had less testing so
far, so please [report](https://github.com/Joost-8/FineNotes/issues) anything
that does not work there.
## Install
- **From Obsidian:** open Settings, then Community plugins, then Browse. Search
for "FineNotes", install it and enable it. Or open the
[FineNotes page](https://community.obsidian.md/plugins/finenotes) in the
Obsidian community directory and choose **Add to Obsidian**.
- **Beta versions:** install the
[BRAT](https://github.com/TfTHacker/obsidian42-brat) plugin, and add
`Joost-8/FineNotes`.
- **By hand:** download `main.js`, `manifest.json` and `styles.css` from the
[latest release](https://github.com/Joost-8/FineNotes/releases/latest) into
`<your vault>/.obsidian/plugins/finenotes/`. Then enable the plugin under
Community plugins.
- **With an AI assistant:** paste the prompt in
[INSTALL_WITH_AI.md](INSTALL_WITH_AI.md) into one that can run commands on
your computer; it installs Obsidian too.
- **With a link:** on a device with Obsidian, open
`obsidian://show-plugin?id=finenotes` (paste it in the browser's address
bar), or tap **Add to Obsidian** on the
[FineNotes page](https://community.obsidian.md/plugins/finenotes), which is
the same link. It opens FineNotes in Obsidian, ready to install. If community
plugins are still off, it opens the page to turn them on first; open the
link again after that.
### New to Obsidian?
Obsidian is a free notes app that keeps everything as plain files in a folder
on your device, called a _vault_. FineNotes runs inside it. On an iPad:
1. Install [Obsidian](https://apps.apple.com/app/obsidian-connected-notes/id1557175442)
from the App Store, open it, and tap **Create new vault**. Give it any name.
2. Open the
[FineNotes page](https://community.obsidian.md/plugins/finenotes) and tap
**Add to Obsidian**.
3. The first time, Obsidian opens its Community plugins settings instead:
allow community plugins there, then go back and tap **Add to Obsidian**
again. Tap **Install**, then **Enable**.
4. FineNotes welcomes you with a short tour, a way to bring your notebooks over
from Goodnotes, Notability, Noteful, reMarkable and other apps, and a button
for a new notebook.
To have your notebooks on several devices, sync the vault: with Obsidian Sync,
iCloud, or any app that syncs a folder.
### Open a notebook from the home screen
In a notebook, open **More** (⋯) and choose **Copy home screen link**. On an
iPad or iPhone, open the Shortcuts app, make a new shortcut with the action
**Open URLs**, paste the link into it, and choose **Add to Home Screen** from
the shortcut's menu. Tapping the icon opens Obsidian straight at that
notebook. On a computer, the same link works as a desktop shortcut or a
bookmark.
## Getting started
1. Open a new notebook, with the notebook button in the left ribbon or the
command **New notebook or page…**. You can also right-click a folder in the
file explorer and choose **New notebook**. Turn this entry off with
**Show New notebook in right-click menu** in FineNotes settings.
The file explorer’s top bar also has a **New notebook** button, controlled
by **Show New notebook in file explorer bar**. The right-click entry starts enabled; the top-bar button starts disabled.
Choose a cover, a paper and a size.
2. Write. The toolbar at the top has:
- on the left: pages, search, AI, and undo/redo;
- in the middle: the writing tools;
- on the right: add page, share, and the notebook's settings.
A tool's options show in a bar under the toolbar; tap the tool again to
hide them.
3. Add a page with **+**, or by pulling past the last page.
There is no save button: every change is written to the note as you go.
## How to use
### The toolbar
- **Left:** **Page thumbnails** (the page sidebar), **Search this notebook**,
**AI** (the sparkles), **Undo** and **Redo**.
- **Middle:** the tools. **Lasso select**, **Pen**, **Eraser**, **Text box**,
**Shapes**, **Insert image** and **Record audio** (the microphone).
- **Right:** **Add page** (+), **Export as PDF** (share), **More** (⋯) and
**Notebook settings** (the gear).
A tool's options appear in a bar under the toolbar. Tap the tool again to
slide them away, and once more to bring them back. The lasso has no options
bar: tap it again to open its menu.
To put the toolbar along the bottom, or upright at the left or right, choose
its place in **More** (⋯) › **Toolbar**. Each device keeps its own. A tool's
bar moves by holding it and dragging it to an edge.
### Writing and erasing
- **Pen type:** the pens at the start of the pen options, each in its own
ink: tap one to write with it. **Ball pen** and **Fountain pen** draw an
even line and **Brush pen** a thicker one; **Highlighter** draws a wide,
see-through stroke. Hold a pen and drag it to put it elsewhere in the row.
The ⌄ after them (or a tap on the pen in hand) holds the **Laser pointer**,
**Pen settings** and **Pen gestures**. With **Pressure-sensitive pens** on
(Settings, advanced), the Fountain and Brush pens get wider the harder you
press.
- **Width:** three widths, and a ⌄ for a slider in millimetres.
- **Colour:** three quick colours. Tap the colour in use again to change it,
or tap **+** for more. **Custom colour…** mixes any colour: pick the shade
in the square and the hue on the slider, then tap the round swatch.
- **Highlighter:** choose **Highlighter** as the pen type, or press **H** on a
keyboard. Choose a pen type again to go back to writing.
- **Eraser:** **Standard** rubs out only what it passes over; **Whole stroke**
removes every stroke it touches. It has three sizes, and **All ink** can be
changed to **Erase highlighter only** or **Erase pen only**. Pictures and
text boxes are never erased. **Clear page** is here too.
### Shapes and pen gestures
- **Draw and hold:** draw a line, arrow, rectangle, circle, ellipse, triangle,
star or cloud in one stroke and hold the Pencil still. It snaps to a clean
shape; keep the pen down and move it to resize and turn the shape. A star
drawn the quick way, with its lines crossing, becomes a star outline. For
an arrow, draw the head in the same stroke, or go back a little way along
the line, then hold. The setting **Draw and hold to make shapes** turns this off.
- **Auto shape**, the last button in the pen options: a stroke that is
plainly a shape snaps as you lift.
- **Pen gestures**, in the pen's ⌄ menu, both on at first:
- **Scribble to erase:** scribble back and forth over writing to erase it.
A scribble on empty paper stays as ink. **Erase shapes and highlighter**
lets it take those too.
- **Circle to lasso:** draw a loop round something and lift, then press and
hold the Pencil on the loop. What it enclosed is selected, ready to drag.
- **The Shapes tool:** **Auto-shape** snaps whatever you draw. Drag out a
**Square**, **Circle**, **Triangle**, **Diamond**, **Rounded square** or
**Star**, or a **Line** or **Arrow**; a tap drops a default-size one.
**Table**: tap a size up to 8 × 8, then drag it out. The disc at the end
sets the shapes' colour.
### Selecting with the lasso
Draw round what you want, or tap one thing. Tap the lasso again to choose
**Freehand** or **Rectangular**, and what it picks up: **Handwriting**,
**Images**, **Shapes**, **Arrows** and **Text boxes**.
Drag inside the frame to move the selection. Its bar has **Cut**,
**Duplicate** and **Delete**; **…** adds **Copy**, **Paste** and a colour row
to recolour ink. Paste works across pages and notebooks; hold the lasso on
empty paper for a **Paste** button right there.
### Text
With **Text box**, tap the page and type; the box grows as you type. Tap a box
to edit it, and drag its handles to move or resize it. The options hold
colour, size, font, **B I** (bold, italic, underline, strikethrough),
alignment, line spacing, bullets and numbering, and box fill. **Drag to size
text boxes** lets a drag set a new box's size. **Pin Text tool** keeps Text
chosen after a box is done. While you type, the red bin deletes the box.
### Pictures and PDFs
**Insert image** offers **Photos**, **Take photo**, **From vault**, and:
- **Scan document:** photograph a sheet of paper, drag the corners onto it if
needed, choose **Colour**, **Greyscale** or **Black & white**, and tap **Add
page**. **Next page** scans several at once.
- **Insert PDF** (beside **Insert image** on the toolbar): choose **From files**
or **From vault**, then **All pages** or **Selected pages** and a
range such as `1-3, 5` (or `5, 3-1` to change the order).
- **From vault** in the PDF menu reuses an existing PDF without making a copy.
You can also use **Import PDF into notebook** in its file menu while a notebook
is active.
- Drop a PDF file onto the notebook to open the same page selection dialog.
Imported pages follow the current page and undo together. The source PDF
remains unchanged; writing and text boxes sit above its page backdrop.
Convert a single page to a notebook before importing PDF pages. PDF pages
are rendered directly from their source at the settled zoom, in small
display-sized regions, so zooming does not enlarge a compressed page image.
- Drop pictures from your computer or the vault onto the notebook to insert
them like **Insert image**. PNG, JPEG, GIF, WebP, BMP and SVG are supported;
other image formats depend on your device, just like the image file picker.
Existing vault pictures are reused without making a copy.
- **Generate with AI**, once an image service is set up.
A new picture is selected: drag its corners to resize it and the knob below
to rotate it. To select it later, tap it with the lasso, or with a finger
whatever tool is in hand. Its bar has
**Crop**, **Cut**, **Duplicate** and **Delete**; **…** adds **Front**,
**Back**, **Copy**, **Paste**, **Lock image**, **Flip horizontal** and
**Flip vertical**. The lasso ignores a locked
picture, such as a worksheet you write on; hold the lasso on it and tap
**Unlock** to free it.
### Pages
- **Add a page** with **+**: choose **Before**, **After** or **Last page**,
and a recent template or **More from templates…**. Or pull past the last
page until it says **Release to add page**.
- **The page sidebar:** tap a page to go there, or its ribbon to bookmark it;
**All pages** switches to **Bookmarks only**. A page's ⌄ menu can bookmark,
copy a link, add, duplicate, move, clear or delete pages, and **Change
template** (**Change cover** on a cover).
- **More** (⋯) does the same for the page you are on, and has **Go to page**.
- **Notebook settings** (the gear): **Scroll direction** (**Vertical**, or
**Horizontal** for one page at a time), and folders for this notebook's
**Images**, **Recordings** and **PDF exports**.
- **A single page** cannot take more pages until you choose **Convert to
notebook** in its ⌄ menu in the sidebar.
PDF display uses one cached image per page, drawn at the exact resolution of the screen. Zoomed in further than that image can go (about 1.4× for an A4 page on an iPad), it sharpens only the visible portion, with at most two PDF renders in flight. On a device short of memory it keeps fewer pages around. Old visible-area renders are cancelled and their canvases released when you scroll away; ink and the sidebar keep their existing rendering paths.
### Search, links and export
- **Search this notebook** finds typed text and transcribed handwriting.
Handwriting that has not been transcribed cannot be found.
- **Links:** `[[Biology.notebook#Page 3]]` (or `#page=3`) opens a notebook at
page 3. **Copy link to page** makes one for you.
- **Export as PDF:** all pages, **This page**, or **Choose pages** (tap them in
the order you want, or type `1-3, 5`), then **Export**. The PDF goes into
the **PDF exports** folder, or else next to the notebook. Then **Open** or
**Share…** it. PDF-backed pages retain their original PDF text and vector
detail, with notebook handwriting, pictures and text boxes as a transparent
overlay. Ordinary notebook pages use the existing image-based export.
A missing, corrupt or password-protected PDF source stops the export with
an error instead of silently replacing its content.
### Audio
Tap the microphone to record. A red pill shows the time: tap **Stop** to end,
or the bin to throw the recording away. Recording stops if the iPad locks or
you leave Obsidian.
Recordings are in the sidebar's **Audio** tab, with **Play** and
**Transcribe**. While the player is open, tap your writing to hear it from
five seconds before you wrote it. **Transcribe** needs an OpenAI or Google
key, or your own server; the transcript is a note of its own next to the
audio.
### Reading your handwriting (Grape)
Grape (handwriting recognizer model) reads your ink on the device a few
seconds after you stop writing: notebook search and Obsidian's search then
find it. Nothing leaves the device. Switch it off under Settings → FineNotes
→ Models on this device → **Read handwriting on this device**.
Grape is kept in the plugin's `handwriting` folder, so vault sync brings it
to your other devices. If you already used FineNotes, it puts its built-in
copy there by itself. On a new install, the first time a handwriting
feature needs it, FineNotes offers a one-time 3.5 MB download (with **Not
now**). Settings → Models on this device shows it, with **Re-download**
and **Remove**.
To make it read your own handwriting much better:
1. Tap the **AI** button, then **Teach it your handwriting…**. A practice
file opens, with a cover that explains what to do.
2. Copy each grey line on the empty line below it, in your normal
handwriting. It takes about 8 minutes.
3. Tap **AI** → **Learn my handwriting** (or Settings → Models on this
device → **Learn now**). It learns on the device in a few minutes, in
the background, and keeps the result only if it reads your writing
better.
Each of the three practice sets has different lines, and every set you
write helps. Settings → Models on this device lists your practice sheets,
how many lines each has, and which ones your learned model was built
from. **Read with my learned model** switches between it and Grape alone
without deleting anything; the model before your last learning is kept,
to go back to; and deleting your learned model is its own button, which
asks first. **AI** → **Read this page** shows how Grape reads a page.
Grape is a work in progress that still needs more training on real
handwriting. It is open source (Apache 2.0) at
[Joost-8/Grape](https://github.com/Joost-8/Grape).
### AI (optional)
1. Open Settings → FineNotes → **AI with your own key**, and tap **Show**.
2. Choose an **AI service**: Anthropic (Claude), OpenAI (GPT), Google
(Gemini), OpenRouter, or a **Custom endpoint** such as Ollama.
3. Tap **Add key** and paste your API key. For OpenRouter you can tap
**Connect OpenRouter** and approve in the browser instead. For a custom
endpoint, fill in **Endpoint URL** (see [SELF_HOSTING.md](SELF_HOSTING.md)).
4. To generate pictures with Claude or a custom endpoint, choose OpenAI,
Google or OpenRouter under **Image generation** and add that key.
The **AI** button then offers **Ask…**, **Generate image…** and **Transcribe
recording…**. A greyed-out entry says what it needs. The first request asks
once whether to send; tap **Send**.
**Ask** is a chat about your notes, in a window or a sidebar beside the page.
Pick up to 10 pages to send (the page you are on is picked), attach PDFs,
pictures or text files, and keep a chat in the notebook's AI chats folder
with **Save chat**. While it answers, the AI can use the notebook: read
other pages, search its text, add a text box or a page, go to a page, and
put a drawing on a page; each change can be undone. An answer can be put on
the page with **Insert as text box**, and a drawing in it with **Insert on
page**. With a custom endpoint, the tools depend on your server and model:
see [SELF_HOSTING.md](SELF_HOSTING.md#ask-with-a-local-model-notebook-tools).
Transcriptions go into the note's text layer, one heading per page, which
opens under the pages so you can correct it.
To transcribe as you go, set **Handwriting recognition** to **Cloud AI** and
switch on **Recognize automatically**: the page you are on is transcribed
about 30 seconds after you stop writing.
Two optional settings return secondary tools to your previous pen or highlighter: **Select active tool again to return to pen** and **Return to pen after one use**. Both are off by default and apply to eraser, lasso, text and shapes. A single use finishes an eraser stroke or shape, finishes text editing (overriding Pin Text tool), or ends a lasso session when you click outside the selection or delete or cut it. Moving, scaling or other selection actions keep the lasso active.
### Keyboard shortcuts
| Keys | What they do |
| ---------------------------- | --------------------------------------------- |
| Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z | Undo, redo |
| P, H, E, V, S, T | Pen, highlighter, eraser, lasso, shapes, text |
| Cmd/Ctrl+C, X, V | Copy, cut, paste |
| Delete or Backspace | Delete the selection |
| Escape | Close a menu, deselect, cancel a crop |
| Return | Finish a crop |
| Page Up, Page Down | Previous or next page |
| ↑, ↓ | Scroll |
Ctrl+Y also redoes. Shortcuts act on the active notebook; text fields keep their
normal editing shortcuts. On a computer, drag the right or bottom scroll
indicator to scroll directly.
On a computer, Ctrl/Cmd with the scroll wheel (or a trackpad pinch) zooms.
### Commands
Besides the toolbar's own actions, the command palette has **New notebook or
page…**, **Create notebook with last settings**, **Convert single page to
notebook**, **Scan document into this notebook**, **Show or hide the text
layer**, **Transcribe this notebook's handwriting**, **Switch between notebook
and Markdown view**, **Fit the page and go to the top**, **Zoom in**, **Zoom
out** and **Show the changelog**.
**Transcribe this notebook's handwriting** follows the **Handwriting
recognition** setting. On **Manual**, as it starts, it opens the text layer
for you to type in.
### Tips for the iPad
- **Switch off Scribble** in the iPad's Settings app, under Apple Pencil →
Scribble. This iPadOS handwriting feature can take a fast Pencil stroke for
itself before FineNotes sees it, and the stroke goes missing.
- **Keep the screen on while you record.**
- **A notebook that opens read-only** did not load its ink, usually because a
sync had not finished. Nothing on disk has changed: reopen it once the sync
is done.
- **Ink looks garbled?** Switch off **Desynchronized canvas** in the settings.
- **Reporting a bug:** run **Show or hide the input debug overlay** and make a
screen recording. For a shape that will not snap, run **Copy shape
diagnostics**: it saves a note, "FineNotes shape diagnostics.md", to paste
into the issue.
## How your notes are stored
- A notebook is a Markdown file in your vault called `Title.notebook.md`. A
single page is called `Title.page.md`.
- The ink sits in a compressed block inside a `%%` comment, which Obsidian
hides when reading.
- Transcribed text goes into a marked section of the same file, with one
heading per page. Obsidian's search, links and backlinks all see it.
- Pictures, recordings, PDFs and exports are ordinary files next to the note.
- Your notes sync with whatever syncs your vault.
- Without the plugin, a notebook still opens as a Markdown file: its text is
readable, its ink is not.
- Notes made with earlier versions, under the name GoodObsidian (`Title.ink.md`
included), open as they are.
## Privacy and network use
FineNotes works fully offline. It sends nothing anywhere, and it has no
telemetry, no ads and no account. Your handwriting is read by Grape
(handwriting recognizer model) on the device; practice files and what Grape
learns from them stay in your vault.
The network is used in four cases, all optional.
**Grape (handwriting recognizer model).** It is downloaded rather than built
into the plugin, to keep the plugin small:
- **What is downloaded:** the Grape model file (`grape-2.0.bin`, 5.7 MB).
Nothing is uploaded.
- **From where:** the public GitHub releases of
[Joost-8/Grape](https://github.com/Joost-8/Grape/releases)
(`github.com`, which redirects to GitHub's file host).
- **Why:** reading handwriting on the device needs the model; without it,
every other feature works.
- **When:** once, after you tap **Download** on the card that appears the
first time a handwriting feature needs it, or in Settings → Models on
this device. A file
already in your vault (written by an earlier FineNotes, or synced from
another device) is checked and used, not downloaded again. FineNotes checks
the file's size and SHA-256 checksum before using it, and a newer Grape
arrives the same way, with a plugin update.
- **What GitHub sees:** like any download, your IP address, once.
**The template gallery.** It downloads only when you open it (Browse
template gallery), from FineNotes' own gallery on GitHub
([Joost-8/FineNotes-templates](https://github.com/Joost-8/FineNotes-templates)),
or from another address set in Settings → Pages and notebooks:
its list of templates, their preview pictures, and the one template you
choose to add. Nothing about you or your vault is sent. A template is only
accepted if it is a PDF, PNG, JPEG or WebP file of at most 40 MB, or a
FineNotes template file, so nothing in it can run.
**Checking for updates.** Once a day at most, FineNotes reads the version
number in its own `manifest.json` on GitHub
(`raw.githubusercontent.com/Joost-8/FineNotes/main/manifest.json`, the file
Obsidian's own updater reads), and puts a dot on the toolbar's gear when a
newer FineNotes is out. Nothing about you or your vault is sent; GitHub sees
your IP address, as with any download. It only tells you: updating is still
done by Obsidian, under Settings → Community plugins. Switch it off in
Settings → Advanced → Check for updates.
**The AI features**, only after you:
1. choose an AI service in the settings and give it your own API key;
2. agree to a one-time prompt before the first request to that service.
Then:
- **What is sent:**
- an image of the page, when you transcribe, ask a question, or let a page
be transcribed automatically;
- your prompt, when you generate a picture;
- the audio, when you transcribe a recording.
- **Where it goes:** only to the service you picked:
- Anthropic (`api.anthropic.com`);
- OpenAI (`api.openai.com`);
- Google Gemini (`generativelanguage.googleapis.com`);
- OpenRouter (`openrouter.ai`);
- or your own OpenAI-compatible server, such as Ollama or LM Studio. See
[SELF_HOSTING.md](SELF_HOSTING.md).
- **Why:** these features need a model that reads handwriting, answers
questions, generates pictures or transcribes speech. The service's own terms
and pricing apply.
- **Automatic transcription** (the **Recognize automatically** setting): this
is off by default. When it is on, a page
is only ever sent after you have agreed to the prompt.
- **Connect OpenRouter:** this opens OpenRouter in your browser to approve the
plugin, and then collects the key from `openrouter.ai`.
- **API keys:** they are kept in Obsidian's Keychain, not in your vault's
files, so they do not sync or end up in backups of the vault.
## How it works
A short tour, for the curious and for anyone who wants to contribute.
**Pages have their own coordinates.** Every page has a fixed size in its own
units: an A4 page is 1024 units wide, standing for 210 mm. Strokes are stored
in the coordinates of the page they were written on, and the screen only
decides how large that page is drawn.
That is why a note looks the same on every device, and why ink never drifts
when the window changes width. An infinite canvas has no such anchor.
**Input.** Pointer events tell the Pencil and fingers apart:
- The Pencil writes; one finger scrolls, two pinch, and a palm is ignored.
- FineNotes reads the extra samples the iPad gathers between frames, so fast
handwriting stays smooth.
- It does not draw the samples the iPad predicts: they guess wrong at every
turn, and the ink would swing.
- iPadOS wants a still pen for itself (long press, Scribble), so FineNotes claims
those touches first. A still pen that iPadOS cancels counts as the hold it
was, which is what lets draw-and-hold snap shapes.
**Ink.** Handwriting is smoothed by a curve through the midpoints between the
pen's samples and drawn as a line with round ends, by the canvas itself. It
only ever grows: what is on the page never changes shape while the pen goes
on. With pressure on, a line is drawn in short runs of one width each. Shapes
are drawn as exact lines, so their corners stay sharp.
Shape recognition is geometry, not machine learning: it fits lines, polygons,
circles, ellipses, stars and clouds. It was tuned on real Apple Pencil strokes traced
from screen recordings, so it accepts the hooks and overshoots a real hand
makes.
**Drawing.** There are three stacked canvases:
- the paper;
- finished ink, drawn from cached tiles, so scrolling is cheap;
- the stroke being written, on a fast layer of its own.
The page is never scrolled as a web page. It is moved by a transform, with
iOS-style momentum and a rubber band at the edges.
**Every edit is undoable.** Each change is a command that knows its own
inverse, so undo and redo are exact, and a moved selection is one step.
**The file.** The note's frontmatter and text are ordinary Markdown. The ink is
one `%%` block: the notebook as JSON, compressed with DEFLATE and stored as
base64. Points are rounded to 1/100 of a unit and pressure to 1/255, which keeps
files small without visible loss.
The format is written down in [`contracts/api.md`](contracts/api.md), and 559
golden files pin its exact bytes. FineNotes writes only its own frontmatter keys,
its ink block and its text section; the rest of your note is never touched.
**AI.** Requests go through Obsidian's own network API, because a web view's
`fetch` to these services is blocked on the iPad. Each key is only used for its
own service, and the key for your own server never goes anywhere else.
**Code layout.**
| Folder | What it holds |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| `src/model/` | The notebook, its commands and the file format. Pure TypeScript: no DOM, no Obsidian. |
| `src/ink/` | Stroke building, the ink tracer, shape recognition and pen gestures. Pure. |
| `src/input/` | Pointer handling, palm rejection, pinch and pan. |
| `src/canvas/` | Rendering, tiles, page layout, scroll physics, paper rulings and scanning geometry. |
| `src/view/` | Everything Obsidian-facing: the notebook view, toolbar, sidebar and dialogs. |
| `src/recognition/` | The AI services: requests, keys and transcription. |
| `tests/` | About 2,450 unit tests, including real Pencil ink traced from screen recordings, and the format goldens. |
The pure modules have enforced test coverage. CI runs Obsidian's own
plugin-review lint rules as well as lint, the type check, the tests and the
build.
## Good to know
- Handwriting lives in its own notebook files; it is not placed inside other
notes. To refer to it, link to a notebook or to one of its pages.
- Coming from GoodObsidian? Your settings carry over the first time FineNotes
starts. Custom hotkeys have to be set again, and you can remove the old
plugin afterwards.
- Do not run InkedMark in the same vault: both open `.ink.md` files.
## Feedback and community
- **Ideas and questions:** start a thread in
[Discussions](https://github.com/Joost-8/FineNotes/discussions).
- **Something broken?** [Report a bug](https://github.com/Joost-8/FineNotes/issues/new/choose):
the form says which diagnostics help with which problem.
- **Like FineNotes?** You can support its development on
[GitHub Sponsors](https://github.com/sponsors/Joost-8), monthly or once.
- **Website:** [finenotes.vercel.app](https://finenotes.vercel.app), with a browser demo.
- **Follow FineNotes** for news, tips and demos: [X](https://x.com/finenotes_) · [Instagram](https://www.instagram.com/finenotesobsidian/) · [TikTok](https://www.tiktok.com/@finenotesobsidian) · [YouTube](https://www.youtube.com/@FineNotesAtObsidian).
- The same links are in Settings → FineNotes → Feedback and community.
- Everyone taking part is expected to follow the
[code of conduct](CODE_OF_CONDUCT.md).
## Credits
- Notes are compressed with [fflate](https://github.com/101arrowz/fflate)
(MIT).
- Handwriting is read by [Grape](https://github.com/Joost-8/Grape)
(Apache 2.0), trained on BRUSH, IAM-OnDB, UNIPEN, PluColl and
UJIpenchars2; the attributions are in `THIRD_PARTY_NOTICES.txt`.
- PDFs are rendered with the PDF.js that Obsidian ships.
- FineNotes began as a fork of
[InkedMark](https://github.com/pcrausaz/obsidian-inkedmark) by Pascal
Crausaz, and has since been rewritten; it no longer contains InkedMark's
code. Thanks for the start.
## Development
```
npm install
npm run dev # watch-mode build
npm test # unit tests
npm run lint # eslint, no warnings allowed
npm run lint:review # Obsidian's plugin-review rules, as CI runs them
npm run build
```
To try a build in a vault, put the plugin folder's path
(`<vault>/.obsidian/plugins/finenotes`) in a `.deploy-target` file. Every build
is then copied there.
Bug reports and ideas are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md), or go
straight to the
[issues](https://github.com/Joost-8/FineNotes/issues). For an iPad problem, a
screen recording with **Show or hide the input debug overlay** switched on
helps more than anything else.
## License
FineNotes is licensed under the
[GNU General Public License v3.0 or later](LICENSE).
Versions before 2.0.0 were released under the MIT licence, and code
contributed before 2.0.0 was contributed under it; its notice is kept in
[LICENSE-MIT](LICENSE-MIT). The handwriting model, Grape, which FineNotes
downloads on first use, is licensed separately under the Apache License 2.0
([models/LICENSE](models/LICENSE)).