Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

7.9 KB
Raw Blame
/**
 * Background-music library for the pipeline audio stage.
 *
 * Storage model: a single shared directory at `PATHS.music`. Every track —
 * uploaded today, locally generated tomorrow — lives here under a deterministic
 * basename. The library list is just `readdir + stat` filtered to known audio
 * extensions. No JSON index — the filesystem is the source of truth, which
 * keeps the library robust across server restarts and direct file drops.
 *
 * Provider strategy mirrors `audio.js`: **local-first**. User-upload is the
 * always-available path (zero infra). Local MusicGen via a Python sidecar
 * (4c.2 follow-up) and a 3rd-party Suno stub (4c.3) plug in as sibling
 * sources behind the same library list — the AudioStage picker doesn't
 * care which one wrote the bytes.
 */

import { stat } from 'fs/promises';
import { existsSync } from 'fs';
import { join, basename, extname } from 'path';
import { randomUUID } from 'crypto';
import {
  PATHS,
  ensureDir,
  assertSafeFilename,
  isSafeFilename,
  listDirectoryByExtension,
  copyFileGuarded,
  unlinkGuarded,
  assertFileNotMediaManifest,
} from '../../lib/fileUtils.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';

// Mirror of the sanitizer's MUSIC_SOURCES set in `services/pipeline/issues.js`.
// Exported so routes don't sprinkle bare strings; `'gen'` is reserved for the
// next sub-phase (local MusicGen sidecar / 3rd-party Suno stub).
export const MUSIC_SOURCE = Object.freeze({
  UPLOAD: 'upload',
  LIBRARY: 'library',
  GEN: 'gen',
});

export const SUPPORTED_AUDIO_EXTENSIONS = Object.freeze(['.mp3', '.wav', '.m4a', '.ogg', '.flac']);

export const SUPPORTED_AUDIO_MIME = Object.freeze({
  '.mp3': 'audio/mpeg',
  '.wav': 'audio/wav',
  '.m4a': 'audio/mp4',
  '.ogg': 'audio/ogg',
  '.flac': 'audio/flac',
});

export const MUSIC_UPLOAD_MAX_BYTES = 50 * 1024 * 1024;

// Returns true if the MIME or filename extension marks this as one of our
// supported audio formats. Used by the multipart fileFilter — matching either
// signal handles browsers that report `application/octet-stream` for drag-
// drop uploads while still requiring a known extension.
export function isSupportedMusicUpload(file) {
  if (!file) return false;
  const ext = (extname(file.originalname || '') || '').toLowerCase();
  if (!SUPPORTED_AUDIO_EXTENSIONS.includes(ext)) return false;
  const mime = (file.mimetype || '').toLowerCase();
  if (mime.startsWith('audio/')) return true;
  if (mime === 'application/octet-stream') return true;
  if (mime === 'video/mp4' && ext === '.m4a') return true; // some browsers
  return false;
}

/**
 * Validate a stored music filename — same pattern as the rest of the codebase.
 * Rejects path traversal, separators, and disallowed extensions.
 */
export function assertSafeMusicFilename(filename) {
  assertSafeFilename(filename, {
    extensions: [...SUPPORTED_AUDIO_EXTENSIONS],
    subject: 'music filename',
  });
}

/**
 * The same rule as a predicate, for read-only callers that must treat a bad
 * stored filename as data. `sanitizeTrack` only `trimTo`s the top-level
 * `audioFilename` (unlike `renders[]`, which goes through
 * `trackAudioFilename`), so a legacy or peer-synced track can carry an
 * unsupported name — a preflight has to report that as one blocked asset, not
 * 400 the whole sweep via `assertSafeMusicFilename`.
 */
export const isSafeMusicFilename = (filename) =>
  isSafeFilename(filename, SUPPORTED_AUDIO_EXTENSIONS);

/**
 * Generate a fresh deterministic basename for a newly-uploaded track. Keeps
 * the original extension so the static handler picks the right Content-Type.
 */
export function buildStoredFilename(originalName) {
  const ext = (extname(originalName || '') || '.mp3').toLowerCase();
  const safeExt = SUPPORTED_AUDIO_EXTENSIONS.includes(ext) ? ext : '.mp3';
  return `music-${randomUUID()}${safeExt}`;
}

/**
 * Strip the extension off a stored filename to produce a default label for
 * the library picker when the caller didn't pass one explicitly.
 */
export function deriveDefaultLabel(originalName) {
  const name = basename(originalName || '');
  const ext = extname(name);
  return ext ? name.slice(0, -ext.length) : name;
}

/**
 * List every track currently sitting in the library. Each entry carries the
 * stored filename (what the audio stage persists on `music.trackFilename`),
 * file size, and last-modified timestamp so the picker can show "added X
 * minutes ago" without a separate metadata store.
 *
 * Missing directory → empty list (no surprise 500 on a fresh install).
 */
export async function listMusicLibrary() {
  await ensureDir(PATHS.music);
  // listDirectoryByExtension covers readdir + ENOENT → [] + extension filter
  // + stat + isFile drop. ensureDir runs first, so ENOENT shouldn't trip
  // anyway — but the helper preserves the original safety net.
  const entries = await listDirectoryByExtension(PATHS.music, {
    extensions: [...SUPPORTED_AUDIO_EXTENSIONS],
    mapEntry: (name, _full, s) => ({
      filename: name,
      label: deriveDefaultLabel(name),
      sizeBytes: s.size,
      updatedAt: s.mtime.toISOString(),
    }),
  });
  return entries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
}

/**
 * Move an uploaded temp file into the library and return the persisted
 * filename. Caller (the route) reads `req.file.path` from the multipart
 * helper. Returns `{ filename, sizeBytes }`. The upload filter checks only the
 * name and declared type, so the bytes are checked here before ffmpeg can
 * probe or render the stored file; a refused temp file is removed.
 */
export async function importUploadedTrack(tempPath, originalName) {
  await assertFileNotMediaManifest(tempPath).catch(async (err) => {
    await unlinkGuarded(tempPath).catch(() => {});
    throw err;
  });
  const filename = buildStoredFilename(originalName);
  const dest = join(PATHS.music, filename);
  // The copy is the whole publication: a snapshot copying the library while it
  // runs would capture a truncated file under its final name (#9982). The temp
  // file lives outside `data/`, so its cleanup stays outside the lease.
  const sizeBytes = await withBackupAssetPublication(async () => {
    await ensureDir(PATHS.music);
    // copyFile + unlink instead of rename — the multipart helper writes to
    // os.tmpdir(), which may sit on a different filesystem (rename across
    // devices throws EXDEV on Linux). Copy works regardless.
    await copyFileGuarded(tempPath, dest);
    const s = await stat(dest).catch(() => null);
    return s?.size ?? 0;
  });
  await unlinkGuarded(tempPath).catch(() => {});
  return { filename, sizeBytes };
}

/**
 * Confirm a track exists in the library. Returns the same shape as a list
 * entry (`{ filename, label, sizeBytes }`) or `null` if missing. Validates
 * the filename to prevent path-traversal.
 */
export async function statMusicTrack(filename) {
  assertSafeMusicFilename(filename);
  const full = join(PATHS.music, filename);
  if (!existsSync(full)) return null;
  const s = await stat(full).catch(() => null);
  if (!s || !s.isFile()) return null;
  return {
    filename,
    label: deriveDefaultLabel(filename),
    sizeBytes: s.size,
  };
}

/**
 * Delete a track from the library by stored filename. Returns true if the
 * file existed and was removed; false if it was already gone. Validates the
 * filename so a path-traversal attempt can't escape `PATHS.music`.
 *
 * Issues and projects keep naming the removed file on purpose (see the route),
 * so a snapshot copied before the unlink and dumped after it would carry rows
 * naming bytes it never captured. Holding the lease makes the unlink wait out
 * an open cut and a cut wait out an unlink in flight (#9982).
 */
export async function deleteMusicTrack(filename) {
  assertSafeMusicFilename(filename);
  const full = join(PATHS.music, filename);
  return withBackupAssetPublication(async () => {
    try {
      await unlinkGuarded(full);
      return true;
    } catch (err) {
      if (err.code === 'ENOENT') return false;
      throw err;
    }
  });
}