Customizing calibre

calibre has a highly modular design. Various parts of it can be customized. You can learn how to create recipes to add new sources of online content to calibre in the Section Adding your favorite news website. Here, you will learn, first, how to use environment variables and tweaks to customize calibre‘s behavior, and then how to specify your own static resources like icons and templates to override the defaults and finally how to use plugins to add functionality to calibre.

Environment variables

• CALIBRE_CONFIG_DIRECTORY - sets the directory where configuration files are stored/read.
• CALIBRE_OVERRIDE_DATABASE_PATH - allows you to specify the full path to metadata.db. Using this variable you can have metadata.db be in a location other than the library folder. Useful if your library folder is on a networked drive that does not support file locking.
• CALIBRE_DEVELOP_FROM - Used to run from a calibre development environment. See Setting up a calibre development environment.
• CALIBRE_OVERRIDE_LANG - Used to force the language used by the interface (ISO 639 language code)
• SYSFS_PATH - Use if sysfs is mounted somewhere other than /sys
• http_proxy - Used on linux to specify an HTTP proxy

Tweaks

Tweaks are small changes that you can specify to control various aspects of calibre‘s behavior. You can change them by going to Preferences->Advanced->Tweaks. The default values for the tweaks are reproduced below

#!/usr/bin/env python
# vim:fileencoding=UTF-8:ts=4:sw=4:sta:et:sts=4:ai
__license__   = 'GPL v3'
__copyright__ = '2010, Kovid Goyal <kovid@kovidgoyal.net>'
__docformat__ = 'restructuredtext en'

'''
Contains various tweaks that affect calibre behavior. Only edit this file if
you know what you are doing. If you delete this file, it will be recreated from
defaults.
'''


# The algorithm used to assign a new book in an existing series a series number.
# Possible values are:
# next - Next available number
# const - Assign the number 1 always
series_index_auto_increment = 'next'



# The algorithm used to copy author to author_sort
# Possible values are:
#  invert: use "fn ln" -> "ln, fn" (the original algorithm)
#  copy  : copy author to author_sort without modification
#  comma : use 'copy' if there is a ',' in the name, otherwise use 'invert'
#  nocomma : "fn ln" -> "ln fn" (without the comma)
author_sort_copy_method = 'invert'


# Set whether boolean custom columns are two- or three-valued.
#  Two-values for true booleans
#  three-values for yes/no/unknown
# Set to 'yes' for three-values, 'no' for two-values
bool_custom_columns_are_tristate = 'yes'


# Provide a set of columns to be sorted on when calibre starts
#  The argument is None if saved sort history is to be used
#  otherwise it is a list of column,order pairs. Column is the
#  lookup/search name, found using the tooltip for the column
#  Order is 0 for ascending, 1 for descending
# For example, set it to [('authors',0),('title',0)] to sort by
# title within authors.
sort_columns_at_startup = None

# Format to be used for publication date and the timestamp (date).
#  A string controlling how the publication date is displayed in the GUI
#  d    the day as number without a leading zero (1 to 31)
#  dd    the day as number with a leading zero (01 to 31)
#  ddd    the abbreviated localized day name (e.g. 'Mon' to 'Sun').
#  dddd    the long localized day name (e.g. 'Monday' to 'Qt::Sunday').
#  M    the month as number without a leading zero (1-12)
#  MM    the month as number with a leading zero (01-12)
#  MMM    the abbreviated localized month name (e.g. 'Jan' to 'Dec').
#  MMMM    the long localized month name (e.g. 'January' to 'December').
#  yy    the year as two digit number (00-99)
#  yyyy    the year as four digit number
#  For example, given the date of 9 Jan 2010, the following formats show
#  MMM yyyy ==> Jan 2010    yyyy ==> 2010       dd MMM yyyy ==> 09 Jan 2010
#  MM/yyyy ==> 01/2010      d/M/yy ==> 9/1/10   yy ==> 10
# publication default if not set: MMM yyyy
# timestamp default if not set: dd MMM yyyy
gui_pubdate_display_format = 'MMM yyyy'
gui_timestamp_display_format = 'dd MMM yyyy'

# Control title and series sorting in the library view.
# If set to 'library_order', Leading articles such as The and A will be ignored.
# If set to 'strictly_alphabetic', the titles will be sorted without processing
# For example, with library_order, The Client will sort under 'C'. With
# strictly_alphabetic, the book will sort under 'T'.
# This flag affects Calibre's library display. It has no effect on devices. In
# addition, titles for books added before changing the flag will retain their
# order until the title is edited. Double-clicking on a title and hitting return
# without changing anything is sufficient to change the sort.
title_series_sorting = 'library_order'

# Control how title and series names are formatted when saving to disk/sending
# to device. If set to library_order, leading articles such as The and A will
# be put at the end
# If set to 'strictly_alphabetic', the titles will be sorted without processing
# For example, with library_order, "The Client" will become "Client, The". With
# strictly_alphabetic, it would remain "The Client".
save_template_title_series_sorting = 'library_order'

# Specify a folder that calibre should connect to at startup using
# connect_to_folder. This must be a full path to the folder. If the folder does
# not exist when calibre starts, it is ignored. If there are '\' characters in
# the path (such as in Windows paths), you must double them.
# Examples:
#     auto_connect_to_folder = 'C:\\Users\\someone\\Desktop\\testlib'
#     auto_connect_to_folder = '/home/dropbox/My Dropbox/someone/library'
auto_connect_to_folder = ''


# Create search terms to apply a query across several built-in search terms.
# Syntax: {'new term':['existing term 1', 'term 2', ...], 'new':['old'...] ...}
# Example: create the term 'myseries' that when used as myseries:foo would
# search all of the search categories 'series', '#myseries', and '#myseries2':
# grouped_search_terms={'myseries':['series','#myseries', '#myseries2']}
# Example: two search terms 'a' and 'b' both that search 'tags' and '#mytags':
# grouped_search_terms={'a':['tags','#mytags'], 'b':['tags','#mytags']}
# Note: You cannot create a search term that is a duplicate of an existing term.
# Such duplicates will be silently ignored. Also note that search terms ignore
# case. 'MySearch' and 'mysearch' are the same term.
grouped_search_terms = {}


# Set this to True (not 'True') to ensure that tags in 'Tags to add when adding
# a book' are added when copying books to another library
add_new_book_tags_when_importing_books = False


# Set the maximum number of tags to show per book in the content server
max_content_server_tags_shown=5

Overriding icons, templates, etcetera

calibre allows you to override the static resources, like icons, templates, javascript, etc. with customized versions that you like. All static resources are stored in the resources sub-folder of the calibre install location. On Windows, this is usually C:Program FilesCalibre2resources. On OS X, /Applications/calibre.app/Contents/Resources/resources/. On linux, if you are using the binary installer from the calibre website it will be /opt/calibre/resources. These paths can change depending on where you choose to install calibre.

You should not change the files in this resources folder, as your changes will get overwritten the next time you update calibre. Instead, go to Preferences->Advanced->Miscellaneous and click Open calibre configuration directory. In this configuration directory, create a sub-folder called resources and place the files you want to override in it. Place the files in the appropriate sub folders, for example place images in resources/images, etc. calibre will automatically use your custom file in preference to the builtin one the next time it is started.

For example, if you wanted to change the icon for the Remove books action, you would first look in the builtin resources folder and see that the relevant file is resources/images/trash.svg. Assuming you have an alternate icon in svg format called mytrash.svg you would save it in the configuration directory as resources/images/trash.svg. All the icons used by the calibre user interface are in resources/images and its sub-folders.

A Hello World plugin

Suppose you have an installation of calibre that you are using to self publish various e-documents in EPUB and LRF format. You would like all file generated by calibre to have their publisher set as “Hello world”, here’s how to do it. Create a file name my_plugin.py (the file name must end with plugin.py) and enter the following Python code into it:

import os
from calibre.customize import FileTypePlugin

class HelloWorld(FileTypePlugin):

  name                = 'Hello World Plugin' # Name of the plugin
  description         = 'Set the publisher to Hello World for all new conversions'
  supported_platforms = ['windows', 'osx', 'linux'] # Platforms this plugin will run on
  author              = 'Acme Inc.' # The author of this plugin
  version             = (1, 0, 0)   # The version number of this plugin
  file_types          = set(['epub', 'lrf']) # The file types that this plugin will be applied to
  on_postprocess      = True # Run this plugin after conversion is complete

  def run(self, path_to_ebook):
    from calibre.ebooks.metadata.meta import get_metadata, set_metadata
    file = open(path_to_ebook, 'r+b')
    ext  = os.path.splitext(path_to_ebook)[-1][1:].lower()
    mi = get_metadata(file, ext)
    mi.publisher = 'Hello World'
    set_metadata(file, mi, ext)
    return path_to_ebook

That’s all. To add this code to calibre as a plugin, simply create a zip file with:

zip plugin.zip my_plugin.py

You can download the Hello World plugin from helloworld_plugin.zip. Now either use the configuration dialog in calibre GUI to add this zip file as a plugin, or use the command:

calibre-customize -a plugin.zip

Every time you use calibre to convert a book, the plugin’s run() method will be called and the converted book will have its publisher set to “Hello World”. For more information about calibre‘s plugin system, read on...

The Plugin base class

As you may have noticed above, all calibre plugins are classes. The Plugin classes are organized in a hierarchy at the top of which is calibre.customize.Plugin. The has excellent in source documentation for its various features, here I will discuss a few of the important ones.

First, all plugins must supply a list of platforms they have been tested on by setting the supported_platforms member as in the example above.

If the plugin needs to do any initialization, it should implement the initialize() method. The path to the plugin zip file is available as self.plugin_path. The initialization method could be used to load any needed resources from the zip file.

If the plugin needs to be customized (i.e. it needs some information from the user), it should implement the customization_help() method, to indicate to calibre that it needs user input. This can be useful, for example, to ask the user to input the path to a needed system binary or the URL of a website, etc. When calibre asks the user for the customization information, the string retuned by the customization_help() method is used as help text to le thte user know what information is needed.

Another useful method is temporary_file(), which returns a file handle to an opened temporary file. If your plugin needs to make use of temporary files, it should use this method. Temporary file cleanup is then taken care of automatically.

In addition, whenever plugins are run, their zip files are automatically added to the start of sys.path, so you can directly import any python files you bundle in the zip files. Note that this is not available when the plugin is being initialized, only when it is being run.

Finally, plugins can have a priority (a positive integer). Higher priority plugins are run in preference tolower priority ones in a given context. By default all plugins have priority 1. You can change that by setting the member :attr:’priority` in your subclass.

See Plugin for details.

File type plugins

File type plugins are intended to be associated with specific file types (as identified by extension). They can be run on several different occassions.

• When books/formats are added ot the calibre database (if on_import is set to True).
• Just before an any2whatever converter is run on an input file (if on_preprocess is set to True).
• After an any2whatever converter has run, on the output file (if on_postprocess is set to True).

File type plugins specify which file types they are associated with by specifying the file_types member as in the above example. the actual work should be done in the run() method, which must return the path to the modified ebook (it can be the same as the original if the modifcations are done in place).

See FileTypePlugin for details.

Metadata plugins

Metadata plugins add the ability to read/write metadata from ebook files to calibre. See Metadata plugins for details.

Metadata download plugins

Metadata download plugins add various sources that calibre uses to download metadata based on title/author/isbn etc. See Catalog plugins for details.