groove/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-03-01 05:29:41 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Add feature documentation and artifacts index

Browse source
This commit is contained in:
Tiberiu Ichim 2026-02-20 18:15:06 +02:00
parent 1e5e0d926b
commit 696961ea4c
6 changed files with 257 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

58
artifacts/docs/item_restructuring_guide.md Normal file
View file

@ -0,0 +1,58 @@
# Item Restructuring Guide
## Overview
This guide covers the tools available in Audiobookshelf to reorganize your library items. This includes moving items between libraries, merging multiple items into one, and splitting mixed items into standalone books.
## 1. Move to Library
The **Move to Library** feature allows you to transfer items from one library to another, provided they are of the same media type (e.g., Book to Book).
### Key Features
- **Library Compatibility**: Automatically filters target libraries to those that match the `mediaType` of the source item.
- **Folder Selection**: Allows choosing a specific destination folder within the target library.
- **Transactional Safety**: Uses database transactions combined with filesystem operations. If the database update fails, files are moved back to their original location.
- **Batch Support**: Select multiple items and move them all at once.
### Usage
- **Context Menu**: Right-click a book card and select "Move to library".
- **Batch**: Select items and find "Move to library" in the top selection bar's menu.
---
## 2. Merge Books
The **Merge** feature is used when multiple files or folders (which should be one book) have been imported as separate library items.
### Mechanism
1. **Primary Item**: The first selected item is used as the "Primary" container.
2. **File Migration**: All media files (audio, ebooks, covers) from the other selected items are moved into the folder of the Primary item.
3. **Conflict Handling**: Filenames are checked for collisions; if a file with the same name exists, it is renamed with a numeric suffix.
4. **Database Consolidation**: The "extra" library items are deleted from the database.
5. **Re-Scan**: The Primary item is rescanned to detect all the new files and update chapters/tracks.
### Usage
- Select multiple items in the library.
- Select **Merge** from the context menu in the selection bar.
---
## 3. Promote File to Book (Split Book)
The inverse of merging, this feature allows you to extract files from an existing library item into a new, standalone item.
### Quick Promotion
- Targeted at single files.
- Accessible via the **Library Files** tab on the book page.
- Right-click a file and select **Promote to book**.
- The file is moved to a new folder (named after the file) and a new library item is created.
### Split Book Wizard
For bulk splitting of a single library item containing many unrelated files:
1. Click the **Split Book** button in the Library Files header.
2. **Assign Groups**: Assign each file a "Book Number".
3. **Execution**: Files assigned to Book 2, Book 3, etc., are moved into new folders (e.g., `Original Name - Book 2`).
4. **Result**: The original library item keeps the files assigned to "Book 1", and new library items are scanned into existence for the other groups.
---
## Technical Safety Notes
- **Watcher Integrity**: The file watcher is temporarily paused for the affected directories during moves to prevent "file not found" errors during the split-second migration.
- **Permissions**: These actions generally require `canDelete` and `canUpdate` permissions.
- **Metadata Preservation**: Moving an item preserves its playback progress, collections, and most manual metadata edits.

46
artifacts/docs/library_maintenance_and_migration.md Normal file
View file

@ -0,0 +1,46 @@
# Library Maintenance and Migration
## Overview
This documentation provides guidance on performing technical maintenance on the Audiobookshelf database and organizing the underlying filesystem for optimal performance.
## 1. Local Database Migration
When moving an Audiobookshelf instance from a Docker container to a local development environment (or vice-versa), the absolute paths stored in the SQLite database must be remapped.
### Migration Strategy
1. **Stop the server**: Ensure the database is not in use.
2. **Target Tables**: The following tables contain absolute path references that must be updated:
* `libraryFolders`: The `path` column.
* `libraryItems`: The `path` and `relPath` columns.
* `books`/`podcasts`: The `coverPath` column.
* `feeds`: `coverPath`, `serverAddress`, and various URL columns.
* `settings`: JSON values in `server-settings`.
3. **Remapping Logic**: Use a mapping configuration (e.g., `/audiobooks` -> `/home/user/books`) to recursively replace path prefixes.
---
## 2. Recursive Library Flattening
Audiobookshelf performs best with a shallow folder structure. Deeply nested hierarchies (e.g., `Genre / Author / Series / Book / files`) can cause scanning issues and metadata misclassification.
### The Reorganization Utility
The Python script located at `scripts/reorganize_library.py` is designed to automate the flattening of these structures.
#### Logical Rules
- **Author Extraction**: The first folder segment is treated as the "Context Author".
- **Path Merging**: Nested paths are flattened into a single folder name using the pattern: `{CleanAuthor} - {SubPathSegments}`.
- **Redundancy Removal**: If a sub-folder already starts with the author's name, the prefix is not duplicated (e.g., `Arthur C. Clarke / Arthur C. Clarke - Rama` becomes `Arthur C. Clarke - Rama`).
- **Leaf Node Detection**: A folder is treated as a "Book" if it contains audio files and lacks subdirectories (or contains specific CD/Disc sub-folders).
#### Usage
```bash
python3 scripts/reorganize_library.py /path/to/library --dry-run
```
*Always use `--dry-run` first to verify the planned movements.*
---
## 3. Empty Directory Cleanup
Maintaining a clean filesystem involves removing empty artifacts left behind by moves or deletions.
- **Automatic Cleanup**: Most built-in tools (Move, Consolidate, Split) include a recursive parent-cleanup step.
- **Mechanism**: After a file is moved, the system checks the source directory. If it is empty and not a library root, it is deleted. This process bubbles upwards until it encounters a directory containing other files or folders.
- **Manual Cleanup**: The `reorganize_library.py` script also performs this cleanup automatically after flattening items.

37
artifacts/docs/m4b_authoring_tool.md Normal file
View file

@ -0,0 +1,37 @@
# M4B Authoring Tool
## Overview
Audiobookshelf includes a built-in tool to merge multi-file audiobooks into a single M4B file. This tool is accessible via the **Manage** tab of any book.
## "Stream Copy" (Zero Re-encode)
The most significant improvement to the authoring tool is the **Stream Copy** (Codec: `Copy`) feature.
### Benefits
- **Quality Preservation**: Since the audio is not re-encoded, there is zero loss in audio quality during the merge.
- **Speed**: Processing time is reduced from minutes (for re-encoding) to seconds (for disk I/O).
- **CPU Efficiency**: Minimal processing power is required compared to transcoding.
### How it Works
1. **Concatenation**: FFmpeg uses the `concat` demuxer to join the source files into a continuous stream without decoding them.
2. **Container Swap**: The stream is wrapped into an MP4/M4B container.
3. **Metadata Injection**: Chapters, title, artist, and cover art are injected in a secondary pass, again using `-c copy`.
## Feature Matrix
| Feature | Support |
| :--- | :--- |
| **Codecs** | AAC, OPUS, Copy (Stream Copy) |
| **Chapters** | Automatically generated from Library Item tracks |
| **Cover Art** | Embedded as a video stream (attached_pic) |
| **Metadata** | Title, Artist, Album, and Comment tags |
## Usage
1. Navigate to a book with multiple audio files.
2. Go to **Manage** -> **M4B Encoder**.
3. Select **Codec: Copy**.
4. Click **Merge**.
5. Once complete, a new M4B file will appear in the "Files" tab, and you will be prompted to swap the library item to the new file (optional).
## Requirements
- Source files must be compatible with the M4B container (typically AAC/M4A/MP3).
- **Note**: While MP3 files can technically be copied into an M4B container, some players may have better compatibility if MP3s are transcoded to AAC.

39
artifacts/docs/metadata_management_tools.md Normal file
View file

@ -0,0 +1,39 @@
# Metadata Management Tools
## Overview
Audiobookshelf provides tools to manage and recover metadata when automatic matching fails or when users have manually edited metadata and wish to revert to the data contained within the source files.
## Reset Metadata
The **Reset Metadata** action allows a user to discard all manual edits and server-side metadata files, forcing the scanner to re-evaluate the item from its original source.
### Mechanism
When a "Reset" is triggered:
1. **Server Metadata Removal**: The `metadata.json` file stored in the application's internal metadata directory (`/metadata/items/<id>/metadata.json`) is deleted.
2. **Local Metadata Removal**: If the system is configured to `storeMetadataWithItem`, the `metadata.json` file inside the book's folder is also deleted.
3. **Database Reset**: The `media.coverPath` is set to `null` in the database.
4. **Re-Scan**: A full scan is triggered using `LibraryItemScanner.scanLibraryItem(id)`. This scan prioritizes:
* Embedded Audio Tags (ID3, MP4, etc.)
* OPF or NFO files in the folder.
* Filename and folder structure patterns.
### Usage
- **Single Item**: Found in the **Edit Modal** under the **Details** tab, next to the "ReScan" button.
- **Color**: Represented by a red button (Warning) to indicate a destructive action.
## Batch Reset Metadata
The batch version allows performing the reset operation on multiple selected items simultaneously.
### Usage
1. Select multiple items in the library listing.
2. Open the context menu (three dots) in the selection bar at the top of the interface.
3. Select **Reset Metadata**.
4. A confirmation dialog will appear, confirming the number of items to be reset.
## When to Use
- **Incorrect Matches**: If a book was matched to the wrong title and manual corrections are too cumbersome.
- **File Updates**: If the underlying audio files have been replaced with different versions (e.g., higher bitrate) and the user wants to ensure the database reflects the new file tags.
- **Corrupted Metadata**: If the `metadata.json` has become inconsistent with the actual files on disk.
## Technical Details
- **Permissions**: Requires the `canUpdate` permission.
- **Events**: Triggering a reset will eventually emit an `item_updated` socket event once the subsequent scan completes.

46
artifacts/docs/ui_visual_indicators_system.md Normal file
View file

@ -0,0 +1,46 @@
# UI Visual Indicators System
## Overview
Audiobookshelf uses a system of badges and icons to provide immediate visual feedback on the state and quality of library items. This documentation covers the resolution tiers and consolidation indicators.
## 1. Cover Size Badges
To help users identify high-quality artwork, every book cover can display a resolution badge.
### Size Tiers
The system classifies covers into three tiers based on the natural width or height (whichever is larger):
| Tier | Range | Label | Color | Code |
| :--- | :--- | :--- | :--- | :--- |
| **BIG** | >= 1200px | BIG | Green | `bg-success` |
| **MED** | >= 450px | MED | Blue | `bg-info` |
| **SML** | < 450px | SML | Yellow | `bg-warning` |
### Implementation
- **Server-Side Detection**: Dimensions are detected using `ffprobe` when a cover is uploaded or scanned and stored in the database (`coverWidth`, `coverHeight`).
- **Client-Side Fallback**: If server data is missing, the UI calculates the tier using the browser's `naturalWidth`/`naturalHeight` once the image loads.
- **Visuals**: The badge is a small, semi-transparent pill in the bottom-right corner of the cover.
---
## 2. Consolidation Indicators
The **Consolidation** status indicates whether a book's folder structure matches the standard Audiobookshelf convention (`Author - Title`).
### The "Not Consolidated" Badge
- **Visibility**: Appears on the book card in the bookshelf view for items that are not in the standard format.
- **Criteria**:
- The folder name does not match the sanitized metadata (`Author - Title`).
- The item is located in a subfolder deeper than the library root (e.g., `Author/Title/Book`).
- The item is a single file in the root (requires a folder).
- **Functionality**:
- Acts as a warning that the folder structure is disorganized.
- Provides a **direct shortcut** button to trigger the consolidation process for that item.
### Tooltips and Detail view
- In the **Book Details** page, a yellow folder icon appears next to the title if the item is not consolidated.
- Hovering over the icon provides the "Not Consolidated" description.
---
## 3. UI Placement and Scaling
- **Responsiveness**: All badges use font sizes that scale with the `sizeMultiplier` of the component, ensuring they remain legible whether the cover is a tiny thumbnail or a large hero image.
- **Layering**: Badges are placed with specific `z-index` values to ensure they stay above the cover image but do not block interactive elements like the "Play" button or selection checkboxes.

31
artifacts/index.md Normal file
View file

@ -0,0 +1,31 @@
# Artifacts Index
This index provides a quick reference for specification and documentation files in the `artifacts/` folder.
| Date | File | Summary |
| :--- | :--- | :--- |
| **2026-02-05** | [local_migration.md](2026-02-05/local_migration.md) | Specification for migrating an Audiobookshelf database from Docker to a local environment, remapping absolute paths. |
| **2026-02-06** | [move-to-library-specification.md](2026-02-06/move-to-library-specification.md) | Documentation for the "Move to Library" feature, supporting single and batch moves between compatible libraries. |
| **2026-02-11** | [recursive_libraries.md](2026-02-11/recursive_libraries.md) | Specification for a Python utility (`reorganize_library.py`) to flatten deeply nested library structures. |
| **2026-02-12** | [book-merge.md](2026-02-12/book-merge.md) | Implementation plan and walkthrough for merging multiple library items (e.g., individual files) into a single book item. |
| **2026-02-13** | [consolidate.md](2026-02-13/consolidate.md) | Specification for the "Consolidate" feature, renaming book folders to `Author - Book Name` and moving them to the library root. |
| **2026-02-14** | [implementation_plan.md](2026-02-14/implementation_plan.md) | Implementation plan for the "Reset Metadata" feature, detailing backend and frontend changes. |
| **2026-02-14** | [m4b_conversion.md](2026-02-14/m4b_conversion.md) | Specification for improvements to the M4B merge tool, adding "Stream Copy" support to avoid re-encoding. |
| **2026-02-14** | [reset_metadata_specification.md](2026-02-14/reset_metadata_specification.md) | Detailed specification for the "Reset Metadata" feature, including metadata file deletion and re-scanning logic. |
| **2026-02-15** | [badge.md](2026-02-15/badge.md) | Specification for a client-side cover size badge indicating image resolution tiers. |
| **2026-02-15** | [batch_reset.md](2026-02-15/batch_reset.md) | Specification for the "Batch Reset Metadata" feature for multiple selected items. |
| **2026-02-15** | [batch_reset_implementation_status.md](2026-02-15/batch_reset_implementation_status.md) | Implementation status checklist for the "Batch Reset Metadata" feature. |
| **2026-02-15** | [consolidation_badge.md](2026-02-15/consolidation_badge.md) | Specification for the "Not Consolidated" badge and library-wide status update tool. |
| **2026-02-15** | [reset_filters_on_library_switch.md](2026-02-15/reset_filters_on_library_switch.md) | Specification for automatically resetting library filters when switching between libraries. |
| **2026-02-15** | [select_all.md](2026-02-15/select_all.md) | Specification for the `Ctrl+A` / `Cmd+A` keyboard shortcut to select all library items. |
| **2026-02-17** | [badge.md](2026-02-17/badge.md) | Revised specification for the cover size badge using server-side dimension detection and storage. |
| **2026-02-17** | [consolidate_singles.md](2026-02-17/consolidate_singles.md) | Expansion of the "Consolidate" feature to support single-file books by moving them into new folders. |
| **2026-02-17** | [ui_enhancements.md](2026-02-17/ui_enhancements.md) | Specification for "View All" shortcuts on Home view shelves with specific sorting. |
| **2026-02-20** | [promote_file_to_book.md](2026-02-20/promote_file_to_book.md) | Specification for "promoting" files from an existing book into a standalone library item, including a "Split Book" wizard. |
| **General** | [docs/consolidate_feature.md](docs/consolidate_feature.md) | Comprehensive documentation for the "Consolidate" feature, including conflict resolution and technical details. |
| **General** | [docs/item_restructuring_guide.md](docs/item_restructuring_guide.md) | Guide for Moving, Merging, and Splitting (Promoting) library items. |
| **General** | [docs/metadata_management_tools.md](docs/metadata_management_tools.md) | Documentation for Reset Metadata and Batch Reset operations. |
| **General** | [docs/ui_visual_indicators_system.md](docs/ui_visual_indicators_system.md) | Overview of the badge system (Cover Size, Consolidation Status). |
| **General** | [docs/library_maintenance_and_migration.md](docs/library_maintenance_and_migration.md) | Technical guide for database path migration and library flattening. |
| **General** | [docs/m4b_authoring_tool.md](docs/m4b_authoring_tool.md) | Documentation for the M4B merge tool and Stream Copy feature. |
| **General** | [docs/ux_power_user_shortcuts.md](docs/ux_power_user_shortcuts.md) | Overview of keyboard shortcuts, navigation logic, and batch actions. |