dsh-audiogen 0.3.5 → 0.4.1

package/src/audio-engine.ts

@@ -63,7 +63,13 @@ export function detectAudioMime(data: Uint8Array): string | undefined {
 
 function mimeFromContentType(value: string | null): string | undefined {
   if (value === null || value === '') return undefined
-  return value.split(';')[0]!.trim().toLowerCase()
+  const parts = value.split(';')
+  for (const part of parts.slice(1)) {
+    // `application/json; type=audio/mpeg` —— Stability 官方用该形式携带音频真实类型。
+    const match = /^\s*type=([^;\s]+)/i.exec(part)
+    if (match !== null) return match[1]!.trim().toLowerCase()
+  }
+  return parts[0]!.trim().toLowerCase()
 }
 
 function audioMime(data: Uint8Array, contentType: string | null): string {
@@ -630,30 +636,183 @@ async function minimax(channel: AudioChannel, request: GenerateAudioRequest, sig
   }
 }
 
-async function stabilityAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
-  const base = endpointBase(channel.apiUrl)
-  const endpoint = /\/generation(\?|$)/i.test(base) ? base : `${base}/generation`
-  const model = (request.upstream ?? request.model) || 'stable-audio-2.0'
+/** Stability 内部信号：路由缺失（网关 404 Invalid URL），可切换另一协议重试。 */
+class StabilityRouteMissError extends Error {}
+
+/** 网关风格：apiUrl 形如 .../v1、.../v1/audio/speech 时优先 OpenAI 兼容 speech。 */
+function stabilityGatewayStyle(channel: AudioChannel): boolean {
+  const url = channel.apiUrl.trim().toLowerCase()
+  return /\/v1(\/|$|\?)/.test(url) || /\/audio\/speech(\?|$)/.test(url)
+}
+
+function isStabilityRouteMiss(status: number, detail: string): boolean {
+  return status === 404 && /invalid url|invalid_request_error/i.test(detail)
+}
+
+/**
+ * Stable Audio 官方 v2beta（multipart/form-data）。
+ * - stable-audio-3        → POST {base}/stable-audio/text-to-audio    （202 异步 → GET /v2beta/audio/results/{id} 轮询）
+ * - stable-audio-2 / 2.5  → POST {base}/stable-audio-2/text-to-audio  （200 同步返回音频/JSON base64）
+ * - 不同模型参数不同：stable-audio-3 steps 4-8、duration ≤380；2 steps 30-100、cfg_scale 默认 7；
+ *   2.5 steps 4-8、cfg_scale 默认 1；均支持 seed、output_format(hp3|wav)。
+ */
+async function stabilityNativeAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
+  const rawBase = endpointBase(channel.apiUrl)
+  const model = (request.upstream ?? request.model) || 'stable-audio-2.5'
+  const isV3 = /^stable-audio-3/i.test(model)
+  const isV2 = /^stable-audio-2(\.[05])?$/i.test(model) || /^stable-audio-2-/i.test(model)
+  const group = isV2 ? 'stable-audio-2' : 'stable-audio'
+
+  // 规范化 base：允许 apiUrl 为 `https://api.stability.ai` / `.../v2beta` / `.../v2beta/audio`
+  const base = /\/v2beta\/audio$/i.test(rawBase)
+    ? rawBase
+    : /\/v2beta$/i.test(rawBase)
+      ? `${rawBase}/audio`
+      : `${rawBase}/v2beta/audio`
+  const endpoint = `${base}/${group}/text-to-audio`
+
+  const form = new FormData()
+  form.set('prompt', request.prompt)
+  form.set('model', model)
+  if (request.duration !== undefined && Number.isFinite(request.duration)) {
+    const maxDuration = isV3 ? 380 : 190
+    form.set('duration', String(Math.min(maxDuration, Math.max(1, request.duration))))
+  }
+  if (request.seed !== undefined && Number.isFinite(request.seed)) {
+    form.set('seed', String(Math.floor(Math.min(4294967294, Math.max(0, request.seed)))))
+  }
+  const format = request.format === 'wav' ? 'wav' : 'mp3'
+  form.set('output_format', format)
+  if (request.steps !== undefined && Number.isInteger(request.steps)) {
+    const minSteps = isV2 && !/2\.5/i.test(model) ? 30 : 4
+    const maxSteps = isV2 && !/2\.5/i.test(model) ? 100 : 8
+    form.set('steps', String(Math.min(maxSteps, Math.max(minSteps, request.steps))))
+  }
+  if (request.cfgScale !== undefined && Number.isFinite(request.cfgScale)) {
+    form.set('cfg_scale', String(Math.min(25, Math.max(1, request.cfgScale))))
+  }
+
+  const response = await fetchWithTimeout(endpoint, {
+    method: 'POST',
+    redirect: 'error',
+    headers: {
+      authorization: `Bearer ${channel.apiKey.trim()}`,
+      accept: 'application/json',
+    },
+    body: form,
+    signal,
+  }, isV3 ? 60_000 : UPSTREAM_TIMEOUT_MS)
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '')
+    if (isStabilityRouteMiss(response.status, detail)) throw new StabilityRouteMissError()
+    throw new AudioGenError(`Stable Audio API error (HTTP ${response.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`, 'audio-api-error')
+  }
+
+  // stable-audio-3 异步：202 → 轮询结果
+  if (response.status === 202) {
+    const payload = await response.json().catch(() => ({})) as { id?: string }
+    if (payload.id === undefined || payload.id === '') {
+      throw new AudioGenError('Stable Audio accepted the job but returned no result id', 'audio-empty-result')
+    }
+    const apiOrigin = base.replace(/\/v2beta\/audio$/i, '')
+    const resultUrl = `${apiOrigin}/v2beta/audio/results/${encodeURIComponent(payload.id)}`
+    const deadline = Date.now() + UPSTREAM_TIMEOUT_MS
+    while (Date.now() < deadline) {
+      if (signal?.aborted === true) throw new AudioGenError('Stable Audio generation was aborted', 'audio-aborted')
+      const polled = await fetchWithTimeout(resultUrl, {
+        method: 'GET',
+        redirect: 'error',
+        headers: {
+          authorization: `Bearer ${channel.apiKey.trim()}`,
+          accept: 'application/json',
+        },
+        signal,
+      }, 60_000)
+      if (polled.ok) {
+        return normalizeAudioResponse(polled, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+      }
+      if (polled.status === 404 || polled.status === 202) {
+        await new Promise(resolve => setTimeout(resolve, 5000))
+        continue
+      }
+      const detail = await polled.text().catch(() => '')
+      throw new AudioGenError(`Stable Audio result API error (HTTP ${polled.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`, 'audio-api-error')
+    }
+    throw new AudioGenError('Stable Audio generation timed out waiting for the result', 'audio-timeout')
+  }
+
+  return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+}
+
+/**
+ * Stable Audio 经 OpenAI 兼容网关（如 New API 的 /v1/audio/speech）：
+ * 模型名映射到 Stable 上游，JSON 体为 {model, input, output_format, duration,
+ * seed, steps, cfg_scale} —— 与官方 v2beta 字段一一对应，网关负责转发。
+ */
+async function stabilityGatewayAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
+  const rawBase = endpointBase(channel.apiUrl)
+  const model = (request.upstream ?? request.model) || 'stable-audio-2.5'
+  const isV3 = /^stable-audio-3/i.test(model)
+  const isV2 = /^stable-audio-2(\.[05])?$/i.test(model) || /^stable-audio-2-/i.test(model)
+  const endpoint = /\/audio\/speech(\?|$)/i.test(rawBase) ? rawBase : `${rawBase}/audio/speech`
+  const format = request.format === 'wav' ? 'wav' : 'mp3'
   const body: Record<string, unknown> = {
     model,
-    prompt: request.prompt,
-    ...(request.duration !== undefined ? { duration: request.duration } : {}),
-    ...(request.format !== undefined ? { output_format: request.format } : {}),
+    input: request.prompt,
+    output_format: format,
+    ...(request.duration !== undefined && Number.isFinite(request.duration)
+      ? { duration: Math.min(isV3 ? 380 : 190, Math.max(1, request.duration)) }
+      : {}),
+    ...(request.seed !== undefined && Number.isFinite(request.seed)
+      ? { seed: Math.floor(Math.min(4294967294, Math.max(0, request.seed))) }
+      : {}),
+    ...(request.steps !== undefined && Number.isInteger(request.steps)
+      ? { steps: Math.min(isV2 && !/2\.5/i.test(model) ? 100 : 8, Math.max(isV2 && !/2\.5/i.test(model) ? 30 : 4, request.steps)) }
+      : {}),
+    ...(request.cfgScale !== undefined && Number.isFinite(request.cfgScale)
+      ? { cfg_scale: Math.min(25, Math.max(1, request.cfgScale)) }
+      : {}),
   }
   const response = await fetchWithTimeout(endpoint, {
     method: 'POST',
-    redirect: 'error',
+    redirect: 'follow',
     headers: {
       authorization: `Bearer ${channel.apiKey.trim()}`,
+      accept: 'audio/*',
       'content-type': 'application/json',
-      accept: 'application/json, audio/mpeg, audio/wav',
     },
     body: JSON.stringify(body),
     signal,
   }, UPSTREAM_TIMEOUT_MS)
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '')
+    if (isStabilityRouteMiss(response.status, detail)) throw new StabilityRouteMissError()
+    throw new AudioGenError(`Stable Audio gateway API error (HTTP ${response.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`, 'audio-api-error')
+  }
   return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
 }
 
+/**
+ * 稳定性入口：优先官方 v2beta（api.stability.ai / v2beta 形态），
+ * 网关形态（apiUrl 以 /v1 结尾或已含 /audio/speech）优先 OpenAI 兼容；
+ * 一方返回 404 Invalid URL（未路由）时自动换另一方重试。
+ */
+async function stabilityAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
+  const styles: Array<'native' | 'gateway'> = stabilityGatewayStyle(channel) ? ['gateway', 'native'] : ['native', 'gateway']
+  let lastError: Error | undefined
+  for (const style of styles) {
+    try {
+      if (style === 'gateway') return await stabilityGatewayAudio(channel, request, signal)
+      return await stabilityNativeAudio(channel, request, signal)
+    } catch (error) {
+      if (!(error instanceof StabilityRouteMissError)) throw error
+      lastError = error
+    }
+  }
+  throw lastError ?? new AudioGenError('Stable Audio 渠道未配置或不可达', 'audio-api-error')
+}
+
 async function genericAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
   const base = endpointBase(channel.apiUrl)
   if (request.mode === 'tts' && !/\/generate(\?|$)/i.test(base)) {
@@ -701,7 +860,10 @@ export async function generateAudio(
 
   if (isElevenLabs(channel)) return elevenLabs(channel, request, signal)
   if (isMiniMax(channel)) return minimax(channel, request, signal)
-  if (isStability(channel)) return stabilityAudio(channel, request, signal)
+  // 稳定性渠道或模型名明确为 stable-audio-*（含自定义渠道）→ 走官方 Stable Audio 协议
+  if (isStability(channel) || /^stable-audio-/i.test(((request.upstream ?? request.model) || '').trim())) {
+    return stabilityAudio(channel, request, signal)
+  }
   if (isOpenAICompatible(channel, request.mode)) return openAITTS(channel, request, signal)
   return genericAudio(channel, request, signal)
 }

package/src/audio-presets.ts

@@ -74,10 +74,11 @@ export const AUDIO_PRESETS: AudioPresetProvider[] = [
     name: 'Stability AI（stable-audio）',
     apiUrl: 'https://api.stability.ai/v2beta/audio',
     site: 'https://stability.ai/stable-audio',
-    hint: 'Stability AI 音乐 / 音效生成（stable-audio 系列）',
+    hint: 'Stability AI 文本到音频（TTS 描述 / 音乐 / 音效，stable-audio 系列；stable-audio-3 为异步任务）',
     models: [
-      { alias: 'stable-audio-2.0', id: 'stable-audio-2.0', category: 'music' },
-      { alias: 'stable-audio-1.0', id: 'stable-audio-1.0', category: 'music' },
+      { alias: 'stable-audio-3', id: 'stable-audio-3', category: 'music' },
+      { alias: 'stable-audio-2.5', id: 'stable-audio-2.5', category: 'music' },
+      { alias: 'stable-audio-2', id: 'stable-audio-2', category: 'music' },
     ],
   },
 ]

package/src/audio-store.ts

@@ -1,14 +1,16 @@
 /**
  * Host-side persistence for generated audio and generation history.
  * Files live under ~/.dsh/dsh-audiogen/audio/; history is one JSON document.
+ * The resource library lives under ~/.dsh/dsh-audiogen/library/ with one
+ * index JSON plus files organized by type (voice/music/sfx/tts) and category.
  */
 
-import { mkdir, readFile, writeFile, readdir, unlink } from 'node:fs/promises'
+import { mkdir, readFile, writeFile, unlink, rename, rmdir } from 'node:fs/promises'
 import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 import os from 'node:os'
-import type { HistoryEntry, HistoryEntryInput } from './protocol.ts'
-import { HISTORY_MAX } from './protocol.ts'
+import type { HistoryEntry, HistoryEntryInput, LibraryEntry, LibraryType, LibraryFileRef, LibraryAudioInput, LibraryProvenance } from './protocol.ts'
+import { HISTORY_MAX, LIBRARY_API, LIBRARY_NAME_MAX } from './protocol.ts'
 
 function dshHome(): string {
   return process.env.DSH_HOME ?? path.join(os.homedir(), '.dsh')
@@ -16,6 +18,8 @@ function dshHome(): string {
 
 export const AUDIO_DATA_DIR = path.join(dshHome(), 'dsh-audiogen', 'audio')
 const HISTORY_FILE = path.join(dshHome(), 'dsh-audiogen', 'history.json')
+export const LIBRARY_DATA_DIR = path.join(dshHome(), 'dsh-audiogen', 'library')
+const LIBRARY_INDEX_FILE = path.join(LIBRARY_DATA_DIR, 'index.json')
 
 async function ensureDir(): Promise<void> {
   await mkdir(AUDIO_DATA_DIR, { recursive: true })
@@ -111,6 +115,7 @@ export async function appendHistory(entry: HistoryEntryInput): Promise<HistoryEn
     })),
     ...(entry.channelId === undefined ? {} : { channelId: entry.channelId }),
     ...(entry.channel === undefined ? {} : { channel: entry.channel }),
+    ...(entry.params === undefined ? {} : { params: entry.params }),
   }, ...list].slice(0, HISTORY_MAX)
   await writeHistory(next)
   return next
@@ -131,3 +136,246 @@ export async function clearHistory(): Promise<HistoryEntry[]> {
   await writeHistory([])
   return []
 }
+
+// ---------------------------------------------------------------------------
+// Resource library
+// ---------------------------------------------------------------------------
+
+/** Library type dir names (whitelisted on the audio route too). */
+const LIBRARY_TYPE_DIRS: Record<LibraryType, string> = {
+  voice: 'voice',
+  music: 'music',
+  sfx: 'sfx',
+  tts: 'tts',
+}
+
+/** Sanitize one path segment (cid or voice key). Falls back to 'default'. */
+export function sanitizeSegment(value: string): string {
+  const cleaned = value
+    .replace(/[^a-zA-Z0-9\u4e00-\u9fa5._-]+/g, '_')
+    .replace(/^[._-]+|[._-]+$/g, '')
+    .slice(0, 60)
+  return cleaned === '' ? 'default' : cleaned
+}
+
+/** Infer the category for a save when the client did not provide one. */
+export function defaultLibraryCategory(
+  type: LibraryType,
+  meta: { voice?: string; voiceId?: string },
+): string | undefined {
+  if (type === 'voice') {
+    // Check female first: 'female' contains the substring 'male'.
+    const probe = `${meta.voiceId ?? ''} ${meta.voice ?? ''}`.toLowerCase()
+    if (/female|女/.test(probe)) return 'female'
+    if (/male|男/.test(probe)) return 'male'
+    return 'custom'
+  }
+  if (type === 'tts') return sanitizeSegment(meta.voice ?? meta.voiceId ?? 'default')
+  return undefined
+}
+
+/** Default resource name from the prompt. */
+export function defaultLibraryName(prompt: string): string {
+  const flat = prompt.replace(/\s+/g, ' ').trim()
+  return flat === '' ? '未命名音频' : (flat.length > LIBRARY_NAME_MAX ? `${flat.slice(0, LIBRARY_NAME_MAX)}…` : flat)
+}
+
+async function readLibraryIndex(): Promise<LibraryEntry[]> {
+  try {
+    const text = await readFile(LIBRARY_INDEX_FILE, 'utf8')
+    const parsed = JSON.parse(text) as unknown
+    if (!Array.isArray(parsed)) return []
+    return parsed.filter(isLibraryEntry)
+  } catch {
+    return []
+  }
+}
+
+function isLibraryEntry(value: unknown): value is LibraryEntry {
+  if (value === null || typeof value !== 'object') return false
+  const raw = value as Record<string, unknown>
+  return typeof raw.id === 'string'
+    && typeof raw.name === 'string'
+    && (raw.type === 'voice' || raw.type === 'music' || raw.type === 'sfx' || raw.type === 'tts')
+    && Array.isArray(raw.files)
+    && typeof raw.createdAt === 'number'
+    && typeof (raw as Record<string, unknown>).provenance === 'object'
+}
+
+async function writeLibraryIndex(entries: LibraryEntry[]): Promise<void> {
+  await mkdir(LIBRARY_DATA_DIR, { recursive: true })
+  await writeFile(LIBRARY_INDEX_FILE, JSON.stringify(entries, null, 2))
+}
+
+/** Same-origin URL for a library-relative file path. */
+export function libraryUrlOf(rel: string): string {
+  return `${LIBRARY_API.audio}/${rel.split('/').map(segment => encodeURIComponent(segment)).join('/')}`
+}
+
+/** Merge-library-entry: copy one audio/ file into library/<type>/<category>/. */
+async function copyIntoLibrary(input: LibraryAudioInput, typeDir: string, category: string): Promise<LibraryFileRef> {
+  const stored = await readAudioFile(input.file)
+  if (stored === undefined) {
+    throw new Error(`音频文件不存在：${input.file}（请重新生成后再入库）`)
+  }
+  const ext = path.extname(input.file).replace('.', '') || (stored.mime.split('/')[1]?.replace('mpeg', 'mp3') ?? 'bin')
+  const rel = `${typeDir}/${category}/${input.id}.${ext}`
+  const target = path.join(LIBRARY_DATA_DIR, ...rel.split('/'))
+  await mkdir(path.dirname(target), { recursive: true })
+  await writeFile(target, stored.data)
+  return {
+    url: libraryUrlOf(rel),
+    rel,
+    mime: stored.mime,
+    bytes: stored.bytes,
+    ...(input.duration === undefined ? {} : { duration: input.duration }),
+    ...(input.voiceId === undefined ? {} : { voiceId: input.voiceId }),
+  }
+}
+
+/**
+ * Save one curated library entry: copies the referenced audio files into
+ * library/<type>/<category>/ (audio/ files stay untouched) and appends the
+ * entry to the index.
+ */
+export async function saveToLibrary(input: {
+  audioFiles: LibraryAudioInput[]
+  type: LibraryType
+  category?: string
+  name?: string
+  tags?: string[]
+  note?: string
+  provenance: LibraryProvenance
+}): Promise<LibraryEntry> {
+  if (input.audioFiles.length === 0) throw new Error('没有可入库的音频文件')
+  const typeDir = LIBRARY_TYPE_DIRS[input.type]
+  const category = input.category !== undefined && input.category.trim() !== ''
+    ? sanitizeSegment(input.category.trim())
+    : defaultLibraryCategory(input.type, {
+      voice: input.provenance.voice,
+      voiceId: input.provenance.voiceId ?? input.audioFiles.find(file => file.voiceId !== undefined)?.voiceId,
+    }) ?? 'default'
+  const files = await Promise.all(input.audioFiles.map(file => copyIntoLibrary(file, typeDir, category)))
+  const rawName = (input.name ?? '').trim()
+  const entry: LibraryEntry = {
+    id: randomUUID(),
+    createdAt: Date.now(),
+    type: input.type,
+    category: category === 'default' && input.type !== 'voice' && input.type !== 'tts' ? undefined : category,
+    name: rawName === '' ? defaultLibraryName(input.provenance.prompt) : rawName,
+    tags: Array.isArray(input.tags) ? [...new Set(input.tags.map(tag => tag.trim()).filter(tag => tag !== ''))].slice(0, 20) : [],
+    ...(input.note !== undefined && input.note.trim() !== '' ? { note: input.note.trim() } : {}),
+    files,
+    provenance: input.provenance,
+  }
+  const entries = await readLibraryIndex()
+  entries.unshift(entry)
+  await writeLibraryIndex(entries)
+  return entry
+}
+
+/** Read library entries (newest first). */
+export async function listLibrary(): Promise<LibraryEntry[]> {
+  const entries = await readLibraryIndex()
+  return [...entries].sort((a, b) => b.createdAt - a.createdAt)
+}
+
+/** Move one library-relative file to a new rel path (same volume rename, else copy). */
+async function moveLibraryFile(fromRel: string, toRel: string): Promise<void> {
+  const from = path.join(LIBRARY_DATA_DIR, ...fromRel.split('/'))
+  const to = path.join(LIBRARY_DATA_DIR, ...toRel.split('/'))
+  await mkdir(path.dirname(to), { recursive: true })
+  try {
+    await rename(from, to)
+  } catch {
+    const data = await readFile(from)
+    await writeFile(to, data)
+    await unlink(from)
+  }
+}
+
+/** Patch name/tags/note/type/category; moving type/category relocates files. */
+export async function updateLibraryEntry(id: string, patch: {
+  name?: string
+  tags?: string[]
+  note?: string
+  category?: string
+  type?: LibraryType
+}): Promise<LibraryEntry | undefined> {
+  const entries = await readLibraryIndex()
+  const index = entries.findIndex(entry => entry.id === id)
+  if (index < 0) return undefined
+  const entry = { ...entries[index]!, files: [...entries[index]!.files] }
+  if (patch.type !== undefined && LIBRARY_TYPES_VALID.includes(patch.type)) entry.type = patch.type
+  if (patch.name !== undefined) entry.name = patch.name.trim() === '' ? defaultLibraryName(entry.provenance.prompt) : patch.name.trim()
+  if (patch.tags !== undefined) entry.tags = [...new Set(patch.tags.map(tag => tag.trim()).filter(tag => tag !== ''))].slice(0, 20)
+  if (patch.note !== undefined) entry.note = patch.note.trim() === '' ? undefined : patch.note.trim()
+  if (patch.category !== undefined && patch.category.trim() !== '') {
+    const next = sanitizeSegment(patch.category.trim())
+    if (entry.type === 'voice' || entry.type === 'tts') entry.category = next
+  }
+  const oldCat = entries[index]!.category ?? 'default'
+  const newCat = entry.category ?? 'default'
+  if (entries[index]!.type !== entry.type || oldCat !== newCat) {
+    const moved: LibraryFileRef[] = []
+    for (const file of entry.files) {
+      const fileName = file.rel.split('/').pop() ?? ''
+      const fromRel = `${LIBRARY_TYPE_DIRS[entries[index]!.type]}/${oldCat}/${fileName}`
+      const toRel = `${LIBRARY_TYPE_DIRS[entry.type]}/${newCat}/${fileName}`
+      if (fromRel !== toRel) await moveLibraryFile(fromRel, toRel)
+      moved.push({ ...file, rel: toRel, url: libraryUrlOf(toRel) })
+    }
+    entry.files = moved
+  }
+  entries[index] = entry
+  await writeLibraryIndex(entries)
+  return entry
+}
+
+/** Remove entries and their audio files; best-effort prune empty dirs. */
+export async function removeLibraryEntries(ids: string[]): Promise<LibraryEntry[]> {
+  const entries = await readLibraryIndex()
+  const doomed = new Set(ids)
+  const kept = entries.filter(entry => !doomed.has(entry.id))
+  for (const entry of entries) {
+    if (!doomed.has(entry.id)) continue
+    for (const file of entry.files) {
+      try {
+        await unlink(path.join(LIBRARY_DATA_DIR, ...file.rel.split('/')))
+      } catch {
+        // best-effort
+      }
+    }
+  }
+  // prune now-empty leaf dirs (best effort, one level under type dirs)
+  for (const entry of entries) {
+    if (!doomed.has(entry.id)) continue
+    try {
+      await rmdir(path.dirname(path.join(LIBRARY_DATA_DIR, ...entry.files[0]!.rel.split('/'))), { recursive: false })
+    } catch {
+      // dir not empty or already gone
+    }
+  }
+  await writeLibraryIndex(kept)
+  return kept
+}
+
+/** Read one library file by its rel path (whitelisted, traversal-safe). */
+export async function readLibraryFile(rel: string): Promise<{ data: Buffer; mime: string; bytes: number } | undefined> {
+  const segments = rel.split('/').filter(segment => segment !== '')
+  if (segments.length < 2 || segments.length > 3) return undefined
+  const [typeDir, category, fileName] = segments
+  if (typeDir === undefined || !Object.values(LIBRARY_TYPE_DIRS).includes(typeDir)) return undefined
+  if (category === undefined || sanitizeSegment(category) !== category || category.length > 60) return undefined
+  if (fileName === undefined || !/^[0-9a-f-]{36}\.[a-z0-9]{2,5}$/i.test(fileName)) return undefined
+  const full = path.join(LIBRARY_DATA_DIR, typeDir, category, fileName)
+  if (!full.startsWith(path.join(LIBRARY_DATA_DIR, typeDir, category) + path.sep)) return undefined
+  try {
+    const data = await readFile(full)
+    return { data, mime: mimeFromFile(fileName), bytes: data.byteLength }
+  } catch {
+    return undefined
+  }
+}
+
+const LIBRARY_TYPES_VALID = ['voice', 'music', 'sfx', 'tts'] as const