8000 GitHub - TariqMK/Klippings: Extract Highlights from MyClippings.txt into files per book. Fast and clean. · GitHub
[go: up one dir, main page]

Skip to content
TariqMKPublic

About

Extract Highlights from MyClippings.txt into files per book. Fast and clean.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

59 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Klippings. Turn Kindle clippings into notes and quotes.

Klippings reads the My Clippings.txt file from your Kindle. It saves the highlights of each book as a text file, as quote images, or both. Your My Clippings.txt file is not changed.

Works offline. Sends no data. It goes online only when you select Check for Updates.

Available for Windows, macOS (Apple Silicon) and Linux.

Disclaimer: Most if not all of the code here has been written in Python with the help of AI.

Klippings with a clippings file open: the book list on the left, the highlights of Walden in the middle, and the export options on the right

What Klippings Does

Your Kindle records every highlight from every book in one file, My Clippings.txt. The file gets longer each time you highlight something. Klippings sorts it into one set of files per book.

My Clippings.txt   →   Walden.txt
                       Pride and Prejudice.txt
                       Moby-Dick.txt
  • Text files: one .txt file per book, with or without the page and location of each highlight.
  • Quote images: one 1080 x 1350 px image per highlight, in a folder named after the book.
  • Several files at once: open clippings from several Kindles or dated backups. Klippings combines them into one library.

Download

  1. Open the Releases page.
  2. Download the file for your computer:
Computer File
Windows (x64) Klippings-<version>-windows-x64.exe
macOS (Apple Silicon) Klippings-<version>-macos-arm64.zip
Linux (x64) Klippings-<version>-linux-x64.tar.gz
  1. Start Klippings:
    • Windows: run the .exe file. No installation is necessary.
    • macOS: open the .zip file, then open Klippings.
    • Linux: extract the .tar.gz file, then run Klippings.

Note: The macOS app is unsigned. The first time you open it, macOS blocks it. To allow it, go to System Settings > Privacy & Security and select Open Anyway.

Note: On macOS, move Klippings out of the Downloads folder before you open it, for example to Applications or Documents. If it runs from where it was downloaded, macOS can stop it from saving its settings.


How to Use Klippings

  1. Connect your Kindle to your computer. Find My Clippings.txt in the documents folder on the Kindle.
  2. Drop My Clippings.txt on the Klippings window, or select Choose File. To open several files, select or drop them together.
  3. In the book list, tick the books to export. Use Select All or Select None to change all of them.
  4. Select a book to read its highlights in the middle of the window.
  5. In the export panel on the right, choose what to make:
    • Text files, with or without Include page & location.
    • Quote images, with a Font.
  6. Under Save to, select the button and choose a folder.
  7. Select Export. The button shows how many books it will export, for example Export 6 Books.
  8. After the export, select Show in Folder to see the files.

To open different files, select Choose Another File. To close the open files, select Clear Files. Your export choices stay as they are.

Note: If a file with the same name is already in the folder, Klippings asks before it replaces it. A replaced file can't be recovered.


Export Options

Text files

Klippings saves one text file per book, directly in the folder you choose. The file name is the book title without its subtitle.

Include page & location File name Contents
Ticked (default) Walden.txt Each highlight, with its book, author, page and location
Cleared Walden (simple).txt The title and author, then each highlight, separated by ---

The reading view changes to show which version you will get.

Walden.txt:

1. The mass of men lead lives of quiet desperation.
	<Walden>(Henry David Thoreau) Your Highlight on page 8 | location 104-104

2. Our life is frittered away by detail. Simplify, simplify.
	<Walden>(Henry David Thoreau) Your Highlight on page 14 | location 190-191

Walden (simple).txt, for notes apps such as Obsidian:

Walden
Henry David Thoreau

---

1. The mass of men lead lives of quie
A1F6
t desperation.

---

2. Our life is frittered away by detail. Simplify, simplify.

Quote images

Klippings saves each highlight as a WebP image, in a folder named after the book.

Walden/
├── Highlight_0001.webp
├── Highlight_0002_01.webp
└── Highlight_0002_02.webp

A 1080 x 1350 quote image of a highlight from Walden, with the book and author line at the bottom

  • Every image is 1080 x 1350 px, black text on white.
  • The highlight is size 40, with line spacing 15, wrapped at 43 characters.
  • The book and author line is size 27, at the bottom of the image.
  • A highlight too long for one image is shared evenly across several images, such as Highlight_0002_01.webp and Highlight_0002_02.webp. Klippings breaks at the end of a sentence where one is close.
  • Fine ticks at the top centre of split images show how many images there are. The darker tick shows the current image.
  • Two fonts are included: Vollkorn and Platypi.

To export only images, clear Text files and tick Quote images.

Klippings with Quote images selected and Include page & location cleared: the font menu shows Vollkorn and the preview shows the highlights without page and location

Opening Several Files

You can open clippings files from different Kindles, or dated backups of one Kindle, together.

  • Books found in more than one file are combined into one book.
  • A highlight in a later file is left out if its text, book, author, page, location and date all match one in an earlier file.
  • Repeats inside one file are kept.
  • Highlights are put in the order you took them: by date, then by location. If a book has a date Klippings can't read, that book is sorted by location only.

With one file open, highlights stay in the order of the file.


What Klippings Leaves Out

Klippings exports highlights only. It leaves out these entries and shows how many of each it skipped:

  • Bookmarks
  • Notes
  • Article clips
  • Empty highlights
  • Clipping limit messages
  • Copies already in another file

Select Show Details in the status bar to see the counts.


Keyboard Shortcuts

On macOS, use Cmd in place of Ctrl.

Shortcut Action
Ctrl+O Choose files
Ctrl+Return Export
Up / Down Move through the books
Space Include or leave out the current book
Esc Cancel an export

On macOS, Open…, Export and Clear Files are also in the File menu.


Check for Updates

  1. Select Check for Updates, next to the version number at the top of the window.
  2. If a newer version is available, select Yes to open its download page in your browser.

Klippings does not download or install updates itself.


Privacy

  • Klippings works offline. Everything it does with your clippings happens on your computer.
  • It has no telemetry, analytics, crash reports or tracking.
  • Your text files and quote images are saved only in the folder you choose.
  • Your settings (the last folder you used) are saved in a Klippings-data folder next to the app. Klippings creates it the first time you choose a Save to folder. Nothing is saved anywhere else, so to move Klippings to another folder or computer, move the app and Klippings-data together.
  • If Klippings can't write next to itself, it tells you once and does not save your settings. Your exports are not affected.
  • The app makes one network connection, and only when you select Check for Updates. It sends one request to api.github.com to read the latest release number. It sends no data about you or your files, and it keeps nothing. GitHub sees your IP address, as with any web request.

Known Issues

  • Amazon has changed the format of My Clippings.txt over the years. The common English formats are supported. Files from Kindles set to other languages are not supported yet, and their entries are counted as unrecognised. If you have a problem, please raise an issue.
  • A book with no author whose title ends in brackets, such as Book (Vol 1), shows Vol 1 as its author. The file format does not tell the two apart.
  • If you extend a highlight on your Kindle, the old and new versions are both kept. The Kindle records them as separate highlights.
  • Quote images use a fixed text size and line length. An unusually wide line, or a wider font, can come close to the edges of the image.

Run From Source

Klippings needs Python 3.8 or later.

  1. From the repository root, install Klippings and its libraries:
pip install .
  1. Start the app:
klippings

Note: From source, Klippings-data goes in the folder you start klippings from. With python -m klippings from a checkout, it goes in the repository root. Git ignores it.

Note: From source, the app shows the development version, v0.0.0.dev0. Only release builds show a real version number. Check for Updates does not go online in a development build.

To run the tests:

pip install ".[dev]"
pytest

Add a font for quote images

  1. Check that the font's licence allows it to be built into an app.
  2. Put the .ttf or .otf file in klippings/fonts.
  3. Put any licence file the font requires next to it.

The font appears in the Font menu. Vollkorn and Platypi are already there, with their licences.


Update the Screenshots and Brand Images

The screenshots come from the real app, with sample clippings from public-domain books. Retake them after a change to the interface.

Note: Both scripts need Windows. The screenshot script also needs a screen of at least 2240 x 1380 px. Do not cover the Klippings window while it runs.

  1. Set VERSION at the top of assets/make_screenshots.py to the newest release tag.
  2. From the repository root, run:
python assets/make_screenshots.py

The script writes the images to assets/screenshots.

To rebuild the app icons, the banner and the social card after a change to the icon or tagline, run:

python assets/make_assets.py

The script also copies the site icons and social card into docs/.


Creating a Release

  1. Open the repository's Actions tab and select the Release workflow.
  2. Run it on main, and choose:
    • Release type: draft or public
    • Version increment: patch, minor or major

The new version comes from the highest existing tag or release, including drafts. The app shows it, and the release is tagged with it. The workflow does not commit anything to main, so your local copy stays level with GitHub.

To add release notes, edit the release on GitHub. The workflow adds only a link to the full list of changes.

About

Extract Highlights from MyClippings.txt into files per book. Fast and clean.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages

0