Master files, metadata and report documentation

1 1 Introduction
- 1.1 1.1 About CB and Luisterhuis
- 1.2 1.2 About this document
2 2 Scope
- 2.1 2.1 Principles
- 2.2 2.2 Towards a daily workflow
- 2.3 2.3 Integration step by step
- 2.4 2.4 Checklist (download)
3 3 Technical specifications audio master files
- 3.1 3.1 Audio specifications
- 3.2 3.2 Segmented audio support
- 3.3 3.3 ID3v2 tag support
- 3.4 3.4 File naming convention
- 3.5 3.5 Social DRM
4 4 Table of contents metadata
- 4.1 4.1 Background
- 4.2 4.2 How Luisterhuis supports chapter and table of contents metadata
  - 4.2.1 4.2.1 Chapter name in mp3 ID3v2 header
  - 4.2.2 4.2.2 Chapter name as part of the mp3 file name
  - 4.2.3 4.2.3 Table of contents manifest in separate json file
    - 4.2.3.1 Example json file
  - 4.2.4 4.2.4: Table of Contents in ONIX
5 5 ONIX metadata
- 5.1 5.1 Background
- 5.2 5.2 Platform specific ONIX
- 5.3 5.3 Local ONIX best practices
  - 5.3.1 5.3.1 ProductForm and PrimaryContentType
    - 5.3.1.1 Audiobook ProductForm and ProductFormDetail
  - 5.3.2 5.3.2 Title and collection
    - 5.3.2.1 Example without collection
    - 5.3.2.2 Example with collection
  - 5.3.3 5.3.3 Contributor roles
  - 5.3.4 5.3.4 PrefixToKey in contributor elements
    - 5.3.4.1 Example Contributor with Prefix tot Key
  - 5.3.5 5.3.5 Abridged / unabridged
  - 5.3.6 5.3.6 Language codes
    - 5.3.6.1 Example for Dutch spoken audiobook
    - 5.3.6.2 Example for Dutch spoken audiobook, translated from Swedish
  - 5.3.7 5.3.7 Duration and size values
    - 5.3.7.1 Example ONIX elements duration and size values
  - 5.3.8 5.3.8 Subject metadata
  - 5.3.9 5.3.9 Short and long description/annotation
    - 5.3.9.1 The ONIX element for short text is defined by <TextType> 02
    - 5.3.9.2 The long description is defined by <TextType> 03
  - 5.3.10 5.3.10 Image assets
    - 5.3.10.1 Example ONIX composite for the large image asset
  - 5.3.11 5.3.11 Sample audio file asset
    - 5.3.11.1 Example ONIX SupportingResource compite with sample file
  - 5.3.12 5.3.12 Content Detail
    - 5.3.12.1 Example ContentDetail
    - 5.3.12.2 Example ONIX elements for Related ISBN
    - 5.3.12.3 Example ONIX elements for NSTC
  - 5.3.13 5.3.14 Product availability
    - 5.3.13.1 Example ONIX elements ProductAvailability
    - 5.3.13.2 Example ONIX elements for an announcement
  - 5.3.14 5.3.15 Price fields and territorial restrictions
    - 5.3.14.1 Example ONIX Price composite
6 6 Sales and usage reporting
- 6.1 6.1 Background
- 6.2 6.2 Subscription data
- 6.3 6.3 Sales data
- 6.4 6.4 Delivery method

Document revision history

Date	Version

Date	Version
Jul 19, 2023		Added to 3.1 Audio specifications: Maximum file size: 250 MB
Mar 28, 2023	v1.5	Local ONIX best pratices Added: Content detail effective from 16 May 2023 Changed: the order of Local ONIX best practices topics to match the order in the ONIX Product record
Oct 13, 2022	v1.4	Added to 5.3.14: Announcements, effective from 1 Dec 2022
Aug 16, 2021	v1.3	Added to 5.3.7: RelatedProduct
Sep 1, 2020	v1.2	Update to ONIX 3.0.7 with Code Lists Issue 49, support of Luisterhuis ONIX API v3
Sep 10, 2019	v1.1	Update to ONIX 3.0.6 with Code Lists Issue 46
Nov 1, 2017	v1.0	First English language release, based on ONIX 3.0.4

Published by

Luisterhuis, a subsidiary of CB BV

More information

support@luisterhuis.nl

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.

1 Introduction

1.1 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 productions, ebooks and audiobooks.

Dutch and Flemish publishers use CB as their distribution partner for ebooks (either PDF, EPUB2 or EPUB3) and audiobooks. This offers national and international e-tailers and platforms a one-stop-shop, providing access to the entire Dutch (language) market.

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

Luisterhuis, part of CB since 2020, was established in 2010 and is the leading digital distributor of Dutch and Flemish digital audiobooks. Luisterhuis 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 retailers and platforms are connected directly to the Luisterhuis system for both master file and metadata delivery as for reporting.

1.2 About this document

This documentation is intended for audiobook platforms who needs to integrate with the Luisterhuis system.

The next chapters are dedicated to all details regarding the audiobook integration for platforms:

Chapter 2: Scope
Chapter 3: Technical specifications audio master files
Chapter 4: Table of contents metadata
Chapter 5: Details about the ONIX metadata
Chapter 6: Sales reporting

2 Scope

2.1 Principles

The Luisterhuis master file and metadata delivery principles for platforms are based on file delivery through (S)FTP. In short, all metadata and master files of a single audiobook will be copied by the Luisterhuis exporter to an (S)FTP server managed by the platform. It is up to the platform to regularly check their FTP server, scan its folders, and download and process the files. In addition, the Luisterhuis importer ingests the (monthly) sales reports from the platform.

Wherever possible, Luisterhuis can be configured to match the platform ingestion and reporting specifications. It is essential for the Luisterhuis integration team to get access to the platform specifications, FTP information and (sample) reporting files a.s.a.p.

2.2 Towards a daily workflow

A publisher uses the CB Online-portal to enable an audiobook for a platform client. This can be done 24/7. Once a day, at 02:00 CET (or another time, to be determined in consultation with the platform), the Luisterhuis exporter copies the metadata and audio master files on the (S)FTP server of the platform.

The files to be copied can consist of a combination of:

All audiobook mp3 master files
The ONIX metadata
A sample audio file
A square cover image
(optional) All audiobook files cut to 2 to 3-minute segments in flac format
(optional) A json manifest with table of contents and chapter metadata
(optional) A trigger file, signalling the complete upload of all files belonging to a title

In addition to a full delivery (containing both audio master files and metadata), there are two kinds of updates supported:

Metadata updates (including takedowns, price changes, new cover images, new sample audio)
Audio updates (to replace to old audio files). An audio update always consists of a complete set of the audiobook master files, to replace the original audio files.

After a sales period, Luisterhuis ingests the sales report from the platform. Depending on the business model, difference report fields are required. Luisterhuis parses this data and feeds it into the CB Online system where it will be used for analytics, invoicing and general reporting to the respective publishers.

2.3 Integration step by step

Luisterhuis can be configured to match most platform ingestion and reporting specifications, including flexible (S)FTP file and folder naming options and the use of a trigger file. This manual describes the possibilities of Luisterhuis and the specific metadata aspects for the Dutch language market.