/dev/docs/bookreader
Type: /type/page
body: value: The BookReader was developed by the Internet Archive and <a href="#contributors">open source contributors</a> to provide online access to scanned books.  The Internet Archive has more than <a href="https://openlibrary.org/subjects/accessible_book" title="Internet Archive books">1,000,000 scanned books</a> available to read online.  The BookReader is also used to provide access to materials from <a href="#users">many other organizations</a>.

## Accessing the BookReader on Open Library

Look for the Read Online links to open a book in the BookReader. You can search for available books by checking the "Only show eBooks" checkbox in the Open Library search.

## Accessing the BookReader on the Internet Archive
To use the BookReader, click on the "Read Online" link on the left side of an archive.org [details page](https://www.archive.org/details/birdbookillustra00reedrich).

## Using bookmarks in the online bookreader

A video tutorial is available [here](https://youtu.be/FhsSd1bDRsQ):

<a href="https://youtu.be/FhsSd1bDRsQ"><img src="https://archive.org/download/screenshot-2023-05-31-at-11.58.58/Screenshot%202023-05-31%20at%2011.58.58.png"/></a>

## Download source code
The BookReader source code is available in the Internet Archive github repository.

* [Access the source code](https://github.com/internetarchive/bookreader)
* [Download the latest source code as zip](https://github.com/openlibrary/bookreader/archive/master.zip)

##  Report a bug or request a feature!
* [View open bugs](https://bugs.launchpad.net/bookreader/+bugs)
* [Report a new bug or request a feature](https://bugs.launchpad.net/bookreader/+filebug-advanced)
* [View fixed bugs](https://bugs.launchpad.net/bookreader/+bugs?field.searchtext=&orderby=-importance&search=Search&field.status%3Alist=FIXRELEASED&assignee_option=any&field.assignee=&field.bug_reporter=&field.bug_supervisor=&field.bug_commenter=&field.subscriber=&field.omit_dupes.used=&field.omit_dupes=on&field.has_patch.used=&field.has_cve.used=&field.tag=&field.tags_combinator=ANY)

## <a name="developerinfo">Developer Info</a>
 * [Book URLs](https://openlibrary.org/dev/docs/bookurls) - use bookreader page images in your own web app
 * [Bookreader Testing](https://openlibrary.org/dev/docs/bookreadertesting)
 * [Bookreader Deployment](https://openlibrary.org/dev/docs/bookreaderdeployment)
 * [BookReader Interactions](bookreaderinteractions) - User interaction in the BookReader
 * [How to serve IA-style books from your own cluster](https://raj.blog.archive.org/2011/03/17/how-to-serve-ia-style-books-from-your-own-cluster/) - also includes info on how the BookReader image server works.
 * [Full-text search](https://openlibrary.org/dev/docs/api/search_inside) - How IA implements full-text search for books

## <a name="contributors">Contributors to the Internet Archive Bookreader</a> (2010-2017)
 * Michael Ang (mang) - Bookreader Core - archive.org
 * Lance Arthur (lance.arthur) - Markup and CSS - archive.org
 * Edward Betts (edward) - Full-text search - archive.org
 * Jeff Kaplan (kaplan) - QA - archive.org
 * Raj Kumar (raj)  - Bookreader Core - archive.org
 * Mike McCabe (mccabe) - Table of Contents - archive.org
 * George Oates (glo) - Design - archive.org
 * Alexis Rossi (alexis) - QA - archive.org
 * Yankl - Right-to-left patch - [github commit](https://github.com/openlibrary/bookreader/commit/ba9df9aebf33c72c78892ab2dcc9e43d8f2f7b45)
 * [shenzhuxi](https://github.com/shenzhuxi) - encapsulation of $ and IE6 fixes
 * Richard Caceres (rchrd2) - Bookreader Core, circa 2017 - archive.org
 * Benjamin Mandel - QA - archive.org


## Contributors to older versions
### Contributors to version 2 (gnubook, 2008-2010)
 * Raj Kumar (raj)  - Bookreader Core - archive.org
 * Michael Ang (mang) - Bookreader Core - archive.org
 * Rebecca Malamud (webchick) - OLPC interface - invisible.net
 * Anand Chitipothu (anand) - OLPC interface - archive.org
 * Alex Osborne (aosborne) - [back button fix](https://github.com/ato/bookreader/commit/7858770c9a3d34a7c7f86bd2b92a646e11d2b944) - nla.gov.au
 * Jeffrey Ventrella (jeffrey) - icons - ventrella.com
 * Lance Arthur (lance.arthur) - icons - archive.org
 * Stephanie Collett (scollett) - thumbnail view mode - [California Digital Library](https://www.cdlib.org/)
### Contributors to version 1 (flippy, 2005-2008)
 * Jesse Crossen (jesse) - original author - tackledesign.com
 * Brad Neuberg (bkn3) - IA integration - columbia.edu

## <a name="users">Examples in the Wild</a>
 * [archive.org](https://www.archive.org/details/texts) - [example](https://www.archive.org/stream/birdbookillustra00reedrich)
 * [read.gov](https://read.gov/exquisite-corpse/) - [example](https://www.read.gov/exquisite-corpse/Book)
 * [Biodiversity Heritage Library](https://www.biodiversitylibrary.org) - [example](https://www.biodiversitylibrary.org/item/42239)
 * [Peel's Praire Provences at University of Alberta Libraries](https://peel.library.ualberta.ca/index.html) - [example](https://peel.library.ualberta.ca/bibliography/4587/reader.html)
 * [1960 Rome Olympics commemorative site](https://www.roma1960.it) - [example](https://dlib.coninet.it/bookreader.php?f=14529&p=2&c=1)
 * [Princeton University Digital Library](https://pudl.princeton.edu) - [example](https://pudl.princeton.edu/bookreader.php?obj=4q77fr42n#page/6/mode/2up)
 * [Stanford University Libraries](https://collections.stanford.edu/) - [example](https://collections.stanford.edu/bookreader-public/view.jsp?id=00021264)
 * [Bookleteer][1] - [blog post][2]
 * [New York Philharmonic Digital Archives](https://archives.nyphil.org/) - [example](https://archives.nyphil.org/index.php/artifact/5749cc67-077a-47e6-9622-7b718e6a964c/fullview#page/1/mode/2up)
 * [Drupal fileviewer plugin](https://drupal.org/project/fileviewer)
 * [Electronic Frontier Foundation](https://www.eff.org) - [example](https://www.eff.org/document/defending-privacy-us-border-guide-travelers-carrying-digital-devices)
 * <a href="https://digitalpml.pmlib.org/">Patchogue-Medford Library's Digital PML</a>

##  Attribution
The Bookreader is licensed under the [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.html). It is built upon these open source tools:

* [jQuery](https://jquery.com) - [John Resig and others](https://docs.jquery.com/About#Development_Team) - [Dual MIT and GPL license](https://docs.jquery.com/Licensing).
* [jQuery Easing Plugin](https://gsgd.co.uk/sandbox/jquery/easing/) -  [George Smith at GSGD](https://gsgd.co.uk/freelance/) - MIT License.


## BookReader demo
Once you've downloaded the source code you can open BookReaderDemo/index.html in your web browser and you should see an example book.    To use your own images you would modify BookReaderJSSimple.js to connect the BookReader with your book's page images and metadata.


## <a name="embedding">Embed example</a>

For books hosted on the Internet Archive the BookReader can be embedded on any site that allows you to add an iframe, for example using the code below.

    <iframe src="https://www.archive.org/stream/abroadcranethoma00craniala?ui=embed" width="480px" height="480px"></iframe>

{{iframe('https://www.archive.org/stream/abroadcranethoma00craniala?ui=embed', width='480px', height='480px')}}

You can also link to a specific page and specify that two-page mode should be used:

    <iframe src="https://www.archive.org/stream/abroadcranethoma00craniala?ui=embed#mode/2up/page/18" width="450px" height="400px"></iframe>

{{iframe('https://www.archive.org/stream/abroadcranethoma00craniala?ui=embed#mode/2up/page/18', width='450px', height='400px')}}

## Features
 * Single-Page, Two-page, and Thumbnail view
 * Zoom
 * Right-to-left page progression (e.g. for Yiddish and Chinese)
 * Full-text search with highlighting of search results
 * Support for foldouts and variable page size
 * In-Browser Text-To-Speech
 * Embeddable
 * Bookmark-friendly URLs
 * Works with a variety of image servers, or a simple directory of images
 * Simple access control


## <a name="serving-image">Serving Images</a>
In the case of the Standalone Demo, operation is fairly simple. Images are numbered sequentially and stored in a directory called "StandAloneImages". The images are all the same size, and two functions in [BookReaderJSSimple.js](https://github.com/openlibrary/bookreader/blob/master/BookReaderDemo/BookReaderJSSimple.js), getPageWidth() and getPageHeight(), return the page size. Scaling is done in the web browser.

For books scanned by the Internet Archive and stored on archive.org, bookreader operation is a bit more complex. During the book scanning process, each page is imaged using a high-resolution digital camera, and then each page is cropped and deskewed. The size of the cropped image is stored in a file called scandata.xml. During this process, some images, such as color cards, white cards, and tissue paper pages, are marked as pages that should not be displayed. This information is also stored in scandata.xml. The cropped and deskewed images are stored in JPEG 2000 format in a zip file called bookid_jp2.zip. The raw images, the cropped and deskewed images, and the scandata.xml file are available for each book on archive.org.

Because crop boxes can vary between pages for Internet Archive books, the getPageWidth() and getPageHeight() functions can return a different size for each image in the book. Also, since some pages are not supposed to be displayed, the getPageURI() function maps an "index number" that the book reader uses to a "leaf number" that corresponds to an image in the jp2.zip file. These functions use information from scandata.xml to determine size and url for each page.

Because web browsers generally cannot display JPEG2000 images, a piece of code called  [BookReaderImages.php](https://github.com/openlibrary/bookreader/tree/master/BookReaderIA/BookReaderImages.php) performs on-the-fly JPEG2000 to JPEG conversion on the archive.org cluster. For efficiency, this code also provides server-side image scaling and other image processing.

[More information on how BookReaderImages.php works.](https://raj.blog.archive.org/2011/03/17/how-to-serve-ia-style-books-from-your-own-cluster/)

## Testing and Release Process

Bugs and feature requests against the BookReader can be filed in the [BookReader Launchpad Bug Tracker](https://bugs.launchpad.net/bookreader/).  During development features and bugs in progress are targeted to the next milestone.  Once all the bugs for the milestone are in the "Triaged" status and ready to test the code is given to QA for testing.  Since Launchpad does not have separate QA bug statuses we use the tags "needs-qa", "qa-verified" and "qa-reopened" to designate bugs that are ready for testing, verified by QA or have problems with the fix.

Code in progress on a development milestone branch may be pushed to our [openlibrary/BookReader GitHub account](https://github.com/openlibrary/bookreader/) on that branch.  Once the release candidate has been approved by QA it is pushed out to GitHub on the branch and also merged into master.  The branch point is tagged with the release name which will automatically make it appear on our [BookReader GitHub downloads page](https://github.com/openlibrary/bookreader/downloads).


### Unit Testing

The BookReader is starting to have [unit tests](https://github.com/openlibrary/bookreader/tree/master/BookReaderIA/test/), written in [QUnit](https://docs.jquery.com/QUnit).  We are setting up a [BookReader TestSwarm server](bookreaderstestswarm).

##  Extending bookreader functionality

To make is it easier to work with other sources, the bookreader can expect a book interface from the client with the following methods.

    getPageCount()
    getPage(index)
    getPageWidth(index)
    getPageHeight(index)

The book reader can have optional functionality which is enabled only when the book implementation has a specific method defined.
For example, bookmarks functionality can be enabled only when the book interface has `getBookmarks` method defined.

    getBookmarks(index)

Typical usage:

    <script src="/js/bookreader.js" type="text/javascript"/>
    <script src="/js/archivebook.js" type="text/javascript"/>

    <div id="book1"></div>

    <script>
        document.onload = function() {
            var b = bookreader("book1", ArchiveBook("tomsawyer"));
           b.showPage(42);
        }
    </script>


  [1]: https://bookleteer.com/
  [2]: https://bookleteer.com/blog/2011/06/new-feature-bookleteer-online-bookreader/
  [3]: https://s
title: Internet Archive BookReader
m: edit