Published by
Luisterhuis, a subsidiary of CB BV

More information
support@luisterhuis.nl

© 2010-2021 CB BV
This document contains confidential and proprietary information.
All rights reserved. No part of this publication may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm, without prior written consent of CB.

Document revision history

Introduction

About CB and Luisterhuis

CB is the main book distributor in the Netherlands and Flanders and the link between publisher, (online) bookseller and consumer. Over 1000 publishers and 1500 booksellers trust their logistics to CB for their physical books, POD publications, ebooks and audiobooks.

Dutch and Flemish publishers use CB as their digital distribution partner for ebooks (either PDF, EPUB2 or EPUB3) and audiobooks. With a suite of services available all in one portal, CB offers national and international e-tailers and platforms a one-stop-shop for access to the entire Dutch (language) market.

Publishers use the ‘CB Online’ web interface to offer their titles and data to any connected web shop retailer or platform. Publishers can offer their digital titles for sale, by subscription or for lending via a library. In addition to master files and metadata distribution, CB also offers invoicing services for the net pricing between publishers and e-tailers and provides insightful consolidated data reporting to the publishers using advanced analytics tools.

Luisterhuis, part of CB since 2020, handles digital fulfilment, offers extensive reports and provides master files and metadata to local and international web shops, library services, subscription platforms and other content platforms. For  publishers, Luisterhuis is integrated into the CB Online web interface.

Luisterhuis offers different feeds and services to its B2B audiobook customers, like ONIX metadata web services, digital dropship delivery with download link fulfilment for web shops and (S)FTP based delivery of metadata and audiobook master files for audiobook platforms. Luisterhuis also ingests and processes all (monthly) sales and usage reports from audiobook retailers and platforms.

Audiobook web shop retailers and platforms are connected directly to the Luisterhuis system for both master file and metadata delivery and for reporting.

About this document

This documentation is intended for software developers and systems integrators who want to connect a web shop to the Luisterhuis distribution system to start selling digital audiobooks.
Luisterhuis operates as a RESTful web service and offers all tools necessary for an audiobook web shop:

• It supplies a web shop with catalogue metadata, book-cover images and audio samples.

• It accepts orders from a web shop and delivers the digital download links back to the web shop.

• It handles the fulfilment of the digital audiobook download links for the end user.

• It offers a web-based interface with a real time transaction overview, title repository and other info.

• It uses the award winning BooXtream Audio social DRM protection system, which combines full MP3 compatibility with the assurance of minimized illegal use of the MP3 files.

Architecture

Luisterhuis as a digital distribution service

Luisterhuis operates as a distribution service between publishers of audiobooks and web shops.

It enables a web shop to sell audiobook downloads without actually storing and maintaining the audiobook files in the web shop. Instead, the web shop only has to implement a client interface to Luisterhuis to add audiobook metadata to its catalogue and to place orders. Everything else is handled by the Luisterhuis system, including the delivery of the protected MP3 files to the end user.

A simplified overview of the architecture:

Delivering audiobooks to the end user

Luisterhuis stores all audio master files and all metadata of the audiobooks on its own secure servers. Luisterhuis does not deliver the audio files to the web shop. Instead, Luisterhuis only delivers audiobook metadata, such as price data, author, narrator, description, images and sound samples to the web shop by means of an API. This allows the API client (the web shop) to create and maintain its own catalogue. When an end user orders an audiobook in the web shop, the transaction  details are forwarded to the Luisterhuis API. Luisterhuis then returns a set of download links to the web shop, intended for the end user. It is up to the web shop to provide these download links to the end user (in a web dialogue, by mail and/or in an account). When a download link is activated by the end user, Luisterhuis delivers the audio files directly to the enduser.

MP3 packaging and tagging

Although the MP3 file format for audio files is a world standard, the usage of MP3 for audiobooks introduces three complications that needs to be addressed:

• separate tracks with individual chapters,

• file size

• tagging.

In short:

• Almost every audiobook is divided into separate audio files (usually one MP3 file per chapter). This means that a complete audiobook will consist of a collection of files but downloading separate MP3 files is not user friendly.

• Audiobooks can be very large (10+ hours in duration is not unusual). This means that the amount of MB's to download can be large. A 15-hour long audiobook can easily be 1,5 GB.

• Every modern MP3 audio player (device or app) is able to show and use embedded MP3 ID3 tags. These tags are used by the library in the player to show and sort by Title, Author, chapter title and some other values. Without these tags, the playing sequence can be unpredictable so it’s essential that all MP3 files contain the correct ID3 tags.

• Older (car)players tend to use and show the MP3 file names, so it is essential that the audiobook files are created with usable file names in order to select the correct tracks and play them in the correct order.

The Luisterhuis distribution system automatically takes care of all of this by creating uniquely tagged and named MP3 files and packaging these in a ZIP file for easy download.

ZIP packaging

The size of a digital audiobook can vary from 20 MB to more than 2 GB each, depending on the length of the recording. Unlike ebooks, where the content involves only one single EPUB file, a digital audiobook consists of several MP3 audio files, with up to several hundreds of MP3 files for one audiobook. However, manually downloading a lot of MP3 files for one audiobook, is very unfriendly for the end user.

Because of this, all MP3 files are packed together into one or more ZIP files. A Luisterhuis ZIP file has a maximum size of 250 MB. Small audiobooks are supplied in a single ZIP file. Larger audiobooks use more ZIP files. This enables the end user to selectively download a large audiobook in parts, which is useful when download speeds are low or using a mobile device. 

The identifier is either the ISBN or the short title of the audiobook. 

Examples

Read chapter 7 for more details about the delivery of the download links to the web shop and the customer.

MP3 file naming

Every MP3 file within this ZIP is named using a standard naming convention. This convention contains 4 parts: author name, audiobook title, track number info and chapter title

Example

MP3 tagging

In addition, the Luisterhuis distribution system automatically adds the correct ID3v1 and ID3v2 tags to every audio file. The following tags are created dynamically by the Luisterhuis distribution system.

Album art

Every MP3 audio file contains a watermarked hires image of the audiobook cover. Most modern MP3 audio players (devices and apps) will show this image.

BooXtream Audio Social DRM

Luisterhuis uses BooXtream Audio Social DRM. This means that every MP3 file is created on the fly, with dynamic created information about Luisterhuis, the web shop and the customer. These ‘watermarked’ MP3 files and the enclosed (cover) images within the MP3 file header contain personalized information and other digital fingerprints, like a hidden transactional based code which is different for every web shop transaction, every user and every client (web shop).

An MP3-file with BooXtream Social DRM can be traced back to the individual customer and to the web shop where the customer has bought the audiobook, but the files are 100% compatible with every (hardware and software) MP3 player.

Luisterhuis as central hub for audiobook apps

In addition to the core features of the Luisterhuis distribution system, Luisterhuis also supports audiobook apps with a dedicated set of API’s.

The main use of the app API is to support apps that offer audiobook download and play functions for audiobooks sold by a web shop. The audio content is served directly from the Luisterhuis audiobook repository, bypassing the ZIP delivery format explained earlier. The app API documentation is available on request. Mail to support@luisterhuis.nl

Overview of the Luisterhuis API’s

Introduction

On a day-to-day basis, the API is used as follows: the web shop queries the Luisterhuis Catalogue API web service once a day to process the new and modified product information. The Luisterhuis product information is used to update the web shop catalogue.

The Catalogue API offers several functions to query the Luisterhuis web service for audiobook products, such as a list of all products and a list of changed or new products since a specific date. The Luisterhuis web service returns full ONIX 3 metadata.

When an end user places an order in the web shop, the web shop places the same order at Luisterhuis using the Order API.

After a successful order, the web shop retrieves the download link(s) using the downloadinfo API. The download link has to be stored in a user account and/or sent to the end user.

Endpoints and authentication

The default production endpoint for the Luisterhuis API is:

Quick overview of the API’s

The Luisterhuis API offers several functions to connect to your web shop. Below is a quick overview: They will be described in more detail in the following chapters.

ONIX metadata

The Luisterhuis catalogue of audiobook products contains all metadata of the audiobooks, like author, publisher, prices et cetera. The data is supplied in XML following the international ONIX 3.0 guidelines.

ONIX for Books is a worldwide XML standard to describe book information. It enables connecting the servers of publishers, distributors and retailers, without any conversion or manual data entry of the book data. Information about the ONIX standard is available online on www.editeur.org

It is important to know that to process the Luisterhuis XML files, you will have to 'know' how ONIX works. We can recommend downloading the documentation here: http://www.editeur.org/93/Release- 3.0-Downloads/

Chapter 5 contains information about the specific ONIX elements for audiobooks.

The basic steps to sell audiobooks using Luisterhuis API’s

It all starts with the initial retrieval of the product catalogue from Luisterhuis to incorporate the metadata in your own system. After the Luisterhuis audiobook products are available in your system, you can sell them to your customers. You will also have to check regularly if there are new or changed products. (New products and updated metadata are added on a daily basis; sometimes the price or the description of an existing product can change). The functions for catalogue retrieval are described in Chapter 4.

When an audiobook is being sold from your system, it is common practice to first check if the product is still available at Luisterhuis. So, before you accept payment from your customer, check the availability. There is an API call for that. (In fact: there are two ways of checking: you can simply check, or you can combine the checking with the placement of an order). The reason is not that the product can be out of stock, but the product can be withdrawn from the catalogue due to commercial or legal reasons. The functions for order placement are described in Chapter 6.

After you have received a confirmation that the product is still available, you can proceed to the checkout procedure in your own shop and accept payment from your customer.

When your shop places an order at Luisterhuis, you will have to supply Luisterhuis with some details of the order, like the product(s) to order, the customer name and/or their e-mail address and your internal order number. After Luisterhuis accepts your order, it will supply you with a Luisterhuis order id.

Using this Luisterhuis order id, your shop can request the download link. This download link can be stored in a private area on your site, available only for your end user. And/or you can send the link by e-mail to your end user. Using this link, the end user can download the ZIP files containing the audiobooks. The functions for handling the download links are described in Chapter 7.

Accounting and reporting

Luisterhuis handles all end user orders and fulfils the download links. Therefore Luisterhuis ‘knows’ about every end user transaction. Luisterhuis aggregates this data for the various publishers and uses this data for invoicing and pay-out purposes.

Depending on the agreement the web shop has with CB, they might receive a monthly or quarterly receipt with a detailed description of all audiobooks retrieved, played and/or sold.

A representative of the web shop (usually a member of the support desk) also has access to a real time report of all transactions and sales reports through a dashboard located at www.luisterhuis.nl/reseller or stub-www.luisterhuis.nl/reseller (testing purposes).

This dashboard offers an overview of all available titles, all basic metadata and all transactions. The dashboard can also be used to reset already used (or expired) download links. The dashboard is described in detail in Chapter 8: Reseller dashboard for web shops.

API for catalogue and metadata

Summary of functions

Luisterhuis uses a RESTful web service to provide all audiobook metadata to a web shop.

The interface offers the following API functions:

• Catalogue metadata in ONIX 3 format

• Single product metadata in ONIX 3 format

It is best practice to call the API once a day every 24 hours (for instance every night between 02:00 and 06:00).

Catalogue metadata in ONIX 3 format

To retrieve all metadata of all available audiobooks available for the web shop you can use the inventory API call. The inventory call supports the retrieval of ONIX metadata of a full catalogue (inventory) or only the updates over a certain period (‘what’s new since yesterday’).

Single product metadata in ONIX 3 format

If you know the ISBN of an audiobook and want to retrieve an uptodate metadata record, you could use the ‘product’ API call. All product metadata of a single audiobook can be retrieved like this:

ONIX metadata

Background

The Luisterhuis catalogue of audiobook products contains all metadata of the audiobooks, like author, publisher, prices et cetera. The data is supplied in XML following the ONIX 3.0 guidelines.

The current supported ONIX version by Luisterhuis is a subset of ONIX 3.0 revision 7 with ONIX Code Lists Issue 49. Please note: the ONIX metadata will always be supplied using full reference names.
In this chapter we’ll discuss the subset used by Luisterhuis. Test ONIX XML-files are available on request.

Web shop specific ONIX

Luisterhuis creates web shop specific ONIX metadata. The content is based on a combination of parameters of the underlying CB Online system. The ONIX is tailored and personalized to the specific web shop. For instance, catalogue selection, pricing and publication dates can differ from web shop to web shop based on agreements with publishers.

Local ONIX best practices

Since CB and Luisterhuis both have their roots in the Dutch language publishing market, the ONIX 3.0 subset used by Luisterhuis is highly compatible with the Dutch ONIX subset defined by CB. CB is Charter Member of EDItEUR and takes part in the Dutch language ONIX working group. CB maintains the ‘best practice’ for ONIX in the Dutch language area.

The following paragraphs describe the specific ONIX implementation and best practices for the Dutch market.

ProductForm and PrimaryContentType

For digital audiobooks, the following <ProductForm> is used:

ProductForm

The following values for <PrimaryContentType> are supported:

• 01 Audio (audiobook)

• 02 Performance (audio drama, theatre, cabaret)

• 03 Music Recording 

• 04 Other Audio (nature sounds, soundscapes) 

• 13 Other Speech Content (lectures, interviews, discussions, audio tours)

Title and collection

The ONIX metadata supports the following title and collection elements:

Title detail: