calibredb.el

Table of Contents

• Description
• Installation
• Configuration
• Workflows
• Q&A
• Supported Features
• RELEASES
• Contributor

Description

Yet another calibre client for emacs.

This package integrates calibre (using calibredb) into emacs.

1. Powerful ebook dashboard.
2. Manage ebooks, actually not only ebooks!
3. Fetch metadata from online sources incl. automatic detection of ISBN for pdf and djvu files (automatic detection of ISBN requires pdf-tools and djvu package for pdf and djvu files respectively)
4. Manage Ebooks’ libraries and virtual libraries.
5. Customized Metadata: Tag, comment, highlight, favorite, archive etc.
6. Quick search, filter, make actions on items with ivy and helm.
7. Org-ref support.

Related package

• toc-mode (easily manage pdf/djvu document’s Table Of Contents)
• centaur-tabs/awesome-tab (Enable tab in emacs, turn eamcs into a modern multiple tabs pdf/epub reader.)

Installation

Install sqlite

calibredb will use the built-in SQLite engine if it is available (for emacs >29). For older emacs or emacs that is not built with SQLite support, you should install the external sqlite3 program.

macOS

brew install sqlite

Windows

With chocolatey

choco install sqlite

Linux

For example, in Ubuntu 18.04:

sudo apt install sqlite3

Install calibre

macOS

Download calibre’s DMG file from https://calibre-ebook.com/download_osx, install calibre.app to /Applications

Windows

With chocolatey

choco install calibre

Linux

For example, in Ubuntu 18.04:

sudo apt install calibre

Install calibredb.el

It’s available on Melpa :

M-x package-install calibredb

Spacemacs Layer

For Spacemacs this calibre-layer implements calibre.el with evilified keybindings

Configuration

Quick Start

require

(require 'calibredb)
(setq calibredb-root-dir "~/OneDrive/Doc/Calibre")
(setq calibredb-db-dir (expand-file-name "metadata.db" calibredb-root-dir))
(setq calibredb-library-alist '(("~/OneDrive/Doc/Calibre")
                                ("/Users/damonchan/Documents/Books Library")
                                ("/Users/damonchan/Documents/HELLO")
                                ("/Users/damonchan/Documents/Books")
                                ("/Users/damonchan/Documents/World")))

PS: If sqlite3 and calibredb is in not in your system path, set them with

(setq sql-sqlite-program "/usr/bin/sqlite3") ;; for emacs < 29 or no sqlite built-in emacs 
(setq calibredb-program "/Applications/calibre.app/Contents/MacOS/calibredb")

use-package

(use-package calibredb
  :defer t
  :config
  (setq calibredb-root-dir "~/OneDrive/Org/Doc/Calibre")
  (setq calibredb-db-dir (expand-file-name "metadata.db" calibredb-root-dir))
  (setq calibredb-library-alist '(("~/OneDrive/Org/Doc/Calibre")
                                  ("~/Documents/Books Library")
                                  ("~/Documents/LIB1")
                                  ("/Volumes/ShareDrive/Documents/Library/"))))

Virtual Libraries

Virtual libraries are some convenient shortcuts for quick filtering the Ebooks by setting the calibredb-search-filter.

(setq calibredb-virtual-library-alist '(("1. Development - work" . "work \\(pdf\\|epub\\)")
                                        ("2. Read it later" . "Readit epub")
                                        ("3. Development - rust" . "rust")))

Column width

You can configure the column width:

For example:

(setq calibredb-id-width 4)

• Set positive to limit the width.
• Set 0 to hide.
• Set -1 to keep original length.

The following columns are supported:

• calibredb-id-width
• calibredb-format-width
• calibredb-tag-width
• calibredb-title-width
• calibredb-author-width
• calibredb-comment-width
• calibredb-date-width

Then in *calibredb-search* buffer, press r to refresh the library.

Size indicator

Enable size indicator:

(setq calibredb-size-show t)

Then in *calibredb-search* buffer, press r to refresh the library.

File format icons

You can choose all-the-icons, icons-in-terminal, unicode icons to render the icons. You have to install the icons packages by yourself, otherwise it would not work.

To enable all-the-icons:

(setq calibredb-format-all-the-icons t)

To enable icons-in-terminal:

(setq calibredb-format-icons-in-terminal t)

To use unicode icons,

(setq calibredb-format-character-icons t)

Then in *calibredb-search* buffer, press r to refresh the library.

Notice: Do not enable icons on big libraries, it will consume a lot of time than you imagine.

TODO: Auto disable format icons when dealing with big libraries.

Configure to support org-ref

You can output a BibTex file which can be used in org-ref.

(require 'org-ref)
(setq calibredb-ref-default-bibliography (concat (file-name-as-directory calibredb-root-dir) "catalog.bib"))
(add-to-list 'org-ref-default-bibliography calibredb-ref-default-bibliography)
(setq org-ref-get-pdf-filename-function 'org-ref-get-mendeley-filename)

keybindings

(defvar calibredb-show-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map "?" #'calibredb-entry-dispatch)
    (define-key map "o" #'calibredb-find-file)
    (define-key map "O" #'calibredb-find-file-other-frame)
    (define-key map "V" #'calibredb-open-file-with-default-tool)
    (define-key map "s" #'calibredb-set-metadata-dispatch)
    (define-key map "e" #'calibredb-export-dispatch)
    (define-key map "q" #'calibredb-entry-quit)
    (define-key map "y" #'calibredb-yank-dispatch)
    (define-key map "," #'calibredb-quick-look)
    (define-key map "." #'calibredb-open-dired)
    (define-key map "\M-/" #'calibredb-rga)
    (define-key map "\M-t" #'calibredb-set-metadata--tags)
    (define-key map "\M-a" #'calibredb-set-metadata--author_sort)
    (define-key map "\M-A" #'calibredb-set-metadata--authors)
    (define-key map "\M-T" #'calibredb-set-metadata--title)
    (define-key map "\M-c" #'calibredb-set-metadata--comments)
    map)
  "Keymap for `calibredb-show-mode'.")

(defvar calibredb-search-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map [mouse-3] #'calibredb-search-mouse)
    (define-key map (kbd "<RET>") #'calibredb-find-file)
    (define-key map "?" #'calibredb-dispatch)
    (define-key map "a" #'calibredb-add)
    (define-key map "A" #'calibredb-add-dir)
    (define-key map "c" #'calibredb-clone)
    (define-key map "d" #'calibredb-remove)
    (define-key map "D" #'calibredb-remove-marked-items)
    (define-key map "j" #'calibredb-next-entry)
    (define-key map "k" #'calibredb-previous-entry)
    (define-key map "l" #'calibredb-virtual-library-list)
    (define-key map "L" #'calibredb-library-list)
    (define-key map "n" #'calibredb-virtual-library-next)
    (define-key map "N" #'calibredb-library-next)
    (define-key map "p" #'calibredb-virtual-library-previous)
    (define-key map "P" #'calibredb-library-previous)
    (define-key map "s" #'calibredb-set-metadata-dispatch)
    (define-key map "S" #'calibredb-switch-library)
    (define-key map "o" #'calibredb-find-file)
    (define-key map "O" #'calibredb-find-file-other-frame)
    (define-key map "v" #'calibredb-view)
    (define-key map "V" #'calibredb-open-file-with-default-tool)
    (define-key map "," #'calibredb-quick-look)
    (define-key map "." #'calibredb-open-dired)
    (define-key map "y" #'calibredb-yank-dispatch)
    (define-key map "b" #'calibredb-catalog-bib-dispatch)
    (define-key map "e" #'calibredb-export-dispatch)
    (define-key map "r" #'calibredb-search-refresh-and-clear-filter)
    (define-key map "R" #'calibredb-search-clear-filter)
    (define-key map "q" #'calibredb-search-quit)
    (define-key map "m" #'calibredb-mark-and-forward)
    (define-key map "f" #'calibredb-toggle-favorite-at-point)
    (define-key map "x" #'calibredb-toggle-archive-at-point)
    (define-key map "h" #'calibredb-toggle-highlight-at-point)
    (define-key map "u" #'calibredb-unmark-and-forward)
    (define-key map "i" #'calibredb-edit-annotation)
    (define-key map (kbd "<DEL>") #'calibredb-unmark-and-backward)
    (define-key map (kbd "<backtab>") #'calibredb-toggle-view)
    (define-key map (kbd "TAB") #'calibredb-toggle-view-at-point)
    (define-key map "\M-n" #'calibredb-show-next-entry)
    (define-key map "\M-p" #'calibredb-show-previous-entry)
    (define-key map "/" #'calibredb-search-live-filter)
    (define-key map "\M-t" #'calibredb-set-metadata--tags)
    (define-key map "\M-a" #'calibredb-set-metadata--author_sort)
    (define-key map "\M-A" #'calibredb-set-metadata--authors)
    (define-key map "\M-T" #'calibredb-set-metadata--title)
    (define-key map "\M-c" #'calibredb-set-metadata--comments)
    map)
  "Keymap for `calibredb-search-mode'.")

PS: Keybindings might be changed in future versions.

Workflows

There are three ways to manage your ebooks:

Start with calibredb

First, M-x calibredb to enter ebook dashboard. You can perform the following actions:

• Open/View the ebook
• Open Dired the ebook located
• Fetch (from Google and Amazon.com) and set metadata on the ebook under cursor
• Set metadata on marked ebooks
• Add/Remove ebooks on current library
• Export the ebook under cursor
• Clone/Switch/Jump to different libraries
• Live filter the results
• Generate Catalog, such as a BibTex file
• Favorite, highlight and archive the items

Start with calibredb-find-helm or calibredb-find-counsel

• M-x calibredb-find-helm or calibredb-find-counsel to enter the ebook list
• C-i (Helm) C-o (Counsel) to enter the action menus.

Start with calibredb-list

• M-x calibredb-list to enter ebook dashboard (buffer *calibredb-list*)

PS: Workflows might be slightly changed in future versions.

Notice: This package use calibredb update the metadata.db file rather than use sqlite to update the database. Sqlite is only used for reading rather than updating and deleting. It should be safe to modify the database with this package, but it is still very important to do backup by yourself. For example, with cloud services.

Q&A

The keybindings mentioned below are referenced from

keybindings.

Transient commands

calibredb supports Transient commands just like magit. Most of the features are binded in Transient commands. You can press ? to checkout.

• calibredb-dispatch: Invoke a calibredb command from a list of available commands in *calibredb-search* buffer.
• calibredb-entry-dispatch: Invoke a calibredb command from a list of available commands in *calibredb-entry* buffer.
• calibredb-set-metadata-dispatch: Set metadata.
• calibredb-export-dispatch: Export files.
• calibredb-catalog-bib-dispatch: BibTex operation.
• calibredb-yank-dispatch: Invoke a Yank operation.

What is my working library?

M-x calibredb, your current library path shows in the header in buffer *calibredb-search* Besides, variable calibredb-root-dir also saves the current library location.

How to open an ebook?

1. M-x calibredb
   • In *calibredb-search* buffer, move the cursor to the ebook you want to open.
   • Press RET/o/O/V to open it.
   • If you are using macOS, you can also press =,= to quick look the ebook.
2. M-x calibredb-find-helm or calibredb-find-counsel
   • Select the ebook you want to open in the list
   • Press RET to open it.
3. M-x calibredb
   • In *calibredb-search* buffer, move the cursor to the ebook and press v to show details, or just Right Click on the ebook.
   • Then in *calibredb-entry* buffer, press o/O/V to open it.

How to add ebooks?

1. M-x calibredb-add, select, mark ebooks (only ivy supports mark/unmark currently - with ivy-hydra, in ivy-window, press m to mark, DEL or u to unmark. Other engines can only select one item) and add to current library.
2. M-x calibredb-add-dir and select one directory, all supported formats will be added into current library.
3. M-x dired, mark the files, then M-x calibredb-dired-add, marked files in dired will be added to current library. After adding process ends, dired will ask the user delete the files or not.

Please notice: Add books may fail! There are some reasons:

• The book already exists in the database. If you still want to add the duplicated books, you can set calibredb-add-duplicate to Non-Nil.
• Not all book formats are supported. If you can not add a specific book, check the logs in *calibredb* buffer.

How to remove ebooks?

1. M-x calibredb
   • move the cursor to the ebook you want to delete, press d, calibredb will ask you to delete or not.
2. M-x calibredb-find-helm or calibredb-find-counsel
   • Select the ebook you want to delete in the list
   • C-i (Helm) C-o (Counsel) to enter the action menu.
   • Perform remove action as shown in the menu.

PS: If you want to delete in bulk with marked items, use calibredb-remove-marked-items. m to mark items, D to bulk delete.

How to switch virtual libraries?

First, set calibredb-library-alist to include the calibre virtual libraries.

(setq calibredb-virtual-library-alist '(("1. Development - work" . "work \\(pdf\\|epub\\)")
                                        ("2. Read it later" . "Readit epub")
                                        ("3. Development - rust" . "rust")))

Then, in *calibredb-search* buffer,

• Press l to open the library list and select the library.
• Press n or p to switch to next or previous library.

Or, in *calibredb-search* buffer, call calibredb-virtual-library-list directly and select the library.

How to switch libraries?

Set calibredb-library-alist to include the calibre libraries.

Make sure the libraries are valid. Create libraries using Calibre GUI or M-x calibredb-clone to clone the existing library to a new library, before setting it in calibredb-library-alist.

(setq calibredb-library-alist '(("~/OneDrive/Doc/Calibre")
                                  ("/Users/damonchan/Documents/Books Library")
                                  ("/Users/damonchan/Documents/HELLO")
                                  ("/Users/damonchan/Documents/Books")
                                  ("/Users/damonchan/Documents/World")
                                  ("http://192.168.1.2/opds" "account" "password") ; https://github.com/janeczku/calibre-web
                                  ("http://opds.oreilly.com/opds/")
                                  ("https://bookserver.archive.org/catalog/")
                                  ("http://arxiv.maplepop.com/catalog/")
                                  ("https://m.gutenberg.org/ebooks.opds/")
                                  ("http://www.feedbooks.com/catalog.atom")
                                  ("https://tatsu-zine.com/catalogs.opds")
                                  ("http://aozora.textlive.net/catalog.opds")))

Then, in *calibredb-search* buffer,

• Press L to open the library list and select the library.
• Press N or P to switch to next or previous library.

Or in *calibredb-search* buffer, call calibredb-library-list directly and select the library.

If the library is not defined in calibredb-library-alist, you can call calibredb-switch-library and select the path of the library that you want to switch temporarily.

How to set metadata on ebooks?

• In *calibredb-search* buffer, m/DEL/u to mark/unmark backward/unmark forward items, and s to set metadata in bulk. If you do not mark any items, actions will be performed on the item under cursor.
• In *calibredb-entry* buffer, press s to set metadata.
• In *calibredb-search* buffer, press s f to fetch metadata by author and title or s i to fetch by ISBN. For fetching by author and title enter one (or more) full lastnames of the author(s) (or delete redundant input from initial input). For fetching by ISBN enter the ISBN number (usually can be found and copied from on of the first pages of a book). As the title may contain the ISBN it is set as initial input. Wait few second for Emacs to retrieve metadata from the sources. Subsequently use C-M-n/C-M-p to select and preview the source to use for adding the metadata to the document. Press RET to add selected metadata to source.
• In *calibredb-search* buffer, press s d to fetch metadata by identifier.

Tips: You can filter the result via / before setting the metadata.

About fetch-ebook-metadata

We are using fetch-ebook-metadata cli tool to fetch the metadata. However, fetching ebook metadata is a little tricky, especially about the sources configurations. Since the settings on calibre GUI would affect the fetch-ebook-metadata cli. Follow below steps to setup.

1. Set up the source settings in Calibre GUI. You are right, you need to configure the settings on GUI first.
   • Preferences -> Preferences -> Sharing/Metadata download
   • Tick ‘source’ you like to use
   • Set the ‘Cover priority’
   • Apply
2. Specify the list of metadata download plugins to use, this should be the same as the calibre GUI configuration.

(setq calibredb-fetch-metadata-source-list '("Google" "Amazon.com" "Douban Books"))

How to mark favorite/highlight/archive on ebooks?

• In *calibredb-search* buffer, m to mark the items, f/h/x to toggle favorite/highlight/archive status on marked items.

  Demo:

How to do live filtering?

• Press / to start live filtering.

Minibuffer shows Filter (live), input some texts to start searching (REGEX is supported).

The following columns will be searched:

• id
• text (comment)
• tag
• title
• format
• author_sort
• ids

If the keyword occurs in any of the columns above, the matched ebook records will be shown.

Here is the demo:

If you want to search by one type of metadata, for example, by tag, please check:

How to do group filtering?.

How to do group filtering?

Press g, then press

• t: fitler by tag
• f: filter by format
• a: filter by author
• d: filter by date
• l: filter by virutal library
• L: filter by library
• r: reset (clearing the search filter)

For example, after pressing g t then select any tags, group filter for tag is enabled. In this case, minibuffer shows Filter (tag), if you press /, it only search in tag.

If you press g r, you can switch back to live filtering, and minibuffer will show Filter (live).

How to do quick group filtering?

• Click the calibredb-favorite-icon, authors, file format, and tags.
• Press r/R to reset the filtering.

  Demo:

  

How to do sorting?

Press o, then press

• o: toggle the order (desc or asc)
• i: sort by id
• t: sort by title
• f: sort by format
• a: sort by author
• d: sort by date
• p: sort by pubdate
• T: sort by Tag
• s: sort by size
• l: sort by language

Configure calibredb-sort-by and calibredb-order to control the default sorting.

How to interact with org-ref?

• Setup org-ref

  (require 'org-ref)
  (setq calibredb-ref-default-bibliography "~/Desktop/catalog.bib")
  (add-to-list 'org-ref-default-bibliography calibredb-ref-default-bibliography)
  (setq org-ref-get-pdf-filename-function 'org-ref-get-mendeley-filename)
      

  or

  (use-package! org-ref
  :after-call calibredb
  :config
  (setq calibredb-ref-default-bibliography "~/Desktop/catalog.bib")
  (add-to-list 'org-ref-default-bibliography calibredb-ref-default-bibliography)
  (setq org-ref-get-pdf-filename-function 'org-ref-get-mendeley-filename))
      

• In *calibredb-search* buffer, b b to generate the ebook catalogs with a BibTex file.
• The BibTex file is generated under current library path - calibredb-root-dir.
• Every time you switch your library, the corresponding BibTex file path will added into org-ref-default-bibliography temporarily.
• In an org file, C-c ] to insert cite.

  Demo:

Why the loading time is so long?

For some big libraries, such as the libraries that has 10000+ books, the package will need a few seconds to query and decode all the metadata. This will be improved in future versions.

You should know the following test results and behaviors so that it will not frustrate you when dealing with big libraries:)

1. Tested with a library that has 8668 books, using 4.2 GHz Intel Core i7 in macOS 10.13.6, around 2 to 3 seconds to query the database.
2. DO NOT setq calibredb-format-icon t on big library. Tested with a library that has 8668 books, using 4.2 GHz Intel Core i7 in macOS 10.13.6, around 37 seconds to query the database.
3. The first time to enter calibredb, is to query and decode the whole database. After that, all data will be saved in calibredb-search-entries. Therefore, the next time to load the library is just reading calibredb-search-entries and show again. And you can feel much happier starting from the second time.
4. Update metadata, refresh dashboard, and switch library will re-query and decode the whole database.

Can not remember the keybindings?

Press ?, it will show you almost all actions.

Demo:

How to edit annotation with org-mode?

In *calibredb-search* buffer,

M-x calibredb-edit-annotation

Or press i.

By default, the annotation would be saved to comments field. If you want to change to other filed, please set with the following statement:

(setq calibredb-annotation-field "comments")

Please notice: Due to the limitation of calibredb, the blank new lines will be deleted.

How to search in ebooks directly?

We wrap counsel-ag in calibredb-rga, using the power of ripgrep-all. First, install ripgrep-all, then in *calibredb-search*, *calibredb-entry* buffer or under pdf-view-mode / nov-view-mode,

M-x calibredb-rga

How to interact with calibredb files in org files?

In *calibredb-search* buffer,

• y y copy as calibredb link. If you click the link, it will open the corresponding *calibredb-entry* buffer.
• y f copy as file org link. If you click the link, it will open the file directly.

More examples?

Please check

keybindings .

All are self documented.

Supported Features

For more details on the actions, check the official calibre documents: https://manual.calibre-ebook.com/generated/en/calibredb.html

calibredb

Enter calibre emacs client, a new buffer called *calibredb-search* with calibredb-search-mode

M-x calibredb

RET open the entry

To toggle between detail view or compact view.

M-x calibredb-toggle-view

TODO:

• Multiple dashboard with different libraries.
• Sorting.

calibredb-search-live-filter

In *calibredb-search*, perform live filtering:

M-x calibredb-search-live-filter

The following columns will be searched:

• id
• text (comment)
• tag
• title
• format
• author_sort
• ids

If the keyword occurs in any of the columns above, the matched ebook record will be shown.

1. Live filter searches the results in calibredb-full-entries rather than query the database.
2. Keywords are separated by “Spaces” (AND operation, mainly used to narrow down the results, the more spaces you insert, the fewer results.)
3. Each keyword supports REGEX.

For example, to search Ebooks may contain a tag - work, and the format maybe pdf or epub. You can insert work \(pdf\|epub\) (Notice the single backslash) in mini buffer.

If you set the filter keywords in calibredb-virtual-library-alist, you should (Notice the double backslashes):

(setq calibredb-virtual-library-alist '(("1. Development - work" . "work \\(pdf\\|epub\\)")
                                        ("2. Read it later" . "Readit epub")
                                        ("3. Development - rust" . "rust")))

Check REGEX https://www.gnu.org/software/emacs/manual/html_node/efaq/Using-regular-expressions.html.

Tip: *calibredb-search*, calibredb-find-counsel, and calibredb-find-helm are sharing the same results. Therefore, after the filtering in *calibredb-search*, you can do second-level filter with calibredb-find-counsel, and calibredb-find-helm.

calibredb-find-helm

Use helm to list all ebooks

M-x calibredb-find-helm

calibredb-find-counsel

Use counsel to list all ebooks

M-x calibredb-find-counsel

calibredb-list

Generate an org buffer which contains all files’ cover images, titles and the file links.

M-x calibredb-list

calibredb-clone

Create a clone of the current library. This creates a new, empty library that has all the same custom columns, Virtual libraries and other settings as the current library.

M-x calibredb-clone

Tips: Libraries can be used for any purposes, one for books, one for lecture notes, one for research references etc.

calibredb-library-list

Switch library from library list defined in calibredb-library-alist. If under *calibredb-search* buffer, it will auto refresh after selecting the new item.

M-x calibredb-library-list

calibredb-switch-library

Switch a library temporary by selecting a path.

M-x calibredb-switch-library

Show details

This action will get you to the book details buffer called *calibredb-entry*

Dispatch

calibredb-dispatch

Under *calilbredb-search* or *calilbredb-entry* buffer, you can make actions on selected item with calibredb-dispatch, just like magit-dispatch.

M-x calibredb-dispatch

Or fire with keybinding ?

calibredb-set-metadata-dispatch

M-x calibredb-set-metadata-dispatch

Or fire with keybinding s

calibredb-catalog-bib-dispatch

M-x calibredb-catalog-bib-dispatch

Or fire with keybinding b

calibredb-export-dispatch

M-x calibredb-export-dispatch

Or fire with keybinding e

add

To add a file into calibre, call

M-x calibredb-add

To add a directory into calibre, call

M-x calibredb-add-dir

remove

To remove an item, call

M-x calibredb-remove

To remove the marked items, call

M-x calibredb-remove-marked-items

set_metadata

To set metadata,

M-x calibredb-set-metadata-dispatch

Export

To export the ebook,

M-x calibredb-export-dispatch

Yank

To yank the ebook as org links,

M-x calibredb-yank-dispatch

Catalog

BibTex

Export the ebook catalogs to a BibTex file.

M-x calibredb-catalog-bib-dispatch

PS: Document can be found in https://github.com/kovidgoyal/calibre/blob/master/src/calibre/library/catalogs/bibtex.py

calibredb-rga

Search in ebooks.

RELEASES

Contributor