| 1 |
The calibre:// URL scheme |
| 2 |
========================================= |
| 3 |
|
| 4 |
calibre registers itself as the handler program for calibre:// URLs. So you can |
| 5 |
use these to perform actions like opening books, searching for books, etc from |
| 6 |
other programs/documents or via the command line. For example, running the |
| 7 |
following at the command line:: |
| 8 |
|
| 9 |
calibre calibre://switch-library/Some_Library |
| 10 |
|
| 11 |
Will open calibre with the library named ``Some Library``. Library names are |
| 12 |
the folder name of the library folder with spaces replaced by underscores. The |
| 13 |
special value ``_`` means the current library. |
| 14 |
The various types of URLs are documented below. |
| 15 |
|
| 16 |
You can even place these links inside HTML files or Word documents or similar |
| 17 |
and the operating system will automatically run calibre to perform the |
| 18 |
specified action. |
| 19 |
|
| 20 |
|
| 21 |
.. contents:: |
| 22 |
:depth: 1 |
| 23 |
:local: |
| 24 |
|
| 25 |
Switch to a specific library |
| 26 |
------------------------------- |
| 27 |
|
| 28 |
The URL syntax is:: |
| 29 |
|
| 30 |
calibre://switch-library/Library_Name |
| 31 |
|
| 32 |
Library names are the folder name of the library with spaces replaced by |
| 33 |
underscores. The special value ``_`` means the current library. You can also |
| 34 |
use :ref:`hex encoding <hex_encoding>` for the library names, useful if the library names have |
| 35 |
special characters that would otherwise require URL encoding. Hex encoded |
| 36 |
library names look like:: |
| 37 |
|
| 38 |
_hex_-AD23F4BC |
| 39 |
|
| 40 |
Where the part after the ``_hex_-`` prefix is the library name encoded as UTF-8 |
| 41 |
and every byte represented by two hexadecimal characters. |
| 42 |
|
| 43 |
|
| 44 |
Show a specific book in calibre |
| 45 |
------------------------------- |
| 46 |
|
| 47 |
The URL syntax is:: |
| 48 |
|
| 49 |
calibre://show-book/Library_Name/book_id |
| 50 |
|
| 51 |
This will show the book with ``book_id`` (a number) in calibre. The ids for |
| 52 |
books can be seen in the calibre interface by hovering over the |
| 53 |
:guilabel:`Click to open` link in the :guilabel:`Book details` panel, it is the number in |
| 54 |
brackets at the end of the path to the book folder. |
| 55 |
|
| 56 |
You can copy a link to the current book displayed in calibre by right clicking |
| 57 |
the :guilabel:`Book details` panel and choosing :guilabel:`Copy link to book`. |
| 58 |
|
| 59 |
If a search is active and the book is not matched by the search then the search is cleared. |
| 60 |
|
| 61 |
If a Virtual library is selected, calibre will use it when showing the book. If |
| 62 |
the book isn't found in that virtual library then the virtual library is cleared. |
| 63 |
|
| 64 |
If you want to switch to a particular Virtual library when showing the book, use:: |
| 65 |
|
| 66 |
calibre://show-book/Library_Name/book_id?virtual_library=Library%20Name |
| 67 |
or |
| 68 |
calibre://show-book/Library_Name/book_id?encoded_virtual_library=hex_encoded_virtual_library_name |
| 69 |
|
| 70 |
replacing spaces in the Virtual library name by ``%20``. If the book isn't found in that |
| 71 |
virtual library then the virtual library is ignored. |
| 72 |
|
| 73 |
|
| 74 |
Open a specific book in the E-book viewer at a specific position |
| 75 |
------------------------------------------------------------------- |
| 76 |
|
| 77 |
The URL syntax is:: |
| 78 |
|
| 79 |
calibre://view-book/Library_Name/book_id/book_format?open_at=location |
| 80 |
|
| 81 |
Here, ``book_format`` is the format of the book, for example, ``EPUB`` or |
| 82 |
``MOBI`` and the ``location`` is an optional location inside the book. The |
| 83 |
easiest way to get these links is to open a book in the viewer, then in the |
| 84 |
viewer controls select :guilabel:`Go to->Location` and there such a link |
| 85 |
will be given that you can copy/paste elsewhere. |
| 86 |
|
| 87 |
|
| 88 |
Searching for books |
| 89 |
------------------------------ |
| 90 |
|
| 91 |
The URL syntax is:: |
| 92 |
|
| 93 |
calibre://search/Library_Name?q=query |
| 94 |
calibre://search/Library_Name?eq=hex_encoded_query |
| 95 |
|
| 96 |
Here query is any valid :ref:`search expression <search_interface>`. If the |
| 97 |
search expression is complicated, :ref:`encode it as a hex string <hex_encoding>` |
| 98 |
and use ``eq`` instead. Leaving out the query will cause the current search to |
| 99 |
be cleared. |
| 100 |
|
| 101 |
By default, if a Virtual library is selected, calibre will clear it before |
| 102 |
doing the search to ensure all books are found. If you want to preserve the |
| 103 |
Virtual library, use:: |
| 104 |
|
| 105 |
calibre://search/Library_Name?q=query&virtual_library=_ |
| 106 |
|
| 107 |
If you want to switch to a particular Virtual library, use:: |
| 108 |
|
| 109 |
calibre://search/Library_Name?virtual_library=Library%20Name |
| 110 |
or |
| 111 |
calibre://search/Library_Name?encoded_virtual_library=hex_encoded_virtual_library_name |
| 112 |
|
| 113 |
replacing spaces in the Virtual library name by ``%20``. |
| 114 |
|
| 115 |
If you perform a search in calibre and want to generate a link for it you can |
| 116 |
do so by right clicking the search bar and choosing :guilabel:`Copy search as |
| 117 |
URL`. |
| 118 |
|
| 119 |
Open a book details window on a book in some library |
| 120 |
------------------------------------------------------ |
| 121 |
|
| 122 |
The URL syntax is:: |
| 123 |
|
| 124 |
calibre://book-details/Library_Name/book_id |
| 125 |
|
| 126 |
This opens a book details window on the specified book from the specified library without changing the |
| 127 |
current library or the selected book. |
| 128 |
|
| 129 |
|
| 130 |
Open the notes associated with an author/series/etc. |
| 131 |
------------------------------------------------------ |
| 132 |
|
| 133 |
The URL syntax is:: |
| 134 |
|
| 135 |
calibre://show-note/Library_Name/Field_Name/id_Item_Id |
| 136 |
|
| 137 |
This opens a window showing the notes of the specified item. |
| 138 |
The easiest way to create such URLs is to show the notes you want |
| 139 |
in calibre and click the :guilabel:`Copy URL` button to copy the URL |
| 140 |
to the clipboard and paste it wherever you need. |
| 141 |
|
| 142 |
Here ``Field_Name`` is the name of the columns such as ``authors`` or ``tags``. |
| 143 |
For user created columns, replace the leading ``#`` in the field name with |
| 144 |
an underscore, so ``#mytags`` becomes ``_mytags``. |
| 145 |
|
| 146 |
In addition to specifying items by id using ``Item_Id`` you can also specify |
| 147 |
them by name using either ``val_Item_Name`` or ``hex_Hex_Encoded_Item_Name``. |
| 148 |
For example:: |
| 149 |
|
| 150 |
calibre://book-details/Library_Name/authors/val_John%20Doe |
| 151 |
|
| 152 |
|
| 153 |
.. _hex_encoding: |
| 154 |
|
| 155 |
Hex encoding of URL parameters |
| 156 |
---------------------------------- |
| 157 |
|
| 158 |
Hex encoding of URL parameters is done by first encoding the parameter as UTF-8 |
| 159 |
bytes, and then replacing each byte by two hexadecimal characters representing |
| 160 |
the byte. For example, the string ``abc`` is the bytes ``0x61 0x62 and 0x63`` in |
| 161 |
UTF-8, so the encoded version is the string: ``616263``. |