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
+26
View File
@@ -13,6 +13,7 @@ interface PathsStepProps {
downloadDir: string;
mediaDir: string;
metadataTaggingEnabled: boolean;
plexFormatCoercionEnabled: boolean;
chapterMergingEnabled: boolean;
pathsTested: boolean;
onUpdate: (field: string, value: any) => void;
@@ -24,6 +25,7 @@ export function PathsStep({
downloadDir,
mediaDir,
metadataTaggingEnabled,
plexFormatCoercionEnabled,
chapterMergingEnabled,
pathsTested,
onUpdate,
@@ -246,6 +248,30 @@ export function PathsStep({
</div>
</div>
{/* Plex Format Coercion Toggle */}
<div className="bg-gray-50 dark:bg-gray-800 rounded-lg p-4 border border-gray-200 dark:border-gray-700">
<div className="flex items-start gap-4">
<input
type="checkbox"
id="plex-format-coercion"
checked={plexFormatCoercionEnabled}
onChange={(e) => onUpdate('plexFormatCoercionEnabled', e.target.checked)}
className="mt-1 h-5 w-5 rounded border-gray-300 text-blue-600 focus:ring-blue-500"
/>
<div className="flex-1">
<label
htmlFor="plex-format-coercion"
className="block text-sm font-medium text-gray-900 dark:text-gray-100 cursor-pointer"
>
Coerce file formats for Plex compatibility
</label>
<p className="text-sm text-gray-600 dark:text-gray-400 mt-1">
Rename .mp4 audiobook files (and single-file .m4a) to .m4b before Plex scans. No re-encoding.
</p>
</div>
</div>
</div>
{/* Chapter Merging Toggle */}
<div className="bg-gray-50 dark:bg-gray-800 rounded-lg p-4 border border-gray-200 dark:border-gray-700">
<div className="flex items-start gap-4">