Bookshelf Traveller

A fully featured Audiobookshelf discord bot with playback and administrative functionality. Enjoy your travels! :)

You'll need to create your own discord application in order to do this. This is fairly straightforward; here is a guide:

Create a Discord App - Getting Started

Make sure that you select all intents when setting up your bot and that you have created a URL to add it to your desired discord server.

If you provide the CLIENT_ID environment variable, an invite link will be generated when the bot starts up for you. :)

Note: To find the CLIENT_ID value, go to the discord developer portal, click on OAUTH2, and under client information you'll see the client id.

Ownership by default will allow only you to control the bot. To disable this, use the env variable OWNER_ONLY.

When using commands that use images, i.e. /media_progress or /recent_sessions, the server must use an HTTPS connection due to a requirement from discord's API. If not, no image will be generated.

Important note regarding HTTPS connections: I've experienced a lot of issues when streaming audio from my server to discord using an https connection as the source. I have yet to confirm if this is a double NAT issue, a reverse proxy issue, or otherwise. I suggest you utilize a direct connection to your server, i.e. http://127.0.0.1:13378, if you intend to listen to an audiobook for more than 15 minutes at a time. As a workaround for including images, I've added the OPT_IMAGE_URL env variable. If this is utilized (with an https connection), the bot will use this link for all images instead of the initial server URL.

Troubleshooting

Before reporting an issue, please make sure that you enable DEBUG_MODE=true. You can use this when reporting an issue as it will describe all backend services and any script-related problems.

Environmental Variables

Database Configuration

By default, the bot uses SQLite for local database storage. For production environments or multi-instance deployments, MariaDB/MySQL is supported.

SQLite (Default)

No additional configuration needed. Database files are stored in the db/ directory.

MariaDB/MySQL Setup

1. Create a database and user:

CREATE DATABASE bookshelf CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookshelf_user'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON bookshelf.* TO 'bookshelf_user'@'%';
FLUSH PRIVILEGES;

1. Set the following environment variables:

DB_TYPE=mariadb
DB_HOST=localhost
DB_PORT=3306
DB_USER=bookshelf_user
DB_PASSWORD=your_password
DB_NAME=bookshelf

Installation

Current installation method is by docker container; however, you can also run main.py within a project folder.

Docker Container

Docker Container Available:

Docker Hub

docker pull donkevlar/bookshelf-traveller:latest

GitHub Package Repository

docker pull ghcr.io/donkevlar/bookshelf-traveller:master

To run the container, paste the following command:

docker run -d \
--name bookshelf-traveller \
-e DISCORD_TOKEN="INSERT_TOKEN" \
-e bookshelfToken="INSERT_TOKEN" \
-e bookshelfURL="http://myurl.domain.com" \
-e CLIENT_ID="CLIENTID" \
-e AUDIO_ENABLED="True" \
-e MULTI_USER="false" \
-v ./bookshelf-traveller:/ABSBOT/db \
donkevlar/bookshelf-traveller:latest

or using docker compose:

services:
  bookshelf-traveller:
    image: donkevlar/bookshelf-traveller:latest
    container_name: bookshelf-traveller
    environment:
      - DISCORD_TOKEN=INSERT_TOKEN
      - bookshelfToken=INSERT_TOKEN
      - bookshelfURL=http://myurl.domain.com
    volumes:
      - ./bookshelf-traveller:/ABSBOT/db
    restart: always

Unraid

Visit the community applications (CA) store and search for the template name listed below, click install and insert your discord and ABS tokens respectively and enjoy!

Template Name: Bookshelf-Traveller

Python Script

Requirements: Python 3.10 or above.

FFmpeg must be installed in the project directory and/or in PATH to run audio commands using the script installation method. If this is too difficult, please use the docker instructions above.

FFmpeg

You'll also need a '.env' file for loading the above ENV Variables

Step 1: Navigate to Directory

Open your terminal and navigate to your desired folder.

Step 2: Clone Project

Git clone the project

git clone https://github.com/donkevlar/Bookshelf-Traveller.git

Step 3: Download Dependencies

Windows

pip install -r requirements.txt

Linux Debian/Ubuntu

For all OS options visit Interactions.py

pip install -r requirements.txt

sudo apt install ffmpeg libffi-dev libnacl-dev

Step 4: Start

Make sure that you are in the /Bookshelf-Traveller directory.

python main.py

Bot Commands

The following commands are available:

By default, set up as '/' commands, or a.k.a. app commands Here's the list of commands sorted alphabetically:

Alternative Packages

Audio-only packages have been deprecated. Please use the environmental variables to modify how you would like your bot to function.

Features

/play

Play any of your audiobooks directly in discord! This also works with Xbox or Mobile clients. The bot will automatically sync your progress to your ABS server, and allow you to use multiple users from one place!

Multi-Channel Notifications (/setup-task)

Monitor and track what is added to your ABS server by utilizing the book check tasks. Select which channels you want the notifications to be subscribed to; multiple channel notifications are supported!

/wishlist

Create a customized wishlist, with direct messages so that your other server members can subscribe to see when something they wishlisted gets added.

/recent-sessions

List your most recent sessions.

/mediaprogress

View all of your media's progress at a glance.

Other examples