JCMS Librivox

Description

A shortcode-based plugin that accesses free public domain readings of out-of-copyright and copyright-free books. Recordings are provided by LibriVox.org and are accessed via the LibriVox REST API

The plugin provides a shortcode interface that allows presentation of a specified book, by its LibriVox API ID, with downloadable or HTML5 playable content, in your content area. Returned content is therefore either MP3 files, or a ZIPped archive of all MP3 files related to the selected book.

The plugin also provides a rich web application that allows direct searching, browsing and playing of any recording in the LibriVox catalogue. This application uses a large subset of the full LibriVox API to realise its functionality.

The rich web application uses a proxy REST API, accessed by client-side JavaScript. This proxy API is also available should other plugins wish to use it.

The plugin uses server-side code to access the remote Librivox API, and presents these to the client-side as local REST emdpoints. This is done using extensions to the relatively new WP REST API (http://v2.wp-api.org/).

The single-book embed shortcode [librivox_book bookid="nnn"] simply passes a valid Librivox book ID to the plugin proxy code, which in turn passes this on to the remote librivox endpoint. The plugin code then constructs HTML output from the response and incorporates this this in the full HTML output send back to the browser. Note you can use something like https://librivox.org/api/feed/audiobooks?fields[]=id&fields[]=title&limit=1000 to get a list of book IDs directly from the Librivox API [there is not yet a nice way of obtaining a book ID via this plugin – perhaps a todo for the future…]. This shortcode does not generate or require any client-side JavaScript.

The rich application trigger shortcode [librivox_app] does not require any parameters and can be used wherever you need on your content template. [Note that you will be able to access a book ID from here as well if you examine the generated HTML for a book list. The Book ID is the attribute ‘bookid’ on each of the book output containing div elements.]

The rich application generated by [librivox_app] utilises several custom WP API endpoints created and exposed by the plugin which act as proxies passing the author search string and book IDs to the Librivox API. These plugin endpoints return JSON for the plugin JavaScript to use as AJAX data sources.

API endpoints are:
List authors (limited to 50): /wp-json/wp-librivox/v1/authors
List books by author (e.g. ‘doyle’): /wp-json/wp-librivox/v1/books/doyle
Get book details by book ID (e.g. 4135): /wp-json/wp-librivox/v1/books/id/4135
Get track list by book ID (for MP3 files): /wp-json/wp-librivox/v1/rss/4135

Usage

  • Adding shortcode for single book: Add shortcode [librivox_book bookid="nnn"] In a suitable location. The parameter ‘nnn’ is the LibriVox book ID. For example, replacing ‘nnn’ with ‘804’ will render the classic Conan Doyle Sherlock Holmes collection ‘Memoirs of Sherlock Holmes’
  • Adding shortcode for interactive app: Add shortcode [librivox_app] In a suitable location. This will trigger the full interactive application, allowing searching for books by author and playing an audio book.

Screenshots

  • View of [librivox_book bookid="804"] rendering the title, description, ZIP download link and HTML5 play links for a book recording.
  • View of [librivox_app] initial output of a search screen, with autocomplete matching an author (this uses JQueryUI Autocomplete, fed from one of the proxy REST endpoints).
  • View of [librivox_app] following selection of an author. All books by that author are listed, again via a proxied request to Librivox API for books by author 'nnn'.
  • View of [librivox_app] following selection of a book. This screen is very similar to the output for [librivox_book bookid="804"].
  • View of player once a track is selected.

Installation

  1. Unzip the plugin archive into /wp-content/plugins/ directory of your WordPress installation, or install the plugin through the WordPress plugins screen directly.
  2. Enable in the plugins section of the wp-admin dashboard. There are no configuration options needed.

FAQ

Installation Instructions
  1. Unzip the plugin archive into /wp-content/plugins/ directory of your WordPress installation, or install the plugin through the WordPress plugins screen directly.
  2. Enable in the plugins section of the wp-admin dashboard. There are no configuration options needed.
How do I find book IDs?

You can either query the Librivox catalog directly with a query such as above, or book IDs can be found within various links on the Librivox ‘Browse’ pages.

Contributors & Developers

“JCMS Librivox” is open source software. The following people have contributed to this plugin.

Contributors

Translate “JCMS Librivox” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.

Changelog

1.0

  • First version.