audiobookshelf-stats-fix

An unofficial script that fixes inflated listening stats in Audiobookshelf (ABS) - those absurd entries like "48h listened in a single day" on the Your Stats heatmap.

This project is not affiliated with the Audiobookshelf developers in any way. It's a database-level patch, not a fix in the application code.

The problem

ABS stores a timeListening field per session in the playbackSessions table, which should reflect the real time spent listening. Under certain conditions (most likely duplicate/overlapping session-sync events from the client, e.g. due to an unstable connection or the app being left in the background) this value can get inflated far beyond reality - in practice, days with a sum exceeding 300+ hours have been observed.

This is a known, recurring issue in ABS itself, documented in:

• advplyr/audiobookshelf#3873 - closed as "not planned"
• advplyr/audiobookshelf#4494

As of writing, there is no official fix in the application.

How the fix works

The script calculates what timeListening should realistically be, based on the playback position delta (currentTime - startTime), hard-capped at the total length of the audiobook (duration). It only corrects sessions where the stored timeListening is clearly (>1.3x) larger than that calculated value, or exceeds the audiobook's duration.

It deliberately does not use wall-clock time (updatedAt - createdAt) as a signal - a session can be left open for hours or days without being closed (e.g. an app left in the background) without any real listening happening, so that signal is unreliable on its own.

Requirements

• Docker (ABS must be running in a container)
• access to the host running Docker (LXC/VM/bare metal)
• the script installs sqlite3 itself, in a disposable temporary Alpine container - nothing needs to be installed manually on the host

Installation

git clone https://github.com/TjomekPL/audiobookshelf-stats-fix.git
cd audiobookshelf-stats-fix
cp config.example.sh config.sh
nano config.sh   # set DB_PATH, CONTAINER_NAME, and the rest for your setup
chmod +x fix-abs-stats.sh

Usage

Preview what would change, without writing anything:

./fix-abs-stats.sh --dry-run

Force the fix now, ignoring the interval:

./fix-abs-stats.sh --force

Normal run (respects MIN_INTERVAL_DAYS from config.sh - if fewer days have passed since the last fix, it exits immediately with no changes):

./fix-abs-stats.sh

Automation (cron)

A server running ABS doesn't need to be up 24/7 - the script tracks on its own when it last ran, so it's enough to trigger it on every opportunity (machine startup + once a day as a fallback), and it will decide on its own whether it's actually time for another fix:

crontab -e

@reboot sleep 120 && /full/path/to/fix-abs-stats.sh
0 4 * * * /full/path/to/fix-abs-stats.sh

Safety

• A database backup is created in BACKUP_DIR before every actual fix (rotation - last 6 backups kept by default).
• If the ABS container is running at fix time, it's briefly stopped (to avoid a write conflict on the same database file) and started again right after.
• Always run --dry-run first after changing the config, to see what would be corrected.

License

MIT

---

Po polsku (skrót)

Nieoficjalny skrypt naprawiający zawyżone statystyki słuchania w Audiobookshelf (znany, nierozwiązany bug - patrz linki do issues wyżej). Liczy realny czas na podstawie pozycji odtwarzania w pliku, ograniczony do długości audiobooka, i koryguje tylko wpisy wyraźnie zawyżone.

Instalacja:

git clone https://github.com/TjomekPL/audiobookshelf-stats-fix.git
cd audiobookshelf-stats-fix
cp config.example.sh config.sh
nano config.sh   # ustaw DB_PATH, CONTAINER_NAME pod swój setup
chmod +x fix-abs-stats.sh

Użycie: ./fix-abs-stats.sh --dry-run (podgląd), --force (wymuszenie), albo bez flag (normalne uruchomienie respektujące interwał MIN_INTERVAL_DAYS).

Cron: dodaj do crontab -e:

@reboot sleep 120 && /pelna/sciezka/do/fix-abs-stats.sh
0 4 * * * /pelna/sciezka/do/fix-abs-stats.sh

Przed każdą naprawą tworzona jest kopia zapasowa bazy, a kontener jest bezpiecznie zatrzymywany i uruchamiany ponownie na czas zapisu.