Debian Codegraph @

manual/url_scheme.rst

raw
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``.