audiobookshelf/artifacts/2026-02-14/reset_metadata_specification.md

Reset Metadata Feature Specification

Overview

This document outlines the implementation of the "Reset Metadata" feature, designed to allow users to reset a library item's metadata to its original state derived from the file system (tags, folder structure, OPF files), effectively ignoring or removing any manual edits stored in the database or metadata.json files.

Date

2026-02-14

Rationale

Users may encounter situations where a library item is matched to the wrong book, or the underlying files have changed (e.g., replaced with a different audiobook version). The existing "ReScan" functionality often preserves existing metadata (especially if metadata.json exists) to prevent data loss, which makes it difficult to force a full refresh from the files. A dedicated "Reset" action is needed.

Detailed Implementation

1. Backend Implementation

Server Controller: LibraryItemController.js

• Method: resetMetadata(req, res)
• Logic:
  1. Permission Check: Verifies if the user has update permissions (req.user.canUpdate). Returns 403 if not.
  2. Server Metadata Removal: Identifies and deletes the metadata.json file from the server's metadata directory (/metadata/items/<id>/metadata.json) if it exists.
  3. Local Metadata Removal: Identifies and deletes the metadata.json file from the item's local folder path (if storeMetadataWithItem is enabled and the file exists).
  4. Database Update (Cover): Sets media.coverPath to null in the database. This forces a re-evaluation of the cover image (checking embedded art or cover.jpg in folder) during the subsequent scan.
  5. Re-Scan: Triggers LibraryItemScanner.scanLibraryItem(id) to re-process the item from scratch using the remaining sources (Audio Tags, OPF, NFO, Folder Structure).
  6. Response: Returns the updated library item in JSON format.

API Router: ApiRouter.js

• Route: POST /api/items/:id/reset-metadata
• Middleware: Applies authentication, item access checks, and update permission verification (LibraryItemController.middleware).
• Handler: Maps to the LibraryItemController.resetMetadata method.

2. Frontend Implementation

Vue Component: Details.vue

• Location: client/components/modals/item/tabs/Details.vue
• UI Element: Added a "Reset" button to the "Details" tab in the edit modal, located next to the existing "ReScan" button.
• Styling: Used bg-error (red) for the button to indicate a destructive action.
• Interactivity:
  1. Click Handler: resetMetadata() triggers a confirmation dialog (globals/setConfirmPrompt) explaining the action: "Are you sure you want to reset metadata? This will remove the metadata file and re-scan the item from files."
  2. Action Handler: runResetMetadata() calls the POST /api/items/:id/reset-metadata endpoint.
  3. Feedback: On success, a toast notification "Metadata reset successfully" is displayed. On failure, an error toast is shown.
  4. State Management: Uses a resetting flag to show a loading state on the button while the request is processing.

Verification Scenarios

1. Manual Edit Reversion: Open an audiobook where the title was manually changed. Click "Reset". Verify that the title reverts to the value found in the audio file tags or folder name.
2. Metadata File Deletion: Open an audiobook that has a metadata.json file present. Click "Reset". Verify that the metadata.json file is deleted from the filesystem and the metadata is refreshed.
3. Cover Reset: Ensure that triggering a reset also clears the cover path, causing the scanner to look for a cover again.