Calibre2Opds Using
| Home Page |
Calibre2opds User Guide | Developer Guide | |||||
|---|---|---|---|---|---|---|---|
| Overview | Installing | Generating | Publishing | Using | Troubleshooting | ||
Using Catalogs
Once you have generated a Calibre2opds catalog and then published it you will want to use it. This section of the documentation covers using it with a number of common client applications.
The topic areas covered are:
Contents |
[edit] Network Issues
Before you try and use the catalogs generated by Calibre2opds you will need to make sure that you know the IP address that will be required to access the catalogs over the network. If you are hosting the catalogs on your home network then you are likely to have a different IP address for accessing the catalogs locally to the one that would be used if accessing them remotely via the Internet.
An IP address on a home network will typically be something like 192.168.0.x or 192.168.1.x where 'x' can be any value. This type of address is, however, only visible to devices that can connect to your home network.
If you want to make your library visible from the public Internet then you will need to know the public address of your router. In the simple case you can use a browser with a URL such as http://http://whatismyipaddress.com/ in your browser. However, the problem is that unless you pay for a fixed address your public IP address can change according at any time if your ISP deems it desirable. In practice the address tends to be change rarely if you have a cable connection to the Internet. If you use an ADSL type connection then it can change much more frequently, and you may want to look into services such as those offered by www.dyndns.org.
[edit] Which Catalog Type to Use?
Calibre2opds generates two distinct types of catalog:
- XML based ones formatted according to the OPDS standard
- HTML ones suitable foruse with any web browser
The following is a bit more information about these catalog types
[edit] XML catalogs
The XML catalogs generated by Calibre2opds are based on the OPDS standard.
The XML catalogs can be used with some browsers, but do not seem to work with all browsers. In particular they do not work with Microsoft Internet Explorer. If you want to access the XML catalogs then Firefox is the recommended choice. However in most cases you would be better off using the HTML variants of the catalog when using a Browser.
A more normal usage of the XML versions of the catalogs is to access them via reading software that is OPDS aware. Examples of common software that falls into this category are given below, but the catalogs should be usable by any software that supports the OPDS standard.
In the case of an XML catalog An example of a typical HTML URL used on a home network is
<a href="http://192.168.1.200:8008/_catalog/index.xml
| TIP |
|---|
| If you have the 'Encrypt filename options' set on the Advanced tab then the index.xml file will have its name prefixed by what looks like 8 random characters. These are not truly random as they will stay the same between runs but are specific to your catalog so impossible to guess. |
NOTE: Prior to the 2.4 release of calibre2opds the default URL finished in catalog.xml
[edit] HTML catalogs
HTML catalogs are designed to be accessed by a Web browser. When using the HTML catalogs you would normally point your browser at the top level file called catalog.html. This would therefore be the last part of the catalogpath defined in nthe URL mentioned above.
An example of a typical HTML URL used on a home network is
http://192.168.1.200:8008/_catalog/index.html
| TIP |
|---|
| If you have the 'Encrypt filename options' set on the Advanced tab then the index.html file will have its name prefixed by what looks like 8 random characters. These are not truly random as they will stay the same between runs but are specific to your catalog so impossible to guess. |
NOTE: Prior to the 2.4 release, the default URL for a HTML catalog finished in catalog.html
More detail on using a browser with the HTML version of the catalog is shown later in this section.
[edit] Using a Web Browser
Calibre2opds can generate its catalogs in both XML and HTML formats. Which one you use is up to you, but you should be aware of the fact thtat not all browsers can handle the XML format. Therefore if maximum compatibility with browsers is your aim you should generate HTML catalogs.
Many modern book readers which are WiFi or 3G enabled to enable them to download books over the network include a built-in web browser and can download books from a web page using this built-in browser. Common examples of such devices are the B&N Nook and the Amazon Kindle.
The URL you enter into the browser will be of the form:
http://address:port/catalogpath
where:
- address is the network address to access the server hosting the Calibre2opds files. This can either be a network visible server name or an IP address.
- port is the port that will be used to access the files. It is only required if you are not using the default HTML port of 80
- catalogpath is the path to access the relevant catalog file.
Note that if you have generated the Calibre2opds catalogs to be accessed via SSL encryption then you would use https:// instead of http:// at the start of the URL.
[edit] Using a Calibre2opds HTML Catalog in a Browser
Most computing devices or smartphone support a web browser, so this is a common way to access the calibre2opds catalogs.
You would normally start at the top level of an HTML based catalog with the default calibre2opds generated index pag (with a filename of index.html.
Some of the top level sections are optional, and you can control which of these are shown by setting appropriate configuration parameters at the time you generated the Calibre2opds catalogs. For example the above catalog screenshot shows that the following sections have been omitted:
- Publishers
- Ratings
- All Books
From the top level you can drill down a level:
This shows a drill down into the Authors section. You will see that as this is a large library, the authors have been sub-divided by the first letter of the authors name.
You might now want to drill down further into books by a particular author:
The books can be displayed in two modes. The following shows 'cover-browse' mode.
Alternatively you can use a simpler list mode:
Which of these two modes is used is a mconfiguration option when the catalog is generated.
In either mode you can drill down to get more information about a specific book:
[edit] Safari on iOS devices (iPhone/iPod Touch/iPad)
If you are using an iPhone, iPod Touch or iPad as your reading device, then as long as you are using iOS4.0 or later then you can download books from the HTML version of a calibre2opds generated catalog via the Safari Web browser (that is standard with iOS) into any application that during its installation has been configured to handle the relevant file type.
The most obvious application that would fall into this category is Apple's iBooks application, but many third party eReading applications also allow downloads via Safari
When you have selected a book from the Calibre2opds generated catalog, then you will get a book details page. The following is an example of such a page:
At the bottom of the page you will see a series of download links for each of the book formats that you have in your calibre2opds library that are available via the calibre2opds catalog.
As an example if you click on the link to download an ePub file you will get a prompt that looks like the following:
If you click on the button to open the file with iBooks, then the file will be downloaded into the iBooks library, and then iBooks will be started with the book opened to the first page.
You will notice that there is also an Open with option. Pressing the button will give a list of the applications that have registered themselves as being capaqble of handling this file type. the followoing shows an example where several applications have registered themselves as being capable of handling the ePub file type. Not surprisingly iBooks is on this list, plus any other suitable eReader type apps that are installled.
Selecting the relevant app will load the book into that application.
[edit] Using an Calibre2opds OPDS Catalog
There are a wide variety of ereader software packages that support the OPDS standard for downloading books. At the moment there do not appear to be any specialist eReader hardware devices that support the OPDS standard in an 'out-of-the-box' state although this is likely to change in the future.
The remainder of this section shows how to set up a number of eReader software packages to work with a calibre2opds generated OPDS catalog. The ones described are by no means an exhaustive list, but should act as representative examples of the approach that should be used.
[edit] MegaReader/QuickReader/eBook Search (iOS)
MegaReader and QuickReader are variants of the same software for reading books on iOS devices (iPhone, iPod Touch/iPad) and have the same level of OPDS catalog support. eBook Search by the same author provides the OPDS catalog support without the reading capability so that it can act as am OPDS front end for loading books into other iOS reading software that does not support OPDs directly (e.g. iBooks, BlueFire, GoodReader, Kindle reader).
If you are using any of these applications on an iPhone, iTouch or iPad then you will want to add your Calibre2opds catalog as a user-defined catalog. This will allow you to browse the catalog, and download any books that you want to read. These applications are treated as a unit here as the OPDs aspects of configuring the application for an OPDs catalog and then using it download are basically the same in all these applications.
[edit] Configuring a Catalog in MegaReader/QuickReader/eBook Search
The process of adding a calibre2opds generated catalog to all these packages follows idential lines and uses the same set of dialogs so they are all treated as single entity for the purposes of this document. The screenshots are from the iPhone versions of the app, but the iPad dialogs have the same content merely adjusted for the larger screen size.
To add a calibreopds catalog to you start by selecting the Library tab.
From there you select the Download Books option near the top of the screen.
This will take you to the list of catalogs that are currently configured:
Quickreader comes with a number of online catalogs pre-configured as shown below:
If you click on the Edit button at the top right, then you will see that the option to add new catalog appears:
Clicking on this takes you to the dialog where you can define a new catalog. Here you would set up the URL for your calibre2opds generated catalog.
The following screenshots show typical entries for such a catalog. The right-hand screenshot shows how you can preset a username/password in the URL. Quickreader does not remember username/password across reading sessions, so this avoids you having to enter it every time.
When you have completed setting up the catalog and press Add then Quickreader will verify that it can access the catalog you have just defined. After verifying this you are returned to the previous dialog. You will see that the new catalog you have just set up appears under the Other catgory.
[edit] Using Catalogs in Quickreader/MegaReader/eBook Search
The library you have configured will be displayed in the Other Section. You can select your library and you will then be shown the top level index of your calibre2opds catalog.
You can drill down to the book you are interested in. The following shows the Book Details page for a book entry.
There is a Download button at the top right. If you press this then the book will be downloaded.
At this point you can either start reading your book, or return to your main Quickreader library where the book will now be listed and be available for reading at a later date.
[edit] Marvin (iOS)
Details to be filled in ASAP
[edit] Stanza (iOS)
Stanza is an iOS based ereader app. Stanza was one of the first eReader type applications on the iPhone , and as a result it has been very widely installed. It was also a leader in providing support for the eaerly versions of the OPDS standard.
| NOTE |
|---|
| Stanza versions earlier than v3.2 do not run on iOS5 (or later) which has caused problems for users of older generations of iOS based devices such as early iPhones and iPads.Stanza v3.2 does run on iOS 5 devices although there have been some reported problems that users have encountered..Support and maintenance of Stanza has been discontinued by Amazon (who are the current owners of Stanza) so it does not look like these issues will be resolved. Despite the above issues there is still a very large installed base of Stanza users so it is still an important software package in the iOS market. For more information on what has been happening with Stanza you may want to refer to the Wikipedia article at http://en.wikipedia.org/wiki/Lexcycle_Stanza |
If you are using the Stanza application on an iPhone, iTouch or iPad then you will want to add your Calibre2opds as a user-defined catalog. This will allow you to browse the catalog, and download any books that you want to read.
[edit] Configuring a catalog in Stanza
Start by selecting "Get Books" from the options at the bottom of the screen, and the "Shared" at the top of the screen.
This will bring up the list of custom Book sources that you have previously configured. If you have not previously added any then this list will be empty.
| NOTE |
|---|
| In the above list you see that there are entries labelled (local) and (remote). The reason for this is that i this particuar case the eBook library is being hosted on a Web Server located on the home network. The IP address to access this web server is different if using the home WiFi network compared to accessing from the public Internet. The (local) entries are therefore used if at thome, and the (remote) ones are used when away from home. If you are using something like DropBox to host your eBook library then you will probably only need a single entry as the same address can used both at home and on the move. |
Click on Edit to go into the dialog for editing the list of Book sources.
You can now add a new source by selecting the Add Book Source option, or edit any of the existing sources.
You can also:
- Delete a Book Source by clicking on the Red icon
- Edit an existing Books source by clicking on the Right-Arrow
- Re-order the Book Source entries by using the 3-bars icon.
Assuming you have selected the Add Book Source option you will be taken to the following dialog:
You can now give the name that you want displayed in the list of Book Sources and the URL for accessing the first page in the catalog.
You will also see that you can add both catalogs and Web pages via this dialog. Make sure this option is set to Catalog for a Calibre2Opds catalog.
If you need to make a change you can later go in and change the settings. Note however that you cannot change an entry from being a catalog entry to a web page entry. If you want to do that you need to delete the entry and then create a new one.
This is an example of the settings for accessing a Calibre2Opds catalog that has been hosted on a web serve on the local WiFi network.
| Tip |
|---|
| If you are not sure what the URL is to use with Stanza, you can first test it using a browser. Although the browser may not display the catalog correctly it should still show a web page that has the basic structure of the catalog. If the page does not display then either you have the URL wrong, or a firewall is blocking it at the server end. |
Note that you are not limited to adding books that are your own private library. There are a number of publishers who now expose their catalogs in OPDS compatible format as the following example shows
The above example is for the Baen Free Library - books that are published commercially in paper format but are available for free download in eBook format.
Baen books are a heavy promoter of eBooks, particularily of the Science Fiction and Fantasy Genre. They offer good prices and their books are available in a variety of formats and unlike many other publishers are not DRM (Digital Rights Management) protected.
[edit] Using Catalogs in Stanza
If you have got Stanza configured correctly, then when you select the Calibre2Opds catalog entry from your list of Book sources you will get the top level of the calibre2Opds catalog displayed.
Using Calibre2Opds online catalogs means that you do not need to keep lots of eBooks loaded into Stanza as you can download them on demand. The Calibre2Opds catalogs also provide ways of browsing your library that are not supported by Stanza such as by series or books recently added to your Calibre library.
The Structure of this catalog is organised to give you a number of ways of getting at the same book. Which one is most appropriate will vary according to just what you are currently trying to do. From this list you can drill down a level.
For instance if you selected Authors then the display might look something like the following
The sub-divisions are on the first letter of Author Surname.
You can drill down to a specific level. For instance selecting W might give something like
[TBD]
From the list of authors you could select the one you are interested in.
In the following dialog David Weber has been selected.
[TBD]
Most people are interested in having books for an Author organized into Series where relevant. Therefore you will see any series this author has contributed to listed in alphabetical order, and following that any books that are not part of a series
If for example a the series Dahak was selected this would then display a list of books that are part of that series.
[TBD]
Note that this series listing will also include any books by other authors that are part of the series, but since the author is given under the Book title it is easy to see which ones belong to this author.
Finally we can then select the particular book we are interested in and look at the more detailed information about that book. If there is a suitable format of the book in our library then the Download button can be used to load it into stanza
Not all book sources conform to the calibre2Opds catalog structure. As an example of a different one here is what is happen if you have configured the Baen Free Library as mentioned earlier and then select it from within Stanza
If you select the Baen Free Library you will get the list of books they have made available for free download
Just like with Stanza catalogs you can drill down to specific books, although the information about the book will be displayed in whatever layout Baen have selected. However since it is still Stanza displaying the information it will follow the same basic layout as books displayed from a Calibre2Opds catalog.
From here you could download the book using the Download button.
[edit] Aldiko (Android)
This section is currently incomplete
Users of the Aldiko application are encouraged to provide screen shots to help complete this section
[edit] FBReader (Android)
This section is currently incomplete
Users of the FBReader application are encouraged to provide screen shots to help complete this section
steps involved are:
- In FBreader open Network Library.
- Go to the very bottom of the page and click on + Add Catalog
- Click on Enter URL Manually
- Enter the full path to the top level of the OPDS catalog
(i.e. http://www.shtfinfo.com/shtffiles/books/_catalog/index.xml)
[edit] Nook/Trook
Calibre2opds is best utitlised on a Nook system that has been soft-rooted and has the Trook software installed. Trook can then use the calibre2opds generated catalogs as the way of indexing/finding the books you have loaded.
This section is currently incomplete
Nook users are encouraged to provide screen shots to help complete this section
[edit] Kindle
The Kindle comes with a web browser that can be used to acess the HTML version of the calibre2opds generated catalogs.
This section is currently incomplete
Kindle users are encouraged to provide screen shots to help complete this section.
