Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/laxamentumtech/audnexus

An audiobook data aggregation API that harmonizes data from multiple sources into a unified stream. It offers a consistent and user-friendly source of audiobook data for various applications.
https://github.com/laxamentumtech/audnexus

api audiobooks audnexus data-aggregation docker fastify metadata mongodb nodejs papr redis typescript

Last synced: 4 days ago
JSON representation

An audiobook data aggregation API that harmonizes data from multiple sources into a unified stream. It offers a consistent and user-friendly source of audiobook data for various applications.

Host: GitHub
URL: https://github.com/laxamentumtech/audnexus
Owner: laxamentumtech
License: gpl-3.0
Created: 2021-09-06T20:33:57.000Z (about 3 years ago)
Default Branch: main
Last Pushed: 2024-10-30T04:41:47.000Z (5 days ago)
Last Synced: 2024-10-30T07:24:36.051Z (5 days ago)
Topics: api, audiobooks, audnexus, data-aggregation, docker, fastify, metadata, mongodb, nodejs, papr, redis, typescript
Language: TypeScript
Homepage: https://audnex.us/
Size: 6.61 MB
Stars: 120
Watchers: 4
Forks: 5
Open Issues: 21
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

awesome - laxamentumtech/audnexus - An audiobook data aggregation API that harmonizes data from multiple sources into a unified stream. It offers a consistent and user-friendly source of audiobook data for various applications. (TypeScript)

README

        


  

 



audnexus




[![Status](https://status.audnex.us/api/badge/4/status)](https://status.audnex.us)

[![GitHub Issues](https://img.shields.io/github/issues/djdembeck/audnexus.svg)](https://github.com/djdembeck/audnexus/issues)

[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/djdembeck/audnexus.svg)](https://github.com/djdembeck/audnexus/pulls)

[![License](https://img.shields.io/badge/license-GNUGPL-blue.svg)](/LICENSE)

[![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/djdembeck/audnexus)](https://www.codefactor.io/repository/github/djdembeck/audnexus)

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=laxamentumtech_audnexus&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=laxamentumtech_audnexus)



---

 An audiobook data aggregation API, combining multiple sources of data into one, consistent source.

    
 



## 📝 Table of Contents

- [About](#about)

- [Getting Started](#getting_started)

- [Deployment](#deployment)

- [Usage](#usage)

- [Built Using](#built_using)

- [TODO](../TODO.md)

- [Contributing](../CONTRIBUTING.md)

- [Authors](#authors)

- [Acknowledgments](#acknowledgement)

## 🧐 About 

_Nexus - noun: a connection or series of connections linking two or more things._

Looking around for audiobook metadata, we realized there's no solid (or open) single source of truth. Further, some solutions had community curated data, only to close their API. As such, this project has been created to enable development to include multiple sources of audiobook content in one response.

This project also makes integration into existing media servers very streamlined. Since all data can be returned with 1-2 API calls, there's little to no overhead processing on the client side. This enables rapid development of stable client plugins. Audnexus serves as a provider during the interim of waiting for a community driven audiobook database, at which time audnexus will be a seeder for such a database.

## 🏁 Getting Started 

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See [deployment](#deployment) for notes on how to deploy the project on a live system.

### Prerequisites

- There are 2 ways to deploy this project - for the purposes of this project, this guide will only cover Docker deployment:

  - [Docker Swarm](https://docs.docker.com/engine/swarm/swarm-tutorial/)

  - Directly, via `pnpm run` or `pm2`

    - Mongo 4 or greater

    - Node/NPM 16 or greater

    - Redis

  - Registered Audible device keys, `ADP_TOKEN` and `PRIVATE_KEY`, for chapters. You will need Python and `audible` for this. [More on that here](https://audible.readthedocs.io/en/latest/auth/register.html)

### Installing locally

- Install Mongo, Node and Redis on your system

- `pnpm install` from project directory to get dependencies

- Set `ADP_TOKEN` and `PRIVATE_KEY` environment variables as mentioned above if you are using the chapters endpoint.

- `pnpm run watch-debug` to start the server

Test an API call with

```

http://localhost:3000/books/${ASIN}

```

## 🔧 Running the tests 

Tests for this project use the Jest framework. Tests can be done locally in a dev environment:

- `pnpm test`

After the tests have run, you may also browse the test coverage. This is generated in `coverage/lcov-report/index.html` under the project directory.

## 🎈 Usage 

API usage documentation can be read here: https://audnex.us/

Pre-rendered HTML documentation is also included in docs/index.html.

HTML can be re-generated from the spec, using:

```

pnpm run build-docs

```

## 🚀 Deployment 

Once you have Docker Swarm setup, grab the `docker-compose.yml` from this repo, and use it to start the stack. Using something like Portainer for a Swarm GUI will make this much easier.

The stack defaults to 15 replicas for the node-server container. Customize this as needed.

Environment variables to add:

- `NODE_ADP_TOKEN`: Aforementioned `ADP_TOKEN` value

- `NODE_MAX_REQUESTS`: Maximum amount of requests per 1 minute period from a single source (default 100)

- `NODE_MONGODB_URI`: MongoDB connection URL, such as `mongodb://mongo/audnexus`

- `NODE_PRIVATE_KEY`: Aforementioned `PRIVATE_KEY` value

- `NODE_REDIS_URL`: Redis connection URL, such as `redis://redis:6379`

- `NODE_UPDATE_INTERVAL`: Frequency (in days) to run scheduled update tasks (default 30). Update task is also run at startup.

- `NODE_UPDATE_THRESHOLD`: Minimum number of days after an item is updated, to allow it to check for updates again (either scheduled or param).

- `TRAEFIK_DOMAIN`: FQDN for the API server

- `TRAEFIK_EMAIL`: Email to register SSL cert with

Once the stack is up, test an API call with

```

https://${TRAEFIK_DOMAIN}/books/${ASIN}

```

### Set up DB indexes to keep item lookups fast and to support searches.

1. Connect to the DB either from inside the mongodb container terminal or a MongoDB Compass/MongoSH session.

2. Switch to the correct DB:

   ```

   use audnexus

   ```

3. Create the recommended indexes:

   ```

   db.authors.createIndex( { asin: 1, region: 1 } )

   ```

   ```

   db.books.createIndex( { asin: 1, region: 1 } )

   ```

   ```

   db.chapters.createIndex( { asin: 1, region: 1 } )

   ```

   ```

   db.authors.createIndex( { name: "text" } )

   ```

## ⛏️ Built Using 

- [Fastify](https://www.fastify.io/) - Server Framework

- [MongoDB](https://www.mongodb.com/) - Database

- [NodeJs](https://nodejs.org/en/) - Server Environment

- [Papr](https://github.com/plexinc/papr) - Databse connection

- [Redis](https://redis.io/) - Cached responses

## ✍️ Authors 

- [@djdembeck](https://github.com/djdembeck) - Idea & Initial work

## 🎉 Acknowledgements 

- Huge thanks to [mkb79](https://github.com/mkb79) and their [audible](https://github.com/mkb79/Audible) project for a great starting point.

- [macr0dev](https://github.com/macr0dev) for introducing us to scraping.

- [seanap](https://github.com/seanap) for passionately standardizing audiobook organization.

- [Bookcamp](https://www.bookcamp.app/) for giving us a reason to have awesome audiobook data.