Skip to content

Calibre Search FAQ

Jump to bottom
kiwidude68 edited this page Feb 3, 2023 · 14 revisions

Introduction

These browser web extensions allow you to perform a search against your local calibre library for the selected text or links on a web page.

The search option is available via:

  • a right-click context menu for your selected text or a hyperlink.
  • a keyboard shortcut Ctrl + Q
  • a toolbar button in the extensions area of your browser (if visible).

Prerequisites

This extension also requires you to download/install:

Host application installation

Why do I need it?

In order to pass the search text from your web browser extension to calibre, a native application is required in between. This application acts as a proxy between the secure world of your web browser and your desktop computer. You can see this described with a nice diagram in the first link below:

For the current implementation we have a relatively simple Python script, which listens for a message from the calibre-search web extension containing the text to search. This Python script can then run a calibre command to display your search results in your library using URL scheme syntax added in calibre v5.5.

How do I install it on Windows?

  1. Download the latest calibre-search-app-windows.zip, from the Releases section here
  2. Extract to a temporary folder. e.g. C:\calibre-search-app-windows\
  3. Navigate to C:\calibre-search-app-windows\
  4. Right click on install-host.bat
  5. Select Run as administrator and confirm any prompts.
    • Administrator access is required to install the necessary registry keys for native messaging for your browser.
  6. If you see no errors, you can now delete your temporary folder above.
    • The install-host.bat has made a copy of itself to a folder in your user profile, so the extracted folder is no longer needed.

How do I install it on Mac/Linux?

TODO: Add support/instructions.

For those knowledgable and impatient it should just be a case of copying the relevant manifest-*.json file into the appropriate browser specific subfolder named com.kiwidude.calibre-search and replacing the MANIFESTPATH token inside those files with the path to execute the python script.

See: https://developer.chrome.com/docs/apps/nativeMessaging/#native-messaging-host-location

What does this app consist of?

Instructions will vary by platform, but describing the most common case of Windows users:

  • install-host.bat batch file a user can run (as administrator) to install this app in one step.
  • Registry key entries to point to the browser specific manifest-*.json file below.
  • manifest-chrome.json and manifest-firefox.json files, describing the command lines to run.
  • calibre-search.cmd batch file invoked every time you do a search from the extension to run the Python script.
  • calibre-search.py Python script that listens for the message from the browser and launches the calibre search.

Where does it install to?

On Windows if you run install-host.cmd then all the necessary files will be copied to:

%LOCALAPPDATA%\com.kiwidude.calibre_search\

If you don't like this location you can of course move things around, but you must make sure the registry keys and the paths within the manifest-*.json files reflect the location.

Why Python?

Could I have chosen a different tech stack? Of course. However as a personal project with Python already installed it was super quick to get up and running.

A couple of other options I considered (and may yet offer in future) are listed below:

  • Build a custom executable using Golang. This would give a very nice small executable, not requiring other runtime support like Python or nodejs.
    • Update This is actually now implemented, I just need to package it up in a release build for end users.
    • Some users may freak out over the (unavoidable) Windows antivirus warnings an executable like this can generate.
    • The Go application does the exact same thing as the Python script, source code is avilable in this repository.
  • Create nodejs scripts, and bundle nodejs with this code. That would negate the need for the user to have Python installed/in their path.
    • Using Python does avoid the need for putting nodejs binaries in my repo and dealing with OS platform builds.

It should be said neither of those approaches avoids the need for the registry keys, manifest files and some form of installation step. They just avoid the need for a user to install Python.

Could we avoid a host application?

This was a suggestion by the calibre creator Kovid Goyal himself on the MobileRead forums. By adding a specific new endpoint to the calibre Content Server, we could have the browser extensions send an http request direct to calibre rather than using the native messaging approach above. The Content Server code would do the equivalent of the Python script above of running a search in calibre.

So no need for this application/separate download, no multi-platform issues - sounds amazing right? Indeed it would be, however...

  1. Someone has to develop this new endpoint, and get it included with a calibre build.
    • Forces users to be running the latest calibre version.
    • Requires calibre source code knowledge I do not have currently.
  2. Each user must have Content Server running
    • Within the gui there is an option to Run server automatically when calibre starts
    • Are there downsides to this like adding to calibre startup/shutdown times?
  3. It is yet to be tested that we could satisfactorily invoke this from extension code.

Never say never on this approach if time allows or someone else volunteers. I could always make it optional in the extensions options pages so a user not wanting to run Content Server could still use this native application approach.

Configuration options

Library name

This is the same name you see in the calibre application library menu, which is also the same as the folder name your library resides in. You can only search against one library.

e.g. Calibre Library or MyBooks

Replace expressions

These are optional words or regular expressions that you would like to apply to the selected text or hyperlinks to filter out characters before passing the search text to calibre. Add as many expressions as you like, one per line. All replacements are made with a space, and all doubled up spaces are reduced before the search.

An expression starting with / will be interpreted as a regular expression, anything else will be treated as a "word". Such "words" will be converted to regular expressions when applying by surrounding them with case insensitive /gi word boundaries \b that will match anywhere in your selected text. So the will become /\bthe\b/gi.

If the simple word replacement is not what you want you can of course write a more specific regular expression. For testing, I suggest a website such as regex101.com

Examples

If we have the following text selected on a website: My Super, Amazing Title by Some Author (2022)

A search against calibre with no replace expressions is unlikely to find a match in your library. There is noise in that selection we do not want of the by word between title and author, and the stuff in parenthesis at the end of (2022). We also may want to strip that comma , out of there too. This is what replace expressions are for.

To remove the word by from all searches we do, we can add either a simple word to the list:

by

Or we can express it as a case insensitive regular expression like this:

/\bby\b/gi

Either of those would result in My Super, Amazing Title Some Author (2022) being passed to calibre.

To strip all the parenthesis and what they enclose, you could use this:

/\([^\)]*\)/g

To remove any occurrences of :, , or & you could use this:

/\:|,|\&/g

With all of the above, the calibre search now becomes: My Super Amazing Title Some Author

An example list of replace expressions you may find useful:

the
series
by
/\([^\)]*\)/g
/\:|,|\&/g

Translations

I have built support for translations into these extensions, but not as yet provided an easy mechanism for contributors such as a Transifex project. Both the Firefox and Chrome extensions have identical text to be translated, so I will just manually copy the files from one repo to the other.

If you did want to contribute a translation, it is as simple as:

  1. Download the calibre-search-chrome repository as a zip file
  2. Extract to a folder and navigate to the addon\_locales\ folder
  3. Copy the contents of the en subfolder to a new subfolder for your appropriate locale code
  4. Translate the contents of both the help.html and messages.json files
  5. Zip up your new locale subfolder and either raise an Issue attaching the files, or contact kiwidude via private message on the MobileRead forums.

Credits

Donations

If you enjoy my calibre plugins or extensions, please feel free to show your appreciation!

paypal

paypal.me/kiwidudeOz

Clone this wiki locally