Mopidy-InternetArchive

Mopidy-InternetArchive is a Mopidy extension for playing music from the Internet Archive.

This extension lets you search for and stream recordings ranging from alternative news programming, to Grateful Dead concerts, to Old Time Radio shows, to book and poetry readings, to original music uploaded by Internet Archive users. It also gives you access to a vast number of high-quality live recordings from the Live Music Archive, and thousands of free audiobooks from the LibriVox collection.

Browsing the Internet Archive

If your Mopidy client supports browsing, there should be a top-level directory named Internet Archive. Beneath that, you will find the Internet Archive collections listed in internetarchive/collections, and you should be able to browse individual audio items (albums) and files (tracks) within these.

For practical and performance reasons, the number of items that will be shown within a collection is limited, e.g. you will not see all 167,967 audio items of the Live Music Archive [1]. The default configuration sets this limit to 100, but this can be changed using internetarchive/browse_limit.

To allow browsing collections using different sort criteria, every collection provides a number of views, virtual subdirectories which let you browse the collection’s items by popularity, title, publish date, and so on. The default views are set up to resemble the archive.org Web interface, but can be changed at your own discretion with internetarchive/browse_views.

Searching the Internet Archive

The Internet Archive only supports searching for items, but not for individual files or tracks. Therefore, only albums will show up when searching in Mopidy. This also means that only album-related search fields are supported, so searching for track names or numbers will yield no results from the Internet Archive.

The number and ordering of search results returned from the Internet Archive can be changed with internetarchive/search_limit and internetarchive/search_order. Unless you explicitly specify an Internet Archive collection to search within, search scope will also be limited to the collections listed in internetarchive/collections.

Archive Favorites

If you have an Internet Archive account - also termed a Virtual Library Card - you can access your Archive Favorites from Mopidy. To do so, you just need to add the identifier of your favorites collection to internetarchive/collections. Typically, the identifier is fav-{username}, but you should be able to figure it out from the archive.org Web site. When added to internetarchive/collections, you will be able to browse and search your Archive Favorites just like the other collections listed there.

Installation

Debian/Ubuntu/Raspbian (jessie): Install the mopidy-internetarchive package from apt.mopidy.com:

apt-get install mopidy-internetarchive

Otherwise, install the package from PyPI:

pip install Mopidy-Internetarchive

Configuration

This extension has a number of configuration values that can be tweaked. However, the default configuration contains everything to get you up and running, and will usually require only a few modifications to match personal preferences.

Configuration Values

internetarchive/enabled

Whether this extension should be enabled or not.

internetarchive/base_url

Base URL to access the Internet Archive.

internetarchive/collections

A list of collection identifiers to show as top-level directories when browsing. These are also used to limit the search scope when no search base is given by Mopidy clients explicitly.

internetarchive/audio_formats

A list of audio file formats, in order of preference.

This entry contains a list of Internet Archive file formats. By default, only audio formats suitable for streaming are requested. Note that the Internet Archive also contains a large number of high-quality media files in FLAC and other lossless formats, but for sake of bandwidth (both your’s and the Archive’s), it is recommended that you stick to lossy audio formats for streaming through Mopidy.

internetarchive/image_formats

A list of image file formats, in order of preference.

This entry contains a list of Internet Archive file formats to be considered when providing images for Internet Archive items. Note that some Mopidy clients, especially MPD clients, will ignore album art provided by Mopidy-InternetArchive or other Mopidy extensions.

internetarchive/browse_limit

The maximum number of browse results.

This is used to limit the number of items returned when browsing the Internet Archive.

internetarchive/browse_views

When browsing Internet Archive collections (or directories in Mopidy), this provides a list of virtual subdirectories so results can be retrieved using a particular sort order.

The format for each entry is <fieldname> (asc|desc) | <label>, where <label> is a name for the entry to show up in the Mopidy client.

internetarchive/search_limit

The maximum number of search results.

This is used to limit the number of items returned when searching the Internet Archive.

internetarchive/search_order

The sort order used when searching the Internet Archive.

internetarchive/cache_size

The number of Internet Archive items to cache in memory.

internetarchive/cache_ttl

The cache time-to-live in seconds.

internetarchive/retries

The maximum number of retries each HTTP connection should attempt.

internetarchive/timeout

The timeout in seconds for HTTP requests to the Internet Archive.

Sort Order Fields

The sort order for searching and browsing is given as <fieldname> (asc|desc), where <fieldname> is one of:

  • addeddate
  • avg_rating
  • call_number
  • createdate
  • creatorSorter
  • date
  • downloads
  • foldoutcount
  • headerImage
  • identifier
  • imagecount
  • indexdate
  • languageSorter
  • licenseurl
  • month
  • nav_order
  • num_reviews
  • publicdate
  • reviewdate
  • stars
  • titleSorter
  • week
  • year

Default Configuration

For reference, this is the default configuration shipped with Mopidy-InternetArchive release 2.0.3:

[internetarchive]
enabled = true

# archive.org base URL
base_url = http://archive.org

# top-level collections for browsing
collections =
    audio
    etree
    librivoxaudio
    audio_bookspoetry
    audio_tech
    audio_music
    audio_news
    audio_foreign
    audio_podcast
    audio_religion

# audio file formats in order of preference
audio_formats = VBR MP3, 64Kbps MP3

# image file formats in order of preference
image_formats = JPEG, JPEG Thumb

# maximum number of browse results
browse_limit = 100

# list of collection browse views: <fieldname> (asc|desc) | <name>
browse_views =
      downloads desc    | Views
      titleSorter asc   | Title
      publicdate desc   | Date Archived
      date desc         | Date Published
      creatorSorter asc | Creator

# maximum number of search results
search_limit = 20

# sort order for searching: <fieldname> (asc|desc); default is score
search_order =

# number of items to cache
cache_size = 128

# cache time-to-live in seconds
cache_ttl = 86400

# maximum number of HTTP connection retries
retries = 3

# HTTP request timeout in seconds
timeout = 10

Change Log

v2.0.3 (2017-06-16)

  • Handle archive.org JSON API changes.

v2.0.2 (2017-01-09)

  • Fix file name handling.

v2.0.1 (2017-01-09)

  • Handle multiple item titles.

v2.0.0 (2015-12-08)

  • Support configurable sort criteria when browsing collections via “browse views”.
  • Include collections in browse results.
  • Add support for LibraryProvider.get_images().
  • Drop support for deprecated Album.images.
  • Drop special handling of bookmarks.
  • Cache root collections.
  • Update documentation.

v1.3.0 (2015-09-11)

  • Require Mopidy >= 1.1.
  • Use Mopidy proxy settings and HTTP User-Agent.
  • Fix track bitrates represented in Kbit/s.
  • Drop exact search support.
  • Only cache items.

v1.2.1 (2015-03-25)

  • Remove search query normalization.
  • Prepare for Mopidy v1.0 exact search API.

v1.2.0 (2015-03-19)

  • Remove playlists provider.
  • Add bookmarks to root directory for browsing.

v1.1.0 (2014-11-19)

  • Load bookmarks as individual playlists.
  • Clear library cache when refreshing playlists.
  • Encode filenames in URIs.
  • Add HTTP connection retries.

v1.0.3 (2014-11-14)

  • Fix handling of re-derived VBR MP3 files.
  • Remove Ogg Vorbis from default audio formats.

v1.0.2 (2014-11-07)

  • Update dependencies.
  • Browse Internet Archive items as albums.
  • Make caching optional.
  • Disable PNG image format in default configuration.
  • Temporarily disable VBR MP3 and track comments.

v1.0.1 (2014-09-29)

  • Add item descriptions as track comments.
  • Filter search results for exact queries.

v1.0.0 (2014-09-26)

  • Major rewrite for version 1.0.0.

v0.5.0 (2014-02-28)

  • Update README with link to documentation.
  • New config values: search_order, browse_order.
  • Allow empty queries for searching.

v0.4.0 (2014-02-25)

  • Various performance and stability improvements.
  • Option to exclude specific collections from searching/browsing.
  • Add image URLs to albums.

v0.3.1 (2014-02-21)

  • Fix default configuration.

v0.3.0 (2014-02-21)

  • Add bookmark browsing support.
  • Better filtering of search results.
  • Stability and performance improvements.

v0.2.0 (2014-01-31)

  • Add library browsing support.
  • Cache search results and metadata.
  • Properly quote/encode query terms.

v0.1.0 (2014-01-24)

  • Initial release.

License

Mopidy-InternetArchive is Copyright (c) 2014-2017 Thomas Kemmer.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this software except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Footnotes

[1]As of Jan. 9, 2017.