@gigamusic/admin 4.3.1 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gigamusic/admin",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "Server-only admin API handler factories for the gigamusic platform (releases CRUD, tracks, uploads, settings, links, orders).",
   "license": "MIT",
   "repository": {
@@ -24,10 +24,10 @@
   },
   "dependencies": {
     "zod": "^3.24.1",
-    "@gigamusic/core": "4.2.0",
     "@gigamusic/audio": "4.3.0",
-    "@gigamusic/db": "4.3.1",
-    "@gigamusic/storage": "3.0.0"
+    "@gigamusic/core": "4.2.0",
+    "@gigamusic/storage": "3.0.0",
+    "@gigamusic/db": "4.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.5",

package/src/handlers/retag.ts

@@ -0,0 +1,187 @@
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeFile, readFile, unlink, stat } from "node:fs/promises";
+import type { DefaultTables, Queries, QueryTables } from "@gigamusic/db";
+import type { AudioTags } from "@gigamusic/audio";
+import type { AdminDeps, RouteHandler } from "../lib/types";
+import { badRequest, json, serverError } from "../lib/responses";
+
+type RetagDeps<T extends QueryTables = DefaultTables> = Pick<
+  AdminDeps<T>,
+  "storage" | "audio" | "logger"
+> & { queries: Queries<T> };
+
+/** One already-uploaded track file to rewrite tags onto, in place. */
+export interface RetagFile {
+  /** Track row to refresh `fileSize` on; omit for not-yet-persisted tracks. */
+  trackId?: number;
+  format: "wav" | "mp3";
+  /** Public URL the file already lives at (as stored in `track_files.storageKey`). */
+  storageKey: string;
+  fileName: string;
+  tags: AudioTags;
+}
+
+export interface RetagTrackFilesInput {
+  files: RetagFile[];
+  /** Release cover; fetched once and embedded as front-cover art on every file. */
+  coverImageUrl?: string;
+  /** Pre-resolved art bytes; takes precedence over `coverImageUrl` when set. */
+  coverArt?: Buffer;
+}
+
+export interface RetagFileResult {
+  trackId?: number;
+  format: "wav" | "mp3";
+  ok: boolean;
+  fileSize?: number;
+  error?: string;
+}
+
+const CONTENT_TYPE: Record<RetagFile["format"], string> = {
+  wav: "audio/wav",
+  mp3: "audio/mpeg",
+};
+
+/**
+ * Rewrite ID3/RIFF tags (and front-cover art) onto already-uploaded track
+ * files, in place, **without re-transcoding**. `tagWav` copies the PCM
+ * bit-for-bit (ffmpeg `-c:a copy`) and `tagMp3` is a `node-id3` frame write, so
+ * the only cost is the storage round-trip of each file's bytes.
+ *
+ * Consumers call this AFTER their own track sync has persisted the
+ * authoritative release/track metadata — it's the save-time counterpart to the
+ * provisional tagging done in `createAdminUploadProcessHandler` at upload time.
+ *
+ * Best-effort per file: a single file's failure is logged and recorded in the
+ * returned results, never thrown — stale metadata is non-fatal and must not
+ * roll back a save. Each successful file's `track_files.fileSize` is refreshed
+ * via `queries.upsertTrackFile`.
+ */
+export async function retagTrackFiles<T extends QueryTables = DefaultTables>(
+  deps: RetagDeps<T>,
+  input: RetagTrackFilesInput,
+): Promise<RetagFileResult[]> {
+  const coverArt = input.coverArt ?? (await resolveCover(deps, input.coverImageUrl));
+
+  const results: RetagFileResult[] = [];
+  for (const file of input.files) {
+    results.push(await retagOne(deps, file, coverArt));
+  }
+  return results;
+}
+
+async function resolveCover<T extends QueryTables>(
+  deps: RetagDeps<T>,
+  coverImageUrl: string | undefined,
+): Promise<Buffer | undefined> {
+  if (!coverImageUrl) return undefined;
+  try {
+    return await deps.storage.getFileBuffer(
+      deps.storage.keyFromPublicUrl(coverImageUrl),
+    );
+  } catch (err) {
+    deps.logger?.warn("retag: cover-image fetch failed; proceeding without art", {
+      error: String(err),
+    });
+    return undefined;
+  }
+}
+
+async function retagOne<T extends QueryTables>(
+  deps: RetagDeps<T>,
+  file: RetagFile,
+  coverArt: Buffer | undefined,
+): Promise<RetagFileResult> {
+  const key = deps.storage.keyFromPublicUrl(file.storageKey);
+  const tmpId = randomUUID();
+  const inputPath = join(tmpdir(), `${tmpId}.in.${file.format}`);
+  const outputPath = join(tmpdir(), `${tmpId}.out.${file.format}`);
+
+  try {
+    const buf = await deps.storage.getFileBuffer(key);
+    await writeFile(inputPath, buf);
+
+    if (file.format === "wav") {
+      await deps.audio.tagWav({ inputPath, outputPath, tags: file.tags, coverArt });
+    } else {
+      await deps.audio.tagMp3({ inputPath, outputPath, tags: file.tags, coverArt });
+    }
+
+    const tagged = await readFile(outputPath);
+    await deps.storage.uploadBuffer(tagged, key, CONTENT_TYPE[file.format]);
+
+    let fileSize = tagged.length;
+    try {
+      fileSize = (await stat(outputPath)).size;
+    } catch {
+      // Best-effort; fall back to the in-memory buffer length.
+    }
+
+    if (file.trackId != null) {
+      await deps.queries.upsertTrackFile({
+        trackId: file.trackId,
+        format: file.format,
+        fileName: file.fileName,
+        storageKey: deps.storage.publicUrlFromKey(key),
+        fileSize,
+      });
+    }
+
+    return { trackId: file.trackId, format: file.format, ok: true, fileSize };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    deps.logger?.error("retag: file failed", {
+      trackId: file.trackId,
+      format: file.format,
+      error,
+    });
+    return { trackId: file.trackId, format: file.format, ok: false, error };
+  } finally {
+    await Promise.allSettled([unlink(inputPath), unlink(outputPath)]);
+  }
+}
+
+interface RetagBody {
+  files?: unknown;
+  coverImageUrl?: unknown;
+}
+
+/**
+ * Build POST /api/admin/retag — a thin HTTP wrapper over `retagTrackFiles` for
+ * consumers that prefer a route over an in-process call. Apps that re-tag from
+ * inside their release-save handler should call `retagTrackFiles` directly.
+ */
+export function createAdminRetagTracksHandler<T extends QueryTables = DefaultTables>(
+  deps: RetagDeps<T>,
+): RouteHandler {
+  return async (req) => {
+    const body = (await safeJson(req)) as RetagBody;
+    if (!Array.isArray(body.files)) {
+      return badRequest("files[] is required");
+    }
+    const coverImageUrl =
+      typeof body.coverImageUrl === "string" ? body.coverImageUrl : undefined;
+    try {
+      const results = await retagTrackFiles(deps, {
+        files: body.files as RetagFile[],
+        coverImageUrl,
+      });
+      return json({ results });
+    } catch (err) {
+      deps.logger?.error("retag failed", { error: String(err) });
+      return serverError("Retag failed", {
+        detail: err instanceof Error ? err.message : String(err),
+      });
+    }
+  };
+}
+
+async function safeJson(req: Request): Promise<unknown> {
+  try {
+    return await req.json();
+  } catch {
+    return {};
+  }
+}

package/src/handlers/upload.ts

@@ -72,7 +72,8 @@ export function createAdminUploadPresignHandler(deps: PresignDeps): RouteHandler
   };
 }
 
-interface AudioMetadata {
+/** Client-supplied audio tag fields accepted by the upload/process endpoint. */
+export interface UploadAudioMetadata {
   title?: string;
   artist?: string;
   album?: string;
@@ -87,10 +88,10 @@ interface AudioMetadata {
  * are trimmed: stray whitespace embeds into the file and trips up players
  * like Apple Music that treat otherwise-identical tracks as separate albums.
  */
-function parseMetadata(raw: unknown): AudioMetadata | undefined {
+function parseMetadata(raw: unknown): UploadAudioMetadata | undefined {
   if (!raw || typeof raw !== "object") return undefined;
   const r = raw as Record<string, unknown>;
-  const out: AudioMetadata = {};
+  const out: UploadAudioMetadata = {};
   if (typeof r.title === "string" && r.title.trim()) out.title = r.title.trim();
   if (typeof r.artist === "string" && r.artist.trim()) out.artist = r.artist.trim();
   if (typeof r.album === "string" && r.album.trim()) out.album = r.album.trim();
@@ -174,11 +175,13 @@ export function createAdminUploadProcessHandler<T extends QueryTables = DefaultT
 
       const tags = metadataToTags(metadata);
 
-      // 2. Tag the WAV.
+      // 2. Tag the WAV (cover art included so the lossless master carries the
+      // same front-cover the MP3 gets).
       await deps.audio.tagWav({
         inputPath: wavPath,
         outputPath: taggedWavPath,
         tags,
+        coverArt: artBuffer ?? undefined,
       });
       await deps.storage.uploadBuffer(
         await readFile(taggedWavPath),
@@ -270,7 +273,7 @@ function basename(key: string): string {
   return slash < 0 ? key : key.slice(slash + 1);
 }
 
-function metadataToTags(meta: AudioMetadata | undefined) {
+function metadataToTags(meta: UploadAudioMetadata | undefined) {
   return {
     title: meta?.title ?? "",
     artist: meta?.artist ?? "",

package/src/server.ts

@@ -21,6 +21,16 @@ export {
   createAdminUploadPresignHandler,
   createAdminUploadProcessHandler,
 } from "./handlers/upload";
+export type { UploadAudioMetadata } from "./handlers/upload";
+export {
+  retagTrackFiles,
+  createAdminRetagTracksHandler,
+} from "./handlers/retag";
+export type {
+  RetagFile,
+  RetagTrackFilesInput,
+  RetagFileResult,
+} from "./handlers/retag";
 export { createAdminSettingsHandlers } from "./handlers/settings";
 export { createAdminLinksHandlers } from "./handlers/links";
 export { createAdminOrdersHandler } from "./handlers/orders";