From b5caadd4c2d222b569cd8e7deba30b5adc59220e Mon Sep 17 00:00:00 2001
From: Tiberiu Ichim <tiberiu.ichim@gmail.com>
Date: Fri, 20 Feb 2026 20:26:33 +0200
Subject: [PATCH] feat: Add 'Write Metadata Files' button to Library Tools
 modal

---
 .../modals/libraries/LibraryTools.vue         | 40 +++++++++++++++
 client/strings/en-us.json                     |  5 ++
 server/controllers/LibraryController.js       | 50 +++++++++++++++++++
 server/routers/ApiRouter.js                   |  1 +
 .../utils/migrations/absMetadataMigration.js  |  4 +-
 5 files changed, 99 insertions(+), 1 deletion(-)

diff --git a/client/components/modals/libraries/LibraryTools.vue b/client/components/modals/libraries/LibraryTools.vue
index 16d89625a..8d3212116 100644
--- a/client/components/modals/libraries/LibraryTools.vue
+++ b/client/components/modals/libraries/LibraryTools.vue
@@ -1,5 +1,17 @@
 <template>
   <div class="w-full h-full px-1 md:px-2 py-1 mb-4">
+    <div class="w-full border border-black-200 p-4 my-8">
+      <div class="flex flex-wrap items-center">
+        <div>
+          <p class="text-lg">{{ $strings.LabelWriteMetadataFiles }}</p>
+          <p class="max-w-sm text-sm pt-2 text-gray-300">{{ $strings.LabelWriteMetadataFilesHelp }}</p>
+        </div>
+        <div class="grow" />
+        <div>
+          <ui-btn @click.stop="writeMetadataFilesClick">{{ $strings.LabelWriteMetadataFiles }}</ui-btn>
+        </div>
+      </div>
+    </div>
     <div class="w-full border border-black-200 p-4 my-8">
       <div class="flex flex-wrap items-center">
         <div>
@@ -89,6 +101,34 @@ export default {
     }
   },
   methods: {
+    writeMetadataFilesClick() {
+      const payload = {
+        message: this.$strings.MessageConfirmWriteMetadataFiles,
+        persistent: true,
+        callback: (confirmed) => {
+          if (confirmed) {
+            this.writeMetadataFiles()
+          }
+        },
+        type: 'yesNo'
+      }
+      this.$store.commit('globals/setConfirmPrompt', payload)
+    },
+    writeMetadataFiles() {
+      this.$emit('update:processing', true)
+      this.$axios
+        .$post(`/api/libraries/${this.libraryId}/write-metadata-files`)
+        .then((data) => {
+          this.$toast.success(this.$getString('ToastWriteMetadataFilesSuccess', [data.created, data.skipped]))
+        })
+        .catch((error) => {
+          console.error('Failed to write metadata files', error)
+          this.$toast.error(this.$strings.ToastWriteMetadataFilesFailed)
+        })
+        .finally(() => {
+          this.$emit('update:processing', false)
+        })
+    },
     removeAllMetadataClick(ext) {
       const payload = {
         message: this.$getString('MessageConfirmRemoveMetadataFiles', [ext]),
diff --git a/client/strings/en-us.json b/client/strings/en-us.json
index 25e3a822a..98faff97e 100644
--- a/client/strings/en-us.json
+++ b/client/strings/en-us.json
@@ -291,6 +291,8 @@
   "LabelUpdateConsolidationStatusHelp": "Checks all items in this library and updates their consolidation status. This is useful if you have manually moved folders on disk.",
   "LabelUpdateCoverDimensions": "Update Cover Dimensions",
   "LabelUpdateCoverDimensionsHelp": "Detect and update cover width and height for all items in this library.",
+  "LabelWriteMetadataFiles": "Write Metadata Files",
+  "LabelWriteMetadataFilesHelp": "Generate a metadata.json file for each item in this library that does not already have one. Useful after enabling 'Store metadata with item'.",
   "LabelClickForMoreInfo": "Click for more info",
   "LabelClickToUseCurrentValue": "Click to use current value",
   "LabelClosePlayer": "Close player",
@@ -813,6 +815,7 @@
   "MessageConfirmCleanupAuthors": "Are you sure you want to remove all authors with no books in this library?",
   "MessageConfirmUpdateConsolidationStatus": "Are you sure you want to update the consolidation status for all items in this library? This will re-calculate the 'Not Consolidated' badge for every book.",
   "MessageConfirmUpdateCoverDimensions": "Are you sure you want to update cover dimensions for all items in this library? This will use ffprobe to detect dimensions for each cover.",
+  "MessageConfirmWriteMetadataFiles": "Are you sure you want to write metadata.json files for all items in this library? Only items that do not already have a metadata file will be created.",
   "MessageConfirmRemoveEpisodeNote": "Note: This does not delete the audio file unless toggling \"Hard delete file\"",
   "MessageConfirmRemoveEpisodes": "Are you sure you want to remove {0} episodes?",
   "MessageConfirmRemoveListeningSessions": "Are you sure you want to remove {0} listening sessions?",
@@ -1115,6 +1118,8 @@
   "ToastMetadataFilesRemovedNoneFound": "No metadata.{0} files found in library",
   "ToastMetadataFilesRemovedNoneRemoved": "No metadata.{0} files removed",
   "ToastMetadataFilesRemovedSuccess": "{0} metadata.{1} files removed",
+  "ToastWriteMetadataFilesSuccess": "{0} metadata file(s) created, {1} already existed",
+  "ToastWriteMetadataFilesFailed": "Failed to write metadata files",
   "ToastMustHaveAtLeastOnePath": "Must have at least one path",
   "ToastNameEmailRequired": "Name and email are required",
   "ToastNameRequired": "Name is required",
diff --git a/server/controllers/LibraryController.js b/server/controllers/LibraryController.js
index 0179fe548..b2a74873f 100644
--- a/server/controllers/LibraryController.js
+++ b/server/controllers/LibraryController.js
@@ -1575,6 +1575,56 @@ class LibraryController {
     }
   }
 
+  /**
+   * POST: /api/libraries/:id/write-metadata-files
+   * Write metadata.json files for all items in library that don't already have one
+   *
+   * @param {LibraryControllerRequest} req
+   * @param {Response} res
+   */
+  async writeMetadataFiles(req, res) {
+    if (!req.user.isAdminOrUp) {
+      Logger.error(`[LibraryController] Non-admin user "${req.user.username}" attempted to write metadata files`)
+      return res.sendStatus(403)
+    }
+
+    const absMetadataMigration = require('../utils/migrations/absMetadataMigration')
+
+    Logger.info(`[LibraryController] Writing metadata files for library "${req.library.name}"`)
+
+    let created = 0
+    let skipped = 0
+    let failed = 0
+    let offset = 0
+    const batchSize = 500
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const libraryItems = await Database.libraryItemModel.getLibraryItemsIncrement(offset, batchSize, {
+        libraryId: req.library.id,
+        isMissing: false
+      })
+      if (!libraryItems.length) break
+
+      for (const libraryItem of libraryItems) {
+        const result = await absMetadataMigration.writeMetadataFileForItem(libraryItem)
+        if (result === null) {
+          skipped++ // Already existed
+        } else if (result === false) {
+          failed++
+        } else {
+          created++
+        }
+      }
+
+      if (libraryItems.length < batchSize) break
+      offset += libraryItems.length
+    }
+
+    Logger.info(`[LibraryController] Finished writing metadata files for library "${req.library.name}" (created=${created}, skipped=${skipped}, failed=${failed})`)
+    res.json({ created, skipped, failed })
+  }
+
   /**
    *
    * @param {RequestWithUser} req
diff --git a/server/routers/ApiRouter.js b/server/routers/ApiRouter.js
index c7cc65e2f..f01802b6f 100644
--- a/server/routers/ApiRouter.js
+++ b/server/routers/ApiRouter.js
@@ -96,6 +96,7 @@ class ApiRouter {
     this.router.post('/libraries/:id/remove-metadata', LibraryController.middleware.bind(this), LibraryController.removeAllMetadataFiles.bind(this))
     this.router.post('/libraries/:id/update-consolidation', LibraryController.middleware.bind(this), LibraryController.updateConsolidationStatus.bind(this))
     this.router.post('/libraries/:id/update-cover-dimensions', LibraryController.middleware.bind(this), LibraryController.updateCoverDimensions.bind(this))
+    this.router.post('/libraries/:id/write-metadata-files', LibraryController.middleware.bind(this), LibraryController.writeMetadataFiles.bind(this))
     this.router.get('/libraries/:id/podcast-titles', LibraryController.middleware.bind(this), LibraryController.getPodcastTitles.bind(this))
     this.router.get('/libraries/:id/download', LibraryController.middleware.bind(this), LibraryController.downloadMultiple.bind(this))
 
diff --git a/server/utils/migrations/absMetadataMigration.js b/server/utils/migrations/absMetadataMigration.js
index 0d9f909a9..715995db9 100644
--- a/server/utils/migrations/absMetadataMigration.js
+++ b/server/utils/migrations/absMetadataMigration.js
@@ -90,4 +90,6 @@ module.exports.migrate = async (Database) => {
   Logger.info(`[absMetadataMigration] Starting metadata.json migration`)
   const totalCreated = await runMigration(Database)
   Logger.info(`[absMetadataMigration] Finished metadata.json migration (${totalCreated} files created)`)
-}
\ No newline at end of file
+}
+
+module.exports.writeMetadataFileForItem = writeMetadataFileForItem
\ No newline at end of file