OverDrive Download

As Overdrive has deprecated Overdrive Media Console and even hidden the ability to download required .odm files for various platforms, it has become more challenging to download library audiobooks for offline use. This project aims to simplify the process for users who care to download and manage mp3 audiobooks.

The project provides a CLI, as well as code libraries, that can be used to download audiobooks from the Overdrive website for your library. There are simple commands to automate the entire process, as well as access to each capability for individual use. The project currently supports:

• Downloading the the .odm file and acquiring the appropriate licenses
• Downloading the .mp3 audiobook files
• Renaming the files and directories in a format of your choosing
• Normalizing ID3 tags for consistency

Respect the content creators

This project is designed for the legal acquisition of audiobooks for library patrons. Please treat authors and content creators with respect by honoring their copyrights.

Quickstart

To get started simply install the command using npm, create a configuration file, and download any book that you have borrowed from Overdrive.

Quickstart Commands

npm install -g overdrivedownload
odm config -l example-library-name -u example-username -p example-password -dl "./example/download/path"
odm "Title of book"

Example

npm install -g overdrivedownload
odm config -l nypl -u 123456 -p abcdef -dl "~/Downloads/Audiobooks"
odm "The Old Man and the Sea"

CLI Usage

CLI installation

npm install -g overdrivedownload

Once the CLI has been installed a configuration file needs to be created. A cli command odm config has been created to simplify this process. See the Configuration section of this document for more details on the range of possible configuration values.

Example config creation

odm config -l example-library-name -u example-username -p example-password -dl "./example/dowload/path" }

Example auto download

This example finds the first book available in on the loans page and downloads it. This performs the full download process including: downloading the .odm, downloading the .mp3 files, renaming them consistently, and normalizing the ID3 tags.

odm auto

Example basic download

This example finds the book by the specified title, and performs the full download process.

Auto Borrow

When a title is specified, the book will automatically borrowed if it is on hold. This simplifies the process when a hold request is filled and an email notification is received that a book is available.

odm "The Old Man and the Sea"

Example .odm download only

This example finds the book by the specified title and downloads the .odm. This can be useful if you wish to use another application like Overdrive Media Console to download the audiobook .mp3 files.

odm download-odm "The Old Man and the Sea"

Example .mp3 download from existing .odm

This example uses the specified .odm to download the .mp3 audiobook files.

odm download-mp3 "./downloads/TheOldManandtheSea.odm"

Example rename

This example renames the files using the least parameters possible. This command uses the author and title parameters to calculate the path to the book and relies on the config file for other parameters.

odm rename --author "Ernest Hemingway" --title "The Old Man and the Sea"

See the Renaming section of this document for more information about configuring directory and file naming patterns.

Example rename using all possible parameters

This example renames all the files in the ./downloads/Ernest Hemingway/The Old Man and the Sea path. It will result in a new directory Ernest Hemingway - The Old Man and the Sea containing files Part 1.mp3, Part 2.mp3, etc.

odm rename --author "Ernest Hemingway" --title "The Old Man and the Sea" --path "./downloads/Ernest Hemingway/The Old Man and the Sea" --directoryPattern "${author} - ${title}" --filePattern "Part ${trackNumber}${fileExtension}"

Example run with logging

This example performs the full download process while logging addition information to the terminal. This option may be useful while diagnosing problems with the download.

odm "The Old Man and the Sea" --verbose

Web Server

This project includes a simple webserver that hosts a basic user interfact that can be used to perform basic operations remotely, without the need for SSH access to the terminal.

In addition to the code to run the server directly, the basics for a docker container have been included to simplify the entire process of running the server.

Once the server is up and running use a web browser to visit http://example-server-name and enter the name of the book you would like to download. If you have borrowed the title, the audiobook will be downloaded to the configured path.

Docker Quickstart Command

docker run -d -p 80:80 --mount type=bind,source=/example/download/path,target=/usr/download -e ODM_LIBRARY=example-library-name -e ODM_USERNAME=example-username -e ODM_PASSWORD=example-password johngully/overdrive-download

Docker Compose

The easiest way to configure and run the web server is using docker-compose. Begin by creating a docker-compose.yml and configuring the local volume where downloads will be stored, as well as the Overdrive library credentials.

Template docker-compose.yml

version: "3.9"
services:
  server:
    image: johngully/overdrive-download
    ports:
      - 80:80
    volumes:
      - ./downloads:/usr/downloads # local-path:docker-contaier-path
    environment:
      - ODM_LIBRARY=  # Library name
      - ODM_USERNAME= # Overdrive username
      - ODM_PASSWORD= # Overdrive password

Docker compose command

docker-compose up -d

Example doccker compose configuration

version: "3.9"
services:
  server:
    image: johngully/overdrive-download
    ports:
      - 7979:80
    volumes:
      - /usr/downloads/audiobooks:/usr/downloads
    environment:
      - ODM_LIBRARY=nypl
      - ODM_USERNAME=123456
      - ODM_PASSWORD=abcdef

Package usage

The project is currently designed to simplify the workflow of downloading audiobooks from your local Overdrive library and currently supports four primary functions.

• Downloading the the .odm file and acquiring the appropriate licenses
• Downloading the .mp3 audiobook files
• Renaming the files and directories in a format of your choosing
• Normalizing ID3 tags for consistency

Begin by logging into the Overdrive website for your library. Find the book you are interested in, and "Borrow" the title. This should add the book to the "Loans" page under "My Account". Once the title is on loan, you may use the library to acquire the .odm file and the associated .mp3 files. Renaming and tagging of files are convienience operations that will work with files regardless of Overdrive.

Example

import OverdriveDownload from "overdrivedownload";
const overdrive = new OverdriveDownload();

// Modify this to match the book title on the 
// loans page of your library's overdrive website
const title = "The Old Man and the Sea"; 

// Download the ODM for the specified title from the library website
const odmFilePath = await overdrive.odm.download(title);
console.log("ODM file path:", odmFilePath);

// Use the ODM to download the title mp3 files
const downloadResults = await overdrive.mp3.download(odmFilePath);
console.log(`Download of ${downloadResults.partCount} parts complete:`, downloadResults.bookPath)

// Use the download results to rename the files consistently
const renameResults = await overdrive.files.rename(downloadResults.bookMetadata);
console.log(`Rename of ${renameResults.files.length} files complete:`, renameResults.directory);

// Use the rename results to normalize the ID3 tags
const tagResults = await overdrive.tags.normalizeTags(renameResults.directory, downloadResults.bookMetadata);
console.log(`Tagging of ${tagResults.files.length} files complete`, renameResults.directory);

// Cleanup the odm and license files
fs.rmSync(downloadResults.odmPath);
fs.rmSync(downloadResults.licensePath);

Configuration

Configuration of the the library are stored in a .overdrivedownloadsrc file. The configuration values are stored in a json format and are persisted across uses. A CLI command odm config has been created to simplify the process of creating.

Running the odm config command additional times will update the config file with new values. Each execution of the command is additive, which means that you are not required to specify all the values every time.

Base Path

The path where files will be downloaded. This path can be an absolute path or a path relative to the execution path of the library.

Default Value = ./

Optional

Library Name

The name of the library that is associated with Overdrive. This is typically the prefix CNAME to the overdrive.com url. In the case of https://example.overdrive.com the library name would be example

Required

Username

The username used to login to the Overdrive library website. This may be your library card number.

Required

Password

The password used to login to the Overdrive library website.

This value should remain on the computer executing the overdrive-download library. Do not commit the .overdrivedownloadrc configuration to a source control repository.

Required

Directory Pattern

The pattern used to name the directories that will contain the audiobook files. This can be a single directory name, or a path.

Default Value = ${artist}/${title}

Optional

File Pattern

The pattern used to name the audiobook files.

Default Value = ${title} - Part ${trackNumber}.{fileExtension}

Optional

Title Pattern

The pattern used to format the title tag during ID3 tag normalization.

Default Value = ${title} - Part ${trackNumber}

Optional

Example configuration file

Minimum required configuration

{
  "basePath": "./downloads",
  "libraryName": "cityname",
  "username": "123456",
  "password": "mysecretpassword"
}

All possible configuration values

{
  "basePath": "./downloads",
  "libraryName": "cityname",
  "username": "123456",
  "password": "mysecretpassword",
  "directoryPattern": "${artist}/${title}",
  "filePattern": "${title} - Part ${trackNumber}.{fileExtension}",
  "titlePattern": "${title} - Part ${trackNumber}"
}

Renaming files

By default the files will be named using the following pattern. This will create a directory structure with the Author's name then another directory with the Title of the book. Each file will be named with the Title of the book - Part 01 incrementing the number for each track.

Default naming pattern

`${author}/${title}/${title} - Part ${trackNumber}${fileExtension}`

Resulting files

> Earnest Hemingway
  ↳ The Old Man and the Sea
    ↳ The Old Man and the Sea - Part 01.mp3
    ↳ The Old Man and the Sea - Part 02.mp3
    ↳ The Old Man and the Sea - Part 03.mp3
    ...

Altering the naming pattern

To change how directories and files are named, modify the configuration file adding the optional directoryPattern and filePattern values. Use the book metadata keys as tokens in the pattern strings.

Patterns use the javascript template literal syntax for value substitution.

Configuration file

{
  ...
  "directoryPattern": "${author}/${series}",
  "filePattern": "${title} - ${trackNumber}${fileExtension}"
}

Expected directory and file naming

> J.K. Rowling
  ↳ Harry Potter 1
    ↳ Harry Potter and the Sorcerers Stone - 01.mp3
    ↳ Harry Potter and the Sorcerers Stone - 02.mp3
    ↳ Harry Potter and the Sorcerers Stone - 03.mp3
  ...

Example book metadata structure

Book metadata can be used set the renaming patterns. Use the JSON keys in the directoryPattern and filePattern configuration string to modify the naming process.

{
  "author": "",        // The name of the book author
  "title": "",         // The title of the book
  "series": "",        // The name of the book series if one exists
  "trackNumber": "",   // The number of the current track/part
  "partCount": "",     // The total number of tracks/parts
  "directoryPath": "", // The path to the book files
  "filePath": "",      // The path to the current file
  "fileName": "",      // The name of the current file (without file extension)
  "fileExtension": ""  // The file extension of the current file including "."
}

Examples of book metadata

Ernest Hemingway - The Old Man and the Sea

{
  "author": "Ernest Hemingway",
  "title": "The Old Man and the Sea",
  "series": "",
  "trackNumber": "1",
  "partCount": 6,
  "directoryPath": "./base/path/Ernest Hemingway/The Old Man and the Sea",
  "filePath": "./base/path/Ernest Hemingway/The Old Man and the Sea/The Old Man and the Sea - Part 01.mp3",
  "fileName": "The Old Man and the Sea - Part 1",
  "fileExtension": ".mp3"
}

J.K. Rowling - Harry Potter and the Sorcerer's Stone

{
  "author": "J.K. Rowling",
  "title": "Harry Potter and the Sorcerer's Stone",
  "series": "Harry Potter 1",
  "trackNumber": "01",
  "partCount": 14,
  "directoryPath": "./base/path/J.K. Rowling/Harry Potter and the Sorcerers Stone",
  "filePath": "./base/path/J.K. Rowling/Harry Potter and the Sorcerers Stone/Harry Potter and the Sorcerers Stone - Part 1.mp3",
  "fileName": "Harry Potter and the Sorcerers Stone - Part 1",
  "fileExtension": ".mp3"
}