Add Plex format coercion (.mp4 → .m4b)

Implement Plex-compatible file-extension coercion to avoid Plex silently ignoring .mp4 (and single-file .m4a) audiobooks (issue #166). Adds a DB migration and configuration key (plex_format_coercion_enabled, default true), exposes a toggle in the setup wizard and Admin Paths settings, and persists/reads the setting in the admin/setup APIs.

Introduces src/lib/utils/format-coercion.ts (coerceToPlexCompatible) and related constants in src/lib/constants/audio-formats.ts (PLEX_COMPATIBLE_EXTENSIONS, COERCION_RENAME_MAP, DRM_EXTENSIONS, TRANSCODE_REQUIRED_EXTENSIONS). The organize-files processor now runs coercion after organizing/tagging and before generating the filesHash and triggering scans; coercion is idempotent, never overwrites existing targets, logs warnings on DRM/transcode/permission errors, and is non-fatal.

Adds unit tests for the coercion util and updates processor & setup UI tests. Updates documentation (TABLEOFCONTENTS, file-organization, fixes/file-hash-matching, settings-pages) describing behavior, config, and constraints.
This commit is contained in:
kikootwo
2026-05-15 19:33:59 -04:00
parent 6f8ac86a43
commit f23afc1ba2
18 changed files with 815 additions and 7 deletions
@@ -0,0 +1,18 @@
-- Add Plex format coercion configuration
-- This allows admin to enable/disable post-organization file-extension rename to Plex-compatible formats
-- Motivation: issue #166 — Plex silently fails to import .mp4 (and some .m4a) audiobook files
-- Coercion is extension-swap only — no re-encoding, no metadata changes
-- Insert default configuration for Plex format coercion (enabled by default)
INSERT INTO configuration (id, key, value, encrypted, category, description, created_at, updated_at)
VALUES (
gen_random_uuid(),
'plex_format_coercion_enabled',
'true',
false,
'automation',
'Rename audio files to Plex-compatible extensions after organization (e.g., .mp4 → .m4b). No re-encoding. Prevents the silent-import failure described in issue #166.',
NOW(),
NOW()
)
ON CONFLICT (key) DO NOTHING;