Files
Server-scripts/audiobook_metadata/metadata_audiobooks_library.py
T

1514 lines
49 KiB
Python
Raw Normal View History

#!/home/lucas/scripts/.venv/bin/python
import argparse
2026-10-25 14:22:43 +01:00
import json
import logging
import re
import sqlite3
2026-10-25 14:22:43 +01:00
import subprocess
import sys
import tempfile
from collections import defaultdict
from concurrent.futures import ThreadPoolExecutor, as_completed
from pathlib import Path
from mutagen import File
from mutagen.id3 import (
COMM,
ID3,
TALB,
TCOM,
TCON,
TIT1,
TIT2,
TPE1,
TPE2,
)
from mutagen.mp4 import MP4, MP4Tags
from mutagen.oggopus import OggOpus
from serverlibrary import (
AUDIO_RE_SUFFIXES,
AUDIO_SUFFIXES,
CustomLogger,
blue_tag,
green_tag,
red_tag,
score_match_jaccard,
setup_logging,
words,
)
ID3_FRAME_CLASSES = {
"TIT2": TIT2,
"TALB": TALB,
"TPE1": TPE1,
"TPE2": TPE2,
"TCON": TCON,
"TCOM": TCOM,
"TIT1": TIT1,
}
2026-10-16 22:05:09 +02:00
logging.setLoggerClass(CustomLogger)
logger: CustomLogger = logging.getLogger(__name__) # type: ignore[assignment]
MP4_MAP = {
"artist": "\xa9ART",
"album": "\xa9alb",
"title": "\xa9nam",
"genre": "\xa9gen",
"comment": "\xa9cmt",
"composer": "\xa9wrt",
"albumartist": "aART",
"grouping": "\xa9grp",
"description": "desc",
}
ID3_MAP = {
"artist": "TPE1",
"album": "TALB",
"title": "TIT2",
"genre": "TCON",
"composer": "TCOM",
"albumartist": "TPE2",
"grouping": "TIT1",
}
metadata_fields = [
"artist",
"album",
"composer",
"comment",
"genre",
"grouping",
"albumartist",
"description",
"title",
]
SEP = r"\s*[-_:,.]+\s*"
series_patterns = [
rf"^(\d+){SEP}(.+)$",
rf"^(.+?){SEP}(\d+)$",
rf"^(.+?){SEP}(?:Book|Band|Volume)\s+(\d+)(?:{SEP}(.+))$",
]
2026-10-25 14:22:43 +01:00
def ffmpeg_escape(path: Path) -> str:
return str(path.resolve()).replace("'", r"'\''")
2026-10-25 14:22:43 +01:00
def clean_genre(genre):
if not genre:
return ""
genre_old = genre
# genre = genre.lower()
2026-10-25 14:22:43 +01:00
genre = re.sub(r"(?i)^audio\s*books?$", "", genre)
genre = re.sub(r"(?i)^audiobooks?;?$", "", genre)
genre = re.sub(r"(?i)\b(hörb(uch|ücher)|hoerb(uch|uecher))\b", "", genre)
genre = re.sub(r"(?i)^(hörspiele?|hoerspiele?)$", "", genre)
genre = re.sub(r"(?i)^spoken\s*word$", "", genre)
genre = re.sub(r"(?i)gesprochene\s*inhalte$", "", genre)
genre = re.sub(r"(?i)^speech$", "", genre)
genre = re.sub(r"Fanasie", "Fantasie", genre)
genre = re.sub(r"Mit Videospiel-?", "Videospielbezug", genre)
genre = re.sub(r"(?i)nonfiction", "NonFiction", genre)
genre = re.sub(r"(?i)^speech$", "", genre)
genre = re.sub(r"(?i)^vocal$", "", genre)
genre = re.sub(r"(?i)^retail$", "", genre)
genre = re.sub(r"(?i)^other$", "", genre)
genre = re.sub(r"(?i)^misc$", "", genre)
genre = re.sub(r"(?i)^(sci[- ]?fi|sf)$", "Science Fiction", genre)
genre = re.sub(r"(?i)^\(?science fiction\)?$", "Science Fiction", genre)
genre = re.sub(r"Thrillers", "Thriller", genre)
genre = re.sub(r"(?i)\bchildren'?s audiobooks?\b", "", genre)
genre = re.sub(r"^-\s*|\s*-$", "", genre)
genre = re.sub(r"(?i)Engelske\s*\sLydbånd", "", genre)
genre = re.sub(r"^FIC028000.*$", "", genre)
genre = re.sub(r"^800.*$", "", genre)
genre = re.sub(r"^Fantastic Beasts.*$", "", genre)
genre = re.sub(r"^and thei.*$", "", genre)
genre = re.sub(r"^those you.*$", "", genre)
# Normalize separators
genre = re.sub(r"\s*[,:/]\s*", ";", genre)
genre = re.sub(r"\s*;\s*", "; ", genre)
# Trim punctuation / whitespace
genre = re.sub(r"^[\s,;:\-]+", "", genre)
genre = re.sub(r"[\s,;\-]+$", "", genre)
genre = genre.strip()
genre = genre.lstrip()
if genre != genre_old:
logger.debug(f"Update genre from {genre_old} to {genre}")
2026-10-25 14:22:43 +01:00
return genre
2026-10-16 17:44:37 +02:00
def ffmetadata_escape(value: str) -> str:
return (
2026-10-25 14:22:43 +01:00
value.replace("\\", "\\\\")
2026-10-16 17:44:37 +02:00
.replace("=", "\\=")
.replace(";", "\\;")
.replace("#", "\\#")
.replace("\n", "\\\n")
)
2026-10-16 17:44:37 +02:00
def get_chapters(media: Path) -> list[dict]:
result = subprocess.run(
[
"ffprobe",
2026-10-25 14:22:43 +01:00
"-v",
"error",
2026-10-16 17:44:37 +02:00
"-show_chapters",
2026-10-25 14:22:43 +01:00
"-of",
"json",
2026-10-16 17:44:37 +02:00
str(media),
],
capture_output=True,
text=True,
check=True,
)
data = json.loads(result.stdout)
return data.get("chapters", [])
def _to_str(value) -> str:
if value is None:
return ""
if hasattr(value, "text"):
value = value.text
if isinstance(value, (list, tuple)):
return "; ".join(str(v) for v in value)
return str(value)
def get_metadata_all(file: Path) -> dict[str, str]:
metadata = dict.fromkeys(metadata_fields, "")
try:
audio = File(file)
if audio is None or audio.tags is None:
return metadata
# MP4/M4A/M4B
if isinstance(audio.tags, MP4Tags):
for field, tag in MP4_MAP.items():
value = audio.tags.get(tag)
if value:
metadata[field] = _to_str(value)
# ID3 (MP3 or mislabeled .m4b)
elif isinstance(audio.tags, ID3):
for field, frame_id in ID3_MAP.items():
frame = audio.tags.get(frame_id)
if frame:
metadata[field] = _to_str(frame)
comments = audio.tags.getall("COMM")
if comments:
metadata["comment"] = _to_str(comments[0])
# Optional fallback
if not metadata["description"]:
metadata["description"] = metadata["comment"]
# FLAC / Opus / Vorbis
else:
for field in metadata_fields:
value = audio.tags.get(field)
if value:
metadata[field] = _to_str(value)
except Exception:
logger.exception(f"Error getting metadata for {file}")
return metadata
def write_metadata(file, fields, values, dry_run=False):
changes = {
field.lower().replace(" ", ""): str(value)
for field, value in zip(fields, values)
}
logger.debug(f"Writing metadata for {file}: {changes}")
if dry_run:
2026-10-25 14:22:43 +01:00
return
try:
suffix = file.suffix.lower()
# MP3 / ID3
if suffix == ".mp3":
tags = ID3(file)
for field, value in changes.items():
if field == "comment":
tags.delall("COMM")
if value:
tags.add(
COMM(
encoding=3,
lang="eng",
desc="",
text=[value],
)
)
continue
frame_id = ID3_MAP.get(field)
if not frame_id:
continue
tags.delall(frame_id)
if value:
frame_cls = ID3_FRAME_CLASSES[frame_id]
tags.add(frame_cls(encoding=3, text=[value]))
tags.save(file)
# M4A / M4B / MP4
elif suffix in {".m4a", ".m4b", ".mp4"}:
tags = MP4(file)
for field, value in changes.items():
mp4_key = MP4_MAP.get(field)
if not mp4_key:
logger.debug(f"Unsupported MP4 tag: {field}")
continue
if value:
tags[mp4_key] = [value]
else:
tags.pop(mp4_key, None)
tags.save()
# Opus
elif suffix == ".opus":
tags = OggOpus(file)
for field, value in changes.items():
if value:
tags[field] = [value]
else:
tags.pop(field, None)
tags.save()
else:
logger.warning(f"Unsupported file type: {file}")
except Exception:
logger.exception(f"Error writing metadata for {file}")
2026-10-16 17:44:37 +02:00
def get_duration_ms(media: Path) -> int:
duration = subprocess.check_output(
[
"ffprobe",
"-v",
"error",
"-show_entries",
"format=duration",
"-of",
"default=noprint_wrappers=1:nokey=1",
str(media),
],
text=True,
).strip()
return int(float(duration) * 1000)
def normalize_name(name: str, series: str) -> str:
# Remove anything in (), [], {}
name_out = ""
# name = re.sub(
# rf"^(?:{re.escape(series)}){SEP}|{SEP}(?:{re.escape(series)})$",
# "", name, flags=re.IGNORECASE, ).strip()
name = re.sub(r"\s*[(\[{].*?[)\]}]\s*", " ", name).strip()
name = re.sub(r"\s+", " ", name)
for pattern in series_patterns:
match = re.match(pattern, name, re.IGNORECASE)
if match:
if pattern.startswith(r"^(\d+)"):
name_out = match.group(2).strip()
else:
name_out = match.group(1).strip()
break
else:
name_out = name
pattern = rf"^(.+?){SEP}(?:Book|Band|Volume)\s+(\d+){SEP}(.+)$"
match = re.match(pattern, name, re.IGNORECASE)
if match:
name_out1 = match.group(1).strip()
name_out3 = match.group(3).strip()
if score_match_jaccard(words(name_out1), words(series)) > score_match_jaccard(
words(name_out3), words(series)
):
return name_out3
else:
return name_out1
return name_out
2026-10-25 14:22:43 +01:00
def cleanup(text: str) -> str:
# Collapse repeated punctuation groups like ", ,", ". .", "! !", "? ?"
while True:
new_text = re.sub(r"([.,!?;:-])(?:\s+\1)+", r"\1", text)
2026-10-25 14:22:43 +01:00
if new_text == text:
break
text = new_text
# Optional: normalize multiple spaces
text = re.sub(r"\s{2,}", " ", text)
2026-10-25 14:22:43 +01:00
return text.strip()
def get_empty_keys(data: dict) -> str:
empty_keys = [str(key) for key, value in data.items() if not value]
return f"Empty: {', '.join(empty_keys)}" if empty_keys else ""
def get_codec_bitrate(file: Path | None) -> tuple[str, str]:
if not file:
raise ValueError
info = json.loads(
subprocess.check_output(
[
"ffprobe",
"-v",
"error",
"-select_streams",
"a:0",
"-show_entries",
"stream=codec_name,bit_rate",
"-of",
"json",
str(file),
],
text=True,
)
)
stream = info["streams"][0]
bitrate = int(stream.get("bit_rate") or 128000)
bitrate_k = f"{bitrate // 1000}k"
return stream["codec_name"].lower(), bitrate_k # codec, bits/s
2026-10-25 14:22:43 +01:00
class Audiobook:
def __init__(self, book_path: Path, library_root_path: Path) -> None:
self.action_required = False
2026-10-25 14:22:43 +01:00
self.changed = None
# Metadata
self.metadata = {}
self.metadata_original = {}
2026-10-25 14:22:43 +01:00
self.artist = ""
self.genre = ""
self.composer = ""
self.name = ""
self.comment = ""
self.description = ""
self.series_and_num = ""
self.series = ""
self.series_num = ""
self.title: str = ""
self.title_list: list = []
# File Paths
2026-10-25 14:22:43 +01:00
self.files: list[Path] = []
self.files_extra = []
2026-10-16 22:05:09 +02:00
self.bookPath = book_path
2026-10-25 14:22:43 +01:00
self.library_root_path = library_root_path
self.firstFile: Path | None = None
self.pdf_file = None
self.epub_file = None
# Files
self.singleFile = False
self.fileConunt = 0
self.size = 0
2026-10-25 14:22:43 +01:00
def init_book(self) -> None:
self.files = sorted(
(
file
for file in self.bookPath.iterdir()
if file.is_file() and file.suffix.lower() in AUDIO_SUFFIXES
),
key=self.extract_track_number,
)
epubs = list(self.bookPath.glob("*.epub"))
self.epub_file = epubs[0] if len(epubs) == 1 else None
pdfs = list(self.bookPath.glob("*.pdf"))
self.pdf_file = pdfs[0] if len(pdfs) == 1 else None
self.files_extra = [
file
for file in self.bookPath.glob("*")
if file.suffix.lower() not in AUDIO_SUFFIXES
]
self.firstFile = self.get_first_file()
2026-10-25 14:22:43 +01:00
self.size = sum(
file.stat().st_size
for pattern in AUDIO_RE_SUFFIXES
2026-10-25 14:22:43 +01:00
for file in self.bookPath.glob(pattern)
)
self.fileConunt = len(self.files)
2026-10-16 22:05:09 +02:00
self.singleFile = self.fileConunt == 1
# Metadata
2026-10-16 17:44:37 +02:00
self.load_metadata()
logger.info(
f"Found {self.bookPath.name}, {self.fileConunt} files, {get_empty_keys(self.metadata)}"
)
2026-10-16 22:05:09 +02:00
self.changed = False
def __repr__(self):
return (
f"Audiobook("
f"name={self.name!r}, "
f"artist={self.artist!r}, "
f"composer={self.composer!r}, "
f"path={str(self.bookPath)!r}),"
f"size={self.size!r}, "
f"fileConunt={self.fileConunt!r}, "
)
2026-10-25 14:22:43 +01:00
def get_first_file(self) -> Path:
return self.files[0]
2026-10-25 14:22:43 +01:00
def write_fields_from_metadata(self) -> None:
self.name = self.metadata["album"]
self.title = self.metadata["title"]
2026-10-25 14:22:43 +01:00
self.composer = self.metadata["composer"]
self.comment = self.metadata["comment"]
self.genre = self.metadata["genre"]
if "#" in self.metadata["grouping"]:
self.series, self.series_num = self.metadata["grouping"].rsplit("#", 1)
self.series = self.series.strip()
self.series_and_num = self.metadata["grouping"]
if self.metadata.get("artist"):
self.artist = self.metadata["artist"].strip()
elif self.metadata.get("albumartist"):
self.artist = self.metadata.get("albumartist")
2026-10-25 14:22:43 +01:00
self.description = self.metadata["description"]
def write_metadata_from_fields(self):
self.metadata["album"] = self.name
self.metadata["title"] = self.title
2026-10-25 14:22:43 +01:00
self.metadata["composer"] = self.composer
self.metadata["genre"] = self.genre
self.metadata["grouping"] = self.series_and_num
2026-10-25 14:22:43 +01:00
self.metadata["comment"] = self.comment
self.metadata["description"] = self.description
if self.artist:
self.metadata["artist"] = self.artist
self.metadata["albumartist"] = self.artist
2026-10-25 14:22:43 +01:00
def extract_track_number(self, file: Path) -> int:
stem = file.stem
title = self.name
# Remove title if it appears at the beginning
if title:
escaped_title = re.escape(title)
stem = re.sub(
rf"^{escaped_title}(?:\s*[-_:]\s*)?",
"",
stem,
flags=re.IGNORECASE,
).strip()
patterns = [
# 0099_Apollo, 01 Title, 001 Chapter, 02GLCK~1.WMA
r"^(\d+)(?=\D|$)",
# CD1-01, CD 1 - 01, CD1 - 01.
r"CD\s*(\d+)\s*-\s*(\d{1,3})",
# 018-01, 018 - 01, 138-01, 0001-0999
r"^(\d+)\s*-\s*(\d+)(?:\D|$)",
# Track 01
r"Track\s+(\d+)$",
# 01 - Kapitel 01
r"^(\d+)\s*-",
# Rubinrot 101, 102, 201, 202
r".*?(\d)(\d{2})$",
# A Thousand Ships - 007
r".*?-\s*(\d+)\s*$",
]
for pattern in patterns:
m = re.search(pattern, stem, re.IGNORECASE)
if not m:
continue
groups = m.groups()
if len(groups) == 1:
return int(groups[0])
if len(groups) == 2 and "CD" in pattern:
disc = int(groups[0])
track = int(groups[1])
return (disc - 1) * 1000 + track
if len(groups) == 2 and stem.startswith(groups[0]):
disc = int(groups[0])
track = int(groups[1])
if track < 100:
return disc * 1000 + track
if len(groups) == 2 and len(groups[0]) == 1:
disc = int(groups[0])
track = int(groups[1])
return disc * 1000 + track
return int(groups[-1])
return 0
2026-10-16 17:44:37 +02:00
def load_metadata(self):
self.metadata = get_metadata_all(self.get_first_file())
self.metadata_original = self.metadata.copy()
2026-10-25 14:22:43 +01:00
self.write_fields_from_metadata()
logger.trace(f"Load metadata {self.metadata}")
def fix_artist_dir(self):
rel_path = self.bookPath.relative_to(self.library_root_path).parts
if not self.artist:
logger.trace(f"No artist tag for {self.name}")
return
if len(rel_path) < 2:
desired_path, desired_name = self.generate_dir_from_metadata()
self.move(desired_path, desired_name)
logger.debug(f"Artist not visible in folder structure: {rel_path}")
2026-10-25 14:22:43 +01:00
def fix_artist_from_comment(self):
if not isinstance(self.comment, str):
logger.trace(f"No comment for {self.name}")
return
2026-10-16 22:05:09 +02:00
m = re.search(
2026-10-25 14:22:43 +01:00
r"(?:"
r"author(?:s)?:?|"
r"writer(?:s)?:?|"
r"co[- ]?author(?:s)?:?|"
r"co[- ]?writer(?:s)?:?|"
r"creator(?:s)?:?|"
r"contributor(?:s)?:?|"
r"composer(?:s)?:?|"
r"lyricist(?:s)?:?|"
r"songwriter(?:s)?:?|"
r"written\s+by:?|"
r"story\s+by:?|"
r"autorin(?:nen)?:?|"
r"autor\(en\):?|"
r"autor(?:en)?:?|"
r"text(?:e)?\s+von:?|"
r"geschrieben\s+von:?|"
r"verfasst\s+von:?|"
r"auteur(?:s)?:?|"
r"autore(?:i)?:?|"
r"autor(?:es)?:?|"
r"escritor(?:es|as)?:?"
r")\s*:?\s*([^\n.,;]+)",
2026-10-16 22:05:09 +02:00
self.comment,
re.IGNORECASE,
)
if not m:
logger.trace(f"No artist found in comment for {self.bookPath}")
2026-10-16 22:05:09 +02:00
return
if len(m.group(1).strip()) < 5:
logger.debug(f"Match group {m.group(1)} found but discarded")
return
logger.trace(f"Match groups: {m.group()}, Book: {self.name}")
2026-10-25 14:22:43 +01:00
self.changed = True
artist = re.sub(r"\s*\([^)]*\)", "", m.group(1).strip()).strip()
logger.trace(f"Remove {artist} from comment: {self.comment}")
self.comment = (self.comment[: m.start()] + self.comment[m.end() :]).strip(
" .,;\n"
)
self.comment = cleanup(self.comment)
2026-10-25 14:22:43 +01:00
if not self.artist:
self.artist = artist
self.changed = True
2026-10-25 14:22:43 +01:00
elif self.artist != artist:
logger.warning(
f"{red_tag('Action Required')} artist {artist} found not matching {self.artist} for {self.bookPath}"
2026-10-25 14:22:43 +01:00
)
self.action_required = True
2026-10-25 14:22:43 +01:00
else:
logger.debug(f"Artist {artist} matches file metadata for {self.name}")
def fix_artist_from_path(self, force_artist_from_path):
rel_path = self.bookPath.relative_to(self.library_root_path).parts
if len(rel_path) < 2:
logger.trace(f"Artist not visible in folder structure: {rel_path}")
return
if self.artist == rel_path[0]:
return
if not self.artist or force_artist_from_path:
self.changed = True
2026-10-25 14:22:43 +01:00
self.artist = rel_path[0]
logger.info(
f"[Updated] artist {self.artist} found in path for {self.bookPath}"
)
2026-10-25 14:22:43 +01:00
def fix_composer_from_narrator(self):
if not self.metadata.get("narrator"):
logger.trace(f"No Narrator found in metadata for {self.name}")
return
if not self.composer or len(self.composer) < 5:
self.composer = self.metadata["narrator"]
2026-10-25 14:22:43 +01:00
def fix_composer_from_comment(self):
m = re.search(
r"(?:read\s+by:?|"
r"spoken\s+by:?|"
r"erzähler:?|"
2026-10-25 14:22:43 +01:00
r"narrated\s+by:?|"
r"gesprochen\s+von:?|"
r"gelesen\s+von)\s+([^\n.,;]+)",
self.comment,
re.IGNORECASE,
)
if not m:
logger.trace(f"No composer found in comment for {self.name}")
2026-10-25 14:22:43 +01:00
return
self.changed = True
self.comment = (self.comment[: m.start()] + self.comment[m.end() :]).strip(
" .,;\n"
)
self.comment = cleanup(self.comment)
if not self.composer or len(self.composer) < 5:
2026-10-25 14:22:43 +01:00
logger.info(f"[Updated] composer found in comment for {self.name}")
self.composer = str(m.group(1).strip())
2026-10-16 22:05:09 +02:00
2026-10-25 14:22:43 +01:00
def fix_composer_from_path(self):
rel_path = self.bookPath.relative_to(self.library_root_path)
m = re.search(
r"(?:read\s+by:?|"
r"spoken\s+by:?|"
r"narrated\s+by:?|"
r"gesprochen\s+von:?|"
r"gelesen\s+von)\s+([^\n.,;]+)",
str(rel_path),
re.IGNORECASE,
)
if not m:
logger.trace(f"No composer found in path for {self.bookPath}")
return
if not self.composer or len(self.composer) < 5:
2026-10-25 14:22:43 +01:00
self.changed = True
logger.info(f"[Updated] composer found in Path for {self.bookPath}")
self.composer = str(m.group(1).strip())
2026-10-16 17:44:37 +02:00
def fix_name(self):
if not self.name:
self.name = normalize_name(self.bookPath.name, self.series)
self.changed = True
logger.info(f"[Updated] name {self.name} found in path for {self.bookPath}")
return
name = normalize_name(self.name, self.series)
if name != self.name:
logger.info(f"[Updated] name by cleaning {self.name} to {name}")
self.name = name
self.changed = True
2026-10-25 14:22:43 +01:00
def fix_series(self):
if self.series_and_num:
logger.trace(f"{self.name} already has series: {self.series_and_num}")
2026-10-25 14:22:43 +01:00
rel_path = self.bookPath.relative_to(self.library_root_path).parts
number = ""
2026-10-25 14:22:43 +01:00
if len(rel_path) <= 2:
logger.trace(f"No series found for {self.name}")
return
for i, pattern in enumerate(series_patterns):
2026-10-25 14:22:43 +01:00
match = re.match(pattern, rel_path[2], re.IGNORECASE)
if not match:
continue
if i == 0:
number = match.group(1)
elif i == 1:
number = match.group(2)
else:
number = match.group(2) or match.group(3)
break
number_str = ""
and_number = ""
2026-10-25 14:22:43 +01:00
if not number:
logger.trace(f"No series number found for {self.name}")
else:
number_str = " #" + number
and_number = " and number"
self.series_num = number
if self.series_and_num != rel_path[1] + number_str:
self.series_and_num = rel_path[1] + number_str
self.series = rel_path[1]
self.changed = True
logger.info(
f"[Updated] series{and_number} found for {self.name} to {self.series_and_num}"
)
return
2026-10-25 14:22:43 +01:00
def fix_genre(self):
self.genre = clean_genre(self.genre)
self.changed = True
def move(self, desired_path: Path, desired_name_stem: str, dry_run=False):
logger.trace(f"Moving {self.bookPath} to {desired_path}")
desired_path.mkdir(parents=True, exist_ok=True)
padding = len(str(len(self.files)))
2026-10-31 09:26:58 +01:00
once = True
for number, file in enumerate(self.files, start=1):
if self.singleFile:
new_name = desired_path / f"{desired_name_stem}{file.suffix.lower()}"
else:
new_name = (
desired_path
/ f"{number:0{padding}d} - {desired_name_stem}{file.suffix}"
)
if file == new_name:
continue
2026-10-31 09:26:58 +01:00
if once:
once = False
logger.debug(f"Moving {file} to {new_name}")
else:
logger.trace(f"Moving {file} to {new_name}")
if dry_run:
continue
self.files[number - 1] = file.rename(new_name)
for file in self.files_extra:
if file.suffix.lower() in {".cue", ".log"} or file in {
self.epub_file,
self.pdf_file,
}:
filename = f"{desired_name_stem}{file.suffix.lower()}"
else:
filename = file.name
new_file = desired_path / filename
if file == new_file:
continue
2026-10-31 09:26:58 +01:00
logger.trace(f"Moving {file} to {new_file}")
if dry_run:
continue
new_file = file.rename(new_file)
if file == self.epub_file:
self.epub_file = new_file
elif file == self.pdf_file:
self.pdf_file = new_file
2026-10-25 14:22:43 +01:00
if self.bookPath != desired_path:
logger.debug(f"Moving {self.bookPath} to {desired_path}")
remaining = list(self.bookPath.iterdir())
if not remaining and not dry_run:
self.bookPath.rmdir()
else:
logger.warning(
f"{red_tag('Action Required')} old path not empty after move: "
f"{self.bookPath}: {remaining}"
)
self.bookPath = desired_path
self.files = sorted(self.files, key=self.extract_track_number)
self.firstFile = self.get_first_file()
2026-10-25 14:22:43 +01:00
def generate_dir_from_metadata(self):
composer = ""
2026-10-25 14:22:43 +01:00
name = self.name
if self.composer:
composer = f" (by {self.composer})"
name = self.name + composer
artist = ""
if self.artist:
artist = re.split(r"[,;]", self.artist)[0].strip().replace("/", "_")
desired_path = self.library_root_path / artist / name
if self.series_and_num:
series = self.series_and_num
number = ""
if "#" in self.series_and_num:
series = self.series_and_num.split("#")
number = f"{series[1]} - "
series = series[0].rstrip()
desired_path = (
self.library_root_path
/ artist
/ series.replace("/", "_")
/ f"{number}{name}".replace("/", "_")
)
desired_name_stem = (
f"{self.artist} - {self.name}{composer}{self.bookPath.suffix}"
)
desired_name_stem = desired_name_stem.replace("/", "_")
return desired_path, desired_name_stem
2026-10-25 14:22:43 +01:00
def create_m4b_from_book(self, creat_m4b_no_delete: bool = False) -> None:
output_file_final = self.bookPath / f"{self.bookPath.name}.m4b"
if self.action_required:
logger.warning("Action required, resolve before creating m4b file")
return
if output_file_final.exists():
logger.info(f"{red_tag('SKIP')} {output_file_final}")
logger.info("Book already present")
return
logger.info(f"{blue_tag('create')} {output_file_final}")
2026-10-25 14:22:43 +01:00
with tempfile.TemporaryDirectory(dir=self.library_root_path.parent) as tmp:
tmpdir = Path(tmp)
output_file_tmp = tmpdir / f"{self.bookPath.name}.m4b"
concat_file = tmpdir / "concat.txt"
metadata_file = tmpdir / "chapters.txt"
2026-10-16 17:44:37 +02:00
# Inspect all inputs before deciding how to create chapters.
file_info = []
has_existing_chapters = False
for media in self.files:
chapters = get_chapters(media)
duration_ms = get_duration_ms(media)
2026-10-25 14:22:43 +01:00
file_info.append(
{
"media": media,
"chapters": chapters,
"duration_ms": duration_ms,
}
)
2026-10-16 17:44:37 +02:00
if chapters:
has_existing_chapters = True
if has_existing_chapters:
logger.debug(
2026-10-16 17:44:37 +02:00
"Existing chapter tracks found; preserving chapter metadata"
)
else:
logger.debug(
2026-10-16 17:44:37 +02:00
"No existing chapters found; generating chapters from filenames"
)
current_ms = 0
2026-10-16 17:44:37 +02:00
with (
concat_file.open("w", encoding="utf-8") as cf,
metadata_file.open("w", encoding="utf-8") as mf,
):
mf.write(";FFMETADATA1\n")
2026-10-25 14:22:43 +01:00
2026-10-16 22:05:09 +02:00
for key, value in self.metadata.items():
if key == "title":
mf.write(
f"{ffmetadata_escape(key)}={ffmetadata_escape(self.metadata['album'])}\n"
)
else:
mf.write(
f"{ffmetadata_escape(key)}={ffmetadata_escape(value)}\n"
)
2026-10-16 17:44:37 +02:00
for info in file_info:
media = info["media"]
media_name = info["media"].name
# Remove title
media_name = media_name.replace(self.name, "")
# Clean separators and whitespace
media_name = re.sub(r"[\s._-]+", " ", media_name).strip()
# Remove leading/trailing separators again if needed
media_name = re.sub(r"^[\s._-]+|[\s._-]+$", "", media_name)
info["media"].with_name(media_name)
2026-10-16 17:44:37 +02:00
chapters = info["chapters"]
duration_ms = info["duration_ms"]
cf.write(f"file '{ffmpeg_escape(media)}'\n")
2026-10-16 17:44:37 +02:00
if has_existing_chapters:
# Preserve actual chapter boundaries and titles.
for chapter in chapters:
2026-10-25 14:22:43 +01:00
start_ms = round(float(chapter["start_time"]) * 1000)
end_ms = round(float(chapter["end_time"]) * 1000)
2026-10-16 17:44:37 +02:00
tags = chapter.get("tags", {})
title = tags.get("title", media.stem)
mf.write("[CHAPTER]\n")
mf.write("TIMEBASE=1/1000\n")
mf.write(f"START={current_ms + start_ms}\n")
mf.write(f"END={current_ms + end_ms}\n")
2026-10-25 14:22:43 +01:00
mf.write(f"title={ffmetadata_escape(title)}\n")
2026-10-16 17:44:37 +02:00
else:
# No input contains chapters: one chapter per file.
mf.write("[CHAPTER]\n")
mf.write("TIMEBASE=1/1000\n")
mf.write(f"START={current_ms}\n")
mf.write(f"END={current_ms + duration_ms}\n")
2026-10-25 14:22:43 +01:00
mf.write(f"title={ffmetadata_escape(media.stem)}\n")
current_ms += duration_ms
codec, bitrate_k = get_codec_bitrate(self.firstFile)
codec_args = ["-c:a", "copy"]
if codec == "mp3":
codec_args = ["-c:a", "aac", "-b:a", bitrate_k]
elif codec == "flac":
codec_args = ["-c:a", "alac", "-b:a", bitrate_k]
elif codec not in {"aac", "alac"}:
codec_args = ["-c:a", "aac", "-b:a", bitrate_k]
cmd = [
2026-10-25 14:22:43 +01:00
"ffmpeg",
"-y",
"-f",
"concat",
"-safe",
"0",
"-i",
str(concat_file),
"-i",
str(metadata_file),
"-i",
str(self.firstFile),
2026-10-16 22:05:09 +02:00
# audio from concat
2026-10-25 14:22:43 +01:00
"-map",
"0:a",
2026-10-16 22:05:09 +02:00
# cover image from first media
2026-10-25 14:22:43 +01:00
"-map",
"2:v?",
2026-10-16 22:05:09 +02:00
# Metadata and chapters from our generated FFMETADATA file
2026-10-25 14:22:43 +01:00
"-map_metadata",
"1",
"-map_chapters",
"1",
*codec_args,
2026-10-25 14:22:43 +01:00
"-c:v",
"copy",
"-disposition:v:0",
"attached_pic",
2026-10-16 17:44:37 +02:00
str(output_file_tmp),
]
result = subprocess.run(
cmd,
capture_output=True,
text=True,
check=True,
)
logger.trace(result.stdout)
if result.returncode == 0:
output_file_tmp.rename(output_file_final)
for media in self.files:
2026-10-16 17:44:37 +02:00
if creat_m4b_no_delete:
continue
media.unlink()
2026-10-25 14:22:43 +01:00
self.files = [output_file_final]
self.firstFile = output_file_final
self.fileConunt = 1
self.singleFile = True
2026-10-16 22:05:09 +02:00
self.changed = False
self.size = Path(output_file_final).stat().st_size
2026-10-25 14:22:43 +01:00
logger.info(
f"{green_tag('SUCCESS')} - {self.bookPath.name} - delete media files"
2026-10-25 14:22:43 +01:00
)
else:
logger.error(
f"{red_tag('ERROR')} - {self.bookPath.name} - Code: {result.returncode}, Stderr: {result.stderr}"
2026-10-25 14:22:43 +01:00
)
2026-10-25 14:22:43 +01:00
def write_metadata(self, keys=None, dry_run=False):
if self.action_required:
logger.warning("Action required, resolve before writing metadata file")
return
2026-10-25 14:22:43 +01:00
self.write_metadata_from_fields()
if keys is None:
keys = []
for key, value in self.metadata.items():
if self.metadata_original.get(key) != value and not isinstance(
value, list
):
keys.append(key)
self.metadata_original = self.metadata.copy()
values = [self.metadata[key] for key in keys]
if (not keys or not values) and self.metadata_original.get(
"title"
) != self.title:
logger.trace(f"Nothing to write to file for {self.name}")
return
if keys:
for file in self.files:
write_metadata(file, keys, values, dry_run)
if len(self.title_list) == len(self.files):
for title, file in zip(self.title_list, self.files):
write_metadata(file, ["title"], [title], dry_run)
2026-10-25 14:22:43 +01:00
self.changed = False
def fix_title(self):
if not self.title:
if self.singleFile:
self.title = self.name
else:
padding = len(str(len(self.files)))
for idx, file in enumerate(self.files):
self.title_list.append(f"{self.name} - {idx + 1:0{padding}d}")
class AudiobookLibrary:
2026-10-25 14:22:43 +01:00
def __init__(
self,
library_path: Path,
sql_database_path: Path,
dry_run: bool,
path_filter: str = "",
logfilename: str = "audiobook_library.log",
2026-10-25 14:22:43 +01:00
):
self.path_filter = path_filter
2026-10-25 14:22:43 +01:00
self.sql_database_instance = self.SqlDatabase(sql_database_path)
2026-10-16 22:05:09 +02:00
self.dry_run = dry_run
logging.setLoggerClass(CustomLogger)
logger: CustomLogger = logging.getLogger(__name__) # type: ignore[assignment]
2026-10-25 14:22:43 +01:00
logger.info("Started")
self.libraryPath: Path = Path(library_path)
self.audiobooks: list[Audiobook] = []
self._by_path = {}
self._by_name = defaultdict(list)
self._by_artist = defaultdict(list)
self._by_composer = defaultdict(list)
2026-10-16 22:05:09 +02:00
self.load_audiobooks_from_dir()
2026-10-25 14:22:43 +01:00
self.size = sum(
audiobook.size for audiobook in self.audiobooks
) # size in bytes
class SqlDatabase:
def __init__(self, sql_database_path: Path):
self.tables = []
self.data = {}
2026-10-25 14:22:43 +01:00
self.db = None
self.path = sql_database_path
self.books = []
def connect(self):
if not self.path.is_file():
2026-10-25 14:22:43 +01:00
logger.error(f"{self.path} does not exist")
raise FileExistsError
2026-10-25 14:22:43 +01:00
self.db = sqlite3.connect(self.path)
self.db.row_factory = sqlite3.Row
return True
def cursor(self):
if not self.db:
raise ValueError
2026-10-25 14:22:43 +01:00
return self.db.cursor()
def commit(self):
if not self.db:
raise ValueError
2026-10-25 14:22:43 +01:00
self.db.commit()
def close(self):
if not self.db:
raise ValueError
2026-10-25 14:22:43 +01:00
self.db.close()
def init(self):
if not self.connect():
return False
2026-10-25 14:22:43 +01:00
return self.load_database_data()
2026-10-25 14:22:43 +01:00
def load_database_data(self) -> bool:
if not self.db:
raise ValueError
self.tables = self.db.execute(
"SELECT name FROM sqlite_master WHERE type='table'"
).fetchall()
for table in self.tables:
table_name = table["name"]
rows = []
for row in self.db.execute(f'SELECT * FROM "{table_name}"'):
record = dict(row)
# Auto-decode JSON columns
for key, value in record.items():
if isinstance(value, str) and value[:1] in "[{":
try:
record[key] = json.loads(value)
except json.JSONDecodeError:
pass
2026-10-25 14:22:43 +01:00
rows.append(record)
2026-10-25 14:22:43 +01:00
self.data[table_name] = rows
self.books = self.data["books"]
return True
2026-10-25 14:22:43 +01:00
def update_books(self):
for book in self.books:
self._save_book(book)
def _save_book(self, book):
book = book.copy()
for key, value in book.items():
if isinstance(value, (list, dict)):
book[key] = json.dumps(value, ensure_ascii=False)
columns = [c for c in book if c != "id"]
sql = f"""
UPDATE books
SET {", ".join(f'"{c}" = ?' for c in columns)}
WHERE id = ?
"""
values = [book[c] for c in columns]
values.append(book["id"])
if not self.db:
raise ValueError
2026-10-25 14:22:43 +01:00
self.db.execute(sql, values)
# commit once after all updates
def fix_genres(self):
for book in self.books:
genres = book.get("genres")
if not genres or not any(g.strip() for g in genres):
continue
new_genres = []
for genre in genres:
genre = clean_genre(genre)
if "," in genre:
genre = genre.split(",")
elif ";" in genre:
genre = genre.split(";")
elif " - " in genre:
genre = genre.split(" - ")
elif "Historical Adventure Thriller Mystery" in genre:
genre = genre.split(" ")
2026-10-25 14:22:43 +01:00
if isinstance(genre, str):
if len(genre) > 50 or (5 > len(genre) > 0):
genre = ""
logger.trace(f"Too long or too short: {genre}")
genre = genre.strip()
genre = genre.lstrip()
new_genres.append(genre)
elif isinstance(genre, list):
if len(genres) > 1:
genres = [g.strip() for g in genre if g]
logger.trace(f"REPR: {repr(genres)}")
logger.trace(f"GENRES: {genres}")
new_genres.extend(genre)
2026-10-25 14:22:43 +01:00
new_genres = sorted(set(new_genres))
logger.trace(f"{new_genres}")
list_difference = False
if len(new_genres) < len(genres):
2026-10-25 14:22:43 +01:00
list_difference = True
for old, new in zip(genres, new_genres):
if old != new:
list_difference = True
break
2026-10-25 14:22:43 +01:00
if not list_difference:
logger.trace("No difference: Dont Commit to Database")
continue
2026-10-25 14:22:43 +01:00
logger.debug(f"{genres} -> {new_genres}")
book["genres"] = new_genres
2026-10-25 14:22:43 +01:00
def fix_comments(self):
for book in self.books:
for file in book.get("audioFiles"):
comment = file.get("metaTags").get("tagComment")
if comment and len(comment) < 40:
logger.debug(f"Fix short comment for {book.get('title')}")
comment = ""
file["metaTags"]["tagComment"] = comment
def add(self, book: Audiobook):
self.audiobooks.append(book)
self._by_path[book.bookPath] = book
self._by_name[book.name].append(book)
if book.artist:
self._by_artist[book.artist].append(book)
if book.composer:
self._by_composer[book.composer].append(book)
2026-10-16 22:05:09 +02:00
def print_name(self, books):
if not isinstance(books, list):
books = [books]
for book in books:
if book.name:
logger.info(book.name)
else:
logger.info(f"No name in {book.bookPath.name}")
def get_by_path(self, path):
return self._by_path.get(Path(path))
def get_by_name(self, name):
return self._by_name.get(name, [])
def get_by_artist(self, artist):
return self._by_artist.get(artist, [])
def get_by_composer(self, composer):
return self._by_artist.get(composer, [])
2026-10-16 17:44:37 +02:00
def find_path_contains(self, path) -> list[Audiobook]:
return [
book
for book in self.audiobooks
if book.bookPath == path or book.bookPath.is_relative_to(path)
]
def find_name_contains(self, text):
text = text.lower()
2026-10-25 14:22:43 +01:00
return [book for book in self.audiobooks if text in book.name.lower()]
def find_artist_contains(self, text):
text = text.lower()
return [
book
for book in self.audiobooks
if book.artist and text in book.artist.lower()
]
2026-10-16 22:05:09 +02:00
def load_audiobooks_from_dir(self):
"""
A book directory is any directory containing more than one
audiobook file (.mp3, .m4a, .m4b)
"""
media_files = [
file
for file in self.libraryPath.rglob("*")
if file.is_file()
and file.suffix.lower() in AUDIO_SUFFIXES
and self.path_filter in str(file)
]
dirs = {file.parent for file in media_files}
for directory in dirs:
self.add(Audiobook(directory, self.libraryPath))
2026-10-25 14:22:43 +01:00
for audiobook in self.audiobooks:
audiobook.init_book()
2026-10-16 22:05:09 +02:00
def load_metadata(self):
for audiobook in self.audiobooks:
2026-10-16 17:44:37 +02:00
audiobook.load_metadata()
2026-10-25 14:22:43 +01:00
def write_metadata(self, keys=None):
2026-10-16 22:05:09 +02:00
for audiobook in self.audiobooks:
if audiobook.changed:
logger.trace(f"Writing metadata: {audiobook.name}")
audiobook.write_metadata(keys, dry_run=self.dry_run)
2026-10-25 14:22:43 +01:00
def fix_artist_dir(self):
for book in self.audiobooks:
book.fix_artist_dir()
def create_structured_directories(self, dry_run=False):
for book in self.audiobooks:
desired_path, desired_name = book.generate_dir_from_metadata()
book.move(desired_path, desired_name, dry_run)
def fix_artists(self, force_artist_from_path=False):
2026-10-25 14:22:43 +01:00
for book in self.audiobooks:
book.fix_artist_from_comment()
book.fix_artist_from_path(force_artist_from_path)
2026-10-16 22:05:09 +02:00
def fix_composers(self):
for book in self.audiobooks:
book.fix_composer_from_narrator()
2026-10-25 14:22:43 +01:00
book.fix_composer_from_comment()
book.fix_composer_from_path()
2026-10-16 22:05:09 +02:00
def fix_names(self):
for book in self.audiobooks:
2026-10-16 17:44:37 +02:00
book.fix_name()
2026-10-16 22:05:09 +02:00
def fix_comments(self):
for book in self.audiobooks:
2026-10-16 22:05:09 +02:00
if book.comment and len(book.comment) < 40:
2026-10-25 14:22:43 +01:00
logger.info(f"Remove short comment of {book.name}: {book.comment}")
book.comment = ""
2026-10-25 14:22:43 +01:00
book.changed = True
2026-10-25 14:22:43 +01:00
def fix_genres(self):
for book in self.audiobooks:
book.fix_genre()
def fix_titles(self):
for book in self.audiobooks:
book.fix_title()
2026-10-25 14:22:43 +01:00
def fix_series(self):
for book in self.audiobooks:
book.fix_series()
def create_m4b_from_dir(self, keep_originals: bool = False) -> None:
audiobooks = self.audiobooks
2026-10-25 14:22:43 +01:00
jobs = [audiobook for audiobook in audiobooks if not audiobook.singleFile]
for audiobook in jobs:
logger.debug(f"Create m4b file for {audiobook.name}")
if not self.dry_run:
with ThreadPoolExecutor(max_workers=8) as executor:
futures = {
executor.submit(
audiobook.create_m4b_from_book,
2026-10-25 14:22:43 +01:00
keep_originals,
): audiobook
for audiobook in jobs
}
for future in as_completed(futures):
audiobook = futures[future]
try:
future.result()
except Exception:
logger.exception(f"Failed to create m4b for {audiobook.name}")
2026-10-16 17:44:37 +02:00
def main():
2026-10-25 14:22:43 +01:00
parser = argparse.ArgumentParser(description="Audiobook Directory Processing")
parser.add_argument("library", type=Path, help="Library path")
2026-10-16 22:05:09 +02:00
parser.add_argument(
"-ll",
"--log-level",
type=str.upper,
default="INFO",
choices=["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
help="Set log level",
)
2026-10-25 14:22:43 +01:00
m4b_group = parser.add_argument_group("M4B creation")
m4b_group.add_argument(
"-cm",
2026-10-25 14:22:43 +01:00
"--create-m4b",
action="store_true",
help="Create M4B files from multi-file audiobooks",
2026-10-16 22:05:09 +02:00
)
2026-10-25 14:22:43 +01:00
m4b_group.add_argument(
"--keep-originals",
action="store_true",
help="Do not delete source files after M4B creation",
2026-10-16 22:05:09 +02:00
)
2026-10-25 14:22:43 +01:00
m4b_group.add_argument(
"--name-filter",
metavar="NAME",
default="",
help="Process only books whose name contains NAME",
)
m4b_group.add_argument(
"--path-filter",
metavar="PATH",
default="",
help="Process only books whose path contains PATH",
)
2026-10-16 22:05:09 +02:00
parser.add_argument(
"--dry-run",
action="store_true",
help="Dry run only",
)
2026-10-25 14:22:43 +01:00
parser.add_argument(
"--sql-database",
type=Path,
default=Path("/docker/audiobookshelf/config/absdatabase.sqlite"),
help="SQL Database Path",
)
parser.add_argument(
"-fd",
2026-10-25 14:22:43 +01:00
"--fix-db",
action="store_true",
help="Fix the Database",
)
parser.add_argument(
"-fa",
"--force-artist-from-path",
action="store_true",
help="Force overwrite Artist from Path, only use if Path is correct",
)
parser.add_argument(
"-m",
"--move",
action="store_true",
help="Create structured directories for all books: /artist/series/book(read by X)/file.m4b",
)
2026-10-25 14:22:43 +01:00
args = parser.parse_args()
if "--sql-database" in sys.argv:
args.fix_db = True
setup_logging(args.log_level, "audiobook_library")
2026-10-25 14:22:43 +01:00
library_dir = args.library.expanduser()
library_dir = library_dir.resolve()
if not library_dir.exists():
logger.error(f"Library directory does not exist: {library_dir}")
sys.exit(1)
2026-10-25 14:22:43 +01:00
database_path = args.sql_database.expanduser()
database_path = database_path.resolve()
if args.fix_db and not database_path.is_file():
logger.error(f"Database is not a file: {database_path}")
return
2026-10-16 22:05:09 +02:00
library = AudiobookLibrary(
library_dir, database_path, args.dry_run, path_filter=args.path_filter
)
2026-10-25 14:22:43 +01:00
if args.fix_db:
library.sql_database_instance.init()
library.fix_artist_dir()
library.fix_artists(args.force_artist_from_path)
2026-10-16 22:05:09 +02:00
library.fix_composers()
2026-10-25 14:22:43 +01:00
library.fix_series()
library.fix_names()
2026-10-16 22:05:09 +02:00
library.fix_comments()
2026-10-25 14:22:43 +01:00
library.fix_genres()
library.fix_titles()
2026-10-25 14:22:43 +01:00
if args.create_m4b:
library.create_m4b_from_dir(
keep_originals=args.keep_originals,
)
2026-10-25 14:22:43 +01:00
2026-10-16 22:05:09 +02:00
library.write_metadata()
2026-10-25 14:22:43 +01:00
if args.fix_db:
library.sql_database_instance.fix_genres()
library.sql_database_instance.fix_comments()
if not args.dry_run:
library.sql_database_instance.update_books()
library.sql_database_instance.commit()
library.sql_database_instance.close()
if args.move:
library.create_structured_directories(args.dry_run)
2026-10-25 14:22:43 +01:00
logger.info("All Operations completed successfully")
2026-10-25 14:22:43 +01:00
if __name__ == "__main__":
2026-10-25 14:22:43 +01:00
main()