notesync

This is a simple python CLI tool I created to sync my Supernote files from Gdrive locally, then convert them to page images that an LLM can read directly.

Requires rclone access configuration as well as setup of Gdrive Supernote syncing.

Sync Supernote .note files from a cloud remote via rclone, then render each page to a .png image using supernote-tool.

Prerequisites

1. rclone installed and a remote configured:

   rclone config   # set up e.g. a Google Drive remote named "gdrive"

2. uv (manages Python and dependencies)

Install

cd notesync
uv tool install .    # installs the notesync command on your PATH

Or run it from the project without installing:

uv run notesync --help

Setup

notesync init

This prompts for:

• the rclone remote path where your Supernote uploads notes (e.g. gdrive:Supernote/Note)
• the local directory to sync into
• an optional output directory for .png files (default: alongside each .note)
• an optional audio source directory on a plugged-in USB device (blank: disabled)

Alternatively, copy .env.example to .env and edit it by hand.

Config is written to ~/.config/notesync/.env. A .env in the current directory takes precedence over the user-level file, and real environment variables override both:

NOTESYNC_REMOTE=gdrive:Supernote/Note
NOTESYNC_LOCAL_DIR=~/Supernote/notes
NOTESYNC_SYNC_MODE=copy      # "copy" never deletes local files; "sync" mirrors the remote
# NOTESYNC_OUTPUT_DIR=~/Supernote/png   # default: alongside each .note
NOTESYNC_POLICY=strict       # supernote-tool parsing policy: strict | loose
# NOTESYNC_AUDIO_SOURCE_DIR=/media/you/SUPERNOTE/EXPORT  # USB dir to copy audio from
# NOTESYNC_AUDIO_EXTS=.mp3,.wav   # audio extensions to copy (default: .mp3,.wav)

Audio recordings

If your Supernote also stores voice recordings, notesync can copy them from a plugged-in USB device into the same local notes directory. Set NOTESYNC_AUDIO_SOURCE_DIR to the directory on the mounted device (e.g. /media/you/SUPERNOTE/EXPORT) and run:

notesync audio            # copy audio from the USB device
notesync audio --dry-run  # preview what would be copied

Copying is incremental: a file is skipped when a same-named copy already exists locally and is at least as new as the source. When NOTESYNC_AUDIO_SOURCE_DIR is set, notesync run performs this copy as part of the pipeline (after sync, before convert); when it is unset, audio copying is skipped entirely.

Usage

notesync run              # sync then convert (the full pipeline)
notesync sync             # rclone pull only
notesync audio            # copy audio from a plugged-in USB device
notesync convert          # convert already-synced notes only
notesync run --dry-run    # preview what would transfer and convert
notesync convert --force  # reconvert everything, ignoring timestamps

Each page of a .note becomes a separate image named <note>-<page>.png (e.g. journal-01.png, journal-02.png), rasterized directly from the handwriting itself.

Conversion is incremental: a .note is skipped when its first page image already exists and is newer than the note. Use --force to re-render.

Development

uv sync          # create .venv and install all dependencies (incl. dev)
uv run pytest