mirror of
https://github.com/kikootwo/ReadMeABook.git
synced 2026-06-03 04:40:09 +00:00
kikootwo
125 lines
4.0 KiB
Markdown
125 lines
4.0 KiB
Markdown
# File Organization System
|
|
|
|
**Status:** ✅ Implemented
|
|
|
|
Copies completed downloads to standardized directory structure for Plex. Automatically tags audio files with correct metadata. Originals kept for seeding, cleaned up by scheduled job after requirements met.
|
|
|
|
## Target Structure
|
|
|
|
```
|
|
/media/audiobooks/
|
|
└── Author Name/
|
|
└── Book Title (Year)/
|
|
├── Book Title.m4b
|
|
└── cover.jpg
|
|
```
|
|
|
|
## Process
|
|
|
|
1. Download completes in `/downloads/[torrent-name]/` or `/downloads/[filename]` (single file)
|
|
2. Identify audiobook files (.m4b, .m4a, .mp3) - supports both directories and single files
|
|
3. Create `/media/audiobooks/[Author]/[Title]/`
|
|
4. **Copy** files (not move - originals stay for seeding)
|
|
5. **Tag metadata** (if enabled) - writes correct title, author, narrator to audio files
|
|
6. Copy cover art if found, else download from Audible
|
|
7. Originals remain until seeding requirements met
|
|
|
|
## Metadata Tagging
|
|
|
|
**Status:** ✅ Implemented
|
|
|
|
**Purpose:** Automatically writes correct metadata to audio files during file organization to improve Plex matching accuracy.
|
|
|
|
**Supported Formats:**
|
|
- m4b, m4a, mp4 (AAC audiobooks)
|
|
- mp3 (ID3v2 tags)
|
|
|
|
**Metadata Written:**
|
|
- `title` - Book title
|
|
- `album` - Book title (PRIMARY field for Plex matching)
|
|
- `album_artist` - Author (PRIMARY field for Plex matching)
|
|
- `artist` - Author (fallback)
|
|
- `composer` - Narrator (standard audiobook field)
|
|
- `date` - Year
|
|
|
|
**Configuration:**
|
|
- Key: `metadata_tagging_enabled` (Configuration table)
|
|
- Default: `true`
|
|
- Configurable in: Setup wizard (Paths step), Admin settings (Paths tab)
|
|
|
|
**Implementation:**
|
|
- Uses ffmpeg with `-codec copy` (no re-encoding, metadata only)
|
|
- Fast (no audio transcoding)
|
|
- Lossless (original audio preserved)
|
|
- Runs after file copy, before cover art download
|
|
- Non-blocking (errors don't fail file organization)
|
|
- Logs success/failure per file
|
|
|
|
**Benefits:**
|
|
- Fixes torrents with missing/incorrect metadata
|
|
- Ensures Plex can match audiobooks correctly
|
|
- Writes metadata from Audible/Audnexus (known accurate)
|
|
- Prevents "[Various Albums]" and other metadata issues
|
|
|
|
**Tech Stack:**
|
|
- ffmpeg (system dependency - included in Docker image)
|
|
- `src/lib/utils/metadata-tagger.ts` - Tagging utility
|
|
- Integrated into `src/lib/utils/file-organizer.ts`
|
|
|
|
**Requirements:**
|
|
- ffmpeg must be installed in the container
|
|
- **Multi-container setup** (`Dockerfile`): Added at line 56 via `apk add ffmpeg`
|
|
- **Unified setup** (`dockerfile.unified`): Added at line 16 via `apt-get install ffmpeg`
|
|
- **Verify installation:**
|
|
- Multi-container: `docker exec readmeabook ffmpeg -version`
|
|
- Unified: `docker exec readmeabook-unified ffmpeg -version`
|
|
|
|
## Seeding Support
|
|
|
|
**Config:** `seeding_time_minutes` (0 = unlimited, never cleanup)
|
|
|
|
**Cleanup Job:** `cleanup_seeded_torrents` (every 30 mins)
|
|
1. Check 'available' and 'downloaded' status requests with download history
|
|
2. Query qBittorrent for actual `seeding_time` field
|
|
3. Delete torrent + files only after requirement met
|
|
4. Respects config (0 = never cleanup)
|
|
|
|
## Interface
|
|
|
|
```typescript
|
|
interface OrganizationResult {
|
|
success: boolean;
|
|
targetPath: string;
|
|
filesMovedCount: number;
|
|
errors: string[];
|
|
audioFiles: string[];
|
|
coverArtFile?: string;
|
|
}
|
|
|
|
async function organize(
|
|
downloadPath: string,
|
|
audiobook: {title: string, author: string, year?: number, coverArtUrl?: string}
|
|
): Promise<OrganizationResult>;
|
|
```
|
|
|
|
## Path Sanitization
|
|
|
|
- Remove invalid chars: `<>:"/\|?*`
|
|
- Trim dots/spaces
|
|
- Collapse multiple spaces
|
|
- Limit to 200 chars
|
|
- Example: `Author: The <Best>! Book?` → `Author The Best! Book`
|
|
|
|
## Fixed Issues ✅
|
|
|
|
**1. EPERM errors** - Fixed with `fs.readFile/writeFile` instead of `copyFile`
|
|
**2. Immediate deletion** - Changed to copy-only, scheduled cleanup after seeding
|
|
**3. Files moved not copied** - Now copies to support seeding
|
|
**4. Single file downloads** - Now supports files directly in downloads folder (not just directories)
|
|
|
|
## Tech Stack
|
|
|
|
- Node.js `fs/promises`
|
|
- `path` module
|
|
- axios (cover art download)
|