Library and other configuration options can be accessed using the Customize plugin
The plugin supports multiple lending libraries. Individual libraries and their relative priorities are set in the plugin's configuration. Each library is identified by a short, unique name (chosen by the user), its service provider and a library-id. Configured libraries will only be used for searching and unlinking if they are enabled in the configuration by checking the first column.
The default configuration contains some sample libraries that can be enabled for searching. Additional libraries can be added as needed using the (+
) button and existing libraries can be removed using the (-
OverDrive is the largest provider of lending library services. Books are available in EPUB and PDF formats via Adobe Digital Editions and Kindle formats via Amazon. Audiobooks are also available. Some OverDrive libraries allow recommendation of books for future acquisition.
You can find libraries supported by OverDrive by selecting the Library Search
tab at http://search.overdrive.com
. For OverDrive powered libraries the library-id is the host name of the library web site (e.g.: freelibrary.lib.overdrive.com
for the OverDrive site of the Free Library of Philadelphia). This can be found by examining the browser address bar after surfing to the library.
Some OverDrive libraries require a user to sign in before the catalog of the library can be searched. Also, OverDrive Advantage allows individual lending libraries that are members of a consortium with a shared collection to have additional titles that are only available when their patrons are signed in. A list of branches with Advantage titles can be found at the page ODAdvantage.htm
on your library website.
The plugin configuration has optional fields for the user's credentials for each lending library: branch ID number, library card number and PIN. Entering this data is not required and will only be useful if your lending library has OverDrive Advantage titles or requires a sign in before allowing searches.
If you choose to configure your library credentials in the plugin, then a library card number is required. Some, but not all, libraries also require entry of a branch ID and/or PIN during sign in.
If your library normally prompts for the selection of a specific branch during sign in, the corresponding branch ID number will need to be entered as part of the configuration. This number can sometimes be found by observing the URLs being accessed during a manual sign in to the library. Look for something in the form of:
As an alternative, you can enter your library card and PIN in the plugin configuration, but leave the branch ID field blank, check the first column to enable the library, and then perform a search for any book. The sign in process will fail, but the log of the search should contain a list of valid branches for the consortium along with their corresponding branch ID numbers.
Some libraries do not require a PIN or additional data field beyond the library card number. In those cases leave the PIN field blank in the configuration.
3M Cloud Library
Some lending libraries use 3M Cloud Library in addition to, or instead of, OverDrive. Books are available in EPUB and PDF formats via an application compatible with Adobe Digital Editions. Audiobooks will be available from some libraries starting in August 2014. 3M supports recommendation of books for future acquisition at some libraries.
You can find libraries supported by 3M by using Lookup your library
. The library-id can be found by going to the library web site and examining the browser address bar for the portion of the URL following /library/
. For the Brooklyn Public Library the web site is http://ebook.3m.com/library/bpl/
and so the library-id is bpl
Amazon Kindle Unlimited allows borrowing up to ten e-books at a time with no holds or waits for a monthly fee. The Amazon Kindle Owners' Lending Library is available to Amazon Prime members and allows borrowing of one e-book per month on a registered kindle device. Both services offer a similar, limited collection of books from which to choose.
When configuring, the library-id should be prime
for the Kindle Owners' Lending Library, unlimited
for Kindle Unlimited, kuwn
for Kindle Unlimited with Narration, w4v.store
for purchasable e-books supporting Whispersync for Voice, or store
for all purchasable Kindle e-books. Prefix the library-id with uk-
for Amazon UK. Multiple collections can be searched by creating separate library entries for each in the configuration table.
Searches at Amazon do not always provide complete results, so books may sometimes appear to be removed and re-added to collections when nothing has actually changed. Also, editions of public domain works are added and removed frequently leading to many changes found for those books.
The general configuration option Set amazon identifiers when links to Amazon Kindle editions are added
causes the amazon
book identifier to be updated to point to kindle editions discovered during search.
Somewhat faster searches can be performed at Amazon US by supplying developer credentials for the Amazon Product Advertising API in the library configuration. The card number should be set to your access key ID and the card pin set to the corresponding secret key. You can register to become an Amazon Product Advertising API developer at https://affiliate-program.amazon.com...i/sign-in.html
Currently, only the US Amazon site at http://www.amazon.com
and the the UK Amazon site at http://www.amazon.co.uk
are supported by the plugin. Searching the Kindle Owners' Lending Library is not supported for Amazon UK.
Axis 360 provides access to a variety of titles, including a large collection of children's books. Books are available in EPUB and PDF formats via Adobe Digital Editions, and also in Blio e-book format and Acoustik audiobook format.
Find libraries using http://btol.com/axis360/find-a-library.htm
. The library-id can be found by inspecting the host name in the browser address bar for the portion preceding axis360.baker-taylor.com. For the Orange County (Florida) Library System the Axis 360 web site is http://ocls.axis360.baker-taylor.com/
and so the library-id is ocls
EBSCOhost provides research databases mainly for academic libraries, but also supports e-books and audiobooks. These are mostly reference books and public domain titles, but can include popular books published by Random House. Books may be read online and some are available to download in EPUB or PDF format via Adobe Digital Editions. Audiobooks formats are MP3, WMA and M4B.
Access to the catalog of books for a library requires authentication. EBSCOhost supports a variety of authentication methods and the correct one must be used for each library. Some libraries require the user to be physically present for access. Some require a patron id to be assigned by library staff. Some require the user to sign in at the main library site, which then redirects the web browser to EBSCOhost.
The branch-id in the configuration selects the type of authentication used to sign in to the EBSCOhost library. It may take some experimentation to determine the authentication needed for a particular library. Only a subset of the authentication methods used by EBSCOhost are supported by the plugin.
- athens - Athens Authentication - Not supported
- cpid - Patterned ID - Library card number and pin.
- custuid - Patron ID - Library-specific user id and password.
- ip - IP Address - Sign in allowed only from a computer located at the library or via VPN.
- lib=http://... - Library controlled - A login page at the main library site redirects to EBSCOhost after sign in. Login pages vary by library. This plugin may need changes to support some of these.
- shib - Shibboleth Authentication - not supported
- uid - User ID and Password - EBSCO user id and password
- url - Referring URL - Use lib=... for this type of authentication.
- user - Personal User Authentication - EBSCO user id and password
The library-id must match the EBSCOhost customer id assigned to the library. This can sometimes be obtained from the URL used for library access. For example, Fairfax County Public Library is accessed via:
The card-number and pin fields in the configuration must be set to the user's id and password for the EBSCOhost library.
Due to the need for authentication, clicking links created by the plugin in calibre to open a book's page at an EBSCOhost library will not work if the user is not already signed in to the proper library in their web browser. It also will not work if EBSCOhost is accessed via a proxy URL provided by the library.
Enki Library provides access to a collection of mostly indie-publisher e-books available through multiple library systems in California. Books are in EPUB and PDF formats, delivered via Adobe Digital Editions.
The library-id, card number and pin should all be left blank in the configuration. The web site to access Enki Library is http://enkilibrary.org
Freading provides access to many older titles. Books are available in EPUB and PDF formats via Adobe Digital Editions. It allows a set number of checkouts per week, based on a credit system, with no holds or waits. It appears that the same e-book collection is available at all libraries, however this may not always be the case.
Find libraries using http://www.freading.com/libraries/chooser
. The library-id can be found by inspecting the host name in the browser address bar for the portion preceding freading.com. For the Free Library of Philadelphia the Freading web site is http://freelibrary.freading.com
and so the library-id is freelibrary
Hoopla provides access to audio and video media, including audiobooks, playable using a web browser or a proprietary app. The addition of e-books is planned for sometime in 2014. It allows a set number of checkouts per month with no holds or waits. It appears that the same audiobook collection is available at all libraries, however libraries can block access to more expensive titles to reduce cost. Users must register at http://www.hoopladigital.com/register
using their library credentials and establish an account (email address and password) to use the system.
If the library-id, card number and pin are all left blank in the configuration then searches will be performed without signing in to Hoopla. Users may instead configure the plugin to sign in to search based on their specific library's collection. The card-number and pin fields in the configuration must be set to the user's email address and password registered with Hoopla. If the library-id is left blank in the configuration the plugin will provide a list of valid library-id's when a search is attempted. The library-id should then be changed to the proper one from the list.
OneClickdigital provides access to audiobooks and a small selection of e-books. Audiobooks are playable using a proprietary app. E-books are in EPUB format using Adobe Digital Editions DRM.
The library-id can be found by inspecting the host name in the browser address bar for the portion preceding oneclickdigital.com. For the Austin (TX) Public Library the OneClickdigital web site is http://austinpublictx.oneclickdigital.com
and so the library-id is austinpublictx
. For those outside of the US enter the full host name as the library-id. For example, essex.oneclickdigital.eu
Open Library provides access to a very large collection of books. Books are available for borrowing in EPUB and PDF formats via Adobe Digital Editions. The PDFs contain scanned page images from print books and the EPUBs are generally of low quality with many OCR errors.
There is a small collection of public domain books available to anyone, called the Lending Library. There is also a much larger collection of books available to patrons of specific libraries, called In Library. Participating libraries can be found at https://openlibrary.org/libraries
. Another collection contains accessible books for the disabled. The library-id should be set to the collection to be searched: lendinglibrary
Oyster provides access to e-books readable using a web browser or a proprietary app. It allows unlimited reading with no holds or waits for a monthly fee. It is currently available only in the US.
The library-id, card number and pin should all be left blank in the configuration.
Scribd provides access to e-books and audiobooks via a web browser or a proprietary app. It allows unlimited reading with no holds or waits for a monthly fee. Book availability varies by country. Scribd supports recommendation of books for future acquisition. (This plugin supports only published e-books and audiobooks, not user uploaded documents.)
The library-id should be left blank in the configuration. If the card number and pin are all left blank in the configuration then searches will be performed without signing in and Scribd will attempt to determine your country of origin automatically. Users can see the titles available to them by setting the card-number and pin fields in the configuration o the user-id and password registered with Scribd. Login with Facebook credentials is not supported.
Searching for Books
To search for books at configured libraries first highlight the desired book entries within calibre and the choose Search for selected books
from the plugin's menu. Searches can take a long time and so are done as jobs. After the search completes, a summary of results is shown. If accepted by the user, identifiers are added to the calibre book metadata for each match found to provide a link back to the lending library web page for that book. These links can be later used to open that web page, either through the plugin's menu or the book details panel.
The Select previously linked books / Available books
plugin menu item shows books available for borrowing from any of the configured lending libraries. When selected, these books will have a plugin menu choice of Borrow book from libraryname
or Borrow audiobook from libraryname
which opens a web browser to the page from which the user can borrow that book.
Only one link per book will be shown under Ids:
in the book's details, corresponding to the highest priority library (first in configuration) from which the book is available. A plus sign after the library name indicates that the book is also available from other lending libraries (or in other editions) and the additional links can be found in the plugin menu. A '#' before the library name indicates that the link is to an audiobook.
Discovering Books Missing from calibre
Selecting the plugin menu choice Search for books by selected authors
will cause the search to look for the specific books selected and to also save a list of books by the author(s) of the selected books that are found at enabled lending libraries, but not present in the user's calibre library. (Note: Calibre books that are not selected when a search is started are excluded from search by the plugin. If some books by a particular author are selected and others are not when a search is started, then any links found for the non-selected books will be discarded.)
Selecting the plugin menu choice Discover books by keyword
will cause the search to look for books that match the selected keywords(s) in their title (or description for some providers), but are not present in the user's calibre library. Keywords are configured using Customize plugin
, one set of keywords per line. Examples of keywords are sherlock holmes
. The discover-by-keyword menu choice will not appear unless at least one set of keywords is configured.
After search completion, these results can be accessed using the Manage discovered books
choice from the plugin's menu. A table of books is presented and the user can choose the action to be taken for each: add
to the calibre library as an "empty" book with minimal metadata (author, title, series, publisher, publication date, isbn, odid, odrid and odpid), ignore
so that undesirable books do not appear in subsequent searches, and discard
which will eliminate the book from the search results, but allows it to appear again in subsequent searches.
Books previously marked to be ignored can be displayed again using the Show Ignored
button. The Update Existing
button can be used to check if any of the listed books were recently added to calibre and if so mark them to be updated in calibre (by adding links and missing metadata) and then discarded from the list of discovered books.
Recommending Unavailable Books for Library Acquisition
The search configuration option Check for books that can be recommended for acquisition (slow)
will cause subsequent searches to do an additional check to find books not currently in the library's collection, but potentially available to recommend for acquisition. (Some books may be detected that are not truly available for library acquisition due to restrictions by the publisher, such as geographic restrictions.)
The Select previously linked books / Recommendable
plugin menu item shows books not currently available in any of the configured lending libraries. When selected, these books will have a plugin menu choice of Recommend book to libraryname
which opens a web browser to the page from which the user can issue a recommendation for the library to acquire that book.
Some libraries do not support book recommendations.
Searching for Books Available for Purchase
When the Amazon kindle book store is configured as a search library, the books that are found are listed by the plugin as purchasable.
The Select previously linked books / Purchasable books
plugin menu item shows books linked by this search. When selected, these books will have a plugin menu choice of Purchase book from libraryname
which opens a web browser to the page from which the user can purchase that book. This can be used to quickly determine which calibre book entries are available in Kindle format via Amazon.
Author Name Variants
The plugin searches for matching books using the primary (first) author of the selected calibre books. Searches are done multiple times with variants of the author's name to improve results, e.g., replacing middle names with initials. This usually works well, but can produce extraneous results for common author names and can miss results for pseudonyms and unusual name variants.
A configuration option (Max authors to search per book
) can be used for increase the number of authors searched for books with multiple authors, such as collaborations and anthologies. This increases the likelihood of finding a match at some providers (such as Open Library), but slows the search process. The additional authors will also be used for the discovery of new books.
In order to provide more control over author name searching and matching the plugin configuration has a place for optional Author name variants
. These are entered one author per line with the author name as it appears in your calibre library first and any variants on the name to be used for searching following, separated by '&' characters. For example: Stephen King & Richard Bachman
If only a single name is entered then that only that name will be used in searching and no variants will be generated automatically. For example, entering just John Joseph Adams
will cause searches for books by that author to exclude books by John Adams
or John J. Adams
Placing an author name in square brackets will prevent searches using that name, even if books by that author are selected for searching. For example: [Deepak Chopra]
For a match to occur between a calibre book and a library book an author listed for one must appear in the author list of the other.
You can adjust the titles of your books in calibre to improve matching by the plugin. When matching book titles, text in parentheses or following a colon is optional and a vertical bar ('|') can be used to separate alternate titles for the same book. Some examples of usage:
A book with an optional subtitle with match with or without it: The Ancestor's Tale: A Pilgrimage to the Dawn of Life
A book that was published under multiple titles can match either one: The Barbie Murders (And Other Stories) | Picnic On Nearside
A book title that has an optional prefix: (The Adventures of) Huckleberry Finn
A book title sometimes prefixed with the series name in library catalogs will match either way if entered in calibre with parenthesis: (High Druid of Shannara) Jarka Ruus
Note that in book matching the plugin will treat the the series name as an optional prefix to the title in order to properly match books that are listed that way at libraries, so the above case is usually handled automatically.
Caching of Book Details
As part of searching, the plugin accesses the web page for each book found by the search in order to obtain all of the information needed for filtering results and matching against calibre books. A cache of library book details is kept in a database file in order to avoid accessing these pages multiple times. Using the cache provides much faster results when searches for books are repeated, but introduces a small chance that outdated information may be used if the book details are updated at the library, which rarely happens.
In order to balance speed against accuracy the plugin defaults to keeping book information in the cache for a maximum of 90 days. This can be changed using the plugin configuration option Days to cache library book info
. Setting this to zero disables the cache and setting it larger causes information to be kept longer.
Display of Links
Links to libraries are shown in search results and in the discovered book table with the following special characters: "@" indicates a link to an available book, "!" indicates a link to a recommendable book, and "$" indicates a link to a purchasable book. Links to audiobooks contain "#", while links to e-books do not.
Viewing Links as a Custom Column
You can create a custom column in calibre to show books found to be available from a lending library. Choose Preferences
-> Add your own columns
-> Add custom column
. Enter a Lookup name
and a Column heading
(or any other description you desire.) The Column type
should be Column built from other columns
, select Show checkmarks
and Sort/search column by
should be set to Yes/No
. Enter the following in the Template
for recommendable books or odpid
for purchasable books.
You will need to restart calibre for the change to take effect.
Removing Links to Lending Libraries
Removing a lending library from the plugin's configuration has no effect on calibre books that have already been linked to that library. The only noticeable difference is that the links to an unconfigured library will be shown with a default name (based on the provider and library-id) rather than the previously configured name for the library. So selecting a book and then clicking the plugin's icon will always show the links established for that book, whether or not the lending library still exists in the configuration.
You can remove links by either deleting the odid
identifiers under Ids
in the Edit Metadata
dialog for the book or by selecting Unlink selected book
from the plugin's menu. (The unlink function only removes links for unconfigured libraries and enabled libraries. It leaves unchanged any links to libraries that are configured, but not marked as enabled.)
Restore Default Configuration
The following steps can be used to restore the default configuration for the plugin: From the main Calibre screen select: Preferences
-> Open calibre configuration directory
. Navigate to the plugins
subdirectory and delete the file Overdrive*Link.json
The library book information cache can be cleared by deleting the file Overdrive*Link*Cache.db
in the same directory.
Behind the scenes
The plugin searches each configured library website for matching e-books and audiobooks using variants of the name of the author of the selected calibre books. By default only the primary (first) author is searched, but a configuration option (Max authors to search per book
) allows searching for multiple authors for the same book.
If the configuration option to search for recommendable books has been selected then an additional search to find those books is done, increasing search time.
The results returned by a library search request usually do not contain enough information to properly identify books, so a request is made to get the details for each book, unless they were already cached due to a prior search.
The search results are matched against the selected books and a link is created for each matched book. Fuzzy matching is used to detect matches even when there are minor differences. This may sometimes result in missed matches or association of the wrong books.
If the menu choice to save discovered books was used then any search results that do not match books already present in the user's calibre library are retained for examination by the user.
Links to books discovered at libraries are stored in calibre as identifier metadata. The identifier for a book available in a library's collection is odid,
the identifier for a book recommendable for acquisition by a library is odrid
and the identifier for a book that can be purchased by the user is odpid
The format of these is book_id
for e-books and book_id
for audiobooks, where book_id
is the identifier used by the provider to identify an edition of a book (e.g.: 36 character content reserve identifier for OverDrive), provider_id
identifies the provider of library services (none for OverDrive, '3m' for 3M Cloud Library, 'ak' for Amazon, 'ax' for Axis 360, 'eh' for EBSCOhost, 'en' for Enki Library, 'fr' for Freading, 'ho' for Hoopla, 'ocd' for OneClickdigital, 'ol' for Open Library, 'oy' for Oyster, 'sc' for Scribd) and library_id
identifies the specific library.
If a book is available in multiple editions or from multiple libraries there will be additional links, separated by ampersands. For example:
odid:firstname.lastname@example.org&a1f9399 8-aeb1-4562-9c5d-eceda2243b6d#digitalbooks.brooklynpubliclibrary.or g&ZnJlYWQ6OTc4MDQ4NjExMDUzMDpl@fr/ocls&dot8az9@3m/bpl
A search for identifiers:"=odid:"
can be done to find all books in calibre that are available at any lending library. A search for identifiers:"=odrid:@freelibrary.lib.overdrive.com "
will show only e-books recommendable at that specific library. Commonly used searches can be performed through the plugin's menu under Select previously linked books.
Regular expressions may need to be used for more complex search cases.
The list of discovered books is stored in a hidden part of the calibre library database. This data can be examined in the file metadata_db_prefs_backup.json
in the calibre library folder.
The plugin contains an embedded metadata plugin that provides the clickable links in the book details panel for available books. It can be disabled in the main plugin's configuration if this feature is not desired.